1STRTOL(3)                  Linux Programmer's Manual                 STRTOL(3)
2
3
4

NAME

6       strtol, strtoll, strtoq - convert a string to a long integer
7

SYNOPSIS

9       #include <stdlib.h>
10
11       long strtol(const char *restrict nptr,
12                   char **restrict endptr, int base);
13       long long strtoll(const char *restrict nptr,
14                   char **restrict endptr, int base);
15
16   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
17
18       strtoll():
19           _ISOC99_SOURCE
20               || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
21

DESCRIPTION

23       The  strtol()  function converts the initial part of the string in nptr
24       to a long integer value according to the given base, which must be  be‐
25       tween 2 and 36 inclusive, or be the special value 0.
26
27       The string may begin with an arbitrary amount of white space (as deter‐
28       mined by isspace(3)) followed by a single optional '+' or '-' sign.  If
29       base  is zero or 16, the string may then include a "0x" or "0X" prefix,
30       and the number will be read in base 16; otherwise, a zero base is taken
31       as  10  (decimal) unless the next character is '0', in which case it is
32       taken as 8 (octal).
33
34       The remainder of the string is converted to a long value in the obvious
35       manner,  stopping  at the first character which is not a valid digit in
36       the given base.  (In bases above 10, the letter 'A' in either uppercase
37       or  lowercase  represents 10, 'B' represents 11, and so forth, with 'Z'
38       representing 35.)
39
40       If endptr is not NULL, strtol() stores the address of the first invalid
41       character  in *endptr.  If there were no digits at all, strtol() stores
42       the original value of nptr in *endptr (and returns 0).  In  particular,
43       if  *nptr is not '\0' but **endptr is '\0' on return, the entire string
44       is valid.
45
46       The strtoll() function works just like the strtol()  function  but  re‐
47       turns a long long integer value.
48

RETURN VALUE

50       The  strtol() function returns the result of the conversion, unless the
51       value would underflow or overflow.  If an  underflow  occurs,  strtol()
52       returns  LONG_MIN.   If  an overflow occurs, strtol() returns LONG_MAX.
53       In both cases, errno is set to ERANGE.  Precisely the  same  holds  for
54       strtoll()  (with  LLONG_MIN  and  LLONG_MAX  instead  of  LONG_MIN  and
55       LONG_MAX).
56

ERRORS

58       EINVAL (not in C99) The given base contains an unsupported value.
59
60       ERANGE The resulting value was out of range.
61
62       The implementation may also set errno to EINVAL in case  no  conversion
63       was performed (no digits seen, and 0 returned).
64

ATTRIBUTES

66       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
67       tributes(7).
68
69       ┌─────────────────────────────────────┬───────────────┬────────────────┐
70Interface                            Attribute     Value          
71       ├─────────────────────────────────────┼───────────────┼────────────────┤
72strtol(), strtoll(), strtoq()        │ Thread safety │ MT-Safe locale │
73       └─────────────────────────────────────┴───────────────┴────────────────┘
74

CONFORMING TO

76       strtol(): POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD.
77
78       strtoll(): POSIX.1-2001, POSIX.1-2008, C99.
79

NOTES

81       Since  strtol()  can  legitimately  return  0,  LONG_MAX,  or  LONG_MIN
82       (LLONG_MAX or LLONG_MIN for strtoll()) on both success and failure, the
83       calling program should set errno to 0 before the call, and then  deter‐
84       mine if an error occurred by checking whether errno has a nonzero value
85       after the call.
86
87       According to POSIX.1, in locales other  than  "C"  and  "POSIX",  these
88       functions may accept other, implementation-defined numeric strings.
89
90       BSD also has
91
92           quad_t strtoq(const char *nptr, char **endptr, int base);
93
94       with completely analogous definition.  Depending on the wordsize of the
95       current architecture, this may be equivalent to strtoll()  or  to  str‐
96       tol().
97

EXAMPLES

99       The  program  shown  below demonstrates the use of strtol().  The first
100       command-line argument specifies a string  from  which  strtol()  should
101       parse  a  number.  The second (optional) argument specifies the base to
102       be used for the conversion.  (This argument  is  converted  to  numeric
103       form  using atoi(3), a function that performs no error checking and has
104       a simpler interface than strtol().)  Some examples of the results  pro‐
105       duced by this program are the following:
106
107           $ ./a.out 123
108           strtol() returned 123
109           $ ./a.out '    123'
110           strtol() returned 123
111           $ ./a.out 123abc
112           strtol() returned 123
113           Further characters after number: "abc"
114           $ ./a.out 123abc 55
115           strtol: Invalid argument
116           $ ./a.out ''
117           No digits were found
118           $ ./a.out 4000000000
119           strtol: Numerical result out of range
120
121   Program source
122
123       #include <stdlib.h>
124       #include <limits.h>
125       #include <stdio.h>
126       #include <errno.h>
127
128       int
129       main(int argc, char *argv[])
130       {
131           int base;
132           char *endptr, *str;
133           long val;
134
135           if (argc < 2) {
136               fprintf(stderr, "Usage: %s str [base]\n", argv[0]);
137               exit(EXIT_FAILURE);
138           }
139
140           str = argv[1];
141           base = (argc > 2) ? atoi(argv[2]) : 0;
142
143           errno = 0;    /* To distinguish success/failure after call */
144           val = strtol(str, &endptr, base);
145
146           /* Check for various possible errors. */
147
148           if (errno != 0) {
149               perror("strtol");
150               exit(EXIT_FAILURE);
151           }
152
153           if (endptr == str) {
154               fprintf(stderr, "No digits were found\n");
155               exit(EXIT_FAILURE);
156           }
157
158           /* If we got here, strtol() successfully parsed a number. */
159
160           printf("strtol() returned %ld\n", val);
161
162           if (*endptr != '\0')        /* Not necessarily an error... */
163               printf("Further characters after number: \"%s\"\n", endptr);
164
165           exit(EXIT_SUCCESS);
166       }
167

SEE ALSO

169       atof(3), atoi(3), atol(3), strtod(3), strtoimax(3), strtoul(3),
170

COLOPHON

172       This  page  is  part of release 5.12 of the Linux man-pages project.  A
173       description of the project, information about reporting bugs,  and  the
174       latest     version     of     this    page,    can    be    found    at
175       https://www.kernel.org/doc/man-pages/.
176
177
178
179GNU                               2021-03-22                         STRTOL(3)
Impressum