1.\" $MirOS: src/lib/libc/stdlib/strtoul.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: strtoul.3,v 1.15 2003/06/02 20:18:38 millert Exp $
35.\"
36.Dd $Mdocdate: March 19 2014 $
37.Dt STRTOUL 3
38.Os
39.Sh NAME
40.Nm strtoul ,
41.Nm strtoull ,
42.Nm strtouq
43.Nd "convert a string to an unsigned long or unsigned long long integer"
44.Sh SYNOPSIS
45.Fd #include <stdlib.h>
46.Fd #include <limits.h>
47.Ft unsigned long
48.Fn strtoul "const char *nptr" "char **endptr" "int base"
49.Pp
50.Fd #include <stdlib.h>
51.Fd #include <limits.h>
52.Ft unsigned long long
53.Fn strtoull "const char *nptr" "char **endptr" "int base"
54.Pp
55.Fd #include <inttypes.h>
56.Ft uintmax_t
57.Fn strtoumax "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 u_quad_t
63.Fn strtouq "const char *nptr" "char **endptr" "int base"
64.Sh DESCRIPTION
65The
66.Fn strtoul
67function converts the string in
68.Fa nptr
69to an
70.Li unsigned long
71value.
72The
73.Fn strtoull
74function converts the string in
75.Fa nptr
76to an
77.Li unsigned long long
78value.
79The
80.Fn strtouq
81function is a deprecated equivalent of
82.Fn strtoull
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
87or the special value 0.
88If the string in
89.Fa nptr
90represents a negative number, it will be converted to its unsigned equivalent.
91This behavior is consistent with what happens when a signed integer type is
92cast to its unsigned counterpart.
93.Pp
94The string may begin with an arbitrary amount of whitespace
95(as determined by
96.Xr isspace 3 )
97followed by a single optional
98.Ql +
99or
100.Ql -
101sign.
102If
103.Fa base
104is zero or 16, the string may then include a
105.Ql 0x
106prefix, and the number will be read in base 16; otherwise, a zero
107.Fa base
108is taken as 10 (decimal) unless the next character is
109.Ql 0 ,
110in which case it is taken as 8 (octal).
111.Pp
112The remainder of the string is converted to an
113.Li unsigned long
114value in the obvious manner, stopping at the end of the string
115or at the first character that does not produce a valid digit
116in the given base.
117(In bases above 10, the letter
118.Ql A
119in either upper or lower case represents 10,
120.Ql B
121represents 11, and so forth, with
122.Ql Z
123representing 35.)
124.Pp
125If
126.Fa endptr
127is non-null,
128.Fn strtoul
129stores the address of the first invalid character in
130.Fa *endptr .
131If there were no digits at all, however,
132.Fn strtoul
133stores the original value of
134.Fa nptr
135in
136.Fa *endptr .
137(Thus, if
138.Fa *nptr
139is not
140.Ql \e0
141but
142.Fa **endptr
143is
144.Ql \e0
145on return, the entire string was valid.)
146.Sh RETURN VALUES
147The
148.Fn strtoul
149function returns the result of the conversion,
150unless the value would overflow, in which case
151.Dv ULONG_MAX
152is returned and
153.Va errno
154is set to
155.Er ERANGE .
156If there was a leading minus sign,
157.Fn strtoul
158returns the (unsigned) negation of the absolute value of the number, unless
159the absolute value would overflow.
160In this case,
161.Fn strtoul
162returns
163.Dv ULONG_MAX
164and sets the global variable
165.Va errno
166to
167.Er ERANGE .
168.Pp
169The
170.Fn strtoull
171function has identical return values except that
172.Dv ULLONG_MAX
173is used to indicate overflow.
174.Pp
175There is no way to determine if
176.Fn strtoul
177has processed a negative number (and returned an unsigned value) short of
178examining the string in
179.Fa nptr
180directly.
181.Sh EXAMPLES
182Ensuring that a string is a valid number (i.e., in range and containing no
183trailing characters) requires clearing
184.Va errno
185beforehand explicitly since
186.Va errno
187is not changed on a successful call to
188.Fn strtoul ,
189and the return value of
190.Fn strtoul
191cannot be used unambiguously to signal an error:
192.Bd -literal -offset indent
193char *ep;
194unsigned long ulval;
195
196\&...
197
198errno = 0;
199ulval = strtoul(buf, &ep, 10);
200if (buf[0] == '\e0' || *ep != '\e0')
201	goto not_a_number;
202if (errno == ERANGE && ulval == ULONG_MAX)
203	goto out_of_range;
204.Ed
205.Pp
206This example will accept
207.Dq 12
208but not
209.Dq 12foo
210or
211.Dq 12\en .
212If trailing whitespace is acceptable, further checks must be done on
213.Va *ep ;
214alternately, use
215.Xr sscanf 3 .
216.Sh ERRORS
217.Bl -tag -width Er
218.It Bq Er ERANGE
219The given string was out of range; the value converted has been clamped.
220.El
221.Sh SEE ALSO
222.Xr sscanf 3 ,
223.Xr strtol 3
224.Sh STANDARDS
225The
226.Fn strtoul ,
227.Fn strtoull
228and
229.Fn strtoumax
230functions conform to
231.St -isoC-99 .
232The
233.Fn strtouq
234function is a
235.Bx
236extension and is provided for backwards compatibility with legacy programs.
237.Sh BUGS
238Ignores the current locale.
239