strtonum.3 (91545fccf956c3f2d688c457b79b0b2cf086fbb9) strtonum.3 (ad136d1e29fa5fcb8f2635d42b7c8a1dfef4ff50)
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

--- 8 unchanged lines hidden (view full) ---

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
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

--- 8 unchanged lines hidden (view full) ---

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 .