1*48374Scael.\" Copyright (c) 1990, 1991 The Regents of the University of California. 242092Sbostic.\" All rights reserved. 342092Sbostic.\" 442092Sbostic.\" This code is derived from software contributed to Berkeley by 542092Sbostic.\" Chris Torek. 642092Sbostic.\" %sccs.include.redist.man% 742092Sbostic.\" 8*48374Scael.\" @(#)strtoul.3 5.2 (Berkeley) 04/20/91 942092Sbostic.\" 10*48374Scael.Dd 11*48374Scael.Dt STRTOUL 3 12*48374Scael.Os 13*48374Scael.Sh NAME 14*48374Scael.Nm strtoul 15*48374Scael.Nd convert a string to an unsigned long integer 16*48374Scael.Sh SYNOPSIS 17*48374Scael.Fd #include <stdlib.h> 18*48374Scael.Fd #include <limits.h> 19*48374Scael.Fn strtoul "const char *nptr" "char **endptr" "int base" 20*48374Scael.Sh DESCRIPTION 21*48374ScaelThe 22*48374Scael.Fn strtoul 23*48374Scaelfunction 2442092Sbosticconverts the string in 25*48374Scael.Fa nptr 2642092Sbosticto an 27*48374Scael.Em unsigned long 2842092Sbosticvalue according to the given 29*48374Scael.Fa base , 3042092Sbosticwhich must be between 2 and 36 inclusive, 3142092Sbosticor be the special value 0. 32*48374Scael.Pp 3342092SbosticThe string may begin with an arbitrary amount of white space 3442092Sbostic(as determined by 35*48374Scael.Xr isspace 3 ) 36*48374Scaelfollowed by a single optional 37*48374Scael.Ql + 38*48374Scaelor 39*48374Scael.Ql - 40*48374Scaelsign. 4142092SbosticIf 42*48374Scael.Fa base 4342092Sbosticis zero or 16, 44*48374Scaelthe string may then include a 45*48374Scael.Ql 0x 46*48374Scaelprefix, 4742092Sbosticand the number will be read in base 16; otherwise, a zero 48*48374Scael.Fa base 49*48374Scaelis taken as 10 (decimal) unless the next character is 50*48374Scael.Ql 0 , 5142092Sbosticin which case it is taken as 8 (octal). 52*48374Scael.Pp 5342092SbosticThe remainder of the string is converted to an 54*48374Scael.Em unsigned long 5542092Sbosticvalue in the obvious manner, 5642092Sbosticstopping at the end of the string 5742092Sbosticor at the first character that does not produce a valid digit 5842092Sbosticin the given base. 59*48374Scael(In bases above 10, the letter 60*48374Scael.Ql A 61*48374Scaelin either upper or lower case 62*48374Scaelrepresents 10, 63*48374Scael.Ql B 64*48374Scaelrepresents 11, and so forth, with 65*48374Scael.Ql Z 66*48374Scaelrepresenting 35.) 67*48374Scael.Pp 6842092SbosticIf 69*48374Scael.Fa endptr 7042092Sbosticis non nil, 71*48374Scael.Fn strtoul 7242092Sbosticstores the address of the first invalid character in 73*48374Scael.Fa *endptr . 7442092SbosticIf there were no digits at all, however, 75*48374Scael.Fn strtoul 7642092Sbosticstores the original value of 77*48374Scael.Fa nptr 7842092Sbosticin 79*48374Scael.Fa *endptr . 8042092Sbostic(Thus, if 81*48374Scael.Fa *nptr 82*48374Scaelis not 83*48374Scael.Ql \e0 84*48374Scaelbut 85*48374Scael.Fa **endptr 86*48374Scaelis 87*48374Scael.Ql \e0 88*48374Scaelon return, the entire string was valid.) 89*48374Scael.Sh RETURN VALUES 90*48374ScaelThe 91*48374Scael.Fn strtoul 92*48374Scaelfunction 9342092Sbosticreturns either the result of the conversion 9442092Sbosticor, if there was a leading minus sign, 9542092Sbosticthe negation of the result of the conversion, 9642092Sbosticunless the original (non-negated) value would overflow; 9742092Sbosticin the latter case, 98*48374Scael.Fn strtoul 9942092Sbosticreturns 100*48374Scael.Dv ULONG_MAX 101*48374Scaeland sets the global variable 102*48374Scael.Va errno 10342092Sbosticto 104*48374Scael.Er ERANGE . 105*48374Scael.Sh ERRORS 106*48374Scael.Bl -tag -width [ERANGE] 107*48374Scael.It Bq Er ERANGE 10842092SbosticThe given string was out of range; the value converted has been clamped. 109*48374Scael.El 110*48374Scael.Sh SEE ALSO 111*48374Scael.Xr strtol 3 112*48374Scael.Sh STANDARDS 113*48374ScaelThe 114*48374Scael.Fn strtoul 115*48374Scaelfunction 116*48374Scaelconforms to 117*48374Scael.St -ansiC . 118*48374Scael.Sh BUGS 11942092SbosticIgnores the current locale. 120