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.\" @(#)strtoul.3 8.1 (Berkeley) 06/04/93 11.\" 12.Dd 13.Dt STRTOUL 3 14.Os 15.Sh NAME 16.Nm strtoul, strtouq 17.Nd convert a string to an unsigned long or uquad_t integer 18.Sh SYNOPSIS 19.Fd #include <stdlib.h> 20.Fd #include <limits.h> 21.Ft unsigned long 22.Fn strtoul "const 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 u_quad_t 28.Fn strtouq "const char *nptr" "char **endptr" "int base" 29.Sh DESCRIPTION 30The 31.Fn strtoul 32function 33converts the string in 34.Fa nptr 35to an 36.Em unsigned long 37value. 38The 39.Fn strtouq 40function 41converts the string in 42.Fa nptr 43to a 44.Em u_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 an 72.Em unsigned long 73value in the obvious manner, 74stopping at the end of the string 75or at the first character that does not produce a valid digit 76in the given base. 77(In bases above 10, the letter 78.Ql A 79in either upper or lower case 80represents 10, 81.Ql B 82represents 11, and so forth, with 83.Ql Z 84representing 35.) 85.Pp 86If 87.Fa endptr 88is non nil, 89.Fn strtoul 90stores the address of the first invalid character in 91.Fa *endptr . 92If there were no digits at all, however, 93.Fn strtoul 94stores the original value of 95.Fa nptr 96in 97.Fa *endptr . 98(Thus, if 99.Fa *nptr 100is not 101.Ql \e0 102but 103.Fa **endptr 104is 105.Ql \e0 106on return, the entire string was valid.) 107.Sh RETURN VALUES 108The 109.Fn strtoul 110function 111returns either the result of the conversion 112or, if there was a leading minus sign, 113the negation of the result of the conversion, 114unless the original (non-negated) value would overflow; 115in the latter case, 116.Fn strtoul 117returns 118.Dv ULONG_MAX 119and sets the global variable 120.Va errno 121to 122.Er ERANGE . 123.Sh ERRORS 124.Bl -tag -width [ERANGE] 125.It Bq Er ERANGE 126The given string was out of range; the value converted has been clamped. 127.El 128.Sh SEE ALSO 129.Xr strtol 3 130.Sh STANDARDS 131The 132.Fn strtoul 133function 134conforms to 135.St -ansiC . 136.Sh BUGS 137Ignores the current locale. 138