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.\" %sccs.include.redist.man% 9.\" 10.\" @(#)strtol.3 8.1 (Berkeley) 06/04/93 11.\" 12.Dd 13.Dt STRTOL 3 14.Os 15.Sh NAME 16.Nm strtol, strtoq 17.Nd convert string value to a long or quad_t integer 18.Sh SYNOPSIS 19.Fd #include <stdlib.h> 20.Fd #include <limits.h> 21.Ft long 22.Fn strtol "char *nptr" "char **endptr" "int base" 23 24.Fd #include <sys/types.h> 25.Fd #include <stdlib.h> 26.Fd #include <limits.h> 27.Ft quad_t 28.Fn strtoq "char *nptr" "char **endptr" "int base" 29.Sh DESCRIPTION 30The 31.Fn strtol 32function 33converts the string in 34.Fa nptr 35to a 36.Em long 37value. 38The 39.Fn strtoq 40function 41converts the string in 42.Fa nptr 43to a 44.Em quad_t 45value. 46The conversion is done according to the given 47.Fa base , 48which must be between 2 and 36 inclusive, 49or be the special value 0. 50.Pp 51The string may begin with an arbitrary amount of white space 52(as determined by 53.Xr isspace 3 ) 54followed by a single optional 55.Ql + 56or 57.Ql - 58sign. 59If 60.Fa base 61is zero or 16, 62the string may then include a 63.Ql 0x 64prefix, 65and the number will be read in base 16; otherwise, a zero 66.Fa base 67is taken as 10 (decimal) unless the next character is 68.Ql 0 , 69in which case it is taken as 8 (octal). 70.Pp 71The remainder of the string is converted to a 72.Em long 73value in the obvious manner, 74stopping at the first character which is not a valid digit 75in the given base. 76(In bases above 10, the letter 77.Ql A 78in either upper or lower case 79represents 10, 80.Ql B 81represents 11, and so forth, with 82.Ql Z 83representing 35.) 84.Pp 85If 86.Fa endptr 87is non nil, 88.Fn strtol 89stores the address of the first invalid character in 90.Fa *endptr . 91If there were no digits at all, however, 92.Fn strtol 93stores the original value of 94.Fa nptr 95in 96.Fa *endptr . 97(Thus, if 98.Fa *nptr 99is not 100.Ql \e0 101but 102.Fa **endptr 103is 104.Ql \e0 105on return, the entire string was valid.) 106.Sh RETURN VALUES 107The 108.Fn strtol 109function 110returns the result of the conversion, 111unless the value would underflow or overflow. 112If an underflow occurs, 113.Fn strtol 114returns 115.Dv LONG_MIN . 116If an overflow occurs, 117.Fn strtol 118returns 119.Dv LONG_MAX . 120In both cases, 121.Va errno 122is set to 123.Er ERANGE . 124.Sh ERRORS 125.Bl -tag -width [ERANGE] 126.It Bq Er ERANGE 127The given string was out of range; the value converted has been clamped. 128.El 129.Sh SEE ALSO 130.Xr atof 3 , 131.Xr atoi 3 , 132.Xr atol 3 , 133.Xr strtod 3 , 134.Xr strtoul 3 135.Sh STANDARDS 136The 137.Fn strtol 138function 139conforms to 140.St -ansiC . 141.Sh BUGS 142Ignores the current locale. 143