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