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