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