xref: /original-bsd/lib/libc/stdlib/strtol.3 (revision e59fb703)
1.\" Copyright (c) 1990, 1991 The Regents of the University of California.
2.\" All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Chris Torek and the American National Standards Committee X3,
6.\" on Information Processing Systems.
7.\"
8.\" %sccs.include.redist.man%
9.\"
10.\"     @(#)strtol.3	5.3 (Berkeley) 06/29/91
11.\"
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
24The
25.Fn strtol
26function
27converts the string in
28.Fa nptr
29to a
30.Em long
31value according to the given
32.Fa base ,
33which must be between 2 and 36 inclusive,
34or be the special value 0.
35.Pp
36The string may begin with an arbitrary amount of white space
37(as determined by
38.Xr isspace 3 )
39followed by a single optional
40.Ql +
41or
42.Ql -
43sign.
44If
45.Fa base
46is zero or 16,
47the string may then include a
48.Ql 0x
49prefix,
50and the number will be read in base 16; otherwise, a zero
51.Fa base
52is taken as 10 (decimal) unless the next character is
53.Ql 0 ,
54in which case it is taken as 8 (octal).
55.Pp
56The remainder of the string is converted to a
57.Em long
58value in the obvious manner,
59stopping at the first character which is not a valid digit
60in the given base.
61(In bases above 10, the letter
62.Ql A
63in either upper or lower case
64represents 10,
65.Ql B
66represents 11, and so forth, with
67.Ql Z
68representing 35.)
69.Pp
70If
71.Fa endptr
72is non nil,
73.Fn strtol
74stores the address of the first invalid character in
75.Fa *endptr .
76If there were no digits at all, however,
77.Fn strtol
78stores the original value of
79.Fa nptr
80in
81.Fa *endptr .
82(Thus, if
83.Fa *nptr
84is not
85.Ql \e0
86but
87.Fa **endptr
88is
89.Ql \e0
90on return, the entire string was valid.)
91.Sh RETURN VALUES
92The
93.Fn strtol
94function
95returns the result of the conversion,
96unless the value would underflow or overflow.
97If an underflow occurs,
98.Fn strtol
99returns
100.Dv LONG_MIN .
101If an overflow occurs,
102.Fn strtol
103returns
104.Dv LONG_MAX .
105In both cases,
106.Va errno
107is set to
108.Er ERANGE .
109.Sh ERRORS
110.Bl -tag -width [ERANGE]
111.It Bq Er ERANGE
112The given string was out of range; the value converted has been clamped.
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
121The
122.Fn strtol
123function
124conforms to
125.St -ansiC .
126.Sh BUGS
127Ignores the current locale.
128