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