]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" References consulted: | |
24 | .\" Linux libc source code | |
25 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
26 | .\" 386BSD man pages | |
27 | .\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu) | |
28 | .\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 | |
29 | .TH STRTOL 3 2002-05-30 "GNU" "Linux Programmer's Manual" | |
30 | .SH NAME | |
31 | strtol, strtoll, strtoq \- convert a string to a long integer | |
32 | .SH SYNOPSIS | |
33 | .nf | |
34 | .B #include <stdlib.h> | |
35 | .sp | |
36 | .BI "long int" | |
37 | .BI "strtol(const char *" nptr ", char **" endptr ", int " base ); | |
38 | .sp | |
39 | .BI "long long int" | |
40 | .BI "strtoll(const char *" nptr ", char **" endptr ", int " base ); | |
41 | .fi | |
42 | .SH DESCRIPTION | |
63aa9df0 | 43 | The \fBstrtol\fP() function converts the initial part of the string |
fea681da MK |
44 | in \fInptr\fP to a long integer value according to the given \fIbase\fP, |
45 | which must be between 2 and 36 inclusive, or be the special value 0. | |
46 | .PP | |
3f266a43 | 47 | The string may begin with an arbitrary amount of white space (as |
fea681da MK |
48 | determined by |
49 | .BR isspace (3)) | |
c13182ef MK |
50 | followed by a single optional `+' or `\-' sign. |
51 | If \fIbase\fP is zero or 16, the string may then include a | |
52 | `0x' prefix, and the number will be read in base 16; otherwise, a | |
fea681da MK |
53 | zero \fIbase\fP is taken as 10 (decimal) unless the next character |
54 | is `0', in which case it is taken as 8 (octal). | |
55 | .PP | |
c13182ef | 56 | The remainder of the string is converted to a |
fefe023e MK |
57 | .I long int |
58 | value | |
fea681da | 59 | in the obvious manner, stopping at the first character which is not a |
c13182ef MK |
60 | valid digit in the given base. |
61 | (In bases above 10, the letter `A' in | |
fea681da MK |
62 | either upper or lower case represents 10, `B' represents 11, and so |
63 | forth, with `Z' representing 35.) | |
64 | .PP | |
63aa9df0 | 65 | If \fIendptr\fP is not NULL, \fBstrtol\fP() stores the address of the |
c13182ef MK |
66 | first invalid character in \fI*endptr\fP. |
67 | If there were no digits at | |
63aa9df0 | 68 | all, \fBstrtol\fP() stores the original value of \fInptr\fP in |
fea681da MK |
69 | \fI*endptr\fP (and returns 0). |
70 | In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP | |
71 | is `\\0' on return, the entire string is valid. | |
72 | .PP | |
73 | The | |
63aa9df0 | 74 | .BR strtoll () |
fea681da | 75 | function works just like the |
63aa9df0 | 76 | .BR strtol () |
fea681da MK |
77 | function but returns a long long integer value. |
78 | .SH "RETURN VALUE" | |
63aa9df0 | 79 | The \fBstrtol\fP() function returns the result of the conversion, |
c13182ef MK |
80 | unless the value would underflow or overflow. |
81 | If an underflow occurs, | |
82 | \fBstrtol\fP() returns LONG_MIN. | |
83 | If an overflow occurs, \fBstrtol\fP() | |
84 | returns LONG_MAX. | |
85 | In both cases, \fIerrno\fP is set to ERANGE. | |
fea681da | 86 | Precisely the same holds for |
63aa9df0 | 87 | .BR strtoll () |
fea681da MK |
88 | (with LLONG_MIN and LLONG_MAX instead of LONG_MIN and LONG_MAX). |
89 | .SH ERRORS | |
90 | .TP | |
91 | .B EINVAL | |
92 | (not in C99) | |
93 | The given | |
94 | .I base | |
95 | contains an unsupported value. | |
96 | .TP | |
97 | .B ERANGE | |
98 | The resulting value was out of range. | |
99 | .LP | |
100 | The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case | |
101 | no conversion was performed (no digits seen, and 0 returned). | |
102 | .SH NOTES | |
c13182ef | 103 | Since |
fefe023e | 104 | .BR strtol () |
c13182ef | 105 | can legitimately return 0, |
8699b7dd | 106 | LONG_MAX, or LONG_MIN (LLONG_MAX or LLONG_MIN for |
fefe023e MK |
107 | .BR strtoll ()) |
108 | on both success and failure, the calling program should set | |
109 | .I errno | |
c13182ef | 110 | to 0 before the call, |
fefe023e MK |
111 | and then determine if an error occurred by checking whether |
112 | .I errno | |
113 | has a non-zero value after the call. | |
114 | ||
f1158c07 | 115 | In locales other than the "C" locale, other strings may also be accepted. |
fea681da MK |
116 | (For example, the thousands separator of the current locale may be |
117 | supported.) | |
118 | .LP | |
119 | BSD also has | |
120 | .sp | |
121 | .in +4n | |
122 | .nf | |
123 | .BI "quad_t" | |
124 | .BI "strtoq(const char *" nptr ", char **" endptr ", int " base ); | |
125 | .sp | |
126 | .in -4n | |
127 | .fi | |
128 | with completely analogous definition. | |
129 | Depending on the wordsize of the current architecture, this | |
130 | may be equivalent to | |
63aa9df0 | 131 | .BR strtoll () |
fea681da | 132 | or to |
63aa9df0 | 133 | .BR strtol (). |
fea681da | 134 | .SH "CONFORMING TO" |
63aa9df0 | 135 | .BR strtol () |
1eb85d14 | 136 | conforms to SVr4, 4.3BSD, C89, C99 and POSIX.1-2001, and |
63aa9df0 | 137 | .BR strtoll () |
68e1685c | 138 | to C99 and POSIX.1-2001. |
56aee868 MK |
139 | .SH EXAMPLE |
140 | The program shown below demonstrates the use of | |
141 | .BR strtol (). | |
c13182ef | 142 | The first command line argument specifies a string from which |
56aee868 MK |
143 | .BR strtol () |
144 | should parse a number. | |
c13182ef | 145 | The second (optional) argument specifies the base to be used for |
56aee868 | 146 | the conversion. |
0acd0e57 MK |
147 | (This argument is converted to numeric form using |
148 | .BR atoi (3), | |
c13182ef | 149 | a function that performs no error checking and |
0acd0e57 MK |
150 | has a simpler interface than |
151 | .BR strtol ().) | |
56aee868 MK |
152 | Some examples of the results produced by this program are the following: |
153 | .in +0.25i | |
154 | .nf | |
155 | ||
156 | $ ./a.out 123 | |
157 | strtol() returned 123 | |
158 | $ ./a.out ' 123' | |
159 | strtol() returned 123 | |
160 | $ ./a.out 123abc | |
161 | strtol() returned 123 | |
162 | Further characters after number: abc | |
163 | $ ./a.out 123abc 55 | |
164 | strtol: Invalid argument | |
165 | $ ./a.out '' | |
166 | No digits were found | |
167 | $ ./a.out 4000000000 | |
168 | strtol: Numerical result out of range | |
169 | ||
170 | .fi | |
171 | .in -0.25i | |
172 | The source code of the program is as follows: | |
173 | .nf | |
174 | ||
175 | #include <stdlib.h> | |
176 | #include <limits.h> | |
177 | #include <stdio.h> | |
178 | #include <errno.h> | |
179 | ||
180 | int | |
181 | main(int argc, char *argv[]) | |
182 | { | |
183 | int base; | |
184 | char *endptr, *str; | |
185 | long val; | |
186 | ||
187 | if (argc < 2) { | |
188 | fprintf(stderr, "Usage: %s str [base]\\n", argv[0]); | |
189 | exit(EXIT_FAILURE); | |
c13182ef | 190 | } |
56aee868 MK |
191 | |
192 | str = argv[1]; | |
193 | base = (argc > 2) ? atoi(argv[2]) : 10; | |
194 | ||
195 | errno = 0; /* To distinguish success/failure after call */ | |
196 | val = strtol(str, &endptr, base); | |
197 | ||
198 | /* Check for various possible errors */ | |
199 | ||
200 | if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN)) | |
201 | || (errno != 0 && val == 0)) { | |
202 | perror("strtol"); | |
203 | exit(EXIT_FAILURE); | |
c13182ef | 204 | } |
56aee868 MK |
205 | |
206 | if (endptr == str) { | |
207 | fprintf(stderr, "No digits were found\\n"); | |
208 | exit(EXIT_FAILURE); | |
c13182ef | 209 | } |
56aee868 | 210 | |
0acd0e57 | 211 | /* If we got here, strtol() successfully parsed a number */ |
56aee868 MK |
212 | |
213 | printf("strtol() returned %ld\\n", val); | |
214 | ||
215 | if (*endptr != '\\0') /* Not necessarily an error... */ | |
216 | printf("Further characters after number: %s\\n", endptr); | |
217 | ||
218 | exit(EXIT_SUCCESS); | |
219 | } | |
220 | .fi | |
fea681da MK |
221 | .SH "SEE ALSO" |
222 | .BR atof (3), | |
223 | .BR atoi (3), | |
224 | .BR atol (3), | |
225 | .BR strtod (3), | |
226 | .BR strtoul (3) |