From f2ee8239d197834a9bd38e83dd90bec6dd53b8cf Mon Sep 17 00:00:00 2001
From: leitner <leitner>
Date: Thu, 22 Aug 2013 23:35:34 +0000
Subject: [PATCH] add more examples

---
 scan/scan_ulong.3 | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/scan/scan_ulong.3 b/scan/scan_ulong.3
index 16e5d55..98b8181 100644
--- a/scan/scan_ulong.3
+++ b/scan/scan_ulong.3
@@ -9,5 +9,32 @@ size_t \fBscan_ulong\fP(const char *\fIsrc\fR,unsigned long *\fIdest\fR);
 scan_ulong parses an unsigned long integer in decimal ASCII representation
 from \fIsrc\fR and writes the result into \fIdest\fR. It returns the
 number of bytes read from \fIsrc\fR.
+
+Leading + or - or space (or anything outside of 0-9) is not accepted.
+The libc conventions of "023" for octal or "0x23" for hexadecimal are
+not supported.
+
+scan_ulong will abort the scan if the next character is not a digit, or
+if it is a digit but adding it to the number would lead to an integer
+overflow.
+.SH "RETURN VALUE"
+scan_ulong returns the number of characters successfully scanned and
+processed from src.
+.SH EXAMPLES
+scan_ulong("23",&i) -> i=23, return 2
+
+scan_ulong("+23",&i) -> return 0
+
+scan_ulong("-23",&i) -> return 0
+
+scan_ulong(" 23",&i) -> return 0
+
+scan_ulong("23,42",&i) -> i=23, return 2
+
+scan_ulong("023",&i) -> i=23, return 3
+
+scan_ulong("0x23",&i) -> i=0, return 1
+
+scan_ulong("4294967296",&i" -> i=429496729, return 9 // 32-bit system
 .SH "SEE ALSO"
 scan_xlong(3), scan_8long(3), fmt_ulong(3)