| strtonum.3 (156741) | strtonum.3 (162841) |
|---|---|
| 1.\" Copyright (c) 2004 Ted Unangst 2.\" 3.\" Permission to use, copy, modify, and distribute this software for any 4.\" purpose with or without fee is hereby granted, provided that the above 5.\" copyright notice and this permission notice appear in all copies. 6.\" 7.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 10.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 12.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 13.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 14.\" 15.\" $OpenBSD: strtonum.3,v 1.12 2005/10/26 11:37:58 jmc Exp $ | 1.\" Copyright (c) 2004 Ted Unangst 2.\" 3.\" Permission to use, copy, modify, and distribute this software for any 4.\" purpose with or without fee is hereby granted, provided that the above 5.\" copyright notice and this permission notice appear in all copies. 6.\" 7.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 10.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 12.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 13.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 14.\" 15.\" $OpenBSD: strtonum.3,v 1.12 2005/10/26 11:37:58 jmc Exp $ |
| 16.\" $FreeBSD: head/lib/libc/stdlib/strtonum.3 156741 2006-03-15 14:45:45Z ru $ | 16.\" $FreeBSD: head/lib/libc/stdlib/strtonum.3 162841 2006-09-30 10:34:13Z ru $ |
| 17.\" 18.Dd April 29, 2004 19.Dt STRTONUM 3 20.Os 21.Sh NAME 22.Nm strtonum 23.Nd "reliably convert string value to an integer" 24.Sh SYNOPSIS | 17.\" 18.Dd April 29, 2004 19.Dt STRTONUM 3 20.Os 21.Sh NAME 22.Nm strtonum 23.Nd "reliably convert string value to an integer" 24.Sh SYNOPSIS |
| 25.Fd #include <stdlib.h> 26.Fd #include <limits.h> | 25.In stdlib.h 26.In limits.h |
| 27.Ft long long 28.Fo strtonum 29.Fa "const char *nptr" 30.Fa "long long minval" 31.Fa "long long maxval" 32.Fa "const char **errstr" 33.Fc 34.Sh DESCRIPTION 35The 36.Fn strtonum 37function converts the string in 38.Fa nptr 39to a | 27.Ft long long 28.Fo strtonum 29.Fa "const char *nptr" 30.Fa "long long minval" 31.Fa "long long maxval" 32.Fa "const char **errstr" 33.Fc 34.Sh DESCRIPTION 35The 36.Fn strtonum 37function converts the string in 38.Fa nptr 39to a |
| 40.Li long long | 40.Vt "long long" |
| 41value. 42The 43.Fn strtonum 44function was designed to facilitate safe, robust programming 45and overcome the shortcomings of the 46.Xr atoi 3 47and 48.Xr strtol 3 --- 4 unchanged lines hidden (view full) --- 53.Xr isspace 3 ) 54followed by a single optional 55.Ql + 56or 57.Ql - 58sign. 59.Pp 60The remainder of the string is converted to a | 41value. 42The 43.Fn strtonum 44function was designed to facilitate safe, robust programming 45and overcome the shortcomings of the 46.Xr atoi 3 47and 48.Xr strtol 3 --- 4 unchanged lines hidden (view full) --- 53.Xr isspace 3 ) 54followed by a single optional 55.Ql + 56or 57.Ql - 58sign. 59.Pp 60The remainder of the string is converted to a |
| 61.Li long long | 61.Vt "long long" |
| 62value according to base 10. 63.Pp 64The value obtained is then checked against the provided 65.Fa minval 66and 67.Fa maxval 68bounds. 69If --- 8 unchanged lines hidden (view full) --- 78.Fn strtonum 79function returns the result of the conversion, 80unless the value would exceed the provided bounds or is invalid. 81On error, 0 is returned, 82.Va errno 83is set, and 84.Fa errstr 85will point to an error message. | 62value according to base 10. 63.Pp 64The value obtained is then checked against the provided 65.Fa minval 66and 67.Fa maxval 68bounds. 69If --- 8 unchanged lines hidden (view full) --- 78.Fn strtonum 79function returns the result of the conversion, 80unless the value would exceed the provided bounds or is invalid. 81On error, 0 is returned, 82.Va errno 83is set, and 84.Fa errstr 85will point to an error message. |
| 86On success, |
|
| 86.Fa *errstr 87will be set to | 87.Fa *errstr 88will be set to |
| 88.Dv NULL 89on success; | 89.Dv NULL ; |
| 90this fact can be used to differentiate 91a successful return of 0 from an error. 92.Sh EXAMPLES 93Using 94.Fn strtonum 95correctly is meant to be simpler than the alternative functions. 96.Bd -literal -offset indent 97int iterations; --- 8 unchanged lines hidden (view full) --- 1061 and 64 (inclusive). 107.Sh ERRORS 108.Bl -tag -width Er 109.It Bq Er ERANGE 110The given string was out of range. 111.It Bq Er EINVAL 112The given string did not consist solely of digit characters. 113.It Bq Er EINVAL | 90this fact can be used to differentiate 91a successful return of 0 from an error. 92.Sh EXAMPLES 93Using 94.Fn strtonum 95correctly is meant to be simpler than the alternative functions. 96.Bd -literal -offset indent 97int iterations; --- 8 unchanged lines hidden (view full) --- 1061 and 64 (inclusive). 107.Sh ERRORS 108.Bl -tag -width Er 109.It Bq Er ERANGE 110The given string was out of range. 111.It Bq Er EINVAL 112The given string did not consist solely of digit characters. 113.It Bq Er EINVAL |
| 114.Ar minval | 114The supplied 115.Fa minval |
| 115was larger than | 116was larger than |
| 116.Ar maxval . | 117.Fa maxval . |
| 117.El 118.Pp 119If an error occurs, 120.Fa errstr 121will be set to one of the following strings: 122.Pp | 118.El 119.Pp 120If an error occurs, 121.Fa errstr 122will be set to one of the following strings: 123.Pp |
| 123.Bl -tag -width "too largeXX" -compact 124.It too large | 124.Bl -tag -width ".Li too large" -compact 125.It Li "too large" |
| 125The result was larger than the provided maximum value. | 126The result was larger than the provided maximum value. |
| 126.It too small | 127.It Li "too small" |
| 127The result was smaller than the provided minimum value. | 128The result was smaller than the provided minimum value. |
| 128.It invalid | 129.It Li invalid |
| 129The string did not consist solely of digit characters. 130.El 131.Sh SEE ALSO 132.Xr atof 3 , 133.Xr atoi 3 , 134.Xr atol 3 , 135.Xr atoll 3 , 136.Xr sscanf 3 , 137.Xr strtod 3 , 138.Xr strtol 3 , 139.Xr strtoul 3 140.Sh STANDARDS | 130The string did not consist solely of digit characters. 131.El 132.Sh SEE ALSO 133.Xr atof 3 , 134.Xr atoi 3 , 135.Xr atol 3 , 136.Xr atoll 3 , 137.Xr sscanf 3 , 138.Xr strtod 3 , 139.Xr strtol 3 , 140.Xr strtoul 3 141.Sh STANDARDS |
| 142The |
|
| 141.Fn strtonum | 143.Fn strtonum |
| 142is a | 144function is a |
| 143.Bx 144extension. 145The existing alternatives, such as 146.Xr atoi 3 147and 148.Xr strtol 3 , 149are either impossible or difficult to use safely. 150.Sh HISTORY 151The 152.Fn strtonum 153function first appeared in 154.Ox 3.6 . | 145.Bx 146extension. 147The existing alternatives, such as 148.Xr atoi 3 149and 150.Xr strtol 3 , 151are either impossible or difficult to use safely. 152.Sh HISTORY 153The 154.Fn strtonum 155function first appeared in 156.Ox 3.6 . |