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. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the University of 19.\" California, Berkeley and its contributors. 20.\" 4. Neither the name of the University nor the names of its contributors 21.\" may be used to endorse or promote products derived from this software 22.\" without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" @(#)strtoul.3 8.1 (Berkeley) 6/4/93 37.\" $FreeBSD$ 38.\" 39.Dd June 4, 1993 40.Dt STRTOUL 3 41.Os 42.Sh NAME 43.Nm strtoul , strtoull , strtoumax , strtouq 44.Nd "convert a string to an unsigned long, unsigned long long, uintmax_t, or uquad_t integer" 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 *nptr" "char **endptr" "int base" 52.Ft unsigned long long 53.Fn strtoull "const char *nptr" "char **endptr" "int base" 54.In inttypes.h 55.Ft uintmax_t 56.Fn strtoumax "const char *nptr" "char **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.Em unsigned long 70value. 71The 72.Fn strtoull 73function 74converts the string in 75.Fa nptr 76to an 77.Em unsigned long long 78value. 79The 80.Fn strtoumax 81function 82converts the string in 83.Fa nptr 84to an 85.Em uintmax_t 86value. 87The 88.Fn strtouq 89function 90converts the string in 91.Fa nptr 92to a 93.Em 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.Ql 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.Em 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 non nil, 138.Fn strtoul 139stores the address of the first invalid character in 140.Fa *endptr . 141If there were no digits at all, however, 142.Fn strtoul 143stores the original value of 144.Fa nptr 145in 146.Fa *endptr . 147(Thus, if 148.Fa *nptr 149is not 150.Ql \e0 151but 152.Fa **endptr 153is 154.Ql \e0 155on return, the entire string was valid.) 156.Sh RETURN VALUES 157The 158.Fn strtoul , 159.Fn strtoull , 160.Fn strtoumax 161or 162.Fn strtouq 163function 164returns either the result of the conversion 165or, if there was a leading minus sign, 166the negation of the result of the conversion, 167unless the original (non-negated) value would overflow; 168in the latter case, 169.Fn strtoul 170returns 171.Dv ULONG_MAX , 172.Fn strtoull 173returns 174.Dv ULLONG_MAX , 175.Fn strtoumax 176returns 177.Dv UINTMAX_MAX 178and 179.Fn strtouq 180returns 181.Dv ULLONG_MAX . 182In all cases, 183.Va errno 184is set to 185.Er ERANGE . 186If no conversion could be performed, 0 is returned and 187the global variable 188.Va errno 189is set to 190.Er EINVAL . 191.Sh ERRORS 192.Bl -tag -width Er 193.It Bq Er EINVAL 194The value of 195.Fa base 196is not supported or 197no conversion could be performed. 198.It Bq Er ERANGE 199The given string was out of range; the value converted has been clamped. 200.El 201.Sh SEE ALSO 202.Xr strtol 3 203.Sh STANDARDS 204The 205.Fn strtoul 206function 207conforms to 208.St -isoC . 209The 210.Fn strtoull 211and 212.Fn strtoumax 213functions 214conform to 215.St -isoC-99 . 216The 217.Bx 218.Fn strtouq 219function is deprecated. 220