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