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