2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\" References consulted:
7 .\" Linux libc source code
8 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
10 .\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu)
11 .\" Fixed typo, aeb, 950823
12 .\" 2002-02-22, joey, mihtjel: Added strtoull()
14 .TH strtoul 3 (date) "Linux man-pages (unreleased)"
16 strtoul, strtoull, strtouq \- convert a string to an unsigned long integer
19 .RI ( libc ", " \-lc )
22 .B #include <stdlib.h>
24 .BI "unsigned long strtoul(const char *restrict " nptr ,
25 .BI " char **restrict " endptr ", int " base );
26 .BI "unsigned long long strtoull(const char *restrict " nptr ,
27 .BI " char **restrict " endptr ", int " base );
31 Feature Test Macro Requirements for glibc (see
32 .BR feature_test_macros (7)):
38 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
43 function converts the initial part of the string
48 value according to the
51 which must be between 2 and 36 inclusive, or be
54 The string may begin with an arbitrary amount of white space (as
57 followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq]
61 is zero or 16, the string may then include a
62 "0x" prefix, and the number will be read in base 16; otherwise, a
65 is taken as 10 (decimal) unless the next character
66 is \[aq]0\[aq], in which case it is taken as 8 (octal).
68 The remainder of the string is converted to an
70 value in the obvious manner,
71 stopping at the first character which is not a
72 valid digit in the given base.
73 (In bases above 10, the letter \[aq]A\[aq] in
74 either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so
75 forth, with \[aq]Z\[aq] representing 35.)
81 stores the address of the
82 first invalid character in
84 If there were no digits at
87 stores the original value of
94 is not \[aq]\e0\[aq] but
96 is \[aq]\e0\[aq] on return, the entire string is valid.
100 function works just like the
102 function but returns an
103 .I "unsigned long long"
108 function returns either the result of the conversion
109 or, if there was a leading minus sign, the negation of the result of the
110 conversion represented as an unsigned value,
111 unless the original (nonnegated) value would overflow; in
120 Precisely the same holds for
132 contains an unsupported value.
135 The resulting value was out of range.
137 The implementation may also set
142 no conversion was performed (no digits seen, and 0 returned).
144 For an explanation of the terms used in this section, see
150 Interface Attribute Value
157 T} Thread safety MT-Safe locale
164 POSIX.1-2001, C89, SVr4.
171 can legitimately return 0 or
176 on both success and failure, the calling program should set
178 to 0 before the call,
179 and then determine if an error occurred by checking whether
181 has a nonzero value after the call.
183 In locales other than the "C" locale, other strings may be accepted.
184 (For example, the thousands separator of the current locale may be
191 .BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base );
195 with completely analogous definition.
196 Depending on the wordsize of the current architecture, this
202 Negative values are considered valid input and are
203 silently converted to the equivalent
207 See the example on the
210 the use of the functions described in this manual page is similar.