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