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