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 .\" 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 .\"     @(#)strtol.3    8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdlib/strtol.3,v 1.19 2002/10/10 04:31:57 tjr Exp $
  38 .\"
  39 .Dd November 28, 2001
  40 .Dt STRTOL 3
  41 .Os
  42 .Sh NAME
  43 .Nm strtol , strtoll , strtoimax , strtoq
  44 .Nd "convert a string value to a"
  45 .Vt long , "long long" , intmax_t
  46 or
  47 .Vt quad_t
  48 integer
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In stdlib.h
  53 .In limits.h
  54 .Ft long
  55 .Fn strtol "const char * restrict nptr" "char ** restrict endptr" "int base"
  56 .Ft long long
  57 .Fn strtoll "const char * restrict nptr" "char ** restrict endptr" "int base"
  58 .In inttypes.h
  59 .Ft intmax_t
  60 .Fn strtoimax "const char * restrict nptr" "char ** restrict endptr" "int base"
  61 .In sys/types.h
  62 .In stdlib.h
  63 .In limits.h
  64 .Ft quad_t
  65 .Fn strtoq "const char *nptr" "char **endptr" "int base"
  66 .Sh DESCRIPTION
  67 The
  68 .Fn strtol
  69 function
  70 converts the string in
  71 .Fa nptr
  72 to a
  73 .Vt long
  74 value.
  75 The
  76 .Fn strtoll
  77 function
  78 converts the string in
  79 .Fa nptr
  80 to a
  81 .Vt "long long"
  82 value.
  83 The
  84 .Fn strtoimax
  85 function
  86 converts the string in
  87 .Fa nptr
  88 to an
  89 .Vt intmax_t
  90 value.
  91 The
  92 .Fn strtoq
  93 function
  94 converts the string in
  95 .Fa nptr
  96 to a
  97 .Vt 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 a
 125 .Vt long , "long long" , intmax_t
 126 or
 127 .Vt quad_t
 128 value in the obvious manner,
 129 stopping at the first character which is not a valid digit
 130 in the given base.
 131 (In bases above 10, the letter
 132 .Ql A
 133 in either upper or lower case
 134 represents 10,
 135 .Ql B
 136 represents 11, and so forth, with
 137 .Ql Z
 138 representing 35.)
 139 .Pp
 140 If
 141 .Fa endptr
 142 is not
 143 .Dv NULL ,
 144 .Fn strtol
 145 stores the address of the first invalid character in
 146 .Fa *endptr .
 147 If there were no digits at all, however,
 148 .Fn strtol
 149 stores the original value of
 150 .Fa nptr
 151 in
 152 .Fa *endptr .
 153 (Thus, if
 154 .Fa *nptr
 155 is not
 156 .Ql \e0
 157 but
 158 .Fa **endptr
 159 is
 160 .Ql \e0
 161 on return, the entire string was valid.)
 162 .Sh RETURN VALUES
 163 The
 164 .Fn strtol ,
 165 .Fn strtoll ,
 166 .Fn strtoimax
 167 and
 168 .Fn strtoq
 169 functions
 170 return the result of the conversion,
 171 unless the value would underflow or overflow.
 172 If no conversion could be performed, 0 is returned and
 173 the global variable
 174 .Va errno
 175 is set to
 176 .Er EINVAL .
 177 If an overflow or underflow occurs,
 178 .Va errno
 179 is set to
 180 .Er ERANGE
 181 and the function return value is clamped according
 182 to the following table.
 183 .Bl -column -offset indent ".Fn strtoimax" ".Sy overflow" ".Sy underflow"
 184 .It Sy Function Ta Sy overflow Ta Sy underflow
 185 .It Fn strtol Ta Dv LONG_MIN Ta Dv LONG_MAX
 186 .It Fn strtoll Ta Dv LLONG_MIN Ta Dv LLONG_MAX
 187 .It Fn strtoimax Ta Dv INTMAX_MIN Ta Dv INTMAX_MAX
 188 .It Fn strtoq Ta Dv LLONG_MIN Ta Dv LLONG_MAX
 189 .El
 190 .Sh ERRORS
 191 .Bl -tag -width Er
 192 .It Bq Er EINVAL
 193 The value of
 194 .Fa base
 195 is not supported or
 196 no conversion could be performed.
 197 .It Bq Er ERANGE
 198 The given string was out of range; the value converted has been clamped.
 199 .El
 200 .Sh SEE ALSO
 201 .Xr atof 3 ,
 202 .Xr atoi 3 ,
 203 .Xr atol 3 ,
 204 .Xr strtod 3 ,
 205 .Xr strtoul 3 ,
 206 .Xr wcstol 3
 207 .Sh STANDARDS
 208 The
 209 .Fn strtol
 210 function
 211 conforms to
 212 .St -isoC .
 213 The
 214 .Fn strtoll
 215 and
 216 .Fn strtoimax
 217 functions
 218 conform to
 219 .St -isoC-99 .
 220 The
 221 .Bx
 222 .Fn strtoq
 223 function is deprecated.