lib/libc/stdlib/strtoul.3

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