1.\" $NetBSD: strtoul.3,v 1.29 2015/03/10 13:00:58 christos 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 March 10, 2015 37.Dt STRTOUL 3 38.Os 39.Sh NAME 40.Nm strtou , 41.Nm strtoul , 42.Nm strtoull , 43.Nm strtoumax , 44.Nm strtouq 45.Nd convert a string to an unsigned long, unsigned long long, uintmax_t or uquad_t integer 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In stdlib.h 50.In limits.h 51.Ft unsigned long int 52.Fn strtoul "const char * restrict nptr" "char ** restrict endptr" "int base" 53.Ft unsigned long long int 54.Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base" 55.Pp 56.In inttypes.h 57.Ft uintmax_t 58.Fn strtou "const char * restrict nptr" "char ** restrict endptr" "int base" "uintmax_t lo" "uintmax_t hi" "int *rstatus" 59.Ft uintmax_t 60.Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base" 61.Pp 62.In sys/types.h 63.In stdlib.h 64.In limits.h 65.Ft u_quad_t 66.Fn strtouq "const char * restrict nptr" "char ** restrict endptr" "int base" 67.Sh DESCRIPTION 68The 69.Fn strtoul 70function 71converts the string in 72.Fa nptr 73to an 74.Ft unsigned long int 75value. 76The 77.Fn strtoull 78function 79converts the string in 80.Fa nptr 81to an 82.Ft unsigned long long int 83value. 84The 85.Fn strtoumax 86function 87converts the string in 88.Fa nptr 89to an 90.Ft uintmax_t 91value. 92.Fn strtou 93function 94uses internally 95.Fn strtoumax 96and ensures that the result is always in the range [ 97.Fa lo .. 98.Fa hi 99]. 100In adddition it always places 101.Dv 0 102on success or a conversion status in the 103.Fa rstatus 104argument, avoiding the 105.Dv errno 106gymnastics the other functions require. 107The 108.Fa rstatus 109argument can be 110.Dv NULL 111if conversion status is to be ignored. 112The 113.Fn strtouq 114function 115converts the string in 116.Fa nptr 117to a 118.Ft u_quad_t 119value. 120The conversion is done according to the given 121.Fa base , 122which must be between 2 and 36 inclusive, 123or be the special value 0. 124.Pp 125The string may begin with an arbitrary amount of white space 126(as determined by 127.Xr isspace 3 ) 128followed by a single optional 129.Ql + 130or 131.Ql - 132sign. 133If 134.Fa base 135is zero or 16, 136the string may then include a 137.Ql 0x 138prefix, 139and the number will be read in base 16; otherwise, a zero 140.Fa base 141is taken as 10 (decimal) unless the next character is 142.Ql 0 , 143in which case it is taken as 8 (octal). 144.Pp 145The remainder of the string is converted to an 146.Em unsigned long 147value in the obvious manner, 148stopping at the end of the string 149or at the first character that does not produce a valid digit 150in the given base. 151(In bases above 10, the letter 152.Ql A 153in either upper or lower case 154represents 10, 155.Ql B 156represents 11, and so forth, with 157.Ql Z 158representing 35.) 159.Pp 160If 161.Fa endptr 162is non-nil, 163.Fn strtoul 164stores the address of the first invalid character in 165.Fa *endptr . 166If there were no digits at all, however, 167.Fn strtoul 168stores the original value of 169.Fa nptr 170in 171.Fa *endptr . 172(Thus, if 173.Fa *nptr 174is not 175.Ql \e0 176but 177.Fa **endptr 178is 179.Ql \e0 180on return, the entire string was valid.) 181.Sh RETURN VALUES 182The 183.Fn strtou 184function 185always returns the closest value in the range specified by 186the 187.Fa lo 188and 189.Fa hi 190arguments. 191The 192.Fn strtoul 193function 194returns either the result of the conversion 195or, if there was a leading minus sign, 196the negation of the result of the conversion, 197unless the original (non-negated) value would overflow; 198in the latter case, 199.Fn strtoul 200returns 201.Dv ULONG_MAX , 202.Fn strtoull 203returns 204.Dv ULLONG_MAX , 205.Fn strtoumax 206returns 207.Dv UINTMAX_MAX , 208.Fn strtouq 209returns 210.Dv UQUAD_MAX , 211and the global variable 212.Va errno 213is set to 214.Er ERANGE . 215.Pp 216There is no way to determine if 217.Fn strtoul 218has processed a negative number (and returned an unsigned value) short of 219examining the string in 220.Fa nptr 221directly. 222If the 223.Fa base 224argument is not supported then 225.Va errno 226is set to 227.Er EINVAL 228and the functions return 0. 229.Pp 230If no error occurs, 231.Va errno 232is left unchanged. 233This behavior (which is unlike most library functions) is guaranteed 234by the pertinent standards. 235.Sh EXAMPLES 236The 237.Fn strtou 238function is the simplest to use: 239.Bd -literal -offset indent 240int e; 241uintmax_t lval = strtou(buf, NULL, 0, 1, 99, &e); 242if (e) 243 warnc(e, "conversion of `%s' to a number failed, using %ju", 244 buf, lval); 245.Ed 246.Pp 247This will always return a number in 248.Dv [1..99] 249range no matter what the input is, and warn if the conversion failed. 250.Pp 251Because the return value of 252.Fn strtoul 253cannot be used unambiguously to detect an error, 254.Va errno 255is left unchanged after a successful call. 256To ensure that a string is a valid number (i.e., in range and containing no 257trailing characters), clear 258.Va errno 259beforehand explicitly, then check it afterwards: 260.Bd -literal -offset indent 261char *ep; 262unsigned long ulval; 263 264\&... 265 266errno = 0; 267ulval = strtoul(buf, \*[Am]ep, 10); 268if (buf[0] == '\e0' || *ep != '\e0') 269 goto not_a_number; 270if (errno == ERANGE \*[Am]\*[Am] ulval == ULONG_MAX) 271 goto out_of_range; 272.Ed 273.Pp 274This example will accept 275.Dq 12 276but not 277.Dq 12foo 278or 279.Dq 12\en . 280If trailing whitespace is acceptable, further checks must be done on 281.Va *ep ; 282alternately, use 283.Xr sscanf 3 . 284.Sh ERRORS 285.Bl -tag -width Er 286.It Bq Er EINVAL 287The 288.Ar base 289is not between 2 and 36 and does not contain the special value 0. 290.It Bq Er ERANGE 291The given string was out of range; the value converted has been clamped. 292.El 293.Pp 294In addition to the above errors 295.Fn strtou 296returns: 297.Bl -tag -width Er 298.It Bq Er ECANCELED 299The string did not contain any characters that were converted. 300.It Bq Er ENOTSUP 301The string contained non-numeric characters that did not get converted. 302In this case, 303.Fa endptr 304points to the first unconverted character. 305.It Bq Er ERANGE 306The range given was invalid, i.e. 307.Fa lo 308\*[Gt] 309.Fa hi . 310.El 311.Sh SEE ALSO 312.Xr strtoi 3 , 313.Xr strtoimax 3 , 314.Xr strtol 3 , 315.Xr strtoll 3 316.Sh STANDARDS 317The 318.Fn strtoul 319function 320conforms to 321.St -ansiC . 322The 323.Fn strtoull 324and 325.Fn strtoumax 326functions conform to 327.St -isoC-99 . 328The 329.Fn strtou 330function appeared in 331.Nx 8 . 332.Sh BUGS 333Ignores the current locale. 334