   This file documents the GNU C library.

   This is Edition 0.06 DRAFT, last updated 24 October 1994, of `The
GNU C Library Reference Manual', for Version 1.09 Beta.

   Copyright (C) 1993, 1994 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translations of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

Range of an Integer Type
------------------------

   Suppose you need to store an integer value which can range from zero
to one million.  Which is the smallest type you can use?  There is no
general rule; it depends on the C compiler and target machine.  You can
use the `MIN' and `MAX' macros in `limits.h' to determine which type
will work.

   Each signed integer type has a pair of macros which give the smallest
and largest values that it can hold.  Each unsigned integer type has one
such macro, for the maximum value; the minimum value is, of course,
zero.

   The values of these macros are all integer constant expressions.  The
`MAX' and `MIN' macros for `char' and `short int' types have values of
type `int'.  The `MAX' and `MIN' macros for the other types have values
of the same type described by the macro--thus, `ULONG_MAX' has type
`unsigned long int'.

`SCHAR_MIN'
     This is the minimum value that can be represented by a
     `signed char'.

`SCHAR_MAX'
`UCHAR_MAX'
     These are the maximum values that can be represented by a
     `signed char' and `unsigned char', respectively.

`CHAR_MIN'
     This is the minimum value that can be represented by a `char'.
     It's equal to `SCHAR_MIN' if `char' is signed, or zero otherwise.

`CHAR_MAX'
     This is the maximum value that can be represented by a `char'.
     It's equal to `SCHAR_MAX' if `char' is signed, or `UCHAR_MAX'
     otherwise.

`SHRT_MIN'
     This is the minimum value that can be represented by a
     `signed short int'.  On most machines that the GNU C library runs
     on, `short' integers are 16-bit quantities.

`SHRT_MAX'
`USHRT_MAX'
     These are the maximum values that can be represented by a
     `signed short int' and `unsigned short int', respectively.

`INT_MIN'
     This is the minimum value that can be represented by a
     `signed int'.  On most machines that the GNU C system runs on, an
     `int' is a 32-bit quantity.

`INT_MAX'
`UINT_MAX'
     These are the maximum values that can be represented by,
     respectively, the type `signed int' and the type `unsigned int'.

`LONG_MIN'
     This is the minimum value that can be represented by a
     `signed long int'.  On most machines that the GNU C system runs
     on, `long' integers are 32-bit quantities, the same size as `int'.

`LONG_MAX'
`ULONG_MAX'
     These are the maximum values that can be represented by a
     `signed long int' and `unsigned long int', respectively.

`LONG_LONG_MIN'
     This is the minimum value that can be represented by a
     `signed long long int'.  On most machines that the GNU C system
     runs on, `long long' integers are 64-bit quantities.

`LONG_LONG_MAX'
`ULONG_LONG_MAX'
     These are the maximum values that can be represented by a `signed
     long long int' and `unsigned long long int', respectively.

`WCHAR_MAX'
     This is the maximum value that can be represented by a `wchar_t'.
     See Wide Char Intro.

   The header file `limits.h' also defines some additional constants
that parameterize various operating system and file system limits.
These constants are described in System Configuration.

Floating Type Macros
--------------------

   The specific representation of floating point numbers varies from
machine to machine.  Because floating point numbers are represented
internally as approximate quantities, algorithms for manipulating
floating point data often need to take account of the precise details of
the machine's floating point representation.

   Some of the functions in the C library itself need this information;
for example, the algorithms for printing and reading floating point
numbers (see I/O on Streams.) and for calculating trigonometric and
irrational functions (see Mathematics.) use it to avoid round-off
error and loss of accuracy.  User programs that implement numerical
analysis techniques also often need this information in order to
minimize or compute error bounds.

   The header file `float.h' describes the format used by your machine.

Floating Point Representation Concepts
......................................

   This section introduces the terminology for describing floating point
representations.

   You are probably already familiar with most of these concepts in
terms of scientific or exponential notation for floating point numbers.
For example, the number `123456.0' could be expressed in exponential
notation as `1.23456e+05', a shorthand notation indicating that the
mantissa `1.23456' is multiplied by the base `10' raised to power `5'.

   More formally, the internal representation of a floating point number
can be characterized in terms of the following parameters:

   * The "sign" is either `-1' or `1'.

   * The "base" or "radix" for exponentiation, an integer greater than
     `1'.  This is a constant for a particular representation.

   * The "exponent" to which the base is raised.  The upper and lower
     bounds of the exponent value are constants for a particular
     representation.

     Sometimes, in the actual bits representing the floating point
     number, the exponent is "biased" by adding a constant to it, to
     make it always be represented as an unsigned quantity.  This is
     only important if you have some reason to pick apart the bit
     fields making up the floating point number by hand, which is
     something for which the GNU library provides no support.  So this
     is ignored in the discussion that follows.

   * The "mantissa" or "significand", an unsigned integer which is a
     part of each floating point number.

   * The "precision" of the mantissa.  If the base of the representation
     is B, then the precision is the number of base-B digits in the
     mantissa.  This is a constant for a particular representation.

     Many floating point representations have an implicit "hidden bit"
     in the mantissa.  This is a bit which is present virtually in the
     mantissa, but not stored in memory because its value is always 1
     in a normalized number.  The precision figure (see above) includes
     any hidden bits.

     Again, the GNU library provides no facilities for dealing with such
     low-level aspects of the representation.

   The mantissa of a floating point number actually represents an
implicit fraction whose denominator is the base raised to the power of
the precision.  Since the largest representable mantissa is one less
than this denominator, the value of the fraction is always strictly
less than `1'.  The mathematical value of a floating point number is
then the product of this fraction, the sign, and the base raised to the
exponent.

   We say that the floating point number is "normalized" if the
fraction is at least `1/B', where B is the base.  In other words, the
mantissa would be too large to fit if it were multiplied by the base.
Non-normalized numbers are sometimes called "denormal"; they contain
less precision than the representation normally can hold.

   If the number is not normalized, then you can subtract `1' from the
exponent while multiplying the mantissa by the base, and get another
floating point number with the same value.  "Normalization" consists of
doing this repeatedly until the number is normalized.  Two distinct
normalized floating point numbers cannot be equal in value.

   (There is an exception to this rule: if the mantissa is zero, it is
considered normalized.  Another exception happens on certain machines
where the exponent is as small as the representation can hold.  Then it
is impossible to subtract `1' from the exponent, so a number may be
normalized even if its fraction is less than `1/B'.)

Floating Point Parameters
.........................

   These macro definitions can be accessed by including the header file
`float.h' in your program.

   Macro names starting with `FLT_' refer to the `float' type, while
names beginning with `DBL_' refer to the `double' type and names
beginning with `LDBL_' refer to the `long double' type.  (Currently GCC
does not support `long double' as a distinct data type, so the values
for the `LDBL_' constants are equal to the corresponding constants for
the `double' type.)

   Of these macros, only `FLT_RADIX' is guaranteed to be a constant
expression.  The other macros listed here cannot be reliably used in
places that require constant expressions, such as `#if' preprocessing
directives or in the dimensions of static arrays.

   Although the ANSI C standard specifies minimum and maximum values for
most of these parameters, the GNU C implementation uses whatever values
describe the floating point representation of the target machine.  So in
principle GNU C actually satisfies the ANSI C requirements only if the
target machine is suitable.  In practice, all the machines currently
supported are suitable.

`FLT_ROUNDS'
     This value characterizes the rounding mode for floating point
     addition.  The following values indicate standard rounding modes:

    `-1'
          The mode is indeterminable.

    `0'
          Rounding is towards zero.

    `1'
          Rounding is to the nearest number.

    `2'
          Rounding is towards positive infinity.

    `3'
          Rounding is towards negative infinity.

     Any other value represents a machine-dependent nonstandard rounding
     mode.

     On most machines, the value is `1', in accordance with the IEEE
     standard for floating point.

     Here is a table showing how certain values round for each possible
     value of `FLT_ROUNDS', if the other aspects of the representation
     match the IEEE single-precision standard.

                          0      1             2             3
           1.00000003    1.0    1.0           1.00000012    1.0
           1.00000007    1.0    1.00000012    1.00000012    1.0
          -1.00000003   -1.0   -1.0          -1.0          -1.00000012
          -1.00000007   -1.0   -1.00000012   -1.0          -1.00000012

`FLT_RADIX'
     This is the value of the base, or radix, of exponent
     representation.  This is guaranteed to be a constant expression,
     unlike the other macros described in this section.  The value is 2
     on all machines we know of except the IBM 360 and derivatives.

`FLT_MANT_DIG'
     This is the number of base-`FLT_RADIX' digits in the floating point
     mantissa for the `float' data type.  The following expression
     yields `1.0' (even though mathematically it should not) due to the
     limited number of mantissa digits:

          float radix = FLT_RADIX;

          1.0f + 1.0f / radix / radix / ... / radix

     where `radix' appears `FLT_MANT_DIG' times.

`DBL_MANT_DIG'
`LDBL_MANT_DIG'
     This is the number of base-`FLT_RADIX' digits in the floating point
     mantissa for the data types `double' and `long double',
     respectively.

`FLT_DIG'
     This is the number of decimal digits of precision for the `float'
     data type.  Technically, if P and B are the precision and base
     (respectively) for the representation, then the decimal precision
     Q is the maximum number of decimal digits such that any floating
     point number with Q base 10 digits can be rounded to a floating
     point number with P base B digits and back again, without change
     to the Q decimal digits.

     The value of this macro is supposed to be at least `6', to satisfy
     ANSI C.

`DBL_DIG'
`LDBL_DIG'
     These are similar to `FLT_DIG', but for the data types `double'
     and `long double', respectively.  The values of these macros are
     supposed to be at least `10'.

`FLT_MIN_EXP'
     This is the smallest possible exponent value for type `float'.
     More precisely, is the minimum negative integer such that the value
     `FLT_RADIX' raised to this power minus 1 can be represented as a
     normalized floating point number of type `float'.

`DBL_MIN_EXP'
`LDBL_MIN_EXP'
     These are similar to `FLT_MIN_EXP', but for the data types
     `double' and `long double', respectively.

`FLT_MIN_10_EXP'
     This is the minimum negative integer such that `10' raised to this
     power minus 1 can be represented as a normalized floating point
     number of type `float'.  This is supposed to be `-37' or even less.

`DBL_MIN_10_EXP'
`LDBL_MIN_10_EXP'
     These are similar to `FLT_MIN_10_EXP', but for the data types
     `double' and `long double', respectively.

`FLT_MAX_EXP'
     This is the largest possible exponent value for type `float'.  More
     precisely, this is the maximum positive integer such that value
     `FLT_RADIX' raised to this power minus 1 can be represented as a
     floating point number of type `float'.

`DBL_MAX_EXP'
`LDBL_MAX_EXP'
     These are similar to `FLT_MAX_EXP', but for the data types
     `double' and `long double', respectively.

`FLT_MAX_10_EXP'
     This is the maximum positive integer such that `10' raised to this
     power minus 1 can be represented as a normalized floating point
     number of type `float'.  This is supposed to be at least `37'.

`DBL_MAX_10_EXP'
`LDBL_MAX_10_EXP'
     These are similar to `FLT_MAX_10_EXP', but for the data types
     `double' and `long double', respectively.

`FLT_MAX'
     The value of this macro is the maximum number representable in type
     `float'.  It is supposed to be at least `1E+37'.  The value has
     type `float'.

     The smallest representable number is `- FLT_MAX'.

`DBL_MAX'
`LDBL_MAX'
     These are similar to `FLT_MAX', but for the data types `double'
     and `long double', respectively.  The type of the macro's value is
     the same as the type it describes.

`FLT_MIN'
     The value of this macro is the minimum normalized positive floating
     point number that is representable in type `float'.  It is supposed
     to be no more than `1E-37'.

`DBL_MIN'
`LDBL_MIN'
     These are similar to `FLT_MIN', but for the data types `double'
     and `long double', respectively.  The type of the macro's value is
     the same as the type it describes.

`FLT_EPSILON'
     This is the minimum positive floating point number of type `float'
     such that `1.0 + FLT_EPSILON != 1.0' is true.  It's supposed to be
     no greater than `1E-5'.

`DBL_EPSILON'
`LDBL_EPSILON'
     These are similar to `FLT_EPSILON', but for the data types
     `double' and `long double', respectively.  The type of the macro's
     value is the same as the type it describes.  The values are not
     supposed to be greater than `1E-9'.

IEEE Floating Point
...................

   Here is an example showing how the floating type measurements come
out for the most common floating point representation, specified by the
`IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
754-1985)'.  Nearly all computers designed since the 1980s use this
format.

   The IEEE single-precision float representation uses a base of 2.
There is a sign bit, a mantissa with 23 bits plus one hidden bit (so
the total precision is 24 base-2 digits), and an 8-bit exponent that
can represent values in the range -125 to 128, inclusive.

   So, for an implementation that uses this representation for the
`float' data type, appropriate values for the corresponding parameters
are:

     FLT_RADIX                             2
     FLT_MANT_DIG                         24
     FLT_DIG                               6
     FLT_MIN_EXP                        -125
     FLT_MIN_10_EXP                      -37
     FLT_MAX_EXP                         128
     FLT_MAX_10_EXP                      +38
     FLT_MIN                 1.17549435E-38F
     FLT_MAX                 3.40282347E+38F
     FLT_EPSILON             1.19209290E-07F

   Here are the values for the `double' data type:

     DBL_MANT_DIG                         53
     DBL_DIG                              15
     DBL_MIN_EXP                       -1021
     DBL_MIN_10_EXP                     -307
     DBL_MAX_EXP                        1024
     DBL_MAX_10_EXP                      308
     DBL_MAX         1.7976931348623157E+308
     DBL_MIN         2.2250738585072014E-308
     DBL_EPSILON     2.2204460492503131E-016

Structure Field Offset Measurement
----------------------------------

   You can use `offsetof' to measure the location within a structure
type of a particular structure member.

 - Macro: size_t offsetof (TYPE, MEMBER)
     This expands to a integer constant expression that is the offset
     of the structure member named MEMBER in a the structure type TYPE.
     For example, `offsetof (struct s, elem)' is the offset, in bytes,
     of the member `elem' in a `struct s'.

     This macro won't work if MEMBER is a bit field; you get an error
     from the C compiler in that case.