1.\" $NetBSD: strtol.3,v 1.31 2015/03/11 09:57:35 wiz Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" from: @(#)strtol.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd March 10, 2015 37.Dt STRTOL 3 38.Os 39.Sh NAME 40.Nm strtoi , 41.Nm strtol , 42.Nm strtoll , 43.Nm strtoimax , 44.Nm strtoq 45.Nd convert string value to a long, long long, intmax_t or quad_t integer 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In stdlib.h 50.In limits.h 51.Ft long int 52.Fn strtol "const char * restrict nptr" "char ** restrict endptr" "int base" 53.Ft long long int 54.Fn strtoll "const char * restrict nptr" "char ** restrict endptr" "int base" 55.Pp 56.In inttypes.h 57.Ft intmax_t 58.Fn strtoi "const char * restrict nptr" "char ** restrict endptr" "int base" "intmax_t lo" "intmax_t hi" "int *rstatus" 59.Ft intmax_t 60.Fn strtoimax "const char * restrict nptr" "char ** restrict endptr" "int base" 61.Pp 62.In sys/types.h 63.In stdlib.h 64.In limits.h 65.Ft quad_t 66.Fn strtoq "const char * restrict nptr" "char ** restrict endptr" "int base" 67.Sh DESCRIPTION 68The 69.Fn strtol 70function 71converts the string in 72.Fa nptr 73to a 74.Ft long int 75value. 76The 77.Fn strtoll 78function 79converts the string in 80.Fa nptr 81to a 82.Ft long long int 83value. 84The 85.Fn strtoimax 86function 87converts the string in 88.Fa nptr 89to an 90.Ft intmax_t 91value. 92The 93.Fn strtoi 94function 95uses internally 96.Fn strtoimax 97and ensures that the result is always in the range [ 98.Fa lo .. 99.Fa hi 100]. 101In adddition it always places 102.Dv 0 103on success or a conversion status in the 104.Fa rstatus 105argument, avoiding the 106.Dv errno 107gymnastics the other functions require. 108The 109.Fn strtoi 110function doesn't affect errno on exit. 111The 112.Fa rstatus 113argument can be 114.Dv NULL 115if conversion status is to be ignored. 116The 117.Fn strtoq 118function 119converts the string in 120.Fa nptr 121to a 122.Ft quad_t 123value. 124The conversion is done according to the given 125.Fa base , 126which must be between 2 and 36 inclusive, 127or be the special value 0. 128.Pp 129The string may begin with an arbitrary amount of white space 130(as determined by 131.Xr isspace 3 ) 132followed by a single optional 133.Ql + 134or 135.Ql - 136sign. 137If 138.Fa base 139is zero or 16, 140the string may then include a 141.Ql 0x 142prefix, 143and the number will be read in base 16; otherwise, a zero 144.Fa base 145is taken as 10 (decimal) unless the next character is 146.Ql 0 , 147in which case it is taken as 8 (octal). 148.Pp 149The remainder of the string is converted to a 150.Em long 151value in the obvious manner, 152stopping at the first character which is not a valid digit 153in the given base. 154(In bases above 10, the letter 155.Ql A 156in either upper or lower case 157represents 10, 158.Ql B 159represents 11, and so forth, with 160.Ql Z 161representing 35.) 162.Pp 163If 164.Fa endptr 165is non-nil, 166.Fn strtol 167stores the address of the first invalid character in 168.Fa *endptr . 169If there were no digits at all, however, 170.Fn strtol 171stores the original value of 172.Fa nptr 173in 174.Fa *endptr . 175(Thus, if 176.Fa *nptr 177is not 178.Ql \e0 179but 180.Fa **endptr 181is 182.Ql \e0 183on return, the entire string was valid.) 184.Sh RETURN VALUES 185The 186.Fn strtoi 187function 188always returns the closest value in the range specified by 189the 190.Fa lo 191and 192.Fa hi 193arguments. 194The 195.Fn strtol 196function 197returns the result of the conversion, 198unless the value would underflow or overflow. 199If an underflow occurs, 200.Fn strtol 201returns 202.Dv LONG_MIN , 203.Fn strtoll 204returns 205.Dv LLONG_MIN , 206and 207.Fn strtoimax 208returns 209.Dv INTMAX_MIN . 210If an overflow occurs, 211.Fn strtol 212returns 213.Dv LONG_MAX , 214.Fn strtoll 215returns 216.Dv LLONG_MAX , 217and 218.Fn strtoimax 219returns 220.Dv INTMAX_MAX . 221In these cases, 222.Va errno 223is set to 224.Er ERANGE . 225If the 226.Fa base 227argument is not supported then 228.Va errno 229is set to 230.Er EINVAL 231and the functions return 0. 232.Pp 233If no error occurs, 234.Va errno 235is left unchanged. 236This behavior (which is unlike most library functions) is guaranteed 237by the pertinent standards. 238.Sh EXAMPLES 239The 240.Fn strtoi 241function is the simplest to use: 242.Bd -literal -offset indent 243int e; 244intmax_t lval = strtoi(buf, NULL, 0, 1, 99, &e); 245if (e) 246 warnc(e, "conversion of `%s' to a number failed, using %jd", 247 buf, lval); 248.Ed 249.Pp 250This will always return a number in 251.Dv [1..99] 252range no matter what the input is, and warn if the conversion failed. 253.Pp 254Because the return value of 255.Fn strtol 256cannot be used unambiguously to detect an error, 257.Va errno 258is left unchanged after a successful call. 259To ensure that a string is a valid number (i.e., in range and containing no 260trailing characters), clear 261.Va errno 262beforehand explicitly, then check it afterwards: 263.Bd -literal -offset indent 264char *ep; 265long lval; 266 267\&... 268 269errno = 0; 270lval = strtol(buf, \*[Am]ep, 10); 271if (buf[0] == '\e0' || *ep != '\e0') 272 goto not_a_number; 273if (errno == ERANGE \*[Am]\*[Am] (lval == LONG_MAX || lval == LONG_MIN)) 274 goto out_of_range; 275.Ed 276.Pp 277This example will accept 278.Dq 12 279but not 280.Dq 12foo 281or 282.Dq 12\en . 283If trailing whitespace is acceptable, further checks must be done on 284.Va *ep ; 285alternately, use 286.Xr sscanf 3 . 287.Pp 288If 289.Fn strtol 290is being used instead of 291.Xr atoi 3 , 292error checking is further complicated because the desired return value is an 293.Li int 294rather than a 295.Li long ; 296however, on some architectures integers and long integers are the same size. 297Thus the following is necessary: 298.Bd -literal -offset indent 299char *ep; 300int ival; 301long lval; 302 303\&... 304 305errno = 0; 306lval = strtol(buf, \*[Am]ep, 10); 307if (buf[0] == '\e0' || *ep != '\e0') 308 goto not_a_number; 309if ((errno == ERANGE \*[Am]\*[Am] (lval == LONG_MAX || lval == LONG_MIN)) || 310 (lval \*[Gt] INT_MAX || lval \*[Lt] INT_MIN)) 311 goto out_of_range; 312ival = lval; 313.Ed 314.Sh ERRORS 315.Bl -tag -width Er 316.It Bq Er EINVAL 317The 318.Ar base 319is not between 2 and 36 and does not contain the special value 0. 320.It Bq Er ERANGE 321The given string was out of range; the value converted has been clamped. 322.El 323.Pp 324In addition to the above errors 325.Fn strtoi 326returns: 327.Bl -tag -width Er 328.It Bq Er ECANCELED 329The string did not contain any characters that were converted. 330.It Bq Er ENOTSUP 331The string contained non-numeric characters that did not get converted. 332In this case, 333.Fa endptr 334points to the first unconverted character. 335.It Bq Er ERANGE 336The range given was invalid, i.e. 337.Fa lo 338\*[Gt] 339.Fa hi . 340.El 341.Sh SEE ALSO 342.Xr atof 3 , 343.Xr atoi 3 , 344.Xr atol 3 , 345.Xr atoll 3 , 346.Xr strtod 3 , 347.Xr strtou 3 , 348.Xr strtoul 3 , 349.Xr strtoull 3 , 350.Xr strtoumax 3 351.Sh STANDARDS 352The 353.Fn strtol 354function 355conforms to 356.St -ansiC . 357The 358.Fn strtoll 359and 360.Fn strtoimax 361functions conform to 362.St -isoC-99 . 363The 364.Fn strtoi 365function appeared in 366.Nx 8 . 367.Sh BUGS 368Ignores the current locale. 369