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.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)strtol.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd November 28, 2001 36.Dt STRTOL 3 37.Os 38.Sh NAME 39.Nm strtol , strtoll , strtoimax , strtoq 40.Nd "convert a string value to a" 41.Vt long , "long long" , intmax_t 42or 43.Vt quad_t 44integer 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 * restrict nptr" "char ** restrict endptr" "int base" 52.Ft long long 53.Fn strtoll "const char * restrict nptr" "char ** restrict endptr" "int base" 54.In inttypes.h 55.Ft intmax_t 56.Fn strtoimax "const char * restrict nptr" "char ** restrict 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.Vt long 70value. 71The 72.Fn strtoll 73function 74converts the string in 75.Fa nptr 76to a 77.Vt "long long" 78value. 79The 80.Fn strtoimax 81function 82converts the string in 83.Fa nptr 84to an 85.Vt intmax_t 86value. 87The 88.Fn strtoq 89function 90converts the string in 91.Fa nptr 92to a 93.Vt 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.Dq Li 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.Vt long , "long long" , intmax_t 122or 123.Vt quad_t 124value in the obvious manner, 125stopping at the first character which is not a valid digit 126in the given base. 127(In bases above 10, the letter 128.Ql A 129in either upper or lower case 130represents 10, 131.Ql B 132represents 11, and so forth, with 133.Ql Z 134representing 35.) 135.Pp 136If 137.Fa endptr 138is not 139.Dv NULL , 140.Fn strtol 141stores the address of the first invalid character in 142.Fa *endptr . 143If there were no digits at all, however, 144.Fn strtol 145stores the original value of 146.Fa nptr 147in 148.Fa *endptr . 149(Thus, if 150.Fa *nptr 151is not 152.Ql \e0 153but 154.Fa **endptr 155is 156.Ql \e0 157on return, the entire string was valid.) 158.Sh RETURN VALUES 159The 160.Fn strtol , 161.Fn strtoll , 162.Fn strtoimax 163and 164.Fn strtoq 165functions 166return the result of the conversion, 167unless the value would underflow or overflow. 168If no conversion could be performed, 0 is returned and 169the global variable 170.Va errno 171is set to 172.Er EINVAL 173(the last feature is not portable across all platforms). 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 underflow" ".Sy overflow" 181.It Sy Function Ta Sy underflow Ta Sy overflow 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(the last feature is not portable across all platforms). 195.It Bq Er ERANGE 196The given string was out of range; the value converted has been clamped. 197.El 198.Sh SEE ALSO 199.Xr atof 3 , 200.Xr atoi 3 , 201.Xr atol 3 , 202.Xr strtod 3 , 203.Xr strtonum 3 , 204.Xr strtoul 3 , 205.Xr wcstol 3 206.Sh STANDARDS 207The 208.Fn strtol 209function 210conforms to 211.St -isoC . 212The 213.Fn strtoll 214and 215.Fn strtoimax 216functions 217conform to 218.St -isoC-99 . 219The 220.Bx 221.Fn strtoq 222function is deprecated. 223