Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
fa98d382 KB |
2 | .\" All rights reserved. |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
043368e6 KB |
5 | .\" Chris Torek and the American National Standards Committee X3, |
6 | .\" on Information Processing Systems. | |
7 | .\" | |
fa98d382 KB |
8 | .\" %sccs.include.redist.man% |
9 | .\" | |
1778ab6f | 10 | .\" @(#)strtol.3 5.4 (Berkeley) %G% |
fa98d382 | 11 | .\" |
ae59e04c CL |
12 | .Dd |
13 | .Dt STRTOL 3 | |
14 | .Os | |
15 | .Sh NAME | |
1778ab6f KB |
16 | .Nm strtol, strtoq |
17 | .Nd convert string value to a long or quad_t integer | |
ae59e04c CL |
18 | .Sh SYNOPSIS |
19 | .Fd #include <stdlib.h> | |
20 | .Fd #include <limits.h> | |
21 | .Ft long | |
22 | .Fn strtol "char *nptr" "char **endptr" "int base" | |
1778ab6f KB |
23 | |
24 | .Fd #include <sys/types.h> | |
25 | .Fd #include <stdlib.h> | |
26 | .Fd #include <limits.h> | |
27 | .Ft quad_t | |
28 | .Fn strtoq "char *nptr" "char **endptr" "int base" | |
ae59e04c CL |
29 | .Sh DESCRIPTION |
30 | The | |
31 | .Fn strtol | |
32 | function | |
fa98d382 | 33 | converts the string in |
ae59e04c | 34 | .Fa nptr |
fa98d382 | 35 | to a |
ae59e04c | 36 | .Em long |
1778ab6f KB |
37 | value. |
38 | The | |
39 | .Fn strtoq | |
40 | function | |
41 | converts the string in | |
42 | .Fa nptr | |
43 | to a | |
44 | .Em quad_t | |
45 | value. | |
46 | The conversion is done according to the given | |
ae59e04c | 47 | .Fa base , |
fa98d382 KB |
48 | which must be between 2 and 36 inclusive, |
49 | or be the special value 0. | |
ae59e04c | 50 | .Pp |
fa98d382 KB |
51 | The string may begin with an arbitrary amount of white space |
52 | (as determined by | |
ae59e04c CL |
53 | .Xr isspace 3 ) |
54 | followed by a single optional | |
55 | .Ql + | |
56 | or | |
57 | .Ql - | |
58 | sign. | |
fa98d382 | 59 | If |
ae59e04c | 60 | .Fa base |
fa98d382 | 61 | is zero or 16, |
ae59e04c CL |
62 | the string may then include a |
63 | .Ql 0x | |
64 | prefix, | |
fa98d382 | 65 | and the number will be read in base 16; otherwise, a zero |
ae59e04c CL |
66 | .Fa base |
67 | is taken as 10 (decimal) unless the next character is | |
68 | .Ql 0 , | |
fa98d382 | 69 | in which case it is taken as 8 (octal). |
ae59e04c | 70 | .Pp |
fa98d382 | 71 | The remainder of the string is converted to a |
ae59e04c | 72 | .Em long |
fa98d382 KB |
73 | value in the obvious manner, |
74 | stopping at the first character which is not a valid digit | |
75 | in the given base. | |
ae59e04c CL |
76 | (In bases above 10, the letter |
77 | .Ql A | |
78 | in either upper or lower case | |
79 | represents 10, | |
80 | .Ql B | |
81 | represents 11, and so forth, with | |
82 | .Ql Z | |
83 | representing 35.) | |
84 | .Pp | |
fa98d382 | 85 | If |
ae59e04c | 86 | .Fa endptr |
fa98d382 | 87 | is non nil, |
ae59e04c | 88 | .Fn strtol |
fa98d382 | 89 | stores the address of the first invalid character in |
ae59e04c | 90 | .Fa *endptr . |
fa98d382 | 91 | If there were no digits at all, however, |
ae59e04c | 92 | .Fn strtol |
fa98d382 | 93 | stores the original value of |
ae59e04c | 94 | .Fa nptr |
fa98d382 | 95 | in |
ae59e04c | 96 | .Fa *endptr . |
fa98d382 | 97 | (Thus, if |
ae59e04c CL |
98 | .Fa *nptr |
99 | is not | |
100 | .Ql \e0 | |
101 | but | |
102 | .Fa **endptr | |
103 | is | |
104 | .Ql \e0 | |
105 | on return, the entire string was valid.) | |
106 | .Sh RETURN VALUES | |
107 | The | |
108 | .Fn strtol | |
109 | function | |
fa98d382 KB |
110 | returns the result of the conversion, |
111 | unless the value would underflow or overflow. | |
112 | If an underflow occurs, | |
ae59e04c | 113 | .Fn strtol |
fa98d382 | 114 | returns |
ae59e04c | 115 | .Dv LONG_MIN . |
fa98d382 | 116 | If an overflow occurs, |
ae59e04c | 117 | .Fn strtol |
fa98d382 | 118 | returns |
ae59e04c | 119 | .Dv LONG_MAX . |
fa98d382 | 120 | In both cases, |
ae59e04c | 121 | .Va errno |
fa98d382 | 122 | is set to |
ae59e04c CL |
123 | .Er ERANGE . |
124 | .Sh ERRORS | |
125 | .Bl -tag -width [ERANGE] | |
126 | .It Bq Er ERANGE | |
fa98d382 | 127 | The given string was out of range; the value converted has been clamped. |
ae59e04c CL |
128 | .El |
129 | .Sh SEE ALSO | |
130 | .Xr atof 3 , | |
131 | .Xr atoi 3 , | |
132 | .Xr atol 3 , | |
133 | .Xr strtod 3 , | |
134 | .Xr strtoul 3 | |
135 | .Sh STANDARDS | |
136 | The | |
137 | .Fn strtol | |
138 | function | |
139 | conforms to | |
140 | .St -ansiC . | |
141 | .Sh BUGS | |
fa98d382 | 142 | Ignores the current locale. |