lib/libc/stdlib/strtoul.3

   1 .\"     $NetBSD: strtoul.3,v 1.31 2015/05/03 12:29:28 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Chris Torek and the American National Standards Committee X3,
   8 .\" on Information Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     from: @(#)strtoul.3     8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd April 30, 2015
  37 .Dt STRTOUL 3
  38 .Os
  39 .Sh NAME
  40 .Nm strtoul ,
  41 .Nm strtoull ,
  42 .Nm strtoumax ,
  43 .Nm strtouq
  44 .Nd convert a string to an unsigned long, unsigned long long, uintmax_t or uquad_t integer
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In stdlib.h
  49 .In limits.h
  50 .Ft unsigned long int
  51 .Fn strtoul "const char * restrict nptr" "char ** restrict endptr" "int base"
  52 .Ft unsigned long long int
  53 .Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base"
  54 .Pp
  55 .In inttypes.h
  56 .Ft uintmax_t
  57 .Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base"
  58 .Pp
  59 .In sys/types.h
  60 .In stdlib.h
  61 .In limits.h
  62 .Ft u_quad_t
  63 .Fn strtouq "const char * restrict nptr" "char ** restrict endptr" "int base"
  64 .Sh DESCRIPTION
  65 The
  66 .Fn strtoul
  67 function
  68 converts the string in
  69 .Fa nptr
  70 to an
  71 .Ft unsigned long int
  72 value.
  73 The
  74 .Fn strtoull
  75 function
  76 converts the string in
  77 .Fa nptr
  78 to an
  79 .Ft unsigned long long int
  80 value.
  81 The
  82 .Fn strtoumax
  83 function
  84 converts the string in
  85 .Fa nptr
  86 to an
  87 .Ft uintmax_t
  88 value.
  89 The
  90 .Fn strtouq
  91 function
  92 converts the string in
  93 .Fa nptr
  94 to a
  95 .Ft u_quad_t
  96 value.
  97 .Pp
  98 The conversion is done according to the given
  99 .Fa base ,
 100 which must be between 2 and 36 inclusive,
 101 or be the special value 0.
 102 .Pp
 103 The string may begin with an arbitrary amount of white space
 104 (as determined by
 105 .Xr isspace 3 )
 106 followed by a single optional
 107 .Ql +
 108 or
 109 .Ql -
 110 sign.
 111 If
 112 .Fa base
 113 is zero or 16,
 114 the string may then include a
 115 .Ql 0x
 116 prefix,
 117 and the number will be read in base 16; otherwise, a zero
 118 .Fa base
 119 is taken as 10 (decimal) unless the next character is
 120 .Ql 0 ,
 121 in which case it is taken as 8 (octal).
 122 .Pp
 123 The remainder of the string is converted to an appropriate
 124 value in the obvious manner,
 125 stopping at the end of the string
 126 or at the first character that does not produce a valid digit
 127 in the given base.
 128 (In bases above 10, the letter
 129 .Ql A
 130 in either upper or lower case
 131 represents 10,
 132 .Ql B
 133 represents 11, and so forth, with
 134 .Ql Z
 135 representing 35.)
 136 .Pp
 137 If
 138 .Fa endptr
 139 is non-nil, the functions store the address of the first invalid character in
 140 .Fa *endptr .
 141 If there were no digits at all, however,
 142 the functions store the original value of
 143 .Fa nptr
 144 in
 145 .Fa *endptr .
 146 (Thus, if
 147 .Fa *nptr
 148 is not
 149 .Ql \e0
 150 but
 151 .Fa **endptr
 152 is
 153 .Ql \e0
 154 on return, the entire string was valid.)
 155 .Sh RETURN VALUES
 156 The
 157 .Fn strtoul
 158 function
 159 returns either the result of the conversion
 160 or, if there was a leading minus sign,
 161 the negation of the result of the conversion,
 162 unless the original (non-negated) value would overflow;
 163 in the latter case,
 164 .Fn strtoul
 165 returns
 166 .Dv ULONG_MAX ,
 167 .Fn strtoull
 168 returns
 169 .Dv ULLONG_MAX ,
 170 .Fn strtoumax
 171 returns
 172 .Dv UINTMAX_MAX ,
 173 .Fn strtouq
 174 returns
 175 .Dv UQUAD_MAX ,
 176 and the global variable
 177 .Va errno
 178 is set to
 179 .Er ERANGE .
 180 .Pp
 181 There is no way to determine if
 182 .Fn strtoul
 183 has processed a negative number (and returned an unsigned value) short of
 184 examining the string in
 185 .Fa nptr
 186 directly.
 187 If the
 188 .Fa base
 189 argument is not supported then
 190 .Va errno
 191 is set to
 192 .Er EINVAL
 193 and the functions return 0.
 194 .Pp
 195 If no error occurs,
 196 .Va errno
 197 is left unchanged.
 198 This behavior (which is unlike most library functions) is guaranteed
 199 by the pertinent standards.
 200 .Sh EXAMPLES
 201 Because the return value of
 202 .Fn strtoul
 203 cannot be used unambiguously to detect an error,
 204 .Va errno
 205 is left unchanged after a successful call.
 206 To ensure that a string is a valid number (i.e., in range and containing no
 207 trailing characters), clear
 208 .Va errno
 209 beforehand explicitly, then check it afterwards:
 210 .Bd -literal -offset indent
 211 char *ep;
 212 unsigned long ulval;
 213
 214 \&...
 215
 216 errno = 0;
 217 ulval = strtoul(buf, \*[Am]ep, 10);
 218 if (buf[0] == '\e0' || *ep != '\e0')
 219         goto not_a_number;
 220 if (errno == ERANGE \*[Am]\*[Am] ulval == ULONG_MAX)
 221         goto out_of_range;
 222 .Ed
 223 .Pp
 224 This example will accept
 225 .Dq 12
 226 but not
 227 .Dq 12foo
 228 or
 229 .Dq 12\en .
 230 If trailing whitespace is acceptable, further checks must be done on
 231 .Va *ep ;
 232 alternately, use
 233 .Xr sscanf 3 .
 234 .Sh ERRORS
 235 .Bl -tag -width Er
 236 .It Bq Er EINVAL
 237 The
 238 .Ar base
 239 is not between 2 and 36 and does not contain the special value 0.
 240 .It Bq Er ERANGE
 241 The given string was out of range; the value converted has been clamped.
 242 .El
 243 .Sh SEE ALSO
 244 .Xr atof 3 ,
 245 .Xr atoi 3 ,
 246 .Xr atol 3 ,
 247 .Xr atoll 3 ,
 248 .Xr strtod 3 ,
 249 .Xr strtoi 3 ,
 250 .Xr strtoimax 3 ,
 251 .Xr strtol 3 ,
 252 .Xr strtoll 3 ,
 253 .Xr strtou 3
 254 .Sh STANDARDS
 255 The
 256 .Fn strtoul
 257 function
 258 conforms to
 259 .St -ansiC .
 260 The
 261 .Fn strtoull
 262 and
 263 .Fn strtoumax
 264 functions conform to
 265 .St -isoC-99 .
 266 .Pp
 267 The
 268 .Fn strtouq
 269 function is a
 270 .Bx
 271 legacy function equivalent to
 272 .Fn strtoull
 273 and should not be used in a new code.
 274 .Sh BUGS
 275 Ignores the current locale.