1.\" Copyright (c) 1990, 1991 The Regents of the University of California. 2.\" 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.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the University of 19.\" California, Berkeley and its contributors. 20.\" 4. Neither the name of the University nor the names of its contributors 21.\" may be used to endorse or promote products derived from this software 22.\" without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" $OpenBSD: strtoul.3,v 1.8 2000/08/09 15:51:21 aaron Exp $ 37.\" 38.Dd June 25, 1992 39.Dt STRTOUL 3 40.Os 41.Sh NAME 42.Nm strtoul , 43.Nm strtouq 44.Nd convert a string to an unsigned long or uquad_t integer 45.Sh SYNOPSIS 46.Fd #include <stdlib.h> 47.Fd #include <limits.h> 48.Ft unsigned long 49.Fn strtoul "const char *nptr" "char **endptr" "int base" 50 51.Fd #include <sys/types.h> 52.Fd #include <stdlib.h> 53.Fd #include <limits.h> 54.Ft u_quad_t 55.Fn strtouq "const char *nptr" "char **endptr" "int base" 56.Sh DESCRIPTION 57The 58.Fn strtoul 59function converts the string in 60.Fa nptr 61to an 62.Li unsigned long 63value. 64The 65.Fn strtouq 66function converts the string in 67.Fa nptr 68to a 69.Li u_quad_t 70value. 71The conversion is done according to the given 72.Fa base , 73which must be a number between 2 and 36 inclusive 74or the special value 0. 75.Pp 76The string may begin with an arbitrary amount of whitespace 77(as determined by 78.Xr isspace 3 ) 79followed by a single optional 80.Ql + 81or 82.Ql - 83sign. 84If 85.Fa base 86is zero or 16, the string may then include a 87.Ql 0x 88prefix, and the number will be read in base 16; otherwise, a zero 89.Fa base 90is taken as 10 (decimal) unless the next character is 91.Ql 0 , 92in which case it is taken as 8 (octal). 93.Pp 94The remainder of the string is converted to an 95.Li unsigned long 96value in the obvious manner, stopping at the end of the string 97or at the first character that does not produce a valid digit 98in the given base. 99(In bases above 10, the letter 100.Ql A 101in either upper or lower case represents 10, 102.Ql B 103represents 11, and so forth, with 104.Ql Z 105representing 35.) 106.Pp 107If 108.Fa endptr 109is non-null, 110.Fn strtoul 111stores the address of the first invalid character in 112.Fa *endptr . 113If there were no digits at all, however, 114.Fn strtoul 115stores the original value of 116.Fa nptr 117in 118.Fa *endptr . 119(Thus, if 120.Fa *nptr 121is not 122.Ql \e0 123but 124.Fa **endptr 125is 126.Ql \e0 127on return, the entire string was valid.) 128.Sh RETURN VALUES 129The 130.Fn strtoul 131function returns the result of the conversion, 132unless the value would overflow, in which case 133.Dv ULONG_MAX 134is returned and 135.Va errno 136is set to 137.Er ERANGE . 138If there was a leading minus sign, 139.Fn strtoul 140returns the (unsigned) negation of the absolute value of the number, unless 141the absolute value would overflow. 142In this case, 143.Fn strtoul 144returns 145.Dv ULONG_MAX 146and sets the global variable 147.Va errno 148to 149.Er ERANGE . 150.Pp 151There is no way to determine if 152.Fn strtoul 153has processed a negative number (and returned an unsigned value) short of 154examining the string in 155.Fa nptr 156directly. 157.Sh EXAMPLES 158Ensuring that a string is a valid number (i.e., in range and containing no 159trailing characters) requires clearing 160.Va errno 161beforehand explicitly since 162.Va errno 163is not changed on a successful call to 164.Fn strtoul , 165and the return value of 166.Fn strtoul 167cannot be used unambiguously to signal an error: 168.Bd -literal -offset indent 169char *ep; 170unsigned long ulval; 171 172\&... 173 174errno = 0; 175ulval = strtoul(buf, &ep, 10); 176if (buf[0] == '\e0' || *ep != '\e0') 177 goto not_a_number; 178if (errno == ERANGE && ulval == ULONG_MAX) 179 goto out_of_range; 180.Ed 181.Pp 182This example will accept 183.Dq 12 184but not 185.Dq 12foo 186or 187.Dq 12\en . 188If trailing whitespace is acceptable, further checks must be done on 189.Va *ep ; 190alternately, use 191.Xr sscanf 3 . 192.Sh ERRORS 193.Bl -tag -width Er 194.It Bq Er ERANGE 195The given string was out of range; the value converted has been clamped. 196.El 197.Sh SEE ALSO 198.Xr sscanf 3 , 199.Xr strtol 3 200.Sh STANDARDS 201The 202.Fn strtoul 203function conforms to 204.St -ansiC . 205.Sh BUGS 206Ignores the current locale. 207