Sync strtol(3) and strtoul(3) with FreeBSD.
authorSascha Wildner <swildner@dragonflybsd.org>
Thu, 2 Nov 2006 19:48:55 +0000 (19:48 +0000)
committerSascha Wildner <swildner@dragonflybsd.org>
Thu, 2 Nov 2006 19:48:55 +0000 (19:48 +0000)
This fixes some mdoc nits, adds documentation about when EINVAL is returned
and makes the existance of strtoimax(3) and strtoumax(3) known to the world.

lib/libc/stdlib/Makefile.inc
lib/libc/stdlib/strtol.3
lib/libc/stdlib/strtoul.3

index d9ef926..fabfbbf 100644 (file)
@@ -1,6 +1,6 @@
 #      from @(#)Makefile.inc   8.3 (Berkeley) 2/4/95
 # $FreeBSD: src/lib/libc/stdlib/Makefile.inc,v 1.19.2.4 2001/10/02 11:15:38 ru Exp $
-# $DragonFly: src/lib/libc/stdlib/Makefile.inc,v 1.14 2005/11/01 18:16:52 swildner Exp $
+# $DragonFly: src/lib/libc/stdlib/Makefile.inc,v 1.15 2006/11/02 19:48:55 swildner Exp $
 
 # machine-independent stdlib sources
 .PATH: ${.CURDIR}/../libc/${MACHINE_ARCH}/stdlib ${.CURDIR}/../libc/stdlib
@@ -30,7 +30,7 @@ MLINKS+=qsort.3 heapsort.3 qsort.3 mergesort.3
 MLINKS+=rand.3 rand_r.3 rand.3 srand.3 rand.3 sranddev.3
 MLINKS+=random.3 initstate.3 random.3 setstate.3 random.3 srandom.3 \
        random.3 srandomdev.3
-MLINKS+=strtol.3 strtoll.3 strtol.3 strtoq.3
-MLINKS+=strtoul.3 strtoull.3 strtoul.3 strtouq.3
+MLINKS+=strtol.3 strtoll.3 strtol.3 strtoimax.3 strtol.3 strtoq.3
+MLINKS+=strtoul.3 strtoull.3 strtoul.3 strtoumax.3 strtoul.3 strtouq.3
 MLINKS+=malloc.3 calloc.3 malloc.3 free.3 malloc.3 realloc.3 malloc.3 reallocf.3
 .endif
index e7f0423..88b9af2 100644 (file)
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)strtol.3   8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/stdlib/strtol.3,v 1.4.2.5 2001/12/14 18:33:58 ru Exp $
-.\" $DragonFly: src/lib/libc/stdlib/strtol.3,v 1.3 2005/08/05 22:35:10 swildner Exp $
+.\" $FreeBSD: src/lib/libc/stdlib/strtol.3,v 1.21 2006/05/20 21:11:35 maxim Exp $
+.\" $DragonFly: src/lib/libc/stdlib/strtol.3,v 1.4 2006/11/02 19:48:55 swildner Exp $
 .\"
-.Dd June 4, 1993
+.Dd November 2, 2006
 .Dt STRTOL 3
 .Os
 .Sh NAME
-.Nm strtol ,
-.Nm strtoll ,
-.Nm strtoq
-.Nd "convert a string value to a long, long long, or quad_t integer"
+.Nm strtol , strtoll , strtoimax , strtoq
+.Nd "convert a string value to a"
+.Vt long , "long long" , intmax_t
+or
+.Vt quad_t
+integer
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -54,6 +56,9 @@
 .Fn strtol "const char *nptr" "char **endptr" "int base"
 .Ft long long
 .Fn strtoll "const char *nptr" "char **endptr" "int base"
+.In inttypes.h
+.Ft intmax_t
+.Fn strtoimax "const char *nptr" "char **endptr" "int base"
 .In sys/types.h
 .In stdlib.h
 .In limits.h
@@ -66,7 +71,7 @@ function
 converts the string in
 .Fa nptr
 to a
-.Em long
+.Vt long
 value.
 The
 .Fn strtoll
@@ -74,7 +79,15 @@ function
 converts the string in
 .Fa nptr
 to a
-.Em long long
+.Vt "long long"
+value.
+The
+.Fn strtoimax
+function
+converts the string in
+.Fa nptr
+to an
+.Vt intmax_t
 value.
 The
 .Fn strtoq
@@ -82,7 +95,7 @@ function
 converts the string in
 .Fa nptr
 to a
-.Em quad_t
+.Vt quad_t
 value.
 The conversion is done according to the given
 .Fa base ,
@@ -101,7 +114,7 @@ If
 .Fa base
 is zero or 16,
 the string may then include a
-.Ql 0x
+.Dq Li 0x
 prefix,
 and the number will be read in base 16; otherwise, a zero
 .Fa base
@@ -110,7 +123,9 @@ is taken as 10 (decimal) unless the next character is
 in which case it is taken as 8 (octal).
 .Pp
 The remainder of the string is converted to a
-.Em long
+.Vt long , "long long" , intmax_t
+or
+.Vt quad_t
 value in the obvious manner,
 stopping at the first character which is not a valid digit
 in the given base.
@@ -125,7 +140,8 @@ representing 35.)
 .Pp
 If
 .Fa endptr
-is non nil,
+is not
+.Dv NULL ,
 .Fn strtol
 stores the address of the first invalid character in
 .Fa *endptr .
@@ -146,37 +162,41 @@ is
 on return, the entire string was valid.)
 .Sh RETURN VALUES
 The
-.Fn strtol
-function
-returns the result of the conversion,
-unless the value would underflow or overflow.
-If an underflow occurs,
-.Fn strtol
-returns
-.Dv LONG_MIN .
-If an overflow occurs,
-.Fn strtol
-returns
-.Dv LONG_MAX .
-The
-.Fn strtoll
-function
-returns the result of the conversion,
+.Fn strtol ,
+.Fn strtoll ,
+.Fn strtoimax
+and
+.Fn strtoq
+functions
+return the result of the conversion,
 unless the value would underflow or overflow.
-If an underflow occurs,
-.Fn strtoll
-returns
-.Dv LLONG_MIN .
-If an overflow occurs,
-.Fn strtoll
-returns
-.Dv LLONG_MAX .
-In all cases,
+If no conversion could be performed, 0 is returned and
+the global variable
 .Va errno
 is set to
-.Er ERANGE .
+.Er EINVAL
+(the last feature is not portable across all platforms).
+If an overflow or underflow occurs,
+.Va errno
+is set to
+.Er ERANGE
+and the function return value is clamped according
+to the following table.
+.Bl -column -offset indent ".Fn strtoimax" ".Sy overflow" ".Sy underflow"
+.It Sy Function Ta Sy overflow Ta Sy underflow
+.It Fn strtol Ta Dv LONG_MIN Ta Dv LONG_MAX
+.It Fn strtoll Ta Dv LLONG_MIN Ta Dv LLONG_MAX
+.It Fn strtoimax Ta Dv INTMAX_MIN Ta Dv INTMAX_MAX
+.It Fn strtoq Ta Dv LLONG_MIN Ta Dv LLONG_MAX
+.El
 .Sh ERRORS
 .Bl -tag -width Er
+.It Bq Er EINVAL
+The value of
+.Fa base
+is not supported or
+no conversion could be performed
+(the last feature is not portable across all platforms).
 .It Bq Er ERANGE
 The given string was out of range; the value converted has been clamped.
 .El
@@ -185,7 +205,9 @@ The given string was out of range; the value converted has been clamped.
 .Xr atoi 3 ,
 .Xr atol 3 ,
 .Xr strtod 3 ,
-.Xr strtoul 3
+.Xr strtonum 3 ,
+.Xr strtoul 3 ,
+.Xr wcstol 3
 .Sh STANDARDS
 The
 .Fn strtol
@@ -194,12 +216,12 @@ conforms to
 .St -isoC .
 The
 .Fn strtoll
-function
-conforms to
+and
+.Fn strtoimax
+functions
+conform to
 .St -isoC-99 .
 The
 .Bx
 .Fn strtoq
 function is deprecated.
-.Sh BUGS
-Ignores the current locale.
index c6a8c78..451e21c 100644 (file)
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)strtoul.3  8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/stdlib/strtoul.3,v 1.3.2.7 2002/01/21 12:30:34 ru Exp $
-.\" $DragonFly: src/lib/libc/stdlib/strtoul.3,v 1.3 2005/08/05 22:35:10 swildner Exp $
+.\" $FreeBSD: src/lib/libc/stdlib/strtoul.3,v 1.22 2006/05/20 21:11:35 maxim Exp $
+.\" $DragonFly: src/lib/libc/stdlib/strtoul.3,v 1.4 2006/11/02 19:48:55 swildner Exp $
 .\"
-.Dd June 4, 1993
+.Dd November 2, 2006
 .Dt STRTOUL 3
 .Os
 .Sh NAME
@@ -45,7 +45,7 @@
 .Nm strtoull ,
 .Nm strtouq
 .Nd "convert a string to an"
-.Vt "unsigned long" , "unsigned long long" ,
+.Vt "unsigned long" , "unsigned long long" , uintmax_t ,
 or
 .Vt u_quad_t
 integer
@@ -58,6 +58,9 @@ integer
 .Fn strtoul "const char *nptr" "char **endptr" "int base"
 .Ft "unsigned long long"
 .Fn strtoull "const char *nptr" "char **endptr" "int base"
+.In inttypes.h
+.Ft uintmax_t
+.Fn strtoumax "const char *nptr" "char **endptr" "int base"
 .In sys/types.h
 .In stdlib.h
 .In limits.h
@@ -81,6 +84,14 @@ to an
 .Vt "unsigned long long"
 value.
 The
+.Fn strtoumax
+function
+converts the string in
+.Fa nptr
+to an
+.Vt uintmax_t
+value.
+The
 .Fn strtouq
 function
 converts the string in
@@ -152,38 +163,55 @@ is
 on return, the entire string was valid.)
 .Sh RETURN VALUES
 The
-.Fn strtoul
-function
-returns either the result of the conversion
+.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,
 .Fn strtoul
 returns
-.Dv ULONG_MAX .
-The
-.Fn strtoull
-function
-returns 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,
+.Dv ULONG_MAX ,
 .Fn strtoull
 returns
+.Dv ULLONG_MAX ,
+.Fn strtoumax
+returns
+.Dv UINTMAX_MAX ,
+and
+.Fn strtouq
+returns
 .Dv ULLONG_MAX .
 In all cases,
 .Va errno
 is set to
 .Er ERANGE .
+If no conversion could be performed, 0 is returned and
+the global variable
+.Va errno
+is set to
+.Er EINVAL
+(the last feature is not portable across all platforms).
 .Sh ERRORS
 .Bl -tag -width Er
+.It Bq Er EINVAL
+The value of
+.Fa base
+is not supported or
+no conversion could be performed
+(the last feature is not portable across all platforms).
 .It Bq Er ERANGE
 The given string was out of range; the value converted has been clamped.
 .El
 .Sh SEE ALSO
-.Xr strtol 3
+.Xr strtol 3 ,
+.Xr strtonum 3 ,
+.Xr wcstoul 3
 .Sh STANDARDS
 The
 .Fn strtoul
@@ -192,12 +220,12 @@ conforms to
 .St -isoC .
 The
 .Fn strtoull
-function
-conforms to
+and
+.Fn strtoumax
+functions
+conform to
 .St -isoC-99 .
 The
 .Bx
 .Fn strtouq
 function is deprecated.
-.Sh BUGS
-Ignores the current locale.