lib/libc/stdlib/strtol.3

   1 .\"     $NetBSD: strtol.3,v 1.32 2015/05/01 14:17:56 christos 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 April 30, 2015
  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 .Pp
  98 The conversion is done according to the given
  99 .Fa base ,
 100 which must be between 2 and 36 inclusive,
 101 or be the special value 0.
 102 .Pp
 103 The string may begin with an arbitrary amount of white space
 104 (as determined by
 105 .Xr isspace 3 )
 106 followed by a single optional
 107 .Ql +
 108 or
 109 .Ql -
 110 sign.
 111 If
 112 .Fa base
 113 is zero or 16,
 114 the string may then include a
 115 .Ql 0x
 116 prefix,
 117 and the number will be read in base 16; otherwise, a zero
 118 .Fa base
 119 is taken as 10 (decimal) unless the next character is
 120 .Ql 0 ,
 121 in which case it is taken as 8 (octal).
 122 .Pp
 123 The remainder of the string is converted to an appropriate value
 124 in the obvious manner,
 125 stopping at the first character which is not a valid digit 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 non-nil, the functions store the address of the first invalid character in
 138 .Fa *endptr .
 139 If there were no digits at all, however,
 140 the functions store the original value of
 141 .Fa nptr
 142 in
 143 .Fa *endptr .
 144 (Thus, if
 145 .Fa *nptr
 146 is not
 147 .Ql \e0
 148 but
 149 .Fa **endptr
 150 is
 151 .Ql \e0
 152 on return, the entire string was valid.)
 153 .Sh RETURN VALUES
 154 The
 155 .Fn strtol
 156 function
 157 returns the result of the conversion,
 158 unless the value would underflow or overflow.
 159 If an underflow occurs,
 160 .Fn strtol
 161 returns
 162 .Dv LONG_MIN ,
 163 .Fn strtoll
 164 returns
 165 .Dv LLONG_MIN ,
 166 and
 167 .Fn strtoimax
 168 returns
 169 .Dv INTMAX_MIN .
 170 If an overflow occurs,
 171 .Fn strtol
 172 returns
 173 .Dv LONG_MAX ,
 174 .Fn strtoll
 175 returns
 176 .Dv LLONG_MAX ,
 177 and
 178 .Fn strtoimax
 179 returns
 180 .Dv INTMAX_MAX .
 181 In these cases,
 182 .Va errno
 183 is set to
 184 .Er ERANGE .
 185 If the
 186 .Fa base
 187 argument is not supported then
 188 .Va errno
 189 is set to
 190 .Er EINVAL
 191 and the functions return 0.
 192 .Pp
 193 If no error occurs,
 194 .Va errno
 195 is left unchanged.
 196 This behavior (which is unlike most library functions) is guaranteed
 197 by the pertinent standards.
 198 .Sh EXAMPLES
 199 Because the return value of
 200 .Fn strtol
 201 cannot be used unambiguously to detect an error,
 202 .Va errno
 203 is left unchanged after a successful call.
 204 To ensure that a string is a valid number (i.e., in range and containing no
 205 trailing characters), clear
 206 .Va errno
 207 beforehand explicitly, then check it afterwards:
 208 .Bd -literal -offset indent
 209 char *ep;
 210 long lval;
 211
 212 \&...
 213
 214 errno = 0;
 215 lval = strtol(buf, \*[Am]ep, 10);
 216 if (buf[0] == '\e0' || *ep != '\e0')
 217         goto not_a_number;
 218 if (errno == ERANGE \*[Am]\*[Am] (lval == LONG_MAX || lval == LONG_MIN))
 219         goto out_of_range;
 220 .Ed
 221 .Pp
 222 This example will accept
 223 .Dq 12
 224 but not
 225 .Dq 12foo
 226 or
 227 .Dq 12\en .
 228 If trailing whitespace is acceptable, further checks must be done on
 229 .Va *ep ;
 230 alternately, use
 231 .Xr sscanf 3 .
 232 .Pp
 233 If
 234 .Fn strtol
 235 is being used instead of
 236 .Xr atoi 3 ,
 237 error checking is further complicated because the desired return value is an
 238 .Li int
 239 rather than a
 240 .Li long ;
 241 however, on some architectures integers and long integers are the same size.
 242 Thus the following is necessary:
 243 .Bd -literal -offset indent
 244 char *ep;
 245 int ival;
 246 long lval;
 247
 248 \&...
 249
 250 errno = 0;
 251 lval = strtol(buf, \*[Am]ep, 10);
 252 if (buf[0] == '\e0' || *ep != '\e0')
 253         goto not_a_number;
 254 if ((errno == ERANGE \*[Am]\*[Am] (lval == LONG_MAX || lval == LONG_MIN)) ||
 255     (lval \*[Gt] INT_MAX || lval \*[Lt] INT_MIN))
 256         goto out_of_range;
 257 ival = lval;
 258 .Ed
 259 .Sh ERRORS
 260 .Bl -tag -width Er
 261 .It Bq Er EINVAL
 262 The
 263 .Ar base
 264 is not between 2 and 36 and does not contain the special value 0.
 265 .It Bq Er ERANGE
 266 The given string was out of range; the value converted has been clamped.
 267 .El
 268 .Sh SEE ALSO
 269 .Xr atof 3 ,
 270 .Xr atoi 3 ,
 271 .Xr atol 3 ,
 272 .Xr atoll 3 ,
 273 .Xr strtod 3 ,
 274 .Xr strtou 3 ,
 275 .Xr strtoul 3 ,
 276 .Xr strtoull 3 ,
 277 .Xr strtoumax 3
 278 .Sh STANDARDS
 279 The
 280 .Fn strtol
 281 function
 282 conforms to
 283 .St -ansiC .
 284 The
 285 .Fn strtoll
 286 and
 287 .Fn strtoimax
 288 functions conform to
 289 .St -isoC-99 .
 290 .Pp
 291 The
 292 .Fn strtoq
 293 function is a
 294 .Bx
 295 legacy function equivalent to
 296 .Fn strtoll
 297 and should not be used in a new code.
 298 .Sh BUGS
 299 Ignores the current locale.