xref: /netbsd/lib/libc/stdlib/strtoul.3 (revision c4a72b64) 
1.\"	$NetBSD: strtoul.3,v 1.16 2002/08/11 07:05:41 yamt Exp $
2.\"
3.\" Copyright (c) 1990, 1991, 1993
4.\"	The Regents of the University of California.  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. All advertising materials mentioning features or use of this software
19.\"    must display the following acknowledgement:
20.\"	This product includes software developed by the University of
21.\"	California, Berkeley and its contributors.
22.\" 4. Neither the name of the University nor the names of its contributors
23.\"    may be used to endorse or promote products derived from this software
24.\"    without specific prior written permission.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36.\" SUCH DAMAGE.
37.\"
38.\"     from: @(#)strtoul.3	8.1 (Berkeley) 6/4/93
39.\"
40.Dd August 11, 2002
41.Dt STRTOUL 3
42.Os
43.Sh NAME
44.Nm strtoul ,
45.Nm strtoull ,
46.Nm strtoumax ,
47.Nm strtouq
48.Nd "convert a string to an unsigned long, unsigned long long, uintmax_t or uquad_t integer"
49.Sh LIBRARY
50.Lb libc
51.Sh SYNOPSIS
52.Fd #include \*[Lt]stdlib.h\*[Gt]
53.Fd #include \*[Lt]limits.h\*[Gt]
54.Ft unsigned long int
55.Fn strtoul "const char * restrict nptr" "char ** restrict endptr" "int base"
56.Ft unsigned long long int
57.Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base"
58.Pp
59.Fd #include \*[Lt]inttypes.h\*[Gt]
60.Ft uintmax_t
61.Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base"
62.Pp
63.Fd #include \*[Lt]sys/types.h\*[Gt]
64.Fd #include \*[Lt]stdlib.h\*[Gt]
65.Fd #include \*[Lt]limits.h\*[Gt]
66.Ft u_quad_t
67.Fn strtouq "const char * restrict nptr" "char ** restrict endptr" "int base"
68.Sh DESCRIPTION
69The
70.Fn strtoul
71function
72converts the string in
73.Fa nptr
74to an
75.Em unsigned long int
76value.
77The
78.Fn strtoull
79function
80converts the string in
81.Fa nptr
82to an
83.Em unsigned long long int
84value.
85The
86.Fn strtoumax
87function
88converts the string in
89.Fa nptr
90to an
91.Em uintmax_t
92value.
93The
94.Fn strtouq
95function
96converts the string in
97.Fa nptr
98to a
99.Em u_quad_t
100value.
101The conversion is done according to the given
102.Fa base ,
103which must be between 2 and 36 inclusive,
104or be the special value 0.
105.Pp
106The string may begin with an arbitrary amount of white space
107(as determined by
108.Xr isspace 3 )
109followed by a single optional
110.Ql +
111or
112.Ql -
113sign.
114If
115.Fa base
116is zero or 16,
117the string may then include a
118.Ql 0x
119prefix,
120and the number will be read in base 16; otherwise, a zero
121.Fa base
122is taken as 10 (decimal) unless the next character is
123.Ql 0 ,
124in which case it is taken as 8 (octal).
125.Pp
126The remainder of the string is converted to an
127.Em unsigned long
128value in the obvious manner,
129stopping at the end of the string
130or at the first character that does not produce a valid digit
131in the given base.
132(In bases above 10, the letter
133.Ql A
134in either upper or lower case
135represents 10,
136.Ql B
137represents 11, and so forth, with
138.Ql Z
139representing 35.)
140.Pp
141If
142.Fa endptr
143is non nil,
144.Fn strtoul
145stores the address of the first invalid character in
146.Fa *endptr .
147If there were no digits at all, however,
148.Fn strtoul
149stores the original value of
150.Fa nptr
151in
152.Fa *endptr .
153(Thus, if
154.Fa *nptr
155is not
156.Ql \e0
157but
158.Fa **endptr
159is
160.Ql \e0
161on return, the entire string was valid.)
162.Sh RETURN VALUES
163The
164.Fn strtoul
165function
166returns either the result of the conversion
167or, if there was a leading minus sign,
168the negation of the result of the conversion,
169unless the original (non-negated) value would overflow;
170in the latter case,
171.Fn strtoul
172returns
173.Dv ULONG_MAX ,
174.Fn strtoull
175returns
176.Dv ULLONG_MAX ,
177.Fn strtoumax
178returns
179.Dv UINTMAX_MAX ,
180and the global variable
181.Va errno
182is set to
183.Er ERANGE .
184.Pp
185There is no way to determine if
186.Fn strtoul
187has processed a negative number (and returned an unsigned value) short of
188examining the string in
189.Fa nptr
190directly.
191.Sh EXAMPLES
192Ensuring that a string is a valid number (i.e., in range and containing no
193trailing characters) requires clearing
194.Va errno
195beforehand explicitly since
196.Va errno
197is not changed on a successful call to
198.Fn strtoul ,
199and the return value of
200.Fn strtoul
201cannot be used unambiguously to signal an error:
202.Bd -literal -offset indent
203char *ep;
204unsigned long ulval;
205
206\&...
207
208errno = 0;
209ulval = strtoul(buf, &ep, 10);
210if (buf[0] == '\e0' || *ep != '\e0')
211	goto not_a_number;
212if (errno == ERANGE && ulval == ULONG_MAX)
213	goto out_of_range;
214.Ed
215.Pp
216This example will accept
217.Dq 12
218but not
219.Dq 12foo
220or
221.Dq 12\en .
222If trailing whitespace is acceptable, further checks must be done on
223.Va *ep ;
224alternately, use
225.Xr sscanf 3 .
226.Sh ERRORS
227.Bl -tag -width Er
228.It Bq Er ERANGE
229The given string was out of range; the value converted has been clamped.
230.El
231.Sh SEE ALSO
232.Xr strtoimax 3 ,
233.Xr strtol 3 ,
234.Xr strtoll 3
235.Sh STANDARDS
236The
237.Fn strtoul
238function
239conforms to
240.St -ansiC .
241The
242.Fn strtoull
243and
244.Fn strtoumax
245functions conform to
246.St -isoC99 .
247.Sh BUGS
248Ignores the current locale.
249