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