1*61180Sbostic.\" Copyright (c) 1990, 1991, 1993 2*61180Sbostic.\" The Regents of the University of California. All rights reserved. 342092Sbostic.\" 442092Sbostic.\" This code is derived from software contributed to Berkeley by 550330Sbostic.\" Chris Torek and the American National Standards Committee X3, 650330Sbostic.\" on Information Processing Systems. 750330Sbostic.\" 842092Sbostic.\" %sccs.include.redist.man% 942092Sbostic.\" 10*61180Sbostic.\" @(#)strtoul.3 8.1 (Berkeley) 06/04/93 1142092Sbostic.\" 1248374Scael.Dd 1348374Scael.Dt STRTOUL 3 1448374Scael.Os 1548374Scael.Sh NAME 1654428Sbostic.Nm strtoul, strtouq 1754428Sbostic.Nd convert a string to an unsigned long or uquad_t integer 1848374Scael.Sh SYNOPSIS 1948374Scael.Fd #include <stdlib.h> 2048374Scael.Fd #include <limits.h> 2154428Sbostic.Ft unsigned long 2248374Scael.Fn strtoul "const char *nptr" "char **endptr" "int base" 2354428Sbostic 2454428Sbostic.Fd #include <sys/types.h> 2554428Sbostic.Fd #include <stdlib.h> 2654428Sbostic.Fd #include <limits.h> 2754428Sbostic.Ft u_quad_t 2854428Sbostic.Fn strtouq "const char *nptr" "char **endptr" "int base" 2948374Scael.Sh DESCRIPTION 3048374ScaelThe 3148374Scael.Fn strtoul 3248374Scaelfunction 3342092Sbosticconverts the string in 3448374Scael.Fa nptr 3542092Sbosticto an 3648374Scael.Em unsigned long 3754428Sbosticvalue. 3854428SbosticThe 3954428Sbostic.Fn strtouq 4054428Sbosticfunction 4154428Sbosticconverts the string in 4254428Sbostic.Fa nptr 4354428Sbosticto a 4454428Sbostic.Em u_quad_t 4554428Sbosticvalue. 4654428SbosticThe conversion is done according to the given 4748374Scael.Fa base , 4842092Sbosticwhich must be between 2 and 36 inclusive, 4942092Sbosticor be the special value 0. 5048374Scael.Pp 5142092SbosticThe string may begin with an arbitrary amount of white space 5242092Sbostic(as determined by 5348374Scael.Xr isspace 3 ) 5448374Scaelfollowed by a single optional 5548374Scael.Ql + 5648374Scaelor 5748374Scael.Ql - 5848374Scaelsign. 5942092SbosticIf 6048374Scael.Fa base 6142092Sbosticis zero or 16, 6248374Scaelthe string may then include a 6348374Scael.Ql 0x 6448374Scaelprefix, 6542092Sbosticand the number will be read in base 16; otherwise, a zero 6648374Scael.Fa base 6748374Scaelis taken as 10 (decimal) unless the next character is 6848374Scael.Ql 0 , 6942092Sbosticin which case it is taken as 8 (octal). 7048374Scael.Pp 7142092SbosticThe remainder of the string is converted to an 7248374Scael.Em unsigned long 7342092Sbosticvalue in the obvious manner, 7442092Sbosticstopping at the end of the string 7542092Sbosticor at the first character that does not produce a valid digit 7642092Sbosticin the given base. 7748374Scael(In bases above 10, the letter 7848374Scael.Ql A 7948374Scaelin either upper or lower case 8048374Scaelrepresents 10, 8148374Scael.Ql B 8248374Scaelrepresents 11, and so forth, with 8348374Scael.Ql Z 8448374Scaelrepresenting 35.) 8548374Scael.Pp 8642092SbosticIf 8748374Scael.Fa endptr 8842092Sbosticis non nil, 8948374Scael.Fn strtoul 9042092Sbosticstores the address of the first invalid character in 9148374Scael.Fa *endptr . 9242092SbosticIf there were no digits at all, however, 9348374Scael.Fn strtoul 9442092Sbosticstores the original value of 9548374Scael.Fa nptr 9642092Sbosticin 9748374Scael.Fa *endptr . 9842092Sbostic(Thus, if 9948374Scael.Fa *nptr 10048374Scaelis not 10148374Scael.Ql \e0 10248374Scaelbut 10348374Scael.Fa **endptr 10448374Scaelis 10548374Scael.Ql \e0 10648374Scaelon return, the entire string was valid.) 10748374Scael.Sh RETURN VALUES 10848374ScaelThe 10948374Scael.Fn strtoul 11048374Scaelfunction 11142092Sbosticreturns either the result of the conversion 11242092Sbosticor, if there was a leading minus sign, 11342092Sbosticthe negation of the result of the conversion, 11442092Sbosticunless the original (non-negated) value would overflow; 11542092Sbosticin the latter case, 11648374Scael.Fn strtoul 11742092Sbosticreturns 11848374Scael.Dv ULONG_MAX 11948374Scaeland sets the global variable 12048374Scael.Va errno 12142092Sbosticto 12248374Scael.Er ERANGE . 12348374Scael.Sh ERRORS 12448374Scael.Bl -tag -width [ERANGE] 12548374Scael.It Bq Er ERANGE 12642092SbosticThe given string was out of range; the value converted has been clamped. 12748374Scael.El 12848374Scael.Sh SEE ALSO 12948374Scael.Xr strtol 3 13048374Scael.Sh STANDARDS 13148374ScaelThe 13248374Scael.Fn strtoul 13348374Scaelfunction 13448374Scaelconforms to 13548374Scael.St -ansiC . 13648374Scael.Sh BUGS 13742092SbosticIgnores the current locale. 138