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