148374Scael.\" 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 5*50330Sbostic.\" Chris Torek and the American National Standards Committee X3, 6*50330Sbostic.\" on Information Processing Systems. 7*50330Sbostic.\" 842092Sbostic.\" %sccs.include.redist.man% 942092Sbostic.\" 10*50330Sbostic.\" @(#)strtoul.3 5.3 (Berkeley) 06/29/91 1142092Sbostic.\" 1248374Scael.Dd 1348374Scael.Dt STRTOUL 3 1448374Scael.Os 1548374Scael.Sh NAME 1648374Scael.Nm strtoul 1748374Scael.Nd convert a string to an unsigned long integer 1848374Scael.Sh SYNOPSIS 1948374Scael.Fd #include <stdlib.h> 2048374Scael.Fd #include <limits.h> 2148374Scael.Fn strtoul "const char *nptr" "char **endptr" "int base" 2248374Scael.Sh DESCRIPTION 2348374ScaelThe 2448374Scael.Fn strtoul 2548374Scaelfunction 2642092Sbosticconverts the string in 2748374Scael.Fa nptr 2842092Sbosticto an 2948374Scael.Em unsigned long 3042092Sbosticvalue according to the given 3148374Scael.Fa base , 3242092Sbosticwhich must be between 2 and 36 inclusive, 3342092Sbosticor be the special value 0. 3448374Scael.Pp 3542092SbosticThe string may begin with an arbitrary amount of white space 3642092Sbostic(as determined by 3748374Scael.Xr isspace 3 ) 3848374Scaelfollowed by a single optional 3948374Scael.Ql + 4048374Scaelor 4148374Scael.Ql - 4248374Scaelsign. 4342092SbosticIf 4448374Scael.Fa base 4542092Sbosticis zero or 16, 4648374Scaelthe string may then include a 4748374Scael.Ql 0x 4848374Scaelprefix, 4942092Sbosticand the number will be read in base 16; otherwise, a zero 5048374Scael.Fa base 5148374Scaelis taken as 10 (decimal) unless the next character is 5248374Scael.Ql 0 , 5342092Sbosticin which case it is taken as 8 (octal). 5448374Scael.Pp 5542092SbosticThe remainder of the string is converted to an 5648374Scael.Em unsigned long 5742092Sbosticvalue in the obvious manner, 5842092Sbosticstopping at the end of the string 5942092Sbosticor at the first character that does not produce a valid digit 6042092Sbosticin the given base. 6148374Scael(In bases above 10, the letter 6248374Scael.Ql A 6348374Scaelin either upper or lower case 6448374Scaelrepresents 10, 6548374Scael.Ql B 6648374Scaelrepresents 11, and so forth, with 6748374Scael.Ql Z 6848374Scaelrepresenting 35.) 6948374Scael.Pp 7042092SbosticIf 7148374Scael.Fa endptr 7242092Sbosticis non nil, 7348374Scael.Fn strtoul 7442092Sbosticstores the address of the first invalid character in 7548374Scael.Fa *endptr . 7642092SbosticIf there were no digits at all, however, 7748374Scael.Fn strtoul 7842092Sbosticstores the original value of 7948374Scael.Fa nptr 8042092Sbosticin 8148374Scael.Fa *endptr . 8242092Sbostic(Thus, if 8348374Scael.Fa *nptr 8448374Scaelis not 8548374Scael.Ql \e0 8648374Scaelbut 8748374Scael.Fa **endptr 8848374Scaelis 8948374Scael.Ql \e0 9048374Scaelon return, the entire string was valid.) 9148374Scael.Sh RETURN VALUES 9248374ScaelThe 9348374Scael.Fn strtoul 9448374Scaelfunction 9542092Sbosticreturns either the result of the conversion 9642092Sbosticor, if there was a leading minus sign, 9742092Sbosticthe negation of the result of the conversion, 9842092Sbosticunless the original (non-negated) value would overflow; 9942092Sbosticin the latter case, 10048374Scael.Fn strtoul 10142092Sbosticreturns 10248374Scael.Dv ULONG_MAX 10348374Scaeland sets the global variable 10448374Scael.Va errno 10542092Sbosticto 10648374Scael.Er ERANGE . 10748374Scael.Sh ERRORS 10848374Scael.Bl -tag -width [ERANGE] 10948374Scael.It Bq Er ERANGE 11042092SbosticThe given string was out of range; the value converted has been clamped. 11148374Scael.El 11248374Scael.Sh SEE ALSO 11348374Scael.Xr strtol 3 11448374Scael.Sh STANDARDS 11548374ScaelThe 11648374Scael.Fn strtoul 11748374Scaelfunction 11848374Scaelconforms to 11948374Scael.St -ansiC . 12048374Scael.Sh BUGS 12142092SbosticIgnores the current locale. 122