manual/=limits.texinfo

   1 @node Representation Limits, System Configuration Limits, System Information, Top
   2 @chapter Representation Limits
   3
   4 This chapter contains information about constants and parameters that
   5 characterize the representation of the various integer and
   6 floating-point types supported by the GNU C library.
   7
   8 @menu
   9 * Integer Representation Limits::       Determining maximum and minimum
  10                                          representation values of
  11                                          various integer subtypes.
  12 * Floating-Point Limits ::              Parameters which characterize
  13                                          supported floating-point
  14                                          representations on a particular
  15                                          system.
  16 @end menu
  17
  18 @node Integer Representation Limits, Floating-Point Limits ,  , Representation Limits
  19 @section Integer Representation Limits
  20 @cindex integer representation limits
  21 @cindex representation limits, integer
  22 @cindex limits, integer representation
  23
  24 Sometimes it is necessary for programs to know about the internal
  25 representation of various integer subtypes.  For example, if you want
  26 your program to be careful not to overflow an @code{int} counter
  27 variable, you need to know what the largest representable value that
  28 fits in an @code{int} is.  These kinds of parameters can vary from
  29 compiler to compiler and machine to machine.  Another typical use of
  30 this kind of parameter is in conditionalizing data structure definitions
  31 with @samp{#ifdef} to select the most appropriate integer subtype that
  32 can represent the required range of values.
  33
  34 Macros representing the minimum and maximum limits of the integer types
  35 are defined in the header file @file{limits.h}.  The values of these
  36 macros are all integer constant expressions.
  37 @pindex limits.h
  38
  39 @comment limits.h
  40 @comment ISO
  41 @deftypevr Macro int CHAR_BIT
  42 This is the number of bits in a @code{char}, usually eight.
  43 @end deftypevr
  44
  45 @comment limits.h
  46 @comment ISO
  47 @deftypevr Macro int SCHAR_MIN
  48 This is the minimum value that can be represented by a @code{signed char}.
  49 @end deftypevr
  50
  51 @comment limits.h
  52 @comment ISO
  53 @deftypevr Macro int SCHAR_MAX
  54 This is the maximum value that can be represented by a @code{signed char}.
  55 @end deftypevr
  56
  57 @comment limits.h
  58 @comment ISO
  59 @deftypevr Macro int UCHAR_MAX
  60 This is the maximum value that can be represented by a @code{unsigned char}.
  61 (The minimum value of an @code{unsigned char} is zero.)
  62 @end deftypevr
  63
  64 @comment limits.h
  65 @comment ISO
  66 @deftypevr Macro int CHAR_MIN
  67 This is the minimum value that can be represented by a @code{char}.
  68 It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
  69 otherwise.
  70 @end deftypevr
  71
  72 @comment limits.h
  73 @comment ISO
  74 @deftypevr Macro int CHAR_MAX
  75 This is the maximum value that can be represented by a @code{char}.
  76 It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
  77 @code{UCHAR_MAX} otherwise.
  78 @end deftypevr
  79
  80 @comment limits.h
  81 @comment ISO
  82 @deftypevr Macro int SHRT_MIN
  83 This is the minimum value that can be represented by a @code{signed
  84 short int}.  On most machines that the GNU C library runs on,
  85 @code{short} integers are 16-bit quantities.
  86 @end deftypevr
  87
  88 @comment limits.h
  89 @comment ISO
  90 @deftypevr Macro int SHRT_MAX
  91 This is the maximum value that can be represented by a @code{signed
  92 short int}.
  93 @end deftypevr
  94
  95 @comment limits.h
  96 @comment ISO
  97 @deftypevr Macro int USHRT_MAX
  98 This is the maximum value that can be represented by an @code{unsigned
  99 short int}.  (The minimum value of an @code{unsigned short int} is zero.)
 100 @end deftypevr
 101
 102 @comment limits.h
 103 @comment ISO
 104 @deftypevr Macro int INT_MIN
 105 This is the minimum value that can be represented by a @code{signed
 106 int}.  On most machines that the GNU C system runs on, an @code{int} is
 107 a 32-bit quantity.
 108 @end deftypevr
 109
 110 @comment limits.h
 111 @comment ISO
 112 @deftypevr Macro int INT_MAX
 113 This is the maximum value that can be represented by a @code{signed
 114 int}.
 115 @end deftypevr
 116
 117 @comment limits.h
 118 @comment ISO
 119 @deftypevr Macro {unsigned int} UINT_MAX
 120 This is the maximum value that can be represented by an @code{unsigned
 121 int}.  (The minimum value of an @code{unsigned int} is zero.)
 122 @end deftypevr
 123
 124 @comment limits.h
 125 @comment ISO
 126 @deftypevr Macro {long int} LONG_MIN
 127 This is the minimum value that can be represented by a @code{signed long
 128 int}.  On most machines that the GNU C system runs on, @code{long}
 129 integers are 32-bit quantities, the same size as @code{int}.
 130 @end deftypevr
 131
 132 @comment limits.h
 133 @comment ISO
 134 @deftypevr Macro {long int} LONG_MAX
 135 This is the maximum value that can be represented by a @code{signed long
 136 int}.
 137 @end deftypevr
 138
 139 @comment limits.h
 140 @comment ISO
 141 @deftypevr Macro {unsigned long int} ULONG_MAX
 142 This is the maximum value that can be represented by an @code{unsigned
 143 long int}.  (The minimum value of an @code{unsigned long int} is zero.)
 144 @end deftypevr
 145
 146 @strong{Incomplete:}  There should be corresponding limits for the GNU
 147 C Compiler's @code{long long} type, too.  (But they are not now present
 148 in the header file.)
 149
 150 The header file @file{limits.h} also defines some additional constants
 151 that parameterize various operating system and file system limits.  These
 152 constants are described in @ref{System Parameters} and @ref{File System
 153 Parameters}.
 154 @pindex limits.h
 155
 156
 157 @node Floating-Point Limits ,  , Integer Representation Limits, Representation Limits
 158 @section Floating-Point Limits
 159 @cindex floating-point number representation
 160 @cindex representation, floating-point number
 161 @cindex limits, floating-point representation
 162
 163 Because floating-point numbers are represented internally as approximate
 164 quantities, algorithms for manipulating floating-point data often need
 165 to be parameterized in terms of the accuracy of the representation.
 166 Some of the functions in the C library itself need this information; for
 167 example, the algorithms for printing and reading floating-point numbers
 168 (@pxref{I/O on Streams}) and for calculating trigonometric and
 169 irrational functions (@pxref{Mathematics}) use information about the
 170 underlying floating-point representation to avoid round-off error and
 171 loss of accuracy.  User programs that implement numerical analysis
 172 techniques also often need to be parameterized in this way in order to
 173 minimize or compute error bounds.
 174
 175 The specific representation of floating-point numbers varies from
 176 machine to machine.  The GNU C library defines a set of parameters which
 177 characterize each of the supported floating-point representations on a
 178 particular system.
 179
 180 @menu
 181 * Floating-Point Representation::       Definitions of terminology.
 182 * Floating-Point Parameters::           Descriptions of the library
 183                                          facilities.
 184 * IEEE Floating Point::                 An example of a common
 185                                          representation.
 186 @end menu
 187
 188 @node Floating-Point Representation, Floating-Point Parameters,  , Floating-Point Limits
 189 @subsection Floating-Point Representation
 190
 191 This section introduces the terminology used to characterize the
 192 representation of floating-point numbers.
 193
 194 You are probably already familiar with most of these concepts in terms
 195 of scientific or exponential notation for floating-point numbers.  For
 196 example, the number @code{123456.0} could be expressed in exponential
 197 notation as @code{1.23456e+05}, a shorthand notation indicating that the
 198 mantissa @code{1.23456} is multiplied by the base @code{10} raised to
 199 power @code{5}.
 200
 201 More formally, the internal representation of a floating-point number
 202 can be characterized in terms of the following parameters:
 203
 204 @itemize @bullet
 205 @item
 206 The @dfn{sign} is either @code{-1} or @code{1}.
 207 @cindex sign (of floating-point number)
 208
 209 @item
 210 The @dfn{base} or @dfn{radix} for exponentiation; an integer greater
 211 than @code{1}.  This is a constant for the particular representation.
 212 @cindex base (of floating-point number)
 213 @cindex radix (of floating-point number)
 214
 215 @item
 216 The @dfn{exponent} to which the base is raised.  The upper and lower
 217 bounds of the exponent value are constants for the particular
 218 representation.
 219 @cindex exponent (of floating-point number)
 220
 221 Sometimes, in the actual bits representing the floating-point number,
 222 the exponent is @dfn{biased} by adding a constant to it, to make it
 223 always be represented as an unsigned quantity.  This is only important
 224 if you have some reason to pick apart the bit fields making up the
 225 floating-point number by hand, which is something for which the GNU
 226 library provides no support.  So this is ignored in the discussion that
 227 follows.
 228 @cindex bias (of floating-point number exponent)
 229
 230 @item
 231 The value of the @dfn{mantissa} or @dfn{significand}, which is an
 232 unsigned integer.
 233 @cindex mantissa (of floating-point number)
 234 @cindex significand (of floating-point number)
 235
 236 @item
 237 The @dfn{precision} of the mantissa.  If the base of the representation
 238 is @var{b}, then the precision is the number of base-@var{b} digits in
 239 the mantissa.  This is a constant for the particular representation.
 240
 241 Many floating-point representations have an implicit @dfn{hidden bit} in
 242 the mantissa.  Any such hidden bits are counted in the precision.
 243 Again, the GNU library provides no facilities for dealing with such low-level
 244 aspects of the representation.
 245 @cindex precision (of floating-point number)
 246 @cindex hidden bit (of floating-point number mantissa)
 247 @end itemize
 248
 249 The mantissa of a floating-point number actually represents an implicit
 250 fraction whose denominator is the base raised to the power of the
 251 precision.  Since the largest representable mantissa is one less than
 252 this denominator, the value of the fraction is always strictly less than
 253 @code{1}.  The mathematical value of a floating-point number is then the
 254 product of this fraction; the sign; and the base raised to the exponent.
 255
 256 If the floating-point number is @dfn{normalized}, the mantissa is also
 257 greater than or equal to the base raised to the power of one less
 258 than the precision (unless the number represents a floating-point zero,
 259 in which case the mantissa is zero).  The fractional quantity is
 260 therefore greater than or equal to @code{1/@var{b}}, where @var{b} is
 261 the base.
 262 @cindex normalized floating-point number
 263
 264 @node Floating-Point Parameters, IEEE Floating Point, Floating-Point Representation, Floating-Point Limits
 265 @subsection Floating-Point Parameters
 266
 267 @strong{Incomplete:}  This section needs some more concrete examples
 268 of what these parameters mean and how to use them in a program.
 269
 270 These macro definitions can be accessed by including the header file
 271 @file{float.h} in your program.
 272 @pindex float.h
 273
 274 Macro names starting with @samp{FLT_} refer to the @code{float} type,
 275 while names beginning with @samp{DBL_} refer to the @code{double} type
 276 and names beginning with @samp{LDBL_} refer to the @code{long double}
 277 type.  (In implementations that do not support @code{long double} as
 278 a distinct data type, the values for those constants are the same
 279 as the corresponding constants for the @code{double} type.)@refill
 280 @cindex @code{float} representation limits
 281 @cindex @code{double} representation limits
 282 @cindex @code{long double} representation limits
 283
 284 Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant
 285 expression.  The other macros listed here cannot be reliably used in
 286 places that require constant expressions, such as @samp{#if}
 287 preprocessing directives or array size specifications.
 288
 289 Although the @w{ISO C} standard specifies minimum and maximum values for
 290 most of these parameters, the GNU C implementation uses whatever
 291 floating-point representations are supported by the underlying hardware.
 292 So whether GNU C actually satisfies the @w{ISO C} requirements depends on
 293 what machine it is running on.
 294
 295 @comment float.h
 296 @comment ISO
 297 @deftypevr Macro int FLT_ROUNDS
 298 This value characterizes the rounding mode for floating-point addition.
 299 The following values indicate standard rounding modes:
 300
 301 @table @code
 302 @item -1
 303 The mode is indeterminable.
 304 @item 0
 305 Rounding is towards zero.
 306 @item 1
 307 Rounding is to the nearest number.
 308 @item 2
 309 Rounding is towards positive infinity.
 310 @item 3
 311 Rounding is towards negative infinity.
 312 @end table
 313
 314 @noindent
 315 Any other value represents a machine-dependent nonstandard rounding
 316 mode.
 317 @end deftypevr
 318
 319 @comment float.h
 320 @comment ISO
 321 @deftypevr Macro int FLT_RADIX
 322 This is the value of the base, or radix, of exponent representation.
 323 This is guaranteed to be a constant expression, unlike the other macros
 324 described in this section.
 325 @end deftypevr
 326
 327 @comment float.h
 328 @comment ISO
 329 @deftypevr Macro int FLT_MANT_DIG
 330 This is the number of base-@code{FLT_RADIX} digits in the floating-point
 331 mantissa for the @code{float} data type.
 332 @end deftypevr
 333
 334 @comment float.h
 335 @comment ISO
 336 @deftypevr Macro int DBL_MANT_DIG
 337 This is the number of base-@code{FLT_RADIX} digits in the floating-point
 338 mantissa for the @code{double} data type.
 339 @end deftypevr
 340
 341 @comment float.h
 342 @comment ISO
 343 @deftypevr Macro int LDBL_MANT_DIG
 344 This is the number of base-@code{FLT_RADIX} digits in the floating-point
 345 mantissa for the @code{long double} data type.
 346 @end deftypevr
 347
 348 @comment float.h
 349 @comment ISO
 350 @deftypevr Macro int FLT_DIG
 351 This is the number of decimal digits of precision for the @code{float}
 352 data type.  Technically, if @var{p} and @var{b} are the precision and
 353 base (respectively) for the representation, then the decimal precision
 354 @var{q} is the maximum number of decimal digits such that any floating
 355 point number with @var{q} base 10 digits can be rounded to a floating
 356 point number with @var{p} base @var{b} digits and back again, without
 357 change to the @var{q} decimal digits.
 358
 359 The value of this macro is guaranteed to be at least @code{6}.
 360 @end deftypevr
 361
 362 @comment float.h
 363 @comment ISO
 364 @deftypevr Macro int DBL_DIG
 365 This is similar to @code{FLT_DIG}, but is for the @code{double} data
 366 type.  The value of this macro is guaranteed to be at least @code{10}.
 367 @end deftypevr
 368
 369 @comment float.h
 370 @comment ISO
 371 @deftypevr Macro int LDBL_DIG
 372 This is similar to @code{FLT_DIG}, but is for the @code{long double}
 373 data type.  The value of this macro is guaranteed to be at least
 374 @code{10}.
 375 @end deftypevr
 376
 377 @comment float.h
 378 @comment ISO
 379 @deftypevr Macro int FLT_MIN_EXP
 380 This is the minimum negative integer such that the mathematical value
 381 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
 382 normalized floating-point number of type @code{float}.  In terms of the
 383 actual implementation, this is just the smallest value that can be
 384 represented in the exponent field of the number.
 385 @end deftypevr
 386
 387 @comment float.h
 388 @comment ISO
 389 @deftypevr Macro int DBL_MIN_EXP
 390 This is similar to @code{FLT_MIN_EXP}, but is for the @code{double} data
 391 type.
 392 @end deftypevr
 393
 394 @comment float.h
 395 @comment ISO
 396 @deftypevr Macro int LDBL_MIN_EXP
 397 This is similar to @code{FLT_MIN_EXP}, but is for the @code{long double}
 398 data type.
 399 @end deftypevr
 400
 401 @comment float.h
 402 @comment ISO
 403 @deftypevr Macro int FLT_MIN_10_EXP
 404 This is the minimum negative integer such that the mathematical value
 405 @code{10} raised to this power minus 1 can be represented as a
 406 normalized floating-point number of type @code{float}.  This is
 407 guaranteed to be no greater than @code{-37}.
 408 @end deftypevr
 409
 410 @comment float.h
 411 @comment ISO
 412 @deftypevr Macro int DBL_MIN_10_EXP
 413 This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{double}
 414 data type.
 415 @end deftypevr
 416
 417 @comment float.h
 418 @comment ISO
 419 @deftypevr Macro int LDBL_MIN_10_EXP
 420 This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{long
 421 double} data type.
 422 @end deftypevr
 423
 424
 425
 426 @comment float.h
 427 @comment ISO
 428 @deftypevr Macro int FLT_MAX_EXP
 429 This is the maximum negative integer such that the mathematical value
 430 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
 431 floating-point number of type @code{float}.  In terms of the actual
 432 implementation, this is just the largest value that can be represented
 433 in the exponent field of the number.
 434 @end deftypevr
 435
 436 @comment float.h
 437 @comment ISO
 438 @deftypevr Macro int DBL_MAX_EXP
 439 This is similar to @code{FLT_MAX_EXP}, but is for the @code{double} data
 440 type.
 441 @end deftypevr
 442
 443 @comment float.h
 444 @comment ISO
 445 @deftypevr Macro int LDBL_MAX_EXP
 446 This is similar to @code{FLT_MAX_EXP}, but is for the @code{long double}
 447 data type.
 448 @end deftypevr
 449
 450 @comment float.h
 451 @comment ISO
 452 @deftypevr Macro int FLT_MAX_10_EXP
 453 This is the maximum negative integer such that the mathematical value
 454 @code{10} raised to this power minus 1 can be represented as a
 455 normalized floating-point number of type @code{float}.  This is
 456 guaranteed to be at least @code{37}.
 457 @end deftypevr
 458
 459 @comment float.h
 460 @comment ISO
 461 @deftypevr Macro int DBL_MAX_10_EXP
 462 This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{double}
 463 data type.
 464 @end deftypevr
 465
 466 @comment float.h
 467 @comment ISO
 468 @deftypevr Macro int LDBL_MAX_10_EXP
 469 This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{long
 470 double} data type.
 471 @end deftypevr
 472
 473
 474 @comment float.h
 475 @comment ISO
 476 @deftypevr Macro double FLT_MAX
 477 The value of this macro is the maximum representable floating-point
 478 number of type @code{float}, and is guaranteed to be at least
 479 @code{1E+37}.
 480 @end deftypevr
 481
 482 @comment float.h
 483 @comment ISO
 484 @deftypevr Macro double DBL_MAX
 485 The value of this macro is the maximum representable floating-point
 486 number of type @code{double}, and is guaranteed to be at least
 487 @code{1E+37}.
 488 @end deftypevr
 489
 490 @comment float.h
 491 @comment ISO
 492 @deftypevr Macro {long double} LDBL_MAX
 493 The value of this macro is the maximum representable floating-point
 494 number of type @code{long double}, and is guaranteed to be at least
 495 @code{1E+37}.
 496 @end deftypevr
 497
 498
 499 @comment float.h
 500 @comment ISO
 501 @deftypevr Macro double FLT_MIN
 502 The value of this macro is the minimum normalized positive
 503 floating-point number that is representable by type @code{float}, and is
 504 guaranteed to be no more than @code{1E-37}.
 505 @end deftypevr
 506
 507 @comment float.h
 508 @comment ISO
 509 @deftypevr Macro double DBL_MIN
 510 The value of this macro is the minimum normalized positive
 511 floating-point number that is representable by type @code{double}, and
 512 is guaranteed to be no more than @code{1E-37}.
 513 @end deftypevr
 514
 515 @comment float.h
 516 @comment ISO
 517 @deftypevr Macro {long double} LDBL_MIN
 518 The value of this macro is the minimum normalized positive
 519 floating-point number that is representable by type @code{long double},
 520 and is guaranteed to be no more than @code{1E-37}.
 521 @end deftypevr
 522
 523
 524 @comment float.h
 525 @comment ISO
 526 @deftypevr Macro double FLT_EPSILON
 527 This is the minimum positive floating-point number of type @code{float}
 528 such that @code{1.0 + FLT_EPSILON != 1.0} is true.  It's guaranteed to
 529 be no greater than @code{1E-5}.
 530 @end deftypevr
 531
 532 @comment float.h
 533 @comment ISO
 534 @deftypevr Macro double DBL_EPSILON
 535 This is similar to @code{FLT_EPSILON}, but is for the @code{double}
 536 type.  The maximum value is @code{1E-9}.
 537 @end deftypevr
 538
 539 @comment float.h
 540 @comment ISO
 541 @deftypevr Macro {long double} LDBL_EPSILON
 542 This is similar to @code{FLT_EPSILON}, but is for the @code{long double}
 543 type.  The maximum value is @code{1E-9}.
 544 @end deftypevr
 545
 546
 547 @node IEEE Floating Point,  , Floating-Point Parameters, Floating-Point Limits
 548 @subsection IEEE Floating Point
 549 @cindex IEEE floating-point representation
 550 @cindex floating-point, IEEE
 551 @cindex IEEE Std 754
 552
 553
 554 Here is an example showing how these parameters work for a common
 555 floating point representation, specified by the @cite{IEEE Standard for
 556 Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985 or ANSI/IEEE
 557 Std 854-1987)}.  Nearly all computers today use this format.
 558
 559 The IEEE single-precision float representation uses a base of 2.  There
 560 is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
 561 precision is 24 base-2 digits), and an 8-bit exponent that can represent
 562 values in the range -125 to 128, inclusive.
 563
 564 So, for an implementation that uses this representation for the
 565 @code{float} data type, appropriate values for the corresponding
 566 parameters are:
 567
 568 @example
 569 FLT_RADIX                             2
 570 FLT_MANT_DIG                         24
 571 FLT_DIG                               6
 572 FLT_MIN_EXP                        -125
 573 FLT_MIN_10_EXP                      -37
 574 FLT_MAX_EXP                         128
 575 FLT_MAX_10_EXP                      +38
 576 FLT_MIN                 1.17549435E-38F
 577 FLT_MAX                 3.40282347E+38F
 578 FLT_EPSILON             1.19209290E-07F
 579 @end example
 580
 581 Here are the values for the @code{double} data type:
 582
 583 @example
 584 DBL_MANT_DIG                         53
 585 DBL_DIG                              15
 586 DBL_MIN_EXP                       -1021
 587 DBL_MIN_10_EXP                     -307
 588 DBL_MAX_EXP                        1024
 589 DBL_MAX_10_EXP                      308
 590 DBL_MAX         1.7976931348623157E+308
 591 DBL_MIN         2.2250738585072014E-308
 592 DBL_EPSILON     2.2204460492503131E-016
 593 @end example