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 156708 2006-03-14 17:01:21Z andre $
| 16.\" $FreeBSD: head/lib/libc/stdlib/strtonum.3 156739 2006-03-15 14:05:41Z andre $
|
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>
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
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
49family of interfaces.
50.Pp
51The string may begin with an arbitrary amount of whitespace
52(as determined by
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
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
70.Fa errstr
71is non-null,
72.Fn strtonum
73stores an error string in
74.Fa *errstr
75indicating the failure.
76.Sh RETURN VALUES
77The
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.
86.Fa *errstr
87will be set to
88.Dv NULL
89on success;
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;
98const char *errstr;
99
100iterations = strtonum(optarg, 1, 64, &errstr);
101if (errstr)
102 errx(1, "number of iterations is %s: %s", errstr, optarg);
103.Ed
104.Pp
105The above example will guarantee that the value of iterations is between
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
115was larger than
116.Ar maxval .
117.El
118.Pp
119If an error occurs,
120.Fa errstr
121will be set to one of the following strings:
122.Pp
123.Bl -tag -width "too largeXX" -compact
124.It too large
125The result was larger than the provided maximum value.
126.It too small
127The result was smaller than the provided minimum value.
128.It 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
141.Fn strtonum
| 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>
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
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
49family of interfaces.
50.Pp
51The string may begin with an arbitrary amount of whitespace
52(as determined by
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
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
70.Fa errstr
71is non-null,
72.Fn strtonum
73stores an error string in
74.Fa *errstr
75indicating the failure.
76.Sh RETURN VALUES
77The
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.
86.Fa *errstr
87will be set to
88.Dv NULL
89on success;
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;
98const char *errstr;
99
100iterations = strtonum(optarg, 1, 64, &errstr);
101if (errstr)
102 errx(1, "number of iterations is %s: %s", errstr, optarg);
103.Ed
104.Pp
105The above example will guarantee that the value of iterations is between
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
115was larger than
116.Ar maxval .
117.El
118.Pp
119If an error occurs,
120.Fa errstr
121will be set to one of the following strings:
122.Pp
123.Bl -tag -width "too largeXX" -compact
124.It too large
125The result was larger than the provided maximum value.
126.It too small
127The result was smaller than the provided minimum value.
128.It 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
141.Fn strtonum
|
142is an BSD extension.
| 142is a
143.Bx extension.
|
143The existing alternatives, such as
144.Xr atoi 3
145and
146.Xr strtol 3 ,
147are either impossible or difficult to use safely.
148.Sh HISTORY
149The
150.Fn strtonum
| 144The existing alternatives, such as
145.Xr atoi 3
146and
147.Xr strtol 3 ,
148are either impossible or difficult to use safely.
149.Sh HISTORY
150The
151.Fn strtonum
|
151function first appeared in OpenBSD 3.6 .
| 152function first appeared in
153.Ox 3.6 .
|
| |