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