Debian Codegraph @

upstream/debian-trixie/man3/strtol.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\" and Copyright 2006 Michael Kerrisk <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" References consulted:
8 .\" Linux libc source code
9 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
10 .\" 386BSD man pages
11 .\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith ([email protected])
12 .\" Added correction due to [email protected] (Nick Duffek) - aeb, 950610
13 .TH strtol 3 2024-06-16 "Linux man-pages 6.9.1"
14 .SH NAME
15 strtol, strtoll, strtoq \- convert a string to a long integer
16 .SH LIBRARY
17 Standard C library
18 .RI ( libc ", " \-lc )
19 .SH SYNOPSIS
20 .nf
21 .B #include <stdlib.h>
22 .P
23 .BI "long strtol(const char *restrict " nptr ,
24 .BI " char **_Nullable restrict " endptr ", int " base );
25 .BI "long long strtoll(const char *restrict " nptr ,
26 .BI " char **_Nullable restrict " endptr ", int " base );
27 .fi
28 .P
29 .RS -4
30 Feature Test Macro Requirements for glibc (see
31 .BR feature_test_macros (7)):
32 .RE
33 .P
34 .BR strtoll ():
35 .nf
36 _ISOC99_SOURCE
37 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
38 .fi
39 .SH DESCRIPTION
40 The
41 .BR strtol ()
42 function converts the initial part of the string
43 in
44 .I nptr
45 to a long integer value according to the given
46 .IR base ,
47 which must be between 2 and 36 inclusive, or be the special value 0.
48 .P
49 The string may begin with an arbitrary amount of white space (as
50 determined by
51 .BR isspace (3))
52 followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq] sign.
53 If
54 .I base
55 is zero or 16, the string may then include a
56 "0x" or "0X" prefix, and the number will be read in base 16; otherwise, a
57 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 C11, POSIX.1-2008.
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 .SH CAVEATS
195 Since
196 .BR strtol ()
197 can legitimately return 0,
198 .BR LONG_MAX ,
199 or
200 .B LONG_MIN
201 .RB ( LLONG_MAX
202 or
203 .B LLONG_MIN
204 for
205 .BR strtoll ())
206 on both success and failure, the calling program should set
207 .I errno
208 to 0 before the call,
209 and then determine if an error occurred by checking whether
210 .I errno == ERANGE
211 after the call.
212 .P
213 If the
214 .I base
215 needs to be tested,
216 it should be tested in a call where the string is known to succeed.
217 Otherwise, it's impossible to portably differentiate the errors.
218 .P
219 .in +4n
220 .EX
221 errno = 0;
222 strtol("0", NULL, base);
223 if (errno == EINVAL)
224 goto unsupported_base;
225 .EE
226 .in
227 .SH EXAMPLES
228 The program shown below demonstrates the use of
229 .BR strtol ().
230 The first command-line argument specifies a string from which
231 .BR strtol ()
232 should parse a number.
233 The second (optional) argument specifies the base to be used for
234 the conversion.
235 (This argument is converted to numeric form using
236 .BR atoi (3),
237 a function that performs no error checking and
238 has a simpler interface than
239 .BR strtol ().)
240 Some examples of the results produced by this program are the following:
241 .P
242 .in +4n
243 .EX
244 .RB "$" " ./a.out 123"
245 strtol() returned 123
246 .RB "$" " ./a.out \[aq] 123\[aq]"
247 strtol() returned 123
248 .RB "$" " ./a.out 123abc"
249 strtol() returned 123
250 Further characters after number: "abc"
251 .RB "$" " ./a.out 123abc 55"
252 strtol: Invalid argument
253 .RB "$" " ./a.out \[aq]\[aq]"
254 No digits were found
255 .RB "$" " ./a.out 4000000000"
256 strtol: Numerical result out of range
257 .EE
258 .in
259 .SS Program source
260 \&
261 .\" SRC BEGIN (strtol.c)
262 .EX
263 #include <errno.h>
264 #include <stdio.h>
265 #include <stdlib.h>
266 \&
267 int
268 main(int argc, char *argv[])
269 {
270 int base;
271 char *endptr, *str;
272 long val;
273 \&
274 if (argc < 2) {
275 fprintf(stderr, "Usage: %s str [base]\[rs]n", argv[0]);
276 exit(EXIT_FAILURE);
277 }
278 \&
279 str = argv[1];
280 base = (argc > 2) ? atoi(argv[2]) : 0;
281 \&
282 errno = 0; /* To distinguish success/failure after call */
283 strtol("0", NULL, base);
284 if (errno == EINVAL) {
285 perror("strtol");
286 exit(EXIT_FAILURE);
287 }
288 \&
289 errno = 0; /* To distinguish success/failure after call */
290 val = strtol(str, &endptr, base);
291 \&
292 /* Check for various possible errors. */
293 \&
294 if (errno == ERANGE) {
295 perror("strtol");
296 exit(EXIT_FAILURE);
297 }
298 \&
299 if (endptr == str) {
300 fprintf(stderr, "No digits were found\[rs]n");
301 exit(EXIT_FAILURE);
302 }
303 \&
304 /* If we got here, strtol() successfully parsed a number. */
305 \&
306 printf("strtol() returned %ld\[rs]n", val);
307 \&
308 if (*endptr != \[aq]\[rs]0\[aq]) /* Not necessarily an error... */
309 printf("Further characters after number: \[rs]"%s\[rs]"\[rs]n", endptr);
310 \&
311 exit(EXIT_SUCCESS);
312 }
313 .EE
314 .\" SRC END
315 .SH SEE ALSO
316 .BR atof (3),
317 .BR atoi (3),
318 .BR atol (3),
319 .BR strtod (3),
320 .BR strtoimax (3),
321 .BR strtoul (3)