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 | .\" | |
043368e6 | 10 | .\" @(#)strtol.3 5.3 (Berkeley) %G% |
fa98d382 | 11 | .\" |
ae59e04c CL |
12 | .Dd |
13 | .Dt STRTOL 3 | |
14 | .Os | |
15 | .Sh NAME | |
16 | .Nm strtol | |
17 | .Nd convert string value to a long integer | |
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" | |
23 | .Sh DESCRIPTION | |
24 | The | |
25 | .Fn strtol | |
26 | function | |
fa98d382 | 27 | converts the string in |
ae59e04c | 28 | .Fa nptr |
fa98d382 | 29 | to a |
ae59e04c | 30 | .Em long |
fa98d382 | 31 | value according to the given |
ae59e04c | 32 | .Fa base , |
fa98d382 KB |
33 | which must be between 2 and 36 inclusive, |
34 | or be the special value 0. | |
ae59e04c | 35 | .Pp |
fa98d382 KB |
36 | The string may begin with an arbitrary amount of white space |
37 | (as determined by | |
ae59e04c CL |
38 | .Xr isspace 3 ) |
39 | followed by a single optional | |
40 | .Ql + | |
41 | or | |
42 | .Ql - | |
43 | sign. | |
fa98d382 | 44 | If |
ae59e04c | 45 | .Fa base |
fa98d382 | 46 | is zero or 16, |
ae59e04c CL |
47 | the string may then include a |
48 | .Ql 0x | |
49 | prefix, | |
fa98d382 | 50 | and the number will be read in base 16; otherwise, a zero |
ae59e04c CL |
51 | .Fa base |
52 | is taken as 10 (decimal) unless the next character is | |
53 | .Ql 0 , | |
fa98d382 | 54 | in which case it is taken as 8 (octal). |
ae59e04c | 55 | .Pp |
fa98d382 | 56 | The remainder of the string is converted to a |
ae59e04c | 57 | .Em long |
fa98d382 KB |
58 | value in the obvious manner, |
59 | stopping at the first character which is not a valid digit | |
60 | in the given base. | |
ae59e04c CL |
61 | (In bases above 10, the letter |
62 | .Ql A | |
63 | in either upper or lower case | |
64 | represents 10, | |
65 | .Ql B | |
66 | represents 11, and so forth, with | |
67 | .Ql Z | |
68 | representing 35.) | |
69 | .Pp | |
fa98d382 | 70 | If |
ae59e04c | 71 | .Fa endptr |
fa98d382 | 72 | is non nil, |
ae59e04c | 73 | .Fn strtol |
fa98d382 | 74 | stores the address of the first invalid character in |
ae59e04c | 75 | .Fa *endptr . |
fa98d382 | 76 | If there were no digits at all, however, |
ae59e04c | 77 | .Fn strtol |
fa98d382 | 78 | stores the original value of |
ae59e04c | 79 | .Fa nptr |
fa98d382 | 80 | in |
ae59e04c | 81 | .Fa *endptr . |
fa98d382 | 82 | (Thus, if |
ae59e04c CL |
83 | .Fa *nptr |
84 | is not | |
85 | .Ql \e0 | |
86 | but | |
87 | .Fa **endptr | |
88 | is | |
89 | .Ql \e0 | |
90 | on return, the entire string was valid.) | |
91 | .Sh RETURN VALUES | |
92 | The | |
93 | .Fn strtol | |
94 | function | |
fa98d382 KB |
95 | returns the result of the conversion, |
96 | unless the value would underflow or overflow. | |
97 | If an underflow occurs, | |
ae59e04c | 98 | .Fn strtol |
fa98d382 | 99 | returns |
ae59e04c | 100 | .Dv LONG_MIN . |
fa98d382 | 101 | If an overflow occurs, |
ae59e04c | 102 | .Fn strtol |
fa98d382 | 103 | returns |
ae59e04c | 104 | .Dv LONG_MAX . |
fa98d382 | 105 | In both cases, |
ae59e04c | 106 | .Va errno |
fa98d382 | 107 | is set to |
ae59e04c CL |
108 | .Er ERANGE . |
109 | .Sh ERRORS | |
110 | .Bl -tag -width [ERANGE] | |
111 | .It Bq Er ERANGE | |
fa98d382 | 112 | The given string was out of range; the value converted has been clamped. |
ae59e04c CL |
113 | .El |
114 | .Sh SEE ALSO | |
115 | .Xr atof 3 , | |
116 | .Xr atoi 3 , | |
117 | .Xr atol 3 , | |
118 | .Xr strtod 3 , | |
119 | .Xr strtoul 3 | |
120 | .Sh STANDARDS | |
121 | The | |
122 | .Fn strtol | |
123 | function | |
124 | conforms to | |
125 | .St -ansiC . | |
126 | .Sh BUGS | |
fa98d382 | 127 | Ignores the current locale. |