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