1.\" $NetBSD: strtoul.3,v 1.37 2017/07/03 21:32:50 wiz Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" from: @(#)strtoul.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd November 13, 2015 37.Dt STRTOUL 3 38.Os 39.Sh NAME 40.Nm strtoul , 41.Nm strtoull , 42.Nm strtoumax , 43.Nm strtouq 44.Nd convert a string to an unsigned long, unsigned long long, uintmax_t or u_quad_t integer 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In stdlib.h 49.In limits.h 50.Ft unsigned long int 51.Fn strtoul "const char * restrict nptr" "char ** restrict endptr" "int base" 52.Ft unsigned long long int 53.Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base" 54.Pp 55.In inttypes.h 56.Ft uintmax_t 57.Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base" 58.Pp 59.In sys/types.h 60.In stdlib.h 61.In limits.h 62.Ft u_quad_t 63.Fn strtouq "const char * restrict nptr" "char ** restrict endptr" "int base" 64.Sh DESCRIPTION 65The 66.Fn strtoul 67function 68converts the string in 69.Fa nptr 70to an 71.Ft unsigned long int 72value. 73The 74.Fn strtoull 75function 76converts the string in 77.Fa nptr 78to an 79.Ft unsigned long long int 80value. 81The 82.Fn strtoumax 83function 84converts the string in 85.Fa nptr 86to an 87.Ft uintmax_t 88value. 89The 90.Fn strtouq 91function 92converts the string in 93.Fa nptr 94to a 95.Ft u_quad_t 96value. 97.Pp 98The conversion is done according to the given 99.Fa base , 100which must be between 2 and 36 inclusive, 101or be the special value 0. 102.Pp 103The string may begin with an arbitrary amount of white space 104(as determined by 105.Xr isspace 3 ) 106followed by a single optional 107.Ql + 108or 109.Ql - 110sign. 111If 112.Fa base 113is zero or 16, 114the string may then include a 115.Ql 0x 116or 117.Ql 0X 118prefix, 119and the number will be read in base 16; otherwise, 120.\" if the 121.\" .Fa base 122.\" is zero or 2, 123.\" the string may then include a 124.\" .Ql 0b 125.\" or 126.\" .Ql 0B 127.\" prefix, 128.\" and the number will be read in base 2; otherwise, 129a zero 130.Fa base 131is taken as 10 (decimal) unless the next character is 132.Ql 0 , 133in which case it is taken as 8 (octal). 134.Pp 135The remainder of the string is converted to an appropriate 136value in the obvious manner, 137stopping at the end of the string 138or at the first character that does not produce a valid digit 139in the given base. 140(In bases above 10, the letter 141.Ql A 142in either upper or lower case 143represents 10, 144.Ql B 145represents 11, and so forth, with 146.Ql Z 147representing 35.) 148.Pp 149If 150.Fa endptr 151is non-nil, the functions store the address of the first invalid character in 152.Fa *endptr . 153If there were no digits at all, however, 154the functions store the original value of 155.Fa nptr 156in 157.Fa *endptr . 158(Thus, if 159.Fa *nptr 160is not 161.Ql \e0 162but 163.Fa **endptr 164is 165.Ql \e0 166on return, the entire string was valid.) 167.Sh RETURN VALUES 168The 169.Fn strtoul 170function 171returns either the result of the conversion 172or, if there was a leading minus sign, 173the negation of the result of the conversion, 174unless the original (non-negated) value would overflow; 175in the latter case, 176.Fn strtoul 177returns 178.Dv ULONG_MAX , 179.Fn strtoull 180returns 181.Dv ULLONG_MAX , 182.Fn strtoumax 183returns 184.Dv UINTMAX_MAX , 185.Fn strtouq 186returns 187.Dv UQUAD_MAX , 188and the global variable 189.Va errno 190is set to 191.Er ERANGE . 192.Pp 193There is no way to determine if 194.Fn strtoul 195has processed a negative number (and returned an unsigned value) short of 196examining the string in 197.Fa nptr 198directly. 199If the 200.Fa base 201argument is not supported then 202.Va errno 203is set to 204.Er EINVAL 205and the functions return 0. 206.Pp 207If no error occurs, 208.Va errno 209is left unchanged. 210This behavior (which is unlike most library functions) is guaranteed 211by the pertinent standards. 212.Sh EXAMPLES 213Because the return value of 214.Fn strtoul 215cannot be used unambiguously to detect an error, 216.Va errno 217is left unchanged after a successful call. 218To ensure that a string is a valid number (i.e., in range and containing no 219trailing characters), clear 220.Va errno 221beforehand explicitly, then check it afterwards: 222.Bd -literal -offset indent 223char *ep; 224unsigned long ulval; 225 226\&... 227 228errno = 0; 229ulval = strtoul(buf, &ep, 10); 230if (ep == buf) 231 goto not_a_number; 232if (*ep != '\e0') 233 goto trailing_garbage; 234if (errno) { 235 assert(errno == ERANGE); 236 assert(ulval == ULONG_MAX); 237 goto out_of_range; 238} 239.Ed 240.Pp 241This example will accept 242.Dq 12 243but not 244.Dq 12foo 245or 246.Dq 12\en . 247If trailing whitespace is acceptable, further checks must be done on 248.Va *ep ; 249alternately, use 250.Xr sscanf 3 . 251.Sh ERRORS 252.Bl -tag -width Er 253.It Bq Er EINVAL 254The 255.Ar base 256is not between 2 and 36 and does not contain the special value 0. 257.It Bq Er ERANGE 258The given string was out of range; the value converted has been clamped. 259.El 260.Sh SEE ALSO 261.Xr atof 3 , 262.Xr atoi 3 , 263.Xr atol 3 , 264.Xr atoll 3 , 265.Xr strtod 3 , 266.Xr strtoi 3 , 267.Xr strtoimax 3 , 268.Xr strtol 3 , 269.Xr strtoll 3 , 270.Xr strtou 3 271.Sh STANDARDS 272The 273.Fn strtoul 274function 275conforms to 276.St -ansiC . 277The 278.Fn strtoull 279and 280.Fn strtoumax 281functions conform to 282.St -isoC-99 . 283.Pp 284The 285.Fn strtouq 286function is a 287.Bx 288legacy function equivalent to 289.Fn strtoull 290and should not be used in a new code. 291.Sh BUGS 292Ignores the current locale. 293