1strtol(3C)               Standard C Library Functions               strtol(3C)
2
3
4

NAME

6       strtol,  strtoll, atol, atoll, atoi, lltostr, ulltostr - string conver‐
7       sion routines
8

SYNOPSIS

10       #include <stdlib.h>
11
12       long strtol(const char *restrict str, char **restrict endptr, int base);
13
14
15       long long strtoll(const char *restrict str, char **restrict endptr,
16            int base);
17
18
19       long atol(const char *str);
20
21
22       long long atoll(const char *str);
23
24
25       int atoi(const char *str);
26
27
28       char *lltostr(long long value, char *endptr);
29
30
31       char *ulltostr(unsigned long long value, char *endptr);
32
33

DESCRIPTION

35   strtol() and strtoll()
36       The strtol() function  converts  the  initial  portion  of  the  string
37       pointed to by str to a type long int representation.
38
39
40       The  strtoll()  function  converts  the  initial  portion of the string
41       pointed to by str to a type long long representation.
42
43
44       Both functions first decompose the input string into  three  parts:  an
45       initial,  possibly empty, sequence of white-space characters (as speci‐
46       fied by isspace(3C)); a subject sequence interpreted as an integer rep‐
47       resented  in  some  radix  determined by the value of base; and a final
48       string of one or more unrecognized characters, including the  terminat‐
49       ing  null  byte  of  the input string. They then attempt to convert the
50       subject sequence to an integer and return the result.
51
52
53       If the value of base is 0, the expected form of the subject sequence is
54       that of a decimal constant, octal constant or hexadecimal constant, any
55       of which may be preceded by a + or − sign. A  decimal  constant  begins
56       with a non-zero digit, and consists of a sequence of decimal digits. An
57       octal constant consists of  the  prefix  0  optionally  followed  by  a
58       sequence  of the digits 0 to 7 only. A hexadecimal constant consists of
59       the prefix 0x or 0X followed by a sequence of the  decimal  digits  and
60       letters a (or A) to f (or F) with values 10 to 15 respectively.
61
62
63       If the value of base is between 2 and 36, the expected form of the sub‐
64       ject sequence is a sequence of letters and digits representing an inte‐
65       ger  with  the radix specified by base, optionally preceded by a + or −
66       sign. The letters from a (or A) to z (or Z) inclusive are ascribed  the
67       values  10 to 35; only letters whose ascribed values are less than that
68       of base are permitted. If the value of base is 16, the characters 0x or
69       0X may optionally precede the sequence of letters and digits, following
70       the sign if present.
71
72
73       The subject sequence is defined as the longest initial  subsequence  of
74       the  input  string,  starting with the first non-white-space character,
75       that is of the expected form. The subject sequence contains no  charac‐
76       ters  if  the input string is empty or consists entirely of white-space
77       characters, or if the first non-white-space character is other  than  a
78       sign or a permissible letter or digit.
79
80
81       If  the subject sequence has the expected form and the value of base is
82       0, the sequence of characters starting with the first digit  is  inter‐
83       preted as an integer constant. If the subject sequence has the expected
84       form and the value of base is between 2 and 36, it is used as the  base
85       for  conversion,  ascribing to each letter its value as given above. If
86       the subject sequence begins with a minus sign, the value resulting from
87       the  conversion  is negated. A pointer to the final string is stored in
88       the object pointed to by endptr, provided that endptr  is  not  a  null
89       pointer.
90
91
92       In  other  than  the  POSIX locale, additional implementation-dependent
93       subject sequence forms may be accepted.
94
95
96       If the subject sequence is empty or does not have the expected form, no
97       conversion  is  performed;  the  value  of  str is stored in the object
98       pointed to by endptr, provided that endptr is not a null pointer.
99
100   atol(), atoll() and atoi()
101       Except for behavior on error,  atol()  is  equivalent  to:  strtol(str,
102       (char **)NULL, 10).
103
104
105       Except  for  behavior  on error, atoll() is equivalent to: strtoll(str,
106       (char **)NULL, 10).
107
108
109       Except for behavior on error,  atoi()  is  equivalent  to:  (int)  str‐
110       tol(str, (char **)NULL, 10).
111
112
113       If the value cannot be represented, the behavior is undefined.
114
115   lltostr() and ulltostr()
116       The  lltostr()  function returns a pointer to the string represented by
117       the long long value. The endptr argument is assumed  to  point  to  the
118       byte  following a storage area into which the decimal representation of
119       value is to be placed as a string.   The  lltostr()  function  converts
120       value to decimal and produces the string,  and returns a pointer to the
121       beginning of the string. No leading zeros are produced, and  no  termi‐
122       nating null is produced. The low-order digit of the result always occu‐
123       pies memory position  endptr−1. The behavior of lltostr() is  undefined
124       if  value is negative.  A single zero digit is produced if  value is 0.
125
126
127       The ulltostr() function is similar to lltostr() except that value is an
128       unsigned long long.
129

RETURN VALUES

131       Upon successful completion, strtol(), strtoll(), atol(),  atoll(),  and
132       atoi()  return  the  converted value, if any. If no conversion could be
133       performed, strtol() and strtoll() return 0 and errno may be set to EIN‐
134       VAL.
135
136
137       If the correct value is outside the range of representable values, str‐
138       tol() returns LONG_MAX or LONG_MIN and strtoll() returns  LLONG_MAX  or
139       LLONG_MIN  (according  to  the  sign of the value), and errno is set to
140       ERANGE.
141
142
143       Upon successful completion, lltostr() and ulltostr() return  a  pointer
144       to the converted string.
145

ERRORS

147       The strtol() and strtoll() functions will fail if:
148
149       ERANGE    The  value  to be returned is not representable. The strtol()
150                 and strtoll() functions may fail if:
151
152
153       EINVAL    The value of base is not supported.
154
155

USAGE

157       Because 0, LONG_MIN, LONG_MAX, LLONG_MIN, and LLONG_MAX are returned on
158       error  and are also valid returns on success, an application wishing to
159       check for error situations should set errno to 0,  call  the  function,
160       then check errno and if it is non-zero, assume an error has occurred.
161
162
163       The strtol() function no longer accepts values greater than LONG_MAX or
164       LLONG_MAX as valid input. Use strtoul(3C) instead.
165
166
167       Calls to atoi() and atol() might be faster than corresponding calls  to
168       strtol(), and calls to atoll() might be faster than corresponding calls
169       to strtoll(). However, applications should not use the atoi(),  atol(),
170       or  atoll()  functions  unless  they  know the value represented by the
171       argument will be in range for the corresponding result type.
172

ATTRIBUTES

174       See attributes(5) for descriptions of the following attributes:
175
176
177
178
179       ┌─────────────────────────────┬─────────────────────────────┐
180       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
181       ├─────────────────────────────┼─────────────────────────────┤
182       │Interface Stability          │See below.                   │
183       ├─────────────────────────────┼─────────────────────────────┤
184       │MT-Level                     │MT-Safe                      │
185       └─────────────────────────────┴─────────────────────────────┘
186
187
188       The strtol(), strtoll(), atol(),  atoll(),  and  atoi()  functions  are
189       Standard.
190

SEE ALSO

192       isalpha(3C),    isspace(3C),    scanf(3C),   strtod(3C),   strtoul(3C),
193       attributes(5), standards(5)
194
195
196
197SunOS 5.11                        6 May 2003                        strtol(3C)
Impressum