lib/libc/stdlib/strtoul.3

   1 .\"     $NetBSD: strtoul.3,v 1.25 2009/12/02 12:50:27 pooka 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 December 2, 2009
  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 The conversion is done according to the given
  98 .Fa base ,
  99 which must be between 2 and 36 inclusive,
 100 or be the special value 0.
 101 .Pp
 102 The string may begin with an arbitrary amount of white space
 103 (as determined by
 104 .Xr isspace 3 )
 105 followed by a single optional
 106 .Ql +
 107 or
 108 .Ql -
 109 sign.
 110 If
 111 .Fa base
 112 is zero or 16,
 113 the string may then include a
 114 .Ql 0x
 115 prefix,
 116 and the number will be read in base 16; otherwise, a zero
 117 .Fa base
 118 is taken as 10 (decimal) unless the next character is
 119 .Ql 0 ,
 120 in which case it is taken as 8 (octal).
 121 .Pp
 122 The remainder of the string is converted to an
 123 .Em unsigned long
 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,
 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 function
 162 returns either the result of the conversion
 163 or, if there was a leading minus sign,
 164 the negation of the result of the conversion,
 165 unless the original (non-negated) value would overflow;
 166 in the latter case,
 167 .Fn strtoul
 168 returns
 169 .Dv ULONG_MAX ,
 170 .Fn strtoull
 171 returns
 172 .Dv ULLONG_MAX ,
 173 .Fn strtoumax
 174 returns
 175 .Dv UINTMAX_MAX ,
 176 .Fn strtouq
 177 returns
 178 .Dv UQUAD_MAX ,
 179 and the global variable
 180 .Va errno
 181 is set to
 182 .Er ERANGE .
 183 .Pp
 184 There is no way to determine if
 185 .Fn strtoul
 186 has processed a negative number (and returned an unsigned value) short of
 187 examining the string in
 188 .Fa nptr
 189 directly.
 190 If the
 191 .Fa base
 192 argument is not supported then
 193 .Va errno
 194 is set to
 195 .Er EINVAL
 196 and the functions return 0.
 197 .Pp
 198 If no error occurs,
 199 .Va errno
 200 is left unchanged.
 201 This behavior (which is unlike most library functions) is guaranteed
 202 by the pertinent standards.
 203 .Sh EXAMPLES
 204 Because the return value of
 205 .Fn strtoul
 206 cannot be used unambiguously to detect an error,
 207 .Va errno
 208 is left unchanged after a successful call.
 209 To ensure that a string is a valid number (i.e., in range and containing no
 210 trailing characters), clear
 211 .Va errno
 212 beforehand explicitly, then check it afterwards:
 213 .Bd -literal -offset indent
 214 char *ep;
 215 unsigned long ulval;
 216
 217 \&...
 218
 219 errno = 0;
 220 ulval = strtoul(buf, \*[Am]ep, 10);
 221 if (buf[0] == '\e0' || *ep != '\e0')
 222         goto not_a_number;
 223 if (errno == ERANGE \*[Am]\*[Am] ulval == ULONG_MAX)
 224         goto out_of_range;
 225 .Ed
 226 .Pp
 227 This example will accept
 228 .Dq 12
 229 but not
 230 .Dq 12foo
 231 or
 232 .Dq 12\en .
 233 If trailing whitespace is acceptable, further checks must be done on
 234 .Va *ep ;
 235 alternately, use
 236 .Xr sscanf 3 .
 237 .Sh ERRORS
 238 .Bl -tag -width Er
 239 .It Bq Er EINVAL
 240 The
 241 .Ar base
 242 is not between 2 and 36 and does not contain the special value 0.
 243 .It Bq Er ERANGE
 244 The given string was out of range; the value converted has been clamped.
 245 .El
 246 .Sh SEE ALSO
 247 .Xr strtoimax 3 ,
 248 .Xr strtol 3 ,
 249 .Xr strtoll 3
 250 .Sh STANDARDS
 251 The
 252 .Fn strtoul
 253 function
 254 conforms to
 255 .St -ansiC .
 256 The
 257 .Fn strtoull
 258 and
 259 .Fn strtoumax
 260 functions conform to
 261 .St -isoC-99 .
 262 .Sh BUGS
 263 Ignores the current locale.