Debian Codegraph @

upstream/debian-trixie/man3/strtoul.3

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