- Uniformly use .In for header file references.
[dragonfly.git] / lib / libc / stdlib / strtonum.3
CommitLineData
70e9d14e 1.\" $OpenBSD: strtonum.3,v 1.5 2004/05/06 06:19:01 tedu Exp $
44cb301e 2.\" $DragonFly: src/lib/libc/stdlib/strtonum.3,v 1.4 2006/05/26 19:39:37 swildner Exp $
70e9d14e
JS
3.\"
4.\" Copyright (c) 2004 Ted Unangst
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd July 25, 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
44cb301e
SW
25.In stdlib.h
26.In limits.h
70e9d14e
JS
27.Ft unsigned long long
28.Fo strtonum
29.Fa "const char *nptr"
30.Fa "long long minval"
31.Fa "unsigned 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 an
40.Li unsigned long long
41value.
42Negative values may be obtained by casting the result.
43The
44.Fn strtonum
45function was designed to facilitate safe, robust programming
46and overcome the shortcomings of the
47.Xr atoi 3
48and
49.Xr strtol 3
50family of interfaces.
51.Pp
52The string may begin with an arbitrary amount of whitespace
53(as determined by
54.Xr isspace 3 )
55followed by a single optional
56.Ql +
57or
58.Ql -
59sign.
60.Pp
61The remainder of the string is converted to an
62.Li unsigned long long
63value according to base 10.
64.Pp
65The value obtained is then checked against the provided
66.Fa minval
67and
68.Fa maxval
69bounds.
70If
71.Fa errstr
72is non-null,
73.Fn strtonum
74stores an error string in
75.Fa *errstr
76indicating the failure.
77.Sh RETURN VALUES
78The
79.Fn strtonum
80function returns the result of the conversion,
81unless the value would exceed the provided bounds or is invalid.
82On error, 0 is returned and
83.Fa errstr
84will point to an error message.
85.Sh EXAMPLES
86Using
87.Fn strtonum
88correctly is meant to be simpler than the alternative functions.
89.Bd -literal -offset indent
90int iterations;
91const char *errstr;
92
93iterations = strtonum(optarg, 1, 64, &errstr);
94if (errstr)
95 errx(1, "number of iterations is %s: %s", errstr, optarg);
96.Ed
97.Pp
98The above example will guarantee that the value of iterations is between
991 and 64.
100.Sh ERRORS
101.Bl -tag -width Er
102.It Bq Er ERANGE
103The given string was out of range.
104.It Bq Er EINVAL
105The given string did not consist solely of digit characters.
106.El
107.Pp
108If an error occurs, errstr will be set to one of the following strings.
109.Bl -tag -width "too large"
110.It "too large"
111The result was larger than the provided maximum value.
112.It "too small"
113The result was smaller than the provided minimum value.
114.It "invalid"
115The string did not consist solely of digit characters.
116.El
117.Sh SEE ALSO
118.Xr atof 3 ,
119.Xr atoi 3 ,
120.Xr atol 3 ,
121.Xr atoll 3 ,
122.Xr sscanf 3 ,
123.Xr strtod 3 ,
124.Xr strtol 3 ,
125.Xr strtoul 3
126.Sh STANDARDS
127.Fn strtonum
128was originally implemented as an extension on
129.Ox .
70e9d14e
JS
130The existing alternatives, such as
131.Xr atoi 3
132and
133.Xr strtol 3
134are either impossible or difficult to use safely.