Debian Codegraph @

upstream/debian-unstable/man3/strtoul.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH strtoul 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 strtoul, strtoull, strtouq \- convert a string to an unsigned long integer
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdlib.h>
16 .P
17 .BI "unsigned long strtoul(const char *restrict " nptr ,
18 .BI " char **_Nullable restrict " endptr ", int " base );
19 .BI "unsigned long long strtoull(const char *restrict " nptr ,
20 .BI " char **_Nullable restrict " endptr ", int " base );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR strtoull ():
29 .nf
30 _ISOC99_SOURCE
31 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
32 .fi
33 .SH DESCRIPTION
34 The
35 .BR strtoul ()
36 function converts the initial part of the string
37 in
38 .I nptr
39 to an
40 .I "unsigned long"
41 value according to the
42 given
43 .IR base ,
44 which must be between 2 and 36 inclusive, or be
45 the special value 0.
46 .P
47 The string may begin with an arbitrary amount of white space (as
48 determined by
49 .BR isspace (3))
50 followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq]
51 sign.
52 If
53 .I base
54 is zero or 16, the string may then include a
55 "0x" or "0X" prefix, and the number will be read in base 16;
56 if
57 .I base
58 is zero or 2, the string may then include a
59 "0b" or "0B" prefix, and the number will be read in base 2;
60 otherwise,
61 a zero
62 .I base
63 is taken as 10 (decimal) unless the next character
64 is \[aq]0\[aq], in which case it is taken as 8 (octal).
65 .P
66 The remainder of the string is converted to an
67 .I "unsigned long"
68 value in the obvious manner,
69 stopping at the first character which is not a
70 valid digit in the given base.
71 (In bases above 10, the letter \[aq]A\[aq] in
72 either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so
73 forth, with \[aq]Z\[aq] representing 35.)
74 .P
75 If
76 .I endptr
77 is not NULL,
78 and the
79 .I base
80 is supported,
81 .BR strtoul ()
82 stores the address of the
83 first invalid character in
84 .IR *endptr .
85 If there were no digits at
86 all,
87 .BR strtoul ()
88 stores the original value of
89 .I nptr
90 in
91 .I *endptr
92 (and returns 0).
93 In particular, if
94 .I *nptr
95 is not \[aq]\[rs]0\[aq] but
96 .I **endptr
97 is \[aq]\[rs]0\[aq] on return, the entire string is valid.
98 .P
99 The
100 .BR strtoull ()
101 function works just like the
102 .BR strtoul ()
103 function but returns an
104 .I "unsigned long long"
105 value.
106 .SH RETURN VALUE
107 The
108 .BR strtoul ()
109 function returns either the result of the conversion,
110 or,
111 if there was a leading minus sign,
112 the negation of the result of the conversion
113 represented as an unsigned value,
114 unless the original (nonnegated) value would overflow;
115 in
116 the latter case,
117 .BR strtoul ()
118 returns
119 .B ULONG_MAX
120 and sets
121 .I errno
122 to
123 .BR ERANGE .
124 Precisely the same holds for
125 .BR strtoull ()
126 (with
127 .B ULLONG_MAX
128 instead of
129 .BR ULONG_MAX ).
130 .SH ERRORS
131 This function does not modify
132 .I errno
133 on success.
134 .TP
135 .B EINVAL
136 (not in C99)
137 The given
138 .I base
139 contains an unsupported value.
140 .TP
141 .B ERANGE
142 The resulting value was out of range.
143 .P
144 The implementation may also set
145 .I errno
146 to
147 .B EINVAL
148 in case
149 no conversion was performed (no digits seen, and 0 returned).
150 .SH ATTRIBUTES
151 For an explanation of the terms used in this section, see
152 .BR attributes (7).
153 .TS
154 allbox;
155 lbx lb lb
156 l l l.
157 Interface Attribute Value
158 T{
159 .na
160 .nh
161 .BR strtoul (),
162 .BR strtoull (),
163 .BR strtouq ()
164 T} Thread safety MT-Safe locale
165 .TE
166 .SH VERSIONS
167 In locales other than the "C" locale, other strings may be accepted.
168 (For example, the thousands separator of the current locale may be
169 supported.)
170 .P
171 BSD also has
172 .P
173 .in +4n
174 .EX
175 .BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base );
176 .EE
177 .in
178 .P
179 with completely analogous definition.
180 Depending on the wordsize of the current architecture, this
181 may be equivalent to
182 .BR strtoull ()
183 or to
184 .BR strtoul ().
185 .SH STANDARDS
186 C23, POSIX.1-2024.
187 .SH HISTORY
188 .TP
189 .BR strtoul ()
190 POSIX.1-2001, C89, SVr4.
191 .TP
192 .BR strtoull ()
193 POSIX.1-2001, C99.
194 .TP
195 "0b", "0B"
196 C23.
197 glibc 2.38.
198 (Not in POSIX.)
199 .SH CAVEATS
200 Since
201 .BR strtoul ()
202 can legitimately return 0 or
203 .B ULONG_MAX
204 .RB ( ULLONG_MAX
205 for
206 .BR strtoull ())
207 on both success and failure, the calling program should set
208 .I errno
209 to 0 before the call,
210 and then determine if an error occurred by checking whether
211 .I errno
212 has a nonzero value after the call.
213 .SH BUGS
214 .SS Signed numbers
215 Some negative values
216 are considered valid input and
217 are silently converted to
218 .IR "\%unsigned\ long" .
219 .SS White space
220 These functions silently accept leading whitespace.
221 .SS isalnum(3)
222 To reject white space and/or a sign, call
223 .BR isalnum (3)
224 before
225 .BR strtoul ().
226 .SH EXAMPLES
227 See the example on the
228 .BR strtol (3)
229 manual page;
230 the use of the functions described in this manual page is similar.
231 .SH SEE ALSO
232 .BR a64l (3),
233 .BR atof (3),
234 .BR atoi (3),
235 .BR atol (3),
236 .BR strtod (3),
237 .BR strtol (3),
238 .BR strtoumax (3)