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: src/lib/libc/stdlib/strtol.3,v 1.21 2006/05/20 21:11:35 maxim Exp $ 38.\" $DragonFly: src/lib/libc/stdlib/strtol.3,v 1.4 2006/11/02 19:48:55 swildner Exp $ 39.\" 40.Dd November 2, 2006 41.Dt STRTOL 3 42.Os 43.Sh NAME 44.Nm strtol , strtoll , strtoimax , strtoq 45.Nd "convert a string value to a" 46.Vt long , "long long" , intmax_t 47or 48.Vt quad_t 49integer 50.Sh LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.In stdlib.h 54.In limits.h 55.Ft long 56.Fn strtol "const char *nptr" "char **endptr" "int base" 57.Ft long long 58.Fn strtoll "const char *nptr" "char **endptr" "int base" 59.In inttypes.h 60.Ft intmax_t 61.Fn strtoimax "const char *nptr" "char **endptr" "int base" 62.In sys/types.h 63.In stdlib.h 64.In limits.h 65.Ft quad_t 66.Fn strtoq "const char *nptr" "char **endptr" "int base" 67.Sh DESCRIPTION 68The 69.Fn strtol 70function 71converts the string in 72.Fa nptr 73to a 74.Vt long 75value. 76The 77.Fn strtoll 78function 79converts the string in 80.Fa nptr 81to a 82.Vt "long long" 83value. 84The 85.Fn strtoimax 86function 87converts the string in 88.Fa nptr 89to an 90.Vt intmax_t 91value. 92The 93.Fn strtoq 94function 95converts the string in 96.Fa nptr 97to a 98.Vt quad_t 99value. 100The conversion is done according to the given 101.Fa base , 102which must be between 2 and 36 inclusive, 103or be the special value 0. 104.Pp 105The string may begin with an arbitrary amount of white space 106(as determined by 107.Xr isspace 3 ) 108followed by a single optional 109.Ql + 110or 111.Ql - 112sign. 113If 114.Fa base 115is zero or 16, 116the string may then include a 117.Dq Li 0x 118prefix, 119and the number will be read in base 16; otherwise, a zero 120.Fa base 121is taken as 10 (decimal) unless the next character is 122.Ql 0 , 123in which case it is taken as 8 (octal). 124.Pp 125The remainder of the string is converted to a 126.Vt long , "long long" , intmax_t 127or 128.Vt quad_t 129value in the obvious manner, 130stopping at the first character which is not a valid digit 131in the given base. 132(In bases above 10, the letter 133.Ql A 134in either upper or lower case 135represents 10, 136.Ql B 137represents 11, and so forth, with 138.Ql Z 139representing 35.) 140.Pp 141If 142.Fa endptr 143is not 144.Dv NULL , 145.Fn strtol 146stores the address of the first invalid character in 147.Fa *endptr . 148If there were no digits at all, however, 149.Fn strtol 150stores the original value of 151.Fa nptr 152in 153.Fa *endptr . 154(Thus, if 155.Fa *nptr 156is not 157.Ql \e0 158but 159.Fa **endptr 160is 161.Ql \e0 162on return, the entire string was valid.) 163.Sh RETURN VALUES 164The 165.Fn strtol , 166.Fn strtoll , 167.Fn strtoimax 168and 169.Fn strtoq 170functions 171return the result of the conversion, 172unless the value would underflow or overflow. 173If no conversion could be performed, 0 is returned and 174the global variable 175.Va errno 176is set to 177.Er EINVAL 178(the last feature is not portable across all platforms). 179If an overflow or underflow occurs, 180.Va errno 181is set to 182.Er ERANGE 183and the function return value is clamped according 184to the following table. 185.Bl -column -offset indent ".Fn strtoimax" ".Sy overflow" ".Sy underflow" 186.It Sy Function Ta Sy overflow Ta Sy underflow 187.It Fn strtol Ta Dv LONG_MIN Ta Dv LONG_MAX 188.It Fn strtoll Ta Dv LLONG_MIN Ta Dv LLONG_MAX 189.It Fn strtoimax Ta Dv INTMAX_MIN Ta Dv INTMAX_MAX 190.It Fn strtoq Ta Dv LLONG_MIN Ta Dv LLONG_MAX 191.El 192.Sh ERRORS 193.Bl -tag -width Er 194.It Bq Er EINVAL 195The value of 196.Fa base 197is not supported or 198no conversion could be performed 199(the last feature is not portable across all platforms). 200.It Bq Er ERANGE 201The given string was out of range; the value converted has been clamped. 202.El 203.Sh SEE ALSO 204.Xr atof 3 , 205.Xr atoi 3 , 206.Xr atol 3 , 207.Xr strtod 3 , 208.Xr strtonum 3 , 209.Xr strtoul 3 , 210.Xr wcstol 3 211.Sh STANDARDS 212The 213.Fn strtol 214function 215conforms to 216.St -isoC . 217The 218.Fn strtoll 219and 220.Fn strtoimax 221functions 222conform to 223.St -isoC-99 . 224The 225.Bx 226.Fn strtoq 227function is deprecated. 228