1 files changed, 127 insertions, 46 deletions

diff --git a/src/lib/libc/stdlib/strtoul.3 b/src/lib/libc/stdlib/strtoul.3
index db551b0141..5e86772ef0 100644
--- a/src/lib/libc/stdlib/strtoul.3
+++ b/src/lib/libc/stdlib/strtoul.3
@@ -13,11 +13,7 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"     This product includes software developed by the University of
-.\"     California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"
@@ -33,49 +29,70 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     from: @(#)strtoul.3     5.4 (Berkeley) 6/25/92
-.\"     $Id: strtoul.3,v 1.1.1.1 1995/10/18 08:42:20 deraadt Exp $
+.\"     $OpenBSD: strtoul.3,v 1.20 2010/04/07 18:32:53 jmc Exp $
 .\"
-.Dd June 25, 1992
+.Dd $Mdocdate: April 7 2010 $
 .Dt STRTOUL 3
 .Os
 .Sh NAME
-.Nm strtoul, strtouq
-.Nd convert a string to an unsigned long or uquad_t integer
+.Nm strtoul ,
+.Nm strtoull ,
+.Nm strtoumax ,
+.Nm strtouq
+.Nd "convert a string to an unsigned long, unsigned long long or uintmax_t integer"
 .Sh SYNOPSIS
-.Fd #include <stdlib.h>
 .Fd #include <limits.h>
+.Fd #include <stdlib.h>
 .Ft unsigned long
 .Fn strtoul "const char *nptr" "char **endptr" "int base"
-
+.Ft unsigned long long
+.Fn strtoull "const char *nptr" "char **endptr" "int base"
+.Fd #include <inttypes.h>
+.Ft uintmax_t
+.Fn strtoumax "const char *nptr" "char **endptr" "int base"
 .Fd #include <sys/types.h>
-.Fd #include <stdlib.h>
 .Fd #include <limits.h>
+.Fd #include <stdlib.h>
 .Ft u_quad_t
 .Fn strtouq "const char *nptr" "char **endptr" "int base"
 .Sh DESCRIPTION
 The
 .Fn strtoul
-function
-converts the string in
+function converts the string in
 .Fa nptr
 to an
-.Em unsigned long
+.Li unsigned long
 value.
 The
-.Fn strtouq
-function
-converts the string in
+.Fn strtoull
+function converts the string in
+.Fa nptr
+to an
+.Li unsigned long long
+value.
+The
+.Fn strtoumax
+function converts the string in
 .Fa nptr
 to a
-.Em u_quad_t
+.Li umaxint_t
 value.
+The
+.Fn strtouq
+function is a deprecated equivalent of
+.Fn strtoull
+and is provided for backwards compatibility with legacy programs.
 The conversion is done according to the given
 .Fa base ,
-which must be between 2 and 36 inclusive,
-or be the special value 0.
+which must be a number between 2 and 36 inclusive
+or the special value 0.
+If the string in
+.Fa nptr
+represents a negative number, it will be converted to its unsigned equivalent.
+This behavior is consistent with what happens when a signed integer type is
+cast to its unsigned counterpart.
 .Pp
-The string may begin with an arbitrary amount of white space
+The string may begin with an arbitrary amount of whitespace
 (as determined by
 .Xr isspace 3 )
 followed by a single optional
@@ -85,26 +102,22 @@ or
 sign.
 If
 .Fa base
-is zero or 16,
-the string may then include a
+is zero or 16, the string may then include a
 .Ql 0x
-prefix,
-and the number will be read in base 16; otherwise, a zero
+prefix, and the number will be read in base 16; otherwise, a zero
 .Fa base
 is taken as 10 (decimal) unless the next character is
 .Ql 0 ,
 in which case it is taken as 8 (octal).
 .Pp
 The remainder of the string is converted to an
-.Em unsigned long
-value in the obvious manner,
-stopping at the end of the string
+.Li unsigned long
+value in the obvious manner, stopping at the end of the string
 or at the first character that does not produce a valid digit
 in the given base.
 (In bases above 10, the letter
 .Ql A
-in either upper or lower case
-represents 10,
+in either upper or lower case represents 10,
 .Ql B
 represents 11, and so forth, with
 .Ql Z
@@ -112,7 +125,7 @@ representing 35.)
 .Pp
 If
 .Fa endptr
-is non nil,
+is non-null,
 .Fn strtoul
 stores the address of the first invalid character in
 .Fa *endptr .
@@ -133,32 +146,100 @@ is
 on return, the entire string was valid.)
 .Sh RETURN VALUES
 The
-.Fn strtoul
-function
-returns either the result of the conversion
-or, if there was a leading minus sign,
+.Fn strtoul ,
+.Fn strtoull ,
+.Fn strtoumax
+and
+.Fn strtouq
+functions return either the result of the conversion or,
+if there was a leading minus sign,
 the negation of the result of the conversion,
-unless the original (non-negated) value would overflow;
-in the latter case,
+unless the original (non-negated) value would overflow.
+If overflow occurs,
 .Fn strtoul
 returns
-.Dv ULONG_MAX
-and sets the global variable
+.Dv ULONG_MAX ,
+.Fn strtoull
+returns
+.Dv ULLONG_MAX ,
+.Fn strtoumax
+returns
+.Dv UINTMAX_MAX ,
+.Fn strtouq
+returns
+.Dv ULLONG_MAX
+and the global variable
 .Va errno
-to
+is set to
 .Er ERANGE .
+If no conversion could be performed, 0 is returned;
+the global variable
+.Va errno
+is also set to
+.Er EINVAL ,
+though this is not portable across all platforms.
+.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
 The given string was out of range; the value converted has been clamped.
 .El
 .Sh SEE ALSO
+.Xr sscanf 3 ,
 .Xr strtol 3
 .Sh STANDARDS
 The
-.Fn strtoul
-function
-conforms to
-.St -ansiC .
+.Fn strtoul ,
+.Fn strtoull ,
+and
+.Fn strtoumax
+functions conform to
+.St -ansiC-99 .
+The
+.Fn strtouq
+function is a
+.Bx
+extension and is provided for backwards compatibility with legacy programs.
 .Sh BUGS
 Ignores the current locale.