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