1.\" Copyright (c) 1990, 1991, 1993 2.\" The Regents of the University of California. 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.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the University of 19.\" California, Berkeley and its contributors. 20.\" 4. Neither the name of the University nor the names of its contributors 21.\" may be used to endorse or promote products derived from this software 22.\" without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" @(#)strtol.3 8.1 (Berkeley) 6/4/93 37.\" $FreeBSD$ 38.\" 39.Dd June 4, 1993 40.Dt STRTOL 3 41.Os 42.Sh NAME 43.Nm strtol , strtoll , strtoimax , strtoq 44.Nd "convert a string value to a long, long long, intmax_t or quad_t integer" 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In stdlib.h 49.In limits.h 50.Ft long 51.Fn strtol "const char *nptr" "char **endptr" "int base" 52.Ft long long 53.Fn strtoll "const char *nptr" "char **endptr" "int base" 54.In inttypes.h 55.Ft intmax_t 56.Fn strtoimax "const char *nptr" "char **endptr" "int base" 57.In sys/types.h 58.In stdlib.h 59.In limits.h 60.Ft quad_t 61.Fn strtoq "const char *nptr" "char **endptr" "int base" 62.Sh DESCRIPTION 63The 64.Fn strtol 65function 66converts the string in 67.Fa nptr 68to a 69.Em long 70value. 71The 72.Fn strtoll 73function 74converts the string in 75.Fa nptr 76to a 77.Em long long 78value. 79The 80.Fn strtoimax 81function 82converts the string in 83.Fa nptr 84to an 85.Em intmax_t 86value. 87The 88.Fn strtoq 89function 90converts the string in 91.Fa nptr 92to a 93.Em quad_t 94value. 95The conversion is done according to the given 96.Fa base , 97which must be between 2 and 36 inclusive, 98or be the special value 0. 99.Pp 100The string may begin with an arbitrary amount of white space 101(as determined by 102.Xr isspace 3 ) 103followed by a single optional 104.Ql + 105or 106.Ql - 107sign. 108If 109.Fa base 110is zero or 16, 111the string may then include a 112.Ql 0x 113prefix, 114and the number will be read in base 16; otherwise, a zero 115.Fa base 116is taken as 10 (decimal) unless the next character is 117.Ql 0 , 118in which case it is taken as 8 (octal). 119.Pp 120The remainder of the string is converted to a 121.Em long , 122.Em long long , 123.Em intmax_t 124or 125.Em quad_t 126value in the obvious manner, 127stopping at the first character which is not a valid digit 128in the given base. 129(In bases above 10, the letter 130.Ql A 131in either upper or lower case 132represents 10, 133.Ql B 134represents 11, and so forth, with 135.Ql Z 136representing 35.) 137.Pp 138If 139.Fa endptr 140is non nil, 141.Fn strtol 142stores the address of the first invalid character in 143.Fa *endptr . 144If there were no digits at all, however, 145.Fn strtol 146stores the original value of 147.Fa nptr 148in 149.Fa *endptr . 150(Thus, if 151.Fa *nptr 152is not 153.Ql \e0 154but 155.Fa **endptr 156is 157.Ql \e0 158on return, the entire string was valid.) 159.Sh RETURN VALUES 160The 161.Fn strtol , 162.Fn strtoll , 163.Fn strtoimax 164or 165.Fn strtoq 166function 167returns the result of the conversion, 168unless the value would underflow or overflow. 169If no conversion could be performed, 0 is returned and 170the global variable 171.Va errno 172is set to 173.Er EINVAL . 174If an overflow or underflow occurs, 175.Va errno 176is set to 177.Er ERANGE 178and the function return value is clamped according 179to the following table. 180.Bl -column -offset indent ".Fn strtoimax" ".Sy overflow" ".Sy underflow" 181.It Sy Function Ta Sy overflow Ta Sy underflow 182.It Fn strtol Ta Dv LONG_MIN Ta Dv LONG_MAX 183.It Fn strtoll Ta Dv LLONG_MIN Ta Dv LLONG_MAX 184.It Fn strtoimax Ta Dv INTMAX_MIN Ta Dv INTMAX_MAX 185.It Fn strtoq Ta Dv LLONG_MIN Ta Dv LLONG_MAX 186.El 187.Sh ERRORS 188.Bl -tag -width Er 189.It Bq Er EINVAL 190The value of 191.Fa base 192is not supported or 193no conversion could be performed. 194.It Bq Er ERANGE 195The given string was out of range; the value converted has been clamped. 196.El 197.Sh SEE ALSO 198.Xr atof 3 , 199.Xr atoi 3 , 200.Xr atol 3 , 201.Xr strtod 3 , 202.Xr strtoul 3 203.Sh STANDARDS 204The 205.Fn strtol 206function 207conforms to 208.St -isoC . 209The 210.Fn strtoll 211and 212.Fn strtoimax 213functions 214conform to 215.St -isoC-99 . 216The 217.Bx 218.Fn strtoq 219function is deprecated. 220