1.\" $MirOS: src/lib/libc/stdlib/strtol.3,v 1.3 2014/03/19 22:54:00 tg Exp $
2.\"-
3.\" Copyright (c) 1990, 1991 The Regents of the University of California.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to Berkeley by
7.\" Chris Torek and the American National Standards Committee X3,
8.\" on Information Processing Systems.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\" 3. Neither the name of the University nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\"	$OpenBSD: strtol.3,v 1.13 2003/06/02 20:18:38 millert Exp $
35.\"
36.Dd $Mdocdate: March 19 2014 $
37.Dt STRTOL 3
38.Os
39.Sh NAME
40.Nm strtol ,
41.Nm strtoll ,
42.Nm strtoq
43.Nd "convert string value to a long or long long integer"
44.Sh SYNOPSIS
45.Fd #include <stdlib.h>
46.Fd #include <limits.h>
47.Ft long
48.Fn strtol "const char *nptr" "char **endptr" "int base"
49.Pp
50.Fd #include <stdlib.h>
51.Fd #include <limits.h>
52.Ft long long
53.Fn strtoll "const char *nptr" "char **endptr" "int base"
54.Pp
55.Fd #include <inttypes.h>
56.Ft intmax_t
57.Fn strtoimax "const char *nptr" "char **endptr" "int base"
58.Pp
59.Fd #include <sys/types.h>
60.Fd #include <stdlib.h>
61.Fd #include <limits.h>
62.Ft quad_t
63.Fn strtoq "const char *nptr" "char **endptr" "int base"
64.Sh DESCRIPTION
65The
66.Fn strtol
67function converts the string in
68.Fa nptr
69to a
70.Li long
71value.
72The
73.Fn strtoll
74function converts the string in
75.Fa nptr
76to a
77.Li long long
78value.
79The
80.Fn strtoq
81function is a deprecated equivalent of
82.Fn strtoll
83and is provided for backwards compatibility with legacy programs.
84The conversion is done according to the given
85.Fa base ,
86which must be a number between 2 and 36 inclusive or the special value 0.
87.Pp
88The string may begin with an arbitrary amount of whitespace
89(as determined by
90.Xr isspace 3 )
91followed by a single optional
92.Ql +
93or
94.Ql -
95sign.
96If
97.Fa base
98is zero or 16, the string may then include a
99.Ql 0x
100prefix, and the number will be read in base 16; otherwise, a zero
101.Fa base
102is taken as 10 (decimal) unless the next character is
103.Ql 0 ,
104in which case it is taken as 8 (octal).
105.Pp
106The remainder of the string is converted to a
107.Li long
108value in the obvious manner,
109stopping at the first character which is not a valid digit
110in the given base.
111(In bases above 10, the letter
112.Ql A
113in either upper or lower case represents 10,
114.Ql B
115represents 11, and so forth, with
116.Ql Z
117representing 35.)
118.Pp
119If
120.Fa endptr
121is non-null,
122.Fn strtol
123stores the address of the first invalid character in
124.Fa *endptr .
125If there were no digits at all, however,
126.Fn strtol
127stores the original value of
128.Fa nptr
129in
130.Fa *endptr .
131(Thus, if
132.Fa *nptr
133is not
134.Ql \e0
135but
136.Fa **endptr
137is
138.Ql \e0
139on return, the entire string was valid.)
140.Sh RETURN VALUES
141The
142.Fn strtol
143function returns the result of the conversion,
144unless the value would underflow or overflow.
145If an underflow occurs,
146.Fn strtol
147returns
148.Dv LONG_MIN .
149If an overflow occurs,
150.Fn strtol
151returns
152.Dv LONG_MAX .
153In both cases,
154.Va errno
155is set to
156.Er ERANGE .
157.Pp
158The
159.Fn strtoll
160function has identical return values except that
161.Dv LLONG_MIN
162and
163.Dv LLONG_MAX
164are used to indicate underflow and overflow respectively.
165.Sh EXAMPLES
166Ensuring that a string is a valid number (i.e., in range and containing no
167trailing characters) requires clearing
168.Va errno
169beforehand explicitly since
170.Va errno
171is not changed on a successful call to
172.Fn strtol ,
173and the return value of
174.Fn strtol
175cannot be used unambiguously to signal an error:
176.Bd -literal -offset indent
177char *ep;
178long lval;
179
180\&...
181
182errno = 0;
183lval = strtol(buf, &ep, 10);
184if (buf[0] == '\e0' || *ep != '\e0')
185	goto not_a_number;
186if (errno == ERANGE && (lval == LONG_MAX || lval == LONG_MIN))
187	goto out_of_range;
188.Ed
189.Pp
190This example will accept
191.Dq 12
192but not
193.Dq 12foo
194or
195.Dq 12\en .
196If trailing whitespace is acceptable, further checks must be done on
197.Va *ep ;
198alternately, use
199.Xr sscanf 3 .
200.Pp
201If
202.Fn strtol
203is being used instead of
204.Xr atoi 3 ,
205error checking is further complicated because the desired return value is an
206.Li int
207rather than a
208.Li long ;
209however, on some architectures integers and long integers are the same size.
210Thus the following is necessary:
211.Bd -literal -offset indent
212char *ep;
213int ival;
214long lval;
215
216\&...
217
218errno = 0;
219lval = strtol(buf, &ep, 10);
220if (buf[0] == '\e0' || *ep != '\e0')
221     goto not_a_number;
222if ((errno == ERANGE && (lval == LONG_MAX || lval == LONG_MIN)) ||
223    (lval > INT_MAX || lval < INT_MIN))
224     goto out_of_range;
225ival = lval;
226.Ed
227.Sh ERRORS
228.Bl -tag -width Er
229.It Bq Er ERANGE
230The given string was out of range; the value converted has been clamped.
231.El
232.Sh SEE ALSO
233.Xr atof 3 ,
234.Xr atoi 3 ,
235.Xr atol 3 ,
236.Xr atoll 3 ,
237.Xr sscanf 3 ,
238.Xr strtod 3 ,
239.Xr strtoul 3
240.Sh STANDARDS
241The
242.Fn strtol ,
243.Fn strtoll
244and
245.Fn strtoimax
246functions conform to
247.St -isoC-99 .
248The
249.Fn strtoq
250function is a
251.Bx
252extension and is provided for backwards compatibility with legacy programs.
253.Sh BUGS
254Ignores the current locale.
255