[src/trunk]: src/lib/libc/stdlib bring in EXAMPLES and a note.

[yamt <yamt%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5c5acdb0f760
branches:  trunk
changeset: 535140:5c5acdb0f760
user:      yamt <yamt%NetBSD.org@localhost>
date:      Sun Aug 11 07:05:41 2002 +0000

description:
bring in EXAMPLES and a note.
from openbsd.

diffstat:

 lib/libc/stdlib/strtoul.3 |  46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 44 insertions(+), 2 deletions(-)

diffs (67 lines):

diff -r 531acf72e416 -r 5c5acdb0f760 lib/libc/stdlib/strtoul.3
--- a/lib/libc/stdlib/strtoul.3 Sun Aug 11 07:04:00 2002 +0000
+++ b/lib/libc/stdlib/strtoul.3 Sun Aug 11 07:05:41 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: strtoul.3,v 1.15 2002/02/07 07:00:30 ross Exp $
+.\"    $NetBSD: strtoul.3,v 1.16 2002/08/11 07:05:41 yamt Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -37,7 +37,7 @@
 .\"
 .\"     from: @(#)strtoul.3    8.1 (Berkeley) 6/4/93
 .\"
-.Dd April 26, 2001
+.Dd August 11, 2002
 .Dt STRTOUL 3
 .Os
 .Sh NAME
@@ -181,6 +181,48 @@
 .Va errno
 is set to
 .Er ERANGE .
+.Pp
+There is no way to determine if
+.Fn strtoul
+has processed a negative number (and returned an unsigned value) short of
+examining the string in
+.Fa nptr
+directly.
+.Sh EXAMPLES
+Ensuring that a string is a valid number (i.e., in range and containing no
+trailing characters) requires clearing
+.Va errno
+beforehand explicitly since
+.Va errno
+is not changed on a successful call to
+.Fn strtoul ,
+and the return value of
+.Fn strtoul
+cannot be used unambiguously to signal an error:
+.Bd -literal -offset indent
+char *ep;
+unsigned long ulval;
+
+\&...
+
+errno = 0;
+ulval = strtoul(buf, &ep, 10);
+if (buf[0] == '\e0' || *ep != '\e0')
+       goto not_a_number;
+if (errno == ERANGE && ulval == ULONG_MAX)
+       goto out_of_range;
+.Ed
+.Pp
+This example will accept
+.Dq 12
+but not
+.Dq 12foo
+or
+.Dq 12\en .
+If trailing whitespace is acceptable, further checks must be done on
+.Va *ep ;
+alternately, use
+.Xr sscanf 3 .
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er ERANGE