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