1.\" Copyright (c) 1990, 1991, 1993 2.\" The Regents of the University of California. 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.\" @(#)strtoul.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD: src/lib/libc/stdlib/strtoul.3,v 1.23 2007/01/09 00:28:10 imp Exp $ 34.\" 35.Dd December 25, 2013 36.Dt STRTOUL 3 37.Os 38.Sh NAME 39.Nm strtoul , 40.Nm strtoul_l , 41.Nm strtoull , 42.Nm strtoull_l , 43.Nm strtoumax , 44.Nm strtoumax_l , 45.Nm strtouq 46.Nd "convert a string to an" 47.Vt "unsigned long" , "unsigned long long" , uintmax_t , 48or 49.Vt u_quad_t 50integer 51.Sh LIBRARY 52.Lb libc 53.Sh SYNOPSIS 54.In stdlib.h 55.In limits.h 56.Ft "unsigned long" 57.Fn strtoul "const char * restrict nptr" "char ** restrict endptr" "int base" 58.Ft "unsigned long long" 59.Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base" 60.In inttypes.h 61.Ft uintmax_t 62.Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base" 63.In sys/types.h 64.Ft u_quad_t 65.Fn strtouq "const char *nptr" "char **endptr" "int base" 66.In xlocale.h 67.Ft "unsigned long" 68.Fn strtoul_l "const char * restrict nptr" "char ** restrict endptr" "int base" "locale_t locale" 69.Ft "unsigned long long" 70.Fn strtoull_l "const char * restrict nptr" "char ** restrict endptr" "int base" "locale_t locale" 71.Ft uintmax_t 72.Fn strtoumax_l "const char * restrict nptr" "char ** restrict endptr" "int base" "locale_t locale" 73.Sh DESCRIPTION 74The 75.Fn strtoul 76and 77.Fn strtoul_l 78functions convert the string in 79.Fa nptr 80to an 81.Vt "unsigned long" 82value. 83The 84.Fn strtoull 85and 86.Fn strtoull_l 87functions convert the string in 88.Fa nptr 89to an 90.Vt "unsigned long long" 91value. 92The 93.Fn strtoumax 94and 95.Fn strtoumax_l 96functions convert the string in 97.Fa nptr 98to an 99.Vt uintmax_t 100value. 101The 102.Fn strtouq 103function 104converts the string in 105.Fa nptr 106to a 107.Vt u_quad_t 108value. 109The conversion is done according to the given 110.Fa base , 111which must be between 2 and 36 inclusive, 112or be the special value 0. 113.Pp 114The string may begin with an arbitrary amount of white space 115(as determined by 116.Xr isspace 3 117or 118.Xr isspace_l 3 ) 119followed by a single optional 120.Ql + 121or 122.Ql - 123sign. 124If 125.Fa base 126is zero or 16, 127the string may then include a 128.Dq Li 0x 129prefix, 130and the number will be read in base 16; otherwise, a zero 131.Fa base 132is taken as 10 (decimal) unless the next character is 133.Ql 0 , 134in which case it is taken as 8 (octal). 135.Pp 136The remainder of the string is converted to an 137.Vt "unsigned long" 138value in the obvious manner, 139stopping at the end of the string 140or at the first character that does not produce a valid digit 141in the given base. 142(In bases above 10, the letter 143.Ql A 144in either upper or lower case 145represents 10, 146.Ql B 147represents 11, and so forth, with 148.Ql Z 149representing 35.) 150.Pp 151If 152.Fa endptr 153is not 154.Dv NULL , 155.Fn strtoul 156and 157.Fn strtoul_l 158store the address of the first invalid character in 159.Fa *endptr . 160If there were no digits at all, however, 161.Fn strtoul 162and 163.Fn strtoul_l 164store the original value of 165.Fa nptr 166in 167.Fa *endptr . 168(Thus, if 169.Fa *nptr 170is not 171.Ql \e0 172but 173.Fa **endptr 174is 175.Ql \e0 176on return, the entire string was valid.) 177.Pp 178The 179.Fn strtoul_l , 180.Fn strtoull_l , 181and 182.Fn strtoumax_l 183functions take an explicit 184.Fa locale 185argument, whereas the 186.Fn strtoul , 187.Fn strtoull , 188.Fn strtoumax , 189and 190.Fn strtouq 191functions use the current global or per-thread locale. 192.Sh RETURN VALUES 193The 194.Fn strtoul , 195.Fn strtoul_l , 196.Fn strtoull , 197.Fn strtoull_l , 198.Fn strtoumax , 199.Fn strtoumax_l , 200and 201.Fn strtouq 202functions 203return either the result of the conversion 204or, if there was a leading minus sign, 205the negation of the result of the conversion, 206unless the original (non-negated) value would overflow; 207in the latter case, 208.Fn strtoul 209and 210.Fn strtoul_l 211return 212.Dv ULONG_MAX , 213.Fn strtoull 214and 215.Fn strtoull_l 216return 217.Dv ULLONG_MAX , 218.Fn strtoumax 219and 220.Fn strtoumax_l 221return 222.Dv UINTMAX_MAX , 223and 224.Fn strtouq 225returns 226.Dv ULLONG_MAX . 227In all cases, 228.Va errno 229is set to 230.Er ERANGE . 231If no conversion could be performed, 0 is returned and 232the global variable 233.Va errno 234is set to 235.Er EINVAL 236(the last feature is not portable across all platforms). 237.Sh ERRORS 238.Bl -tag -width Er 239.It Bq Er EINVAL 240The value of 241.Fa base 242is not supported or 243no conversion could be performed 244(the last feature is not portable across all platforms). 245.It Bq Er ERANGE 246The given string was out of range; the value converted has been clamped. 247.El 248.Sh SEE ALSO 249.Xr strtol 3 , 250.Xr strtonum 3 , 251.Xr wcstoul 3 , 252.Xr xlocale 3 253.Sh STANDARDS 254The 255.Fn strtoul 256function 257conforms to 258.St -isoC . 259The 260.Fn strtoull 261and 262.Fn strtoumax 263functions 264conform to 265.St -isoC-99 . 266The 267.Bx 268.Fn strtouq 269function is deprecated. 270