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.\" 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. 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.\" $OpenBSD: strtol.3,v 1.19 2007/11/13 18:30:04 tobias Exp $ 33.\" 34.Dd $Mdocdate: November 13 2007 $ 35.Dt STRTOL 3 36.Os 37.Sh NAME 38.Nm strtol , 39.Nm strtoll , 40.Nm strtoimax , 41.Nm strtoq , 42.Nd "convert string value to a long, long long or intmax_t integer" 43.Sh SYNOPSIS 44.Fd #include <limits.h> 45.Fd #include <stdlib.h> 46.Ft long 47.Fn strtol "const char *nptr" "char **endptr" "int base" 48.Pp 49.Ft long long 50.Fn strtoll "const char *nptr" "char **endptr" "int base" 51.Pp 52.Fd #include <inttypes.h> 53.Ft intmax_t 54.Fn strtoimax "const char *nptr" "char **endptr" "int base" 55.Pp 56.Fd #include <sys/types.h> 57.Fd #include <limits.h> 58.Fd #include <stdlib.h> 59.Ft quad_t 60.Fn strtoq "const char *nptr" "char **endptr" "int base" 61.Sh DESCRIPTION 62The 63.Fn strtol 64function converts the string in 65.Fa nptr 66to a 67.Li long 68value. 69The 70.Fn strtoll 71function converts the string in 72.Fa nptr 73to a 74.Li long long 75value. 76The 77.Fn strtoimax 78function converts the string in 79.Fa nptr 80to an 81.Li intmax_t 82value. 83The 84.Fn strtoq 85function is a deprecated equivalent of 86.Fn strtoll 87and is provided for backwards compatibility with legacy programs. 88The conversion is done according to the given 89.Fa base , 90which must be a number between 2 and 36 inclusive or the special value 0. 91.Pp 92The string may begin with an arbitrary amount of whitespace 93(as determined by 94.Xr isspace 3 ) 95followed by a single optional 96.Ql + 97or 98.Ql - 99sign. 100If 101.Fa base 102is zero or 16, the string may then include a 103.Ql 0x 104prefix, and the number will be read in base 16; otherwise, a zero 105.Fa base 106is taken as 10 (decimal) unless the next character is 107.Ql 0 , 108in which case it is taken as 8 (octal). 109.Pp 110The remainder of the string is converted to a 111.Li long , 112.Li long long , 113or 114.Li intmax_t , 115value in the obvious manner, 116stopping at the first character which is not a valid digit 117in the given base. 118(In bases above 10, the letter 119.Ql A 120in either upper or lower case represents 10, 121.Ql B 122represents 11, and so forth, with 123.Ql Z 124representing 35.) 125.Pp 126If 127.Fa endptr 128is non-null, 129.Fn strtol 130stores the address of the first invalid character in 131.Fa *endptr . 132If there were no digits at all, however, 133.Fn strtol 134stores the original value of 135.Fa nptr 136in 137.Fa *endptr . 138(Thus, if 139.Fa *nptr 140is not 141.Ql \e0 142but 143.Fa **endptr 144is 145.Ql \e0 146on return, the entire string was valid.) 147.Sh RETURN VALUES 148The 149.Fn strtol , 150.Fn strtoll , 151.Fn strtoimax , 152and 153.Fn strtoq 154functions return the result of the conversion, 155unless the value would underflow or overflow. 156If no conversion could be performed, 0 is returned; 157the global variable 158.Va errno 159is also set to 160.Er EINVAL, 161though this is not portable across all platforms. 162If overflow or underflow occurs, 163.Va errno 164is set to 165.Er ERANGE 166and the function return value is as follows: 167.Bl -column -offset indent "strtoimax" "overflow" "underflow" 168.It Sy Function Ta Sy underflow Ta Sy overflow 169.It Fn strtol Ta Dv LONG_MIN Ta Dv LONG_MAX 170.It Fn strtoll Ta Dv LLONG_MIN Ta Dv LLONG_MAX 171.It Fn strtoimax Ta Dv INTMAX_MIN Ta Dv INTMAX_MAX 172.It Fn strtoq Ta Dv LLONG_MIN Ta Dv LLONG_MAX 173.El 174.Sh EXAMPLES 175Ensuring that a string is a valid number (i.e., in range and containing no 176trailing characters) requires clearing 177.Va errno 178beforehand explicitly since 179.Va errno 180is not changed on a successful call to 181.Fn strtol , 182and the return value of 183.Fn strtol 184cannot be used unambiguously to signal an error: 185.Bd -literal -offset indent 186char *ep; 187long lval; 188 189\&... 190 191errno = 0; 192lval = strtol(buf, &ep, 10); 193if (buf[0] == '\e0' || *ep != '\e0') 194 goto not_a_number; 195if (errno == ERANGE && (lval == LONG_MAX || lval == LONG_MIN)) 196 goto out_of_range; 197.Ed 198.Pp 199This example will accept 200.Dq 12 201but not 202.Dq 12foo 203or 204.Dq 12\en . 205If trailing whitespace is acceptable, further checks must be done on 206.Va *ep ; 207alternately, use 208.Xr sscanf 3 . 209.Pp 210If 211.Fn strtol 212is being used instead of 213.Xr atoi 3 , 214error checking is further complicated because the desired return value is an 215.Li int 216rather than a 217.Li long ; 218however, on some architectures integers and long integers are the same size. 219Thus the following is necessary: 220.Bd -literal -offset indent 221char *ep; 222int ival; 223long lval; 224 225\&... 226 227errno = 0; 228lval = strtol(buf, &ep, 10); 229if (buf[0] == '\e0' || *ep != '\e0') 230 goto not_a_number; 231if ((errno == ERANGE && (lval == LONG_MAX || lval == LONG_MIN)) || 232 (lval > INT_MAX || lval < INT_MIN)) 233 goto out_of_range; 234ival = lval; 235.Ed 236.Sh ERRORS 237.Bl -tag -width Er 238.It Bq Er ERANGE 239The given string was out of range; the value converted has been clamped. 240.El 241.Sh SEE ALSO 242.Xr atof 3 , 243.Xr atoi 3 , 244.Xr atol 3 , 245.Xr atoll 3 , 246.Xr sscanf 3 , 247.Xr strtod 3 , 248.Xr strtonum 3 , 249.Xr strtoul 3 250.Sh STANDARDS 251The 252.Fn strtol , 253.Fn strtoll , 254and 255.Fn strtoimax 256functions conform to 257.St -ansiC-99 . 258The 259.Fn strtoq 260function is a 261.Bx 262extension and is provided for backwards compatibility with legacy programs. 263.Sh BUGS 264Ignores the current locale. 265