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