stdlib/FreeBSD/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 , strtoull , strtoumax , 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 .Sh ERRORS
 197 .Bl -tag -width Er
 198 .It Bq Er EINVAL
 199 The value of
 200 .Fa base
 201 is not supported or
 202 no conversion could be performed.
 203 .It Bq Er ERANGE
 204 The given string was out of range; the value converted has been clamped.
 205 .El
 206 .Sh SEE ALSO
 207 .Xr strtol 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.