stdlib/FreeBSD/strtol.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 .\"     @(#)strtol.3    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/stdlib/strtol.3,v 1.23 2007/04/10 11:17:00 ru Exp $
  34 .\"
  35 .Dd November 28, 2001
  36 .Dt STRTOL 3
  37 .Os
  38 .Sh NAME
  39 .Nm strtoimax ,
  40 .Nm strtol ,
  41 .Nm strtoll ,
  42 .Nm strtoq
  43 .Nd "convert a string value to a"
  44 .Vt long , "long long" , intmax_t
  45 or
  46 .Vt quad_t
  47 integer
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In inttypes.h
  52 .Ft intmax_t
  53 .Fo strtoimax
  54 .Fa "const char *restrict str"
  55 .Fa "char **restrict endptr"
  56 .Fa "int base"
  57 .Fc
  58 .In stdlib.h
  59 .Ft long
  60 .Fo strtol
  61 .Fa "const char *restrict str"
  62 .Fa "char **restrict endptr"
  63 .Fa "int base"
  64 .Fc
  65 .Ft long long
  66 .Fo strtoll
  67 .Fa "const char *restrict str"
  68 .Fa "char **restrict endptr"
  69 .Fa "int base"
  70 .Fc
  71 .In sys/types.h
  72 .In stdlib.h
  73 .In limits.h
  74 .Ft quad_t
  75 .Fo strtoq
  76 .Fa "const char *str"
  77 .Fa "char **endptr"
  78 .Fa "int base"
  79 .Fc
  80 .Sh DESCRIPTION
  81 The
  82 .Fn strtol
  83 function
  84 converts the string in
  85 .Fa str
  86 to a
  87 .Vt long
  88 value.
  89 The
  90 .Fn strtoll
  91 function
  92 converts the string in
  93 .Fa str
  94 to a
  95 .Vt "long long"
  96 value.
  97 The
  98 .Fn strtoimax
  99 function
 100 converts the string in
 101 .Fa str
 102 to an
 103 .Vt intmax_t
 104 value.
 105 The
 106 .Fn strtoq
 107 function
 108 converts the string in
 109 .Fa str
 110 to a
 111 .Vt quad_t
 112 value.
 113 The conversion is done according to the given
 114 .Fa base ,
 115 which must be between 2 and 36 inclusive,
 116 or be the special value 0.
 117 .Pp
 118 The string may begin with an arbitrary amount of white space
 119 (as determined by
 120 .Xr isspace 3 )
 121 followed by a single optional
 122 .Ql +
 123 or
 124 .Ql -
 125 sign.
 126 If
 127 .Fa base
 128 is zero or 16,
 129 the string may then include a
 130 .Dq Li 0x
 131 prefix,
 132 and the number will be read in base 16; otherwise, a zero
 133 .Fa base
 134 is taken as 10 (decimal) unless the next character is
 135 .Ql 0 ,
 136 in which case it is taken as 8 (octal).
 137 .Pp
 138 The remainder of the string is converted to a
 139 .Vt long , "long long" , intmax_t
 140 or
 141 .Vt quad_t
 142 value in the obvious manner,
 143 stopping at the first character which is not a valid digit
 144 in the given base.
 145 (In bases above 10, the letter
 146 .Ql A
 147 in either upper or lower case
 148 represents 10,
 149 .Ql B
 150 represents 11, and so forth, with
 151 .Ql Z
 152 representing 35.)
 153 .Pp
 154 If
 155 .Fa endptr
 156 is not
 157 .Dv NULL ,
 158 .Fn strtol
 159 stores the address of the first invalid character in
 160 .Fa *endptr .
 161 If there were no digits at all, however,
 162 .Fn strtol
 163 stores the original value of
 164 .Fa str
 165 in
 166 .Fa *endptr .
 167 (Thus, if
 168 .Fa *str
 169 is not
 170 .Ql \e0
 171 but
 172 .Fa **endptr
 173 is
 174 .Ql \e0
 175 on return, the entire string was valid.)
 176 .Pp
 177 Extended locale versions of these functions are documented in
 178 .Xr strtol_l 3 .
 179 See
 180 .Xr xlocale 3
 181 for more information.
 182 .Sh RETURN VALUES
 183 The
 184 .Fn strtol ,
 185 .Fn strtoll ,
 186 .Fn strtoimax ,
 187 and
 188 .Fn strtoq
 189 functions
 190 return the result of the conversion,
 191 unless the value would underflow or overflow.
 192 If no conversion could be performed, 0 is returned and
 193 the global variable
 194 .Va errno
 195 is set to
 196 .Er EINVAL
 197 (the last feature is not portable across all platforms).
 198 If an overflow or underflow occurs,
 199 .Va errno
 200 is set to
 201 .Er ERANGE
 202 and the function return value is clamped according
 203 to the following table.
 204 .Bl -column -offset indent ".Fn strtoimax" ".Dv INTMAX_MIN" ".Dv INTMAX_MAX"
 205 .It Sy Function Ta Sy underflow Ta Sy overflow
 206 .It Fn strtol Ta Dv LONG_MIN Ta Dv LONG_MAX
 207 .It Fn strtoll Ta Dv LLONG_MIN Ta Dv LLONG_MAX
 208 .It Fn strtoimax Ta Dv INTMAX_MIN Ta Dv INTMAX_MAX
 209 .It Fn strtoq Ta Dv LLONG_MIN Ta Dv LLONG_MAX
 210 .El
 211 .Sh ERRORS
 212 .Bl -tag -width Er
 213 .It Bq Er EINVAL
 214 The value of
 215 .Fa base
 216 is not supported or
 217 no conversion could be performed
 218 (the last feature is not portable across all platforms).
 219 .It Bq Er ERANGE
 220 The given string was out of range; the value converted has been clamped.
 221 .El
 222 .Sh LEGACY SYNOPSIS
 223 .Fd #include <stdlib.h>
 224 .Fd #include <limits.h>
 225 .Pp
 226 .In limits.h
 227 is necessary for the
 228 .Fn strtol
 229 and
 230 .Fn strtoll
 231 functions.
 232 .Sh SEE ALSO
 233 .Xr atof 3 ,
 234 .Xr atoi 3 ,
 235 .Xr atol 3 ,
 236 .Xr strtod 3 ,
 237 .Xr strtol_l 3 ,
 238 .Xr strtoul 3 ,
 239 .Xr wcstol 3 ,
 240 .Xr compat 5
 241 .Sh STANDARDS
 242 The
 243 .Fn strtol
 244 function
 245 conforms to
 246 .St -isoC .
 247 The
 248 .Fn strtoll
 249 and
 250 .Fn strtoimax
 251 functions
 252 conform to
 253 .St -isoC-99 .
 254 The
 255 .Bx
 256 .Fn strtoq
 257 function is deprecated.