Debian Codegraph @

upstream/debian-unstable/man3/strtol.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright 2006, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH strtol 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 strtol, strtoll, strtoq \- convert a string to a long integer
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdlib.h>
17 .P
18 .BI "long strtol(const char *restrict " nptr ,
19 .BI " char **_Nullable restrict " endptr ", int " base );
20 .BI "long long strtoll(const char *restrict " nptr ,
21 .BI " char **_Nullable restrict " endptr ", int " base );
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR strtoll ():
30 .nf
31 _ISOC99_SOURCE
32 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
33 .fi
34 .SH DESCRIPTION
35 The
36 .BR strtol ()
37 function converts the initial part of the string
38 in
39 .I nptr
40 to a long integer value according to the given
41 .IR base ,
42 which must be between 2 and 36 inclusive, or be the special value 0.
43 .P
44 The string may begin with an arbitrary amount of white space (as
45 determined by
46 .BR isspace (3))
47 followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq] sign.
48 If
49 .I base
50 is zero or 16, the string may then include a
51 "0x" or "0X" prefix, and the number will be read in base 16;
52 if
53 .I base
54 is zero or 2, the string may then include a
55 "0b" or "0B" prefix, and the number will be read in base 2;
56 otherwise,
57 a zero
58 .I base
59 is taken as 10 (decimal) unless the next character
60 is \[aq]0\[aq], in which case it is taken as 8 (octal).
61 .P
62 The remainder of the string is converted to a
63 .I long
64 value
65 in the obvious manner, stopping at the first character which is not a
66 valid digit in the given base.
67 (In bases above 10, the letter \[aq]A\[aq] in
68 either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so
69 forth, with \[aq]Z\[aq] representing 35.)
70 .P
71 If
72 .I endptr
73 is not NULL,
74 and the
75 .I base
76 is supported,
77 .BR strtol ()
78 stores the address of the
79 first invalid character in
80 .IR *endptr .
81 If there were no digits at
82 all,
83 .BR strtol ()
84 stores the original value of
85 .I nptr
86 in
87 .I *endptr
88 (and returns 0).
89 In particular, if
90 .I *nptr
91 is not \[aq]\[rs]0\[aq] but
92 .I **endptr
93 is \[aq]\[rs]0\[aq] on return, the entire string is valid.
94 .P
95 The
96 .BR strtoll ()
97 function works just like the
98 .BR strtol ()
99 function but returns a
100 .I long long
101 integer value.
102 .SH RETURN VALUE
103 The
104 .BR strtol ()
105 function returns the result of the conversion,
106 unless the value would underflow or overflow.
107 If an underflow occurs,
108 .BR strtol ()
109 returns
110 .BR LONG_MIN .
111 If an overflow occurs,
112 .BR strtol ()
113 returns
114 .BR LONG_MAX .
115 In both cases,
116 .I errno
117 is set to
118 .BR ERANGE .
119 Precisely the same holds for
120 .BR strtoll ()
121 (with
122 .B LLONG_MIN
123 and
124 .B LLONG_MAX
125 instead of
126 .B LONG_MIN
127 and
128 .BR LONG_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 strtol (),
161 .BR strtoll (),
162 .BR strtoq ()
163 T} Thread safety MT-Safe locale
164 .TE
165 .SH VERSIONS
166 According to POSIX.1,
167 in locales other than "C" and "POSIX",
168 these functions may accept other,
169 implementation-defined numeric strings.
170 .P
171 BSD also has
172 .P
173 .in +4n
174 .EX
175 .BI "quad_t strtoq(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 strtoll ()
183 or to
184 .BR strtol ().
185 .SH STANDARDS
186 C23, POSIX.1-2024.
187 .SH HISTORY
188 .TP
189 .BR strtol ()
190 POSIX.1-2001, C89, SVr4, 4.3BSD.
191 .TP
192 .BR strtoll ()
193 POSIX.1-2001, C99.
194 .TP
195 "0b", "0B"
196 C23.
197 glibc 2.38.
198 (Not in POSIX.)
199 .SH CAVEATS
200 .SS Range checks
201 Since
202 .BR strtol ()
203 can legitimately return 0,
204 .BR LONG_MAX ,
205 or
206 .B LONG_MIN
207 .RB ( LLONG_MAX
208 or
209 .B LLONG_MIN
210 for
211 .BR strtoll ())
212 on both success and failure, the calling program should set
213 .I errno
214 to 0 before the call,
215 and then determine if an error occurred by checking whether
216 .I errno == ERANGE
217 after the call.
218 .P
219 .in +4n
220 .EX
221 errno = 0;
222 n = strtol(s, &end, base);
223 if (end == s)
224 goto no_number;
225 if ((errno == ERANGE && n == _Minof(long)) || n < min)
226 goto too_low;
227 if ((errno == ERANGE && n == _Maxof(long)) || n > max)
228 goto too_high;
229 .EE
230 .in
231 .SS base
232 If the
233 .I base
234 needs to be tested,
235 it should be tested in a call where the string is known to succeed.
236 Otherwise, it's impossible to portably differentiate the errors.
237 .P
238 .in +4n
239 .EX
240 errno = 0;
241 strtol("0", NULL, base);
242 if (errno == EINVAL)
243 goto unsupported_base;
244 .EE
245 .in
246 .SH BUGS
247 .SS White space
248 These functions silently accept leading white space.
249 To reject white space, call
250 .BR isspace (3)
251 before
252 .BR strtol ().
253 .SH EXAMPLES
254 The program shown below demonstrates the use of
255 .BR strtol ().
256 The first command-line argument specifies a string from which
257 .BR strtol ()
258 should parse a number.
259 The second (optional) argument specifies the base to be used for
260 the conversion.
261 (This argument is converted to numeric form using
262 .BR atoi (3),
263 a function that performs no error checking and
264 has a simpler interface than
265 .BR strtol ().)
266 Some examples of the results produced by this program are the following:
267 .P
268 .in +4n
269 .EX
270 .RB "$" " ./a.out 123"
271 strtol() returned 123
272 .RB "$" " ./a.out \[aq] 123\[aq]"
273 strtol() returned 123
274 .RB "$" " ./a.out 123abc"
275 strtol() returned 123
276 Further characters after number: "abc"
277 .RB "$" " ./a.out 123abc 55"
278 strtol: Invalid argument
279 .RB "$" " ./a.out \[aq]\[aq]"
280 No digits were found
281 .RB "$" " ./a.out 4000000000"
282 strtol: Numerical result out of range
283 .EE
284 .in
285 .SS Program source
286 \&
287 .\" SRC BEGIN (strtol.c)
288 .EX
289 #include <errno.h>
290 #include <stdio.h>
291 #include <stdlib.h>
292 \&
293 int
294 main(int argc, char *argv[])
295 {
296 int base;
297 char *endptr, *str;
298 long val;
299 \&
300 if (argc < 2) {
301 fprintf(stderr, "Usage: %s str [base]\[rs]n", argv[0]);
302 exit(EXIT_FAILURE);
303 }
304 \&
305 str = argv[1];
306 base = (argc > 2) ? atoi(argv[2]) : 0;
307 \&
308 errno = 0; /* To distinguish success/failure after call */
309 strtol("0", NULL, base);
310 if (errno == EINVAL) {
311 perror("strtol");
312 exit(EXIT_FAILURE);
313 }
314 \&
315 errno = 0; /* To distinguish success/failure after call */
316 val = strtol(str, &endptr, base);
317 \&
318 /* Check for various possible errors. */
319 \&
320 if (errno == ERANGE) {
321 perror("strtol");
322 exit(EXIT_FAILURE);
323 }
324 \&
325 if (endptr == str) {
326 fprintf(stderr, "No digits were found\[rs]n");
327 exit(EXIT_FAILURE);
328 }
329 \&
330 /* If we got here, strtol() successfully parsed a number. */
331 \&
332 printf("strtol() returned %ld\[rs]n", val);
333 \&
334 if (*endptr != \[aq]\[rs]0\[aq]) /* Not necessarily an error. */
335 printf("Further characters after number: \[rs]"%s\[rs]"\[rs]n", endptr);
336 \&
337 exit(EXIT_SUCCESS);
338 }
339 .EE
340 .\" SRC END
341 .SH SEE ALSO
342 .BR atof (3),
343 .BR atoi (3),
344 .BR atol (3),
345 .BR strtod (3),
346 .BR strtoimax (3),
347 .BR strtoul (3)