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.24 2014/11/30 21:21:59 schwarze Exp $ 33.\" 34.Dd $Mdocdate: November 30 2014 $ 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.Vt unsigned long 65value. 66The 67.Fn strtoull 68function converts the string in 69.Fa nptr 70to an 71.Vt unsigned long long 72value. 73The 74.Fn strtoumax 75function converts the string in 76.Fa nptr 77to a 78.Vt 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 or the special value 0. 88If the string in 89.Fa nptr 90represents a negative number, it will be converted to its unsigned equivalent. 91This behavior is consistent with what happens when a signed integer type is 92cast to its unsigned counterpart. 93.Pp 94The string may begin with an arbitrary amount of whitespace 95(as determined by 96.Xr isspace 3 ) 97followed by a single optional 98.Ql + 99or 100.Ql - 101sign. 102If 103.Fa base 104is zero or 16, the string may then include a 105.Ql 0x 106prefix, and the number will be read in base 16; otherwise, a zero 107.Fa base 108is taken as 10 (decimal) unless the next character is 109.Ql 0 , 110in which case it is taken as 8 (octal). 111.Pp 112The remainder of the string is converted to an 113.Vt unsigned long , 114.Vt unsigned long long , 115or 116.Vt uintmax_t 117value in the obvious manner, 118stopping at the first character which is not a valid digit 119in the given base. 120(In bases above 10, the letter 121.Ql A 122in either upper or lower case represents 10, 123.Ql B 124represents 11, and so forth, with 125.Ql Z 126representing 35.) 127.Pp 128If 129.Fa endptr 130is non-null, 131.Fn strtoul 132stores the address of the first invalid character in 133.Fa *endptr . 134If there were no digits at all, however, 135.Fn strtoul 136stores the original value of 137.Fa nptr 138in 139.Fa *endptr . 140(Thus, if 141.Fa *nptr 142is not 143.Ql \e0 144but 145.Fa **endptr 146is 147.Ql \e0 148on return, the entire string was valid.) 149.Sh RETURN VALUES 150The 151.Fn strtoul , 152.Fn strtoull , 153.Fn strtoumax 154and 155.Fn strtouq 156functions return either the result of the conversion or, 157if there was a leading minus sign, 158the negation of the result of the conversion, 159unless the original (non-negated) value would overflow. 160If overflow occurs, 161.Fn strtoul 162returns 163.Dv ULONG_MAX , 164.Fn strtoull 165returns 166.Dv ULLONG_MAX , 167.Fn strtoumax 168returns 169.Dv UINTMAX_MAX , 170.Fn strtouq 171returns 172.Dv ULLONG_MAX 173and the global variable 174.Va errno 175is set to 176.Er ERANGE . 177.Pp 178There is no way to determine if 179.Fn strtoul 180has processed a negative number (and returned an unsigned value) short of 181examining the string in 182.Fa nptr 183directly. 184.Pp 185If there is no valid digit, 0 is returned. 186If 187.Ar base 188is invalid, 0 is returned and the global variable 189.Va errno 190is set to 191.Er EINVAL . 192.Sh EXAMPLES 193Ensuring that a string is a valid number (i.e., in range and containing no 194trailing characters) requires clearing 195.Va errno 196beforehand explicitly since 197.Va errno 198is not changed on a successful call to 199.Fn strtoul , 200and the return value of 201.Fn strtoul 202cannot be used unambiguously to signal an error: 203.Bd -literal -offset indent 204char *ep; 205unsigned long ulval; 206 207\&... 208 209errno = 0; 210ulval = strtoul(buf, &ep, 10); 211if (buf[0] == '\e0' || *ep != '\e0') 212 goto not_a_number; 213if (errno == ERANGE && ulval == ULONG_MAX) 214 goto out_of_range; 215.Ed 216.Pp 217This example will accept 218.Dq 12 219but not 220.Dq 12foo 221or 222.Dq 12\en . 223If trailing whitespace is acceptable, further checks must be done on 224.Va *ep ; 225alternately, use 226.Xr sscanf 3 . 227.Sh ERRORS 228.Bl -tag -width Er 229.It Bq Er EINVAL 230The value of 231.Ar base 232was neither between 2 and 36 inclusive nor the special value 0. 233.It Bq Er ERANGE 234The given string was out of range; the value converted has been clamped. 235.El 236.Sh SEE ALSO 237.Xr sscanf 3 , 238.Xr strtol 3 239.Sh STANDARDS 240The 241.Fn strtoul , 242.Fn strtoull , 243and 244.Fn strtoumax 245functions conform to 246.St -isoC-99 . 247Setting 248.Va errno 249to 250.Dv EINVAL 251is an extension to that standard required by 252.St -p1003.1-2008 . 253.Pp 254The 255.Fn strtouq 256function is a 257.Bx 258extension and is provided for backwards compatibility with legacy programs. 259.Sh BUGS 260Ignores the current locale. 261