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