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