lib/libc/stdlib/strtol.3

   1 .\"     $NetBSD: strtol.3,v 1.25 2009/07/23 02:54:27 dholland Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Chris Torek and the American National Standards Committee X3,
   8 .\" on Information Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     from: @(#)strtol.3      8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd July 23, 2009
  37 .Dt STRTOL 3
  38 .Os
  39 .Sh NAME
  40 .Nm strtol ,
  41 .Nm strtoll ,
  42 .Nm strtoimax ,
  43 .Nm strtoq
  44 .Nd convert string value to a long, long long, intmax_t or quad_t integer
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In stdlib.h
  49 .In limits.h
  50 .Ft long int
  51 .Fn strtol "const char * restrict nptr" "char ** restrict endptr" "int base"
  52 .Ft long long int
  53 .Fn strtoll "const char * restrict nptr" "char ** restrict endptr" "int base"
  54 .Pp
  55 .In inttypes.h
  56 .Ft intmax_t
  57 .Fn strtoimax "const char * restrict nptr" "char ** restrict endptr" "int base"
  58 .Pp
  59 .In sys/types.h
  60 .In stdlib.h
  61 .In limits.h
  62 .Ft quad_t
  63 .Fn strtoq "const char * restrict nptr" "char ** restrict endptr" "int base"
  64 .Sh DESCRIPTION
  65 The
  66 .Fn strtol
  67 function
  68 converts the string in
  69 .Fa nptr
  70 to a
  71 .Ft long int
  72 value.
  73 The
  74 .Fn strtoll
  75 function
  76 converts the string in
  77 .Fa nptr
  78 to a
  79 .Ft long long int
  80 value.
  81 The
  82 .Fn strtoimax
  83 function
  84 converts the string in
  85 .Fa nptr
  86 to an
  87 .Ft intmax_t
  88 value.
  89 The
  90 .Fn strtoq
  91 function
  92 converts the string in
  93 .Fa nptr
  94 to a
  95 .Ft quad_t
  96 value.
  97 The conversion is done according to the given
  98 .Fa base ,
  99 which must be between 2 and 36 inclusive,
 100 or be the special value 0.
 101 .Pp
 102 The string may begin with an arbitrary amount of white space
 103 (as determined by
 104 .Xr isspace 3 )
 105 followed by a single optional
 106 .Ql +
 107 or
 108 .Ql -
 109 sign.
 110 If
 111 .Fa base
 112 is zero or 16,
 113 the string may then include a
 114 .Ql 0x
 115 prefix,
 116 and the number will be read in base 16; otherwise, a zero
 117 .Fa base
 118 is taken as 10 (decimal) unless the next character is
 119 .Ql 0 ,
 120 in which case it is taken as 8 (octal).
 121 .Pp
 122 The remainder of the string is converted to a
 123 .Em long
 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 non-nil,
 139 .Fn strtol
 140 stores the address of the first invalid character in
 141 .Fa *endptr .
 142 If there were no digits at all, however,
 143 .Fn strtol
 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 strtol
 160 function
 161 returns the result of the conversion,
 162 unless the value would underflow or overflow.
 163 If an underflow occurs,
 164 .Fn strtol
 165 returns
 166 .Dv LONG_MIN ,
 167 .Fn strtoll
 168 returns
 169 .Dv LLONG_MIN ,
 170 and
 171 .Fn strtoimax
 172 returns
 173 .Dv INTMAX_MIN .
 174 If an overflow occurs,
 175 .Fn strtol
 176 returns
 177 .Dv LONG_MAX ,
 178 .Fn strtoll
 179 returns
 180 .Dv LLONG_MAX ,
 181 and
 182 .Fn strtoimax
 183 returns
 184 .Dv INTMAX_MAX .
 185 In these cases,
 186 .Va errno
 187 is set to
 188 .Er ERANGE .
 189 If the
 190 .Fa base
 191 argument is not supported then
 192 .Va errno
 193 is set to
 194 .Er EINVAL
 195 and the functions return 0.
 196 .Pp
 197 If no error occurs,
 198 .Va errno
 199 is left unchanged.
 200 This behavior (which is unlike most library functions) is guaranteed
 201 by the pertinent standards.
 202 .Sh EXAMPLES
 203 Because the return value of
 204 .Fn strtol
 205 cannot be used unambiguously to detect an error,
 206 .Va errno
 207 is left unchanged after a successful call.
 208 To ensure that a string is a valid number (i.e., in range and containing no
 209 trailing characters), clear
 210 .Va errno
 211 beforehand explicitly, then check it afterwards:
 212 .Bd -literal -offset indent
 213 char *ep;
 214 long lval;
 215
 216 \&...
 217
 218 errno = 0;
 219 lval = strtol(buf, \*[Am]ep, 10);
 220 if (buf[0] == '\e0' || *ep != '\e0')
 221         goto not_a_number;
 222 if (errno == ERANGE \*[Am]\*[Am] (lval == LONG_MAX || lval == LONG_MIN))
 223         goto out_of_range;
 224 .Ed
 225 .Pp
 226 This example will accept
 227 .Dq 12
 228 but not
 229 .Dq 12foo
 230 or
 231 .Dq 12\en .
 232 If trailing whitespace is acceptable, further checks must be done on
 233 .Va *ep ;
 234 alternately, use
 235 .Xr sscanf 3 .
 236 .Pp
 237 If
 238 .Fn strtol
 239 is being used instead of
 240 .Xr atoi 3 ,
 241 error checking is further complicated because the desired return value is an
 242 .Li int
 243 rather than a
 244 .Li long ;
 245 however, on some architectures integers and long integers are the same size.
 246 Thus the following is necessary:
 247 .Bd -literal -offset indent
 248 char *ep;
 249 int ival;
 250 long lval;
 251
 252 \&...
 253
 254 errno = 0;
 255 lval = strtol(buf, \*[Am]ep, 10);
 256 if (buf[0] == '\e0' || *ep != '\e0')
 257         goto not_a_number;
 258 if ((errno == ERANGE \*[Am]\*[Am] (lval == LONG_MAX || lval == LONG_MIN)) ||
 259     (lval \*[Gt] INT_MAX || lval \*[Lt] INT_MIN))
 260         goto out_of_range;
 261 ival = lval;
 262 .Ed
 263 .Sh ERRORS
 264 .Bl -tag -width Er
 265 .It Bq Er EINVAL
 266 The
 267 .Ar base
 268 is not between 2 and 36 and does not contain the special value 0.
 269 .It Bq Er ERANGE
 270 The given string was out of range; the value converted has been clamped.
 271 .El
 272 .Sh SEE ALSO
 273 .Xr atof 3 ,
 274 .Xr atoi 3 ,
 275 .Xr atol 3 ,
 276 .Xr atoll 3 ,
 277 .Xr strtod 3 ,
 278 .Xr strtoul 3 ,
 279 .Xr strtoull 3 ,
 280 .Xr strtoumax 3
 281 .Sh STANDARDS
 282 The
 283 .Fn strtol
 284 function
 285 conforms to
 286 .St -ansiC .
 287 The
 288 .Fn strtoll
 289 and
 290 .Fn strtoimax
 291 functions conform to
 292 .St -isoC-99 .
 293 .Sh BUGS
 294 Ignores the current locale.