diff options
| author | christos <christos@NetBSD.org> | 2015-01-18 17:59:36 +0000 |
|---|---|---|
| committer | christos <christos@NetBSD.org> | 2015-01-18 17:59:36 +0000 |
| commit | d010fbe8c51c709f93aabf068f393ae1bb7bcb13 (patch) | |
| tree | 7cd9c750c5ede50359e3f8d485fa6d51894a60ad /lib/libc/stdlib | |
| parent | 9f7f631d862a4fc58736cdeff88dbb2332adb3df (diff) | |
man page for strtonum.3
Diffstat (limited to 'lib/libc/stdlib')
| -rw-r--r-- | lib/libc/stdlib/Makefile.inc | 5 | ||||
| -rw-r--r-- | lib/libc/stdlib/strtonum.3 | 187 |
2 files changed, 190 insertions, 2 deletions
diff --git a/lib/libc/stdlib/Makefile.inc b/lib/libc/stdlib/Makefile.inc index e52bd51d69d..f918e425b3e 100644 --- a/lib/libc/stdlib/Makefile.inc +++ b/lib/libc/stdlib/Makefile.inc @@ -1,4 +1,4 @@ -# $NetBSD: Makefile.inc,v 1.85 2015/01/16 18:41:33 christos Exp $ +# $NetBSD: Makefile.inc,v 1.86 2015/01/18 17:59:36 christos Exp $ # from: @(#)Makefile.inc 8.3 (Berkeley) 2/4/95 # stdlib sources @@ -53,7 +53,8 @@ MAN+= a64l.3 abort.3 abs.3 alloca.3 atexit.3 atof.3 atoi.3 atol.3 atoll.3 \ posix_memalign.3 posix_openpt.3 ptsname.3 \ qabs.3 qdiv.3 quick_exit.3 qsort.3 \ radixsort.3 rand48.3 rand.3 random.3 \ - strfmon.3 strsuftoll.3 strtod.3 strtol.3 strtoul.3 system.3 \ + strfmon.3 strsuftoll.3 strtod.3 strtol.3 strtoul.3 strtonum.3 \ + system.3 \ tsearch.3 \ unlockpt.3 diff --git a/lib/libc/stdlib/strtonum.3 b/lib/libc/stdlib/strtonum.3 new file mode 100644 index 00000000000..dc7ae1e8909 --- /dev/null +++ b/lib/libc/stdlib/strtonum.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: strtonum.3,v 1.1 2015/01/18 17:59:36 christos Exp $ +.\" $OpenBSD: strtonum.3,v 1.17 2013/08/14 06:32:28 jmc Exp $ +.\" +.\" Copyright (c) 2004 Ted Unangst +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 14 2013 $ +.Dt STRTONUM 3 +.Os +.Sh NAME +.Nm strtonum +.Nd reliably convert string value to an integer +.Sh SYNOPSIS +.Vt #define _OPENBSD_SOURCE +.In stdlib.h +.Ft long long +.Fo strtonum +.Fa "const char *nptr" +.Fa "long long minval" +.Fa "long long maxval" +.Fa "const char **errstr" +.Fc +.Sh DESCRIPTION +The +.Fn strtonum +function converts the string in +.Fa nptr +to a +.Li long long +value. +.Pp +The string may begin with an arbitrary amount of whitespace +(as determined by +.Xr isspace 3 ) +followed by a single optional +.Ql + +or +.Ql - +sign. +.Pp +The remainder of the string is converted to a +.Li long long +value according to base 10. +.Pp +The value obtained is then checked against the provided +.Fa minval +and +.Fa maxval +bounds. +If +.Fa errstr +is non-null, +.Fn strtonum +stores an error string in +.Fa *errstr +indicating the failure. +.Sh RETURN VALUES +The +.Fn strtonum +function returns the result of the conversion, +unless the value would exceed the provided bounds or is invalid. +On error, 0 is returned, +.Va errno +is set, and +.Fa errstr +will point to an error message. +.Fa *errstr +will be set to +.Dv NULL +on success; +this fact can be used to differentiate +a successful return of 0 from an error. +.Sh EXAMPLES +Using +.Fn strtonum +correctly is meant to be simpler than the alternative functions. +.Bd -literal -offset indent +int iterations; +const char *errstr; + +iterations = strtonum(optarg, 1, 64, &errstr); +if (errstr) + errx(1, "number of iterations is %s: %s", errstr, optarg); +.Ed +.Pp +The above example will guarantee that the value of iterations is between +1 and 64 (inclusive). +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ERANGE +The given string was out of range. +.It Bq Er EINVAL +The given string did not consist solely of digit characters. +.It Bq Er EINVAL +.Ar minval +was larger than +.Ar maxval . +.El +.Pp +If an error occurs, +.Fa errstr +will be set to one of the following strings: +.Pp +.Bl -tag -width "too largeXX" -compact +.It Qq too large +The result was larger than the provided maximum value. +.It Qq too small +The result was smaller than the provided minimum value. +.It Qq invalid +The string did not consist solely of digit characters. +.El +.Sh CAVEATS +The +.Fn strtonum +function was designed to facilitate safe, +robust programming and overcome the shortcomings of the +.Xr atoi 3 +and +.Xr strtol 3 +family of interfaces, however there are problems with the +.Fn strtonum +API: +.Bl -dash +.It +will return 0 on failure; 0 might not be in range, so that necessitates an error check even if you want to avoid it +.It +does not differentiate 'illegal' returns, so we can't tell the difference between partial and no conversions +.It +returns english strings +.It +can't set the base, or find where the conversion ended +.It +hardcodes long long integer type +.El +To overcome the shortcomings of +.Fn strtonum +.Nx +provides +.Fn strtou 3 +and +.Fn strtoi 3 . +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr atoll 3 , +.Xr sscanf 3 , +.Xr strtoi 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoll 3 , +.Xr strtou 3 , +.Xr strtoul 3 +.Xr strtoull 3 +.Sh STANDARDS +.Fn strtonum +is an +.Ox +extension. +.Sh HISTORY +The +.Fn strtonum +function first appeared in +.Ox 3.6 . +.Fn strtonum +was redesigned in +.Nx 8 +as +.Fn strtoi 3 +and +.Fn strtou 3 . +For compatibility reasons it's available since +.Nx 8 +in the +.Vt _OPENBSD_SOURCE +namespace. |
