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.13 2006/04/25 05:15:42 tedu Exp $ |
---|
16 | .\" $FreeBSD$ |
---|
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 | .In stdlib.h |
---|
26 | .Ft long long |
---|
27 | .Fo strtonum |
---|
28 | .Fa "const char *nptr" |
---|
29 | .Fa "long long minval" |
---|
30 | .Fa "long long maxval" |
---|
31 | .Fa "const char **errstr" |
---|
32 | .Fc |
---|
33 | .Sh DESCRIPTION |
---|
34 | The |
---|
35 | .Fn strtonum |
---|
36 | function converts the string in |
---|
37 | .Fa nptr |
---|
38 | to a |
---|
39 | .Vt "long long" |
---|
40 | value. |
---|
41 | The |
---|
42 | .Fn strtonum |
---|
43 | function was designed to facilitate safe, robust programming |
---|
44 | and overcome the shortcomings of the |
---|
45 | .Xr atoi 3 |
---|
46 | and |
---|
47 | .Xr strtol 3 |
---|
48 | family of interfaces. |
---|
49 | .Pp |
---|
50 | The string may begin with an arbitrary amount of whitespace |
---|
51 | (as determined by |
---|
52 | .Xr isspace 3 ) |
---|
53 | followed by a single optional |
---|
54 | .Ql + |
---|
55 | or |
---|
56 | .Ql - |
---|
57 | sign. |
---|
58 | .Pp |
---|
59 | The remainder of the string is converted to a |
---|
60 | .Vt "long long" |
---|
61 | value according to base 10. |
---|
62 | .Pp |
---|
63 | The value obtained is then checked against the provided |
---|
64 | .Fa minval |
---|
65 | and |
---|
66 | .Fa maxval |
---|
67 | bounds. |
---|
68 | If |
---|
69 | .Fa errstr |
---|
70 | is non-null, |
---|
71 | .Fn strtonum |
---|
72 | stores an error string in |
---|
73 | .Fa *errstr |
---|
74 | indicating the failure. |
---|
75 | .Sh RETURN VALUES |
---|
76 | The |
---|
77 | .Fn strtonum |
---|
78 | function returns the result of the conversion, |
---|
79 | unless the value would exceed the provided bounds or is invalid. |
---|
80 | On error, 0 is returned, |
---|
81 | .Va errno |
---|
82 | is set, and |
---|
83 | .Fa errstr |
---|
84 | will point to an error message. |
---|
85 | On success, |
---|
86 | .Fa *errstr |
---|
87 | will be set to |
---|
88 | .Dv NULL ; |
---|
89 | this fact can be used to differentiate |
---|
90 | a successful return of 0 from an error. |
---|
91 | .Sh EXAMPLES |
---|
92 | Using |
---|
93 | .Fn strtonum |
---|
94 | correctly is meant to be simpler than the alternative functions. |
---|
95 | .Bd -literal -offset indent |
---|
96 | int iterations; |
---|
97 | const char *errstr; |
---|
98 | |
---|
99 | iterations = strtonum(optarg, 1, 64, &errstr); |
---|
100 | if (errstr) |
---|
101 | errx(1, "number of iterations is %s: %s", errstr, optarg); |
---|
102 | .Ed |
---|
103 | .Pp |
---|
104 | The above example will guarantee that the value of iterations is between |
---|
105 | 1 and 64 (inclusive). |
---|
106 | .Sh ERRORS |
---|
107 | .Bl -tag -width Er |
---|
108 | .It Bq Er ERANGE |
---|
109 | The given string was out of range. |
---|
110 | .It Bq Er EINVAL |
---|
111 | The given string did not consist solely of digit characters. |
---|
112 | .It Bq Er EINVAL |
---|
113 | The supplied |
---|
114 | .Fa minval |
---|
115 | was larger than |
---|
116 | .Fa maxval . |
---|
117 | .El |
---|
118 | .Pp |
---|
119 | If an error occurs, |
---|
120 | .Fa errstr |
---|
121 | will be set to one of the following strings: |
---|
122 | .Pp |
---|
123 | .Bl -tag -width ".Li too large" -compact |
---|
124 | .It Li "too large" |
---|
125 | The result was larger than the provided maximum value. |
---|
126 | .It Li "too small" |
---|
127 | The result was smaller than the provided minimum value. |
---|
128 | .It Li invalid |
---|
129 | The 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 | The |
---|
142 | .Fn strtonum |
---|
143 | function is a |
---|
144 | .Bx |
---|
145 | extension. |
---|
146 | The existing alternatives, such as |
---|
147 | .Xr atoi 3 |
---|
148 | and |
---|
149 | .Xr strtol 3 , |
---|
150 | are either impossible or difficult to use safely. |
---|
151 | .Sh HISTORY |
---|
152 | The |
---|
153 | .Fn strtonum |
---|
154 | function first appeared in |
---|
155 | .Ox 3.6 . |
---|