initial import

1 files changed, 593 insertions, 0 deletions

diff --git a/manual/=limits.texinfo b/manual/=limits.texinfo
new file mode 100644
index 0000000000..3e384dd6b6
--- /dev/null
+++ b/manual/=limits.texinfo
@@ -0,0 +1,593 @@
+@node Representation Limits, System Configuration Limits, System Information, Top
+@chapter Representation Limits
+
+This chapter contains information about constants and parameters that
+characterize the representation of the various integer and
+floating-point types supported by the GNU C library.
+
+@menu
+* Integer Representation Limits::       Determining maximum and minimum
+                                         representation values of
+                                         various integer subtypes.
+* Floating-Point Limits ::              Parameters which characterize
+                                         supported floating-point
+                                         representations on a particular
+                                         system. 
+@end menu
+
+@node Integer Representation Limits, Floating-Point Limits ,  , Representation Limits
+@section Integer Representation Limits
+@cindex integer representation limits
+@cindex representation limits, integer
+@cindex limits, integer representation
+
+Sometimes it is necessary for programs to know about the internal
+representation of various integer subtypes.  For example, if you want
+your program to be careful not to overflow an @code{int} counter
+variable, you need to know what the largest representable value that
+fits in an @code{int} is.  These kinds of parameters can vary from
+compiler to compiler and machine to machine.  Another typical use of
+this kind of parameter is in conditionalizing data structure definitions
+with @samp{#ifdef} to select the most appropriate integer subtype that
+can represent the required range of values.
+
+Macros representing the minimum and maximum limits of the integer types
+are defined in the header file @file{limits.h}.  The values of these
+macros are all integer constant expressions.
+@pindex limits.h
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int CHAR_BIT
+This is the number of bits in a @code{char}, usually eight.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int SCHAR_MIN
+This is the minimum value that can be represented by a @code{signed char}.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int SCHAR_MAX
+This is the maximum value that can be represented by a @code{signed char}.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int UCHAR_MAX
+This is the maximum value that can be represented by a @code{unsigned char}.
+(The minimum value of an @code{unsigned char} is zero.)
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int CHAR_MIN
+This is the minimum value that can be represented by a @code{char}.
+It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
+otherwise.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int CHAR_MAX
+This is the maximum value that can be represented by a @code{char}.
+It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
+@code{UCHAR_MAX} otherwise.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int SHRT_MIN
+This is the minimum value that can be represented by a @code{signed
+short int}.  On most machines that the GNU C library runs on,
+@code{short} integers are 16-bit quantities.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int SHRT_MAX
+This is the maximum value that can be represented by a @code{signed
+short int}.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int USHRT_MAX
+This is the maximum value that can be represented by an @code{unsigned
+short int}.  (The minimum value of an @code{unsigned short int} is zero.)
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int INT_MIN
+This is the minimum value that can be represented by a @code{signed
+int}.  On most machines that the GNU C system runs on, an @code{int} is
+a 32-bit quantity.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro int INT_MAX
+This is the maximum value that can be represented by a @code{signed
+int}.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro {unsigned int} UINT_MAX
+This is the maximum value that can be represented by an @code{unsigned
+int}.  (The minimum value of an @code{unsigned int} is zero.)
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro {long int} LONG_MIN
+This is the minimum value that can be represented by a @code{signed long
+int}.  On most machines that the GNU C system runs on, @code{long}
+integers are 32-bit quantities, the same size as @code{int}.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro {long int} LONG_MAX
+This is the maximum value that can be represented by a @code{signed long
+int}.
+@end deftypevr
+
+@comment limits.h
+@comment ANSI
+@deftypevr Macro {unsigned long int} ULONG_MAX
+This is the maximum value that can be represented by an @code{unsigned
+long int}.  (The minimum value of an @code{unsigned long int} is zero.)
+@end deftypevr
+
+@strong{Incomplete:}  There should be corresponding limits for the GNU
+C Compiler's @code{long long} type, too.  (But they are not now present
+in the header file.)
+
+The header file @file{limits.h} also defines some additional constants
+that parameterize various operating system and file system limits.  These
+constants are described in @ref{System Parameters} and @ref{File System
+Parameters}.
+@pindex limits.h
+
+
+@node Floating-Point Limits ,  , Integer Representation Limits, Representation Limits
+@section Floating-Point Limits
+@cindex floating-point number representation
+@cindex representation, floating-point number
+@cindex limits, floating-point representation
+
+Because floating-point numbers are represented internally as approximate
+quantities, algorithms for manipulating floating-point data often need
+to be parameterized in terms of the accuracy of the representation.
+Some of the functions in the C library itself need this information; for
+example, the algorithms for printing and reading floating-point numbers
+(@pxref{I/O on Streams}) and for calculating trigonometric and
+irrational functions (@pxref{Mathematics}) use information about the
+underlying floating-point representation to avoid round-off error and
+loss of accuracy.  User programs that implement numerical analysis
+techniques also often need to be parameterized in this way in order to
+minimize or compute error bounds.
+
+The specific representation of floating-point numbers varies from
+machine to machine.  The GNU C library defines a set of parameters which
+characterize each of the supported floating-point representations on a
+particular system.
+
+@menu
+* Floating-Point Representation::       Definitions of terminology.
+* Floating-Point Parameters::           Descriptions of the library
+                                         facilities. 
+* IEEE Floating Point::                 An example of a common
+                                         representation. 
+@end menu
+
+@node Floating-Point Representation, Floating-Point Parameters,  , Floating-Point Limits
+@subsection Floating-Point Representation
+
+This section introduces the terminology used to characterize the
+representation of floating-point numbers.
+
+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 @code{123456.0} could be expressed in exponential
+notation as @code{1.23456e+05}, a shorthand notation indicating that the
+mantissa @code{1.23456} is multiplied by the base @code{10} raised to
+power @code{5}.
+
+More formally, the internal representation of a floating-point number
+can be characterized in terms of the following parameters:
+
+@itemize @bullet
+@item
+The @dfn{sign} is either @code{-1} or @code{1}.
+@cindex sign (of floating-point number)
+
+@item
+The @dfn{base} or @dfn{radix} for exponentiation; an integer greater
+than @code{1}.  This is a constant for the particular representation.
+@cindex base (of floating-point number)
+@cindex radix (of floating-point number)
+
+@item
+The @dfn{exponent} to which the base is raised.  The upper and lower
+bounds of the exponent value are constants for the particular
+representation.
+@cindex exponent (of floating-point number)
+
+Sometimes, in the actual bits representing the floating-point number,
+the exponent is @dfn{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.
+@cindex bias (of floating-point number exponent)
+
+@item
+The value of the @dfn{mantissa} or @dfn{significand}, which is an
+unsigned integer.
+@cindex mantissa (of floating-point number)
+@cindex significand (of floating-point number)
+
+@item 
+The @dfn{precision} of the mantissa.  If the base of the representation
+is @var{b}, then the precision is the number of base-@var{b} digits in
+the mantissa.  This is a constant for the particular representation.
+
+Many floating-point representations have an implicit @dfn{hidden bit} in
+the mantissa.  Any such hidden bits are counted in the precision.
+Again, the GNU library provides no facilities for dealing with such low-level
+aspects of the representation.
+@cindex precision (of floating-point number)
+@cindex hidden bit (of floating-point number mantissa)
+@end itemize
+
+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
+@code{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.
+
+If the floating-point number is @dfn{normalized}, the mantissa is also
+greater than or equal to the base raised to the power of one less
+than the precision (unless the number represents a floating-point zero,
+in which case the mantissa is zero).  The fractional quantity is
+therefore greater than or equal to @code{1/@var{b}}, where @var{b} is
+the base.
+@cindex normalized floating-point number
+
+@node Floating-Point Parameters, IEEE Floating Point, Floating-Point Representation, Floating-Point Limits
+@subsection Floating-Point Parameters
+
+@strong{Incomplete:}  This section needs some more concrete examples
+of what these parameters mean and how to use them in a program.
+
+These macro definitions can be accessed by including the header file
+@file{float.h} in your program.
+@pindex float.h
+
+Macro names starting with @samp{FLT_} refer to the @code{float} type,
+while names beginning with @samp{DBL_} refer to the @code{double} type
+and names beginning with @samp{LDBL_} refer to the @code{long double}
+type.  (In implementations that do not support @code{long double} as
+a distinct data type, the values for those constants are the same
+as the corresponding constants for the @code{double} type.)@refill
+@cindex @code{float} representation limits
+@cindex @code{double} representation limits
+@cindex @code{long double} representation limits
+
+Of these macros, only @code{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 @samp{#if}
+preprocessing directives or array size specifications.
+
+Although the ANSI C standard specifies minimum and maximum values for
+most of these parameters, the GNU C implementation uses whatever
+floating-point representations are supported by the underlying hardware.
+So whether GNU C actually satisfies the ANSI C requirements depends on
+what machine it is running on.
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int FLT_ROUNDS
+This value characterizes the rounding mode for floating-point addition.
+The following values indicate standard rounding modes:
+
+@table @code
+@item -1
+The mode is indeterminable.
+@item 0
+Rounding is towards zero.
+@item 1
+Rounding is to the nearest number.
+@item 2
+Rounding is towards positive infinity.
+@item 3
+Rounding is towards negative infinity.
+@end table
+
+@noindent
+Any other value represents a machine-dependent nonstandard rounding
+mode.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int 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.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int FLT_MANT_DIG
+This is the number of base-@code{FLT_RADIX} digits in the floating-point
+mantissa for the @code{float} data type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int DBL_MANT_DIG
+This is the number of base-@code{FLT_RADIX} digits in the floating-point
+mantissa for the @code{double} data type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int LDBL_MANT_DIG
+This is the number of base-@code{FLT_RADIX} digits in the floating-point
+mantissa for the @code{long double} data type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int FLT_DIG
+This is the number of decimal digits of precision for the @code{float}
+data type.  Technically, if @var{p} and @var{b} are the precision and
+base (respectively) for the representation, then the decimal precision
+@var{q} is the maximum number of decimal digits such that any floating
+point number with @var{q} base 10 digits can be rounded to a floating
+point number with @var{p} base @var{b} digits and back again, without
+change to the @var{q} decimal digits.
+
+The value of this macro is guaranteed to be at least @code{6}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int DBL_DIG
+This is similar to @code{FLT_DIG}, but is for the @code{double} data
+type.  The value of this macro is guaranteed to be at least @code{10}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int LDBL_DIG
+This is similar to @code{FLT_DIG}, but is for the @code{long double}
+data type.  The value of this macro is guaranteed to be at least
+@code{10}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int FLT_MIN_EXP
+This is the minimum negative integer such that the mathematical value
+@code{FLT_RADIX} raised to this power minus 1 can be represented as a
+normalized floating-point number of type @code{float}.  In terms of the
+actual implementation, this is just the smallest value that can be
+represented in the exponent field of the number.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int DBL_MIN_EXP
+This is similar to @code{FLT_MIN_EXP}, but is for the @code{double} data
+type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int LDBL_MIN_EXP
+This is similar to @code{FLT_MIN_EXP}, but is for the @code{long double}
+data type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int FLT_MIN_10_EXP
+This is the minimum negative integer such that the mathematical value
+@code{10} raised to this power minus 1 can be represented as a
+normalized floating-point number of type @code{float}.  This is
+guaranteed to be no greater than @code{-37}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int DBL_MIN_10_EXP
+This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{double}
+data type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int LDBL_MIN_10_EXP
+This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{long
+double} data type.
+@end deftypevr
+
+
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int FLT_MAX_EXP
+This is the maximum negative integer such that the mathematical value
+@code{FLT_RADIX} raised to this power minus 1 can be represented as a
+floating-point number of type @code{float}.  In terms of the actual
+implementation, this is just the largest value that can be represented
+in the exponent field of the number.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int DBL_MAX_EXP
+This is similar to @code{FLT_MAX_EXP}, but is for the @code{double} data
+type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int LDBL_MAX_EXP
+This is similar to @code{FLT_MAX_EXP}, but is for the @code{long double}
+data type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int FLT_MAX_10_EXP
+This is the maximum negative integer such that the mathematical value
+@code{10} raised to this power minus 1 can be represented as a
+normalized floating-point number of type @code{float}.  This is
+guaranteed to be at least @code{37}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int DBL_MAX_10_EXP
+This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{double}
+data type.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro int LDBL_MAX_10_EXP
+This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{long
+double} data type.
+@end deftypevr
+
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro double FLT_MAX
+The value of this macro is the maximum representable floating-point
+number of type @code{float}, and is guaranteed to be at least
+@code{1E+37}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro double DBL_MAX
+The value of this macro is the maximum representable floating-point
+number of type @code{double}, and is guaranteed to be at least
+@code{1E+37}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro {long double} LDBL_MAX
+The value of this macro is the maximum representable floating-point
+number of type @code{long double}, and is guaranteed to be at least
+@code{1E+37}.
+@end deftypevr
+
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro double FLT_MIN
+The value of this macro is the minimum normalized positive
+floating-point number that is representable by type @code{float}, and is
+guaranteed to be no more than @code{1E-37}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro double DBL_MIN
+The value of this macro is the minimum normalized positive
+floating-point number that is representable by type @code{double}, and
+is guaranteed to be no more than @code{1E-37}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro {long double} LDBL_MIN
+The value of this macro is the minimum normalized positive
+floating-point number that is representable by type @code{long double},
+and is guaranteed to be no more than @code{1E-37}.
+@end deftypevr
+
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro double FLT_EPSILON
+This is the minimum positive floating-point number of type @code{float}
+such that @code{1.0 + FLT_EPSILON != 1.0} is true.  It's guaranteed to
+be no greater than @code{1E-5}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro double DBL_EPSILON
+This is similar to @code{FLT_EPSILON}, but is for the @code{double}
+type.  The maximum value is @code{1E-9}.
+@end deftypevr
+
+@comment float.h
+@comment ANSI
+@deftypevr Macro {long double} LDBL_EPSILON
+This is similar to @code{FLT_EPSILON}, but is for the @code{long double}
+type.  The maximum value is @code{1E-9}.
+@end deftypevr
+
+
+@node IEEE Floating Point,  , Floating-Point Parameters, Floating-Point Limits
+@subsection IEEE Floating Point
+@cindex IEEE floating-point representation 
+@cindex floating-point, IEEE
+@cindex IEEE Std 754
+
+
+Here is an example showing how these parameters work for a common
+floating point representation, specified by the @cite{IEEE Standard for
+Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985)}.  Nearly
+all computers today 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
+@code{float} data type, appropriate values for the corresponding
+parameters are:
+
+@example
+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
+@end example
+
+Here are the values for the @code{double} data type:
+
+@example
+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
+@end example