]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
b6a968bc | 2 | .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@ganil.com> |
fea681da | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
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:53:39 1993 by Rik Faith (faith@cs.unc.edu) | |
11 | .\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 | |
7bd6328f | 12 | .TH STRTOL 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual" |
fea681da MK |
13 | .SH NAME |
14 | strtol, strtoll, strtoq \- convert a string to a long integer | |
e6a419ea AC |
15 | .SH LIBRARY |
16 | Standard C library | |
8fc3b2cf | 17 | .RI ( libc ", " \-lc ) |
fea681da MK |
18 | .SH SYNOPSIS |
19 | .nf | |
20 | .B #include <stdlib.h> | |
68e4db0a | 21 | .PP |
891521ca AC |
22 | .BI "long strtol(const char *restrict " nptr , |
23 | .BI " char **restrict " endptr ", int " base ); | |
24 | .BI "long long strtoll(const char *restrict " nptr , | |
25 | .BI " char **restrict " endptr ", int " base ); | |
fea681da | 26 | .fi |
68e4db0a | 27 | .PP |
d39ad78f | 28 | .RS -4 |
cc4615cc MK |
29 | Feature Test Macro Requirements for glibc (see |
30 | .BR feature_test_macros (7)): | |
d39ad78f | 31 | .RE |
68e4db0a | 32 | .PP |
cc4615cc | 33 | .BR strtoll (): |
9d2adbae MK |
34 | .nf |
35 | _ISOC99_SOURCE | |
36 | || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE | |
37 | .fi | |
fea681da | 38 | .SH DESCRIPTION |
60a90ecd MK |
39 | The |
40 | .BR strtol () | |
41 | function converts the initial part of the string | |
46d8df8e MK |
42 | in |
43 | .I nptr | |
44 | to a long integer value according to the given | |
45 | .IR base , | |
fea681da MK |
46 | which must be between 2 and 36 inclusive, or be the special value 0. |
47 | .PP | |
3f266a43 | 48 | The string may begin with an arbitrary amount of white space (as |
fea681da MK |
49 | determined by |
50 | .BR isspace (3)) | |
f81fb444 | 51 | followed by a single optional \(aq+\(aq or \(aq\-\(aq sign. |
46d8df8e MK |
52 | If |
53 | .I base | |
54 | is zero or 16, the string may then include a | |
e5b5658c | 55 | "0x" or "0X" prefix, and the number will be read in base 16; otherwise, a |
46d8df8e MK |
56 | zero |
57 | .I base | |
58 | is taken as 10 (decimal) unless the next character | |
f81fb444 | 59 | is \(aq0\(aq, in which case it is taken as 8 (octal). |
fea681da | 60 | .PP |
c13182ef | 61 | The remainder of the string is converted to a |
ae85f653 | 62 | .I long |
fefe023e | 63 | value |
fea681da | 64 | in the obvious manner, stopping at the first character which is not a |
c13182ef | 65 | valid digit in the given base. |
f81fb444 | 66 | (In bases above 10, the letter \(aqA\(aq in |
efaef3da | 67 | either uppercase or lowercase represents 10, \(aqB\(aq represents 11, and so |
f81fb444 | 68 | forth, with \(aqZ\(aq representing 35.) |
fea681da | 69 | .PP |
46d8df8e MK |
70 | If |
71 | .I endptr | |
72 | is not NULL, | |
60a90ecd MK |
73 | .BR strtol () |
74 | stores the address of the | |
46d8df8e MK |
75 | first invalid character in |
76 | .IR *endptr . | |
c13182ef | 77 | If there were no digits at |
60a90ecd MK |
78 | all, |
79 | .BR strtol () | |
46d8df8e MK |
80 | stores the original value of |
81 | .I nptr | |
82 | in | |
83 | .I *endptr | |
84 | (and returns 0). | |
85 | In particular, if | |
86 | .I *nptr | |
d1a71985 | 87 | is not \(aq\e0\(aq but |
46d8df8e | 88 | .I **endptr |
d1a71985 | 89 | is \(aq\e0\(aq on return, the entire string is valid. |
fea681da MK |
90 | .PP |
91 | The | |
63aa9df0 | 92 | .BR strtoll () |
fea681da | 93 | function works just like the |
63aa9df0 | 94 | .BR strtol () |
f36f4f85 MK |
95 | function but returns a |
96 | .I long long | |
97 | integer value. | |
47297adb | 98 | .SH RETURN VALUE |
60a90ecd MK |
99 | The |
100 | .BR strtol () | |
101 | function returns the result of the conversion, | |
c13182ef MK |
102 | unless the value would underflow or overflow. |
103 | If an underflow occurs, | |
60a90ecd | 104 | .BR strtol () |
097585ed MK |
105 | returns |
106 | .BR LONG_MIN . | |
60a90ecd MK |
107 | If an overflow occurs, |
108 | .BR strtol () | |
097585ed MK |
109 | returns |
110 | .BR LONG_MAX . | |
46d8df8e MK |
111 | In both cases, |
112 | .I errno | |
113 | is set to | |
09b235db | 114 | .BR ERANGE . |
fea681da | 115 | Precisely the same holds for |
63aa9df0 | 116 | .BR strtoll () |
097585ed MK |
117 | (with |
118 | .B LLONG_MIN | |
119 | and | |
120 | .B LLONG_MAX | |
121 | instead of | |
122 | .B LONG_MIN | |
123 | and | |
124 | .BR LONG_MAX ). | |
fea681da MK |
125 | .SH ERRORS |
126 | .TP | |
127 | .B EINVAL | |
128 | (not in C99) | |
129 | The given | |
130 | .I base | |
131 | contains an unsupported value. | |
132 | .TP | |
133 | .B ERANGE | |
134 | The resulting value was out of range. | |
dd3568a1 | 135 | .PP |
46d8df8e | 136 | The implementation may also set |
1ae6b2c7 | 137 | .I errno |
46d8df8e MK |
138 | to |
139 | .B EINVAL | |
140 | in case | |
fea681da | 141 | no conversion was performed (no digits seen, and 0 returned). |
ca74032e | 142 | .SH ATTRIBUTES |
de80a16a PH |
143 | For an explanation of the terms used in this section, see |
144 | .BR attributes (7). | |
c466875e MK |
145 | .ad l |
146 | .nh | |
de80a16a PH |
147 | .TS |
148 | allbox; | |
c466875e | 149 | lbx lb lb |
de80a16a PH |
150 | l l l. |
151 | Interface Attribute Value | |
152 | T{ | |
ca74032e PH |
153 | .BR strtol (), |
154 | .BR strtoll (), | |
ca74032e | 155 | .BR strtoq () |
de80a16a PH |
156 | T} Thread safety MT-Safe locale |
157 | .TE | |
c466875e MK |
158 | .hy |
159 | .ad | |
160 | .sp 1 | |
3113c7f3 | 161 | .SH STANDARDS |
c2fb338e MK |
162 | .BR strtol (): |
163 | POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD. | |
847e0d88 | 164 | .PP |
c2fb338e MK |
165 | .BR strtoll (): |
166 | POSIX.1-2001, POSIX.1-2008, C99. | |
fea681da | 167 | .SH NOTES |
c13182ef | 168 | Since |
fefe023e | 169 | .BR strtol () |
c13182ef | 170 | can legitimately return 0, |
097585ed MK |
171 | .BR LONG_MAX , |
172 | or | |
173 | .B LONG_MIN | |
174 | .RB ( LLONG_MAX | |
175 | or | |
176 | .B LLONG_MIN | |
177 | for | |
fefe023e MK |
178 | .BR strtoll ()) |
179 | on both success and failure, the calling program should set | |
180 | .I errno | |
c13182ef | 181 | to 0 before the call, |
fefe023e MK |
182 | and then determine if an error occurred by checking whether |
183 | .I errno | |
c7094399 | 184 | has a nonzero value after the call. |
847e0d88 | 185 | .PP |
c2fb338e | 186 | According to POSIX.1, |
c93376e8 | 187 | in locales other than "C" and "POSIX", |
6bdb0096 MK |
188 | these functions may accept other, |
189 | implementation-defined numeric strings. | |
dd3568a1 | 190 | .PP |
fea681da | 191 | BSD also has |
51f5698d | 192 | .PP |
fea681da | 193 | .in +4n |
bdd915e2 | 194 | .EX |
a08ea57c | 195 | .BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); |
b8302363 | 196 | .EE |
e646a1ba | 197 | .in |
b9c93deb | 198 | .PP |
fea681da MK |
199 | with completely analogous definition. |
200 | Depending on the wordsize of the current architecture, this | |
201 | may be equivalent to | |
63aa9df0 | 202 | .BR strtoll () |
fea681da | 203 | or to |
63aa9df0 | 204 | .BR strtol (). |
a14af333 | 205 | .SH EXAMPLES |
56aee868 MK |
206 | The program shown below demonstrates the use of |
207 | .BR strtol (). | |
76c44d83 | 208 | The first command-line argument specifies a string from which |
56aee868 MK |
209 | .BR strtol () |
210 | should parse a number. | |
c13182ef | 211 | The second (optional) argument specifies the base to be used for |
56aee868 | 212 | the conversion. |
0acd0e57 MK |
213 | (This argument is converted to numeric form using |
214 | .BR atoi (3), | |
c13182ef | 215 | a function that performs no error checking and |
0acd0e57 MK |
216 | has a simpler interface than |
217 | .BR strtol ().) | |
56aee868 | 218 | Some examples of the results produced by this program are the following: |
e646a1ba | 219 | .PP |
a08ea57c | 220 | .in +4n |
e646a1ba | 221 | .EX |
b43a3b30 | 222 | .RB "$" " ./a.out 123" |
56aee868 | 223 | strtol() returned 123 |
b43a3b30 | 224 | .RB "$" " ./a.out \(aq 123\(aq" |
56aee868 | 225 | strtol() returned 123 |
b43a3b30 | 226 | .RB "$" " ./a.out 123abc" |
56aee868 | 227 | strtol() returned 123 |
d01c3303 | 228 | Further characters after number: "abc" |
b43a3b30 | 229 | .RB "$" " ./a.out 123abc 55" |
56aee868 | 230 | strtol: Invalid argument |
b43a3b30 | 231 | .RB "$" " ./a.out \(aq\(aq" |
56aee868 | 232 | No digits were found |
b43a3b30 | 233 | .RB "$" " ./a.out 4000000000" |
56aee868 | 234 | strtol: Numerical result out of range |
b8302363 | 235 | .EE |
a08ea57c | 236 | .in |
9c330504 | 237 | .SS Program source |
d84d0300 | 238 | \& |
e7d0bb47 | 239 | .EX |
56aee868 MK |
240 | #include <stdlib.h> |
241 | #include <limits.h> | |
242 | #include <stdio.h> | |
243 | #include <errno.h> | |
244 | ||
245 | int | |
246 | main(int argc, char *argv[]) | |
247 | { | |
248 | int base; | |
249 | char *endptr, *str; | |
250 | long val; | |
251 | ||
252 | if (argc < 2) { | |
d1a71985 | 253 | fprintf(stderr, "Usage: %s str [base]\en", argv[0]); |
56aee868 | 254 | exit(EXIT_FAILURE); |
c13182ef | 255 | } |
56aee868 MK |
256 | |
257 | str = argv[1]; | |
b924e6b6 | 258 | base = (argc > 2) ? atoi(argv[2]) : 0; |
56aee868 MK |
259 | |
260 | errno = 0; /* To distinguish success/failure after call */ | |
261 | val = strtol(str, &endptr, base); | |
262 | ||
c6beb8a1 | 263 | /* Check for various possible errors. */ |
56aee868 | 264 | |
93f36989 | 265 | if (errno != 0) { |
56aee868 MK |
266 | perror("strtol"); |
267 | exit(EXIT_FAILURE); | |
c13182ef | 268 | } |
56aee868 MK |
269 | |
270 | if (endptr == str) { | |
d1a71985 | 271 | fprintf(stderr, "No digits were found\en"); |
56aee868 | 272 | exit(EXIT_FAILURE); |
c13182ef | 273 | } |
56aee868 | 274 | |
c6beb8a1 | 275 | /* If we got here, strtol() successfully parsed a number. */ |
56aee868 | 276 | |
d1a71985 | 277 | printf("strtol() returned %ld\en", val); |
56aee868 | 278 | |
d1a71985 | 279 | if (*endptr != \(aq\e0\(aq) /* Not necessarily an error... */ |
d01c3303 | 280 | printf("Further characters after number: \e"%s\e"\en", endptr); |
56aee868 MK |
281 | |
282 | exit(EXIT_SUCCESS); | |
283 | } | |
e7d0bb47 | 284 | .EE |
47297adb | 285 | .SH SEE ALSO |
fea681da MK |
286 | .BR atof (3), |
287 | .BR atoi (3), | |
288 | .BR atol (3), | |
289 | .BR strtod (3), | |
bba4bbbd | 290 | .BR strtoimax (3), |
ab59d225 | 291 | .BR strtoul (3) |