aboutsummaryrefslogtreecommitdiff
path: root/manual/lang.texi
diff options
context:
space:
mode:
authorRoland McGrath <roland@gnu.org>1995-02-18 01:27:10 +0000
committerRoland McGrath <roland@gnu.org>1995-02-18 01:27:10 +0000
commit28f540f45bbacd939bfd07f213bcad2bf730b1bf (patch)
tree15f07c4c43d635959c6afee96bde71fb1b3614ee /manual/lang.texi
downloadglibc-28f540f45bbacd939bfd07f213bcad2bf730b1bf.tar
glibc-28f540f45bbacd939bfd07f213bcad2bf730b1bf.tar.gz
glibc-28f540f45bbacd939bfd07f213bcad2bf730b1bf.tar.bz2
glibc-28f540f45bbacd939bfd07f213bcad2bf730b1bf.zip
initial import
Diffstat (limited to 'manual/lang.texi')
-rw-r--r--manual/lang.texi1213
1 files changed, 1213 insertions, 0 deletions
diff --git a/manual/lang.texi b/manual/lang.texi
new file mode 100644
index 0000000000..66d41846d2
--- /dev/null
+++ b/manual/lang.texi
@@ -0,0 +1,1213 @@
+@node Language Features, Library Summary, System Configuration, Top
+@appendix C Language Facilities in the Library
+
+Some of the facilities implemented by the C library really should be
+thought of as parts of the C language itself. These facilities ought to
+be documented in the C Language Manual, not in the library manual; but
+since we don't have the language manual yet, and documentation for these
+features has been written, we are publishing it here.
+
+@menu
+* Consistency Checking:: Using @code{assert} to abort if
+ something ``impossible'' happens.
+* Variadic Functions:: Defining functions with varying numbers
+ of args.
+* Null Pointer Constant:: The macro @code{NULL}.
+* Important Data Types:: Data types for object sizes.
+* Data Type Measurements:: Parameters of data type representations.
+@end menu
+
+@node Consistency Checking
+@section Explicitly Checking Internal Consistency
+@cindex consistency checking
+@cindex impossible events
+@cindex assertions
+
+When you're writing a program, it's often a good idea to put in checks
+at strategic places for ``impossible'' errors or violations of basic
+assumptions. These checks are helpful in debugging problems due to
+misunderstandings between different parts of the program.
+
+@pindex assert.h
+The @code{assert} macro, defined in the header file @file{assert.h},
+provides a convenient way to abort the program while printing a message
+about where in the program the error was detected.
+
+@vindex NDEBUG
+Once you think your program is debugged, you can disable the error
+checks performed by the @code{assert} macro by recompiling with the
+macro @code{NDEBUG} defined. This means you don't actually have to
+change the program source code to disable these checks.
+
+But disabling these consistency checks is undesirable unless they make
+the program significantly slower. All else being equal, more error
+checking is good no matter who is running the program. A wise user
+would rather have a program crash, visibly, than have it return nonsense
+without indicating anything might be wrong.
+
+@comment assert.h
+@comment ANSI
+@deftypefn Macro void assert (int @var{expression})
+Verify the programmer's belief that @var{expression} should be nonzero
+at this point in the program.
+
+If @code{NDEBUG} is not defined, @code{assert} tests the value of
+@var{expression}. If it is false (zero), @code{assert} aborts the
+program (@pxref{Aborting a Program}) after printing a message of the
+form:
+
+@smallexample
+@file{@var{file}}:@var{linenum}: Assertion `@var{expression}' failed.
+@end smallexample
+
+@noindent
+on the standard error stream @code{stderr} (@pxref{Standard Streams}).
+The filename and line number are taken from the C preprocessor macros
+@code{__FILE__} and @code{__LINE__} and specify where the call to
+@code{assert} was written.
+
+If the preprocessor macro @code{NDEBUG} is defined at the point where
+@file{assert.h} is included, the @code{assert} macro is defined to do
+absolutely nothing.
+
+@strong{Warning:} Even the argument expression @var{expression} is not
+evaluated if @code{NDEBUG} is in effect. So never use @code{assert}
+with arguments that involve side effects. For example, @code{assert
+(++i > 0);} is a bad idea, because @code{i} will not be incremented if
+@code{NDEBUG} is defined.
+@end deftypefn
+
+@strong{Usage note:} The @code{assert} facility is designed for
+detecting @emph{internal inconsistency}; it is not suitable for
+reporting invalid input or improper usage by @emph{the user} of the
+program.
+
+The information in the diagnostic messages printed by the @code{assert}
+macro is intended to help you, the programmer, track down the cause of a
+bug, but is not really useful for telling a user of your program why his
+or her input was invalid or why a command could not be carried out. So
+you can't use @code{assert} to print the error messages for these
+eventualities.
+
+What's more, your program should not abort when given invalid input, as
+@code{assert} would do---it should exit with nonzero status (@pxref{Exit
+Status}) after printing its error messages, or perhaps read another
+command or move on to the next input file.
+
+@xref{Error Messages}, for information on printing error messages for
+problems that @emph{do not} represent bugs in the program.
+
+
+@node Variadic Functions
+@section Variadic Functions
+@cindex variable number of arguments
+@cindex variadic functions
+@cindex optional arguments
+
+ANSI C defines a syntax for declaring a function to take a variable
+number or type of arguments. (Such functions are referred to as
+@dfn{varargs functions} or @dfn{variadic functions}.) However, the
+language itself provides no mechanism for such functions to access their
+non-required arguments; instead, you use the variable arguments macros
+defined in @file{stdarg.h}.
+
+This section describes how to declare variadic functions, how to write
+them, and how to call them properly.
+
+@strong{Compatibility Note:} Many older C dialects provide a similar,
+but incompatible, mechanism for defining functions with variable numbers
+of arguments, using @file{varargs.h}.
+
+@menu
+* Why Variadic:: Reasons for making functions take
+ variable arguments.
+* How Variadic:: How to define and call variadic functions.
+* Variadic Example:: A complete example.
+@end menu
+
+@node Why Variadic
+@subsection Why Variadic Functions are Used
+
+Ordinary C functions take a fixed number of arguments. When you define
+a function, you specify the data type for each argument. Every call to
+the function should supply the expected number of arguments, with types
+that can be converted to the specified ones. Thus, if the function
+@samp{foo} is declared with @code{int foo (int, char *);} then you must
+call it with two arguments, a number (any kind will do) and a string
+pointer.
+
+But some functions perform operations that can meaningfully accept an
+unlimited number of arguments.
+
+In some cases a function can handle any number of values by operating on
+all of them as a block. For example, consider a function that allocates
+a one-dimensional array with @code{malloc} to hold a specified set of
+values. This operation makes sense for any number of values, as long as
+the length of the array corresponds to that number. Without facilities
+for variable arguments, you would have to define a separate function for
+each possible array size.
+
+The library function @code{printf} (@pxref{Formatted Output}) is an
+example of another class of function where variable arguments are
+useful. This function prints its arguments (which can vary in type as
+well as number) under the control of a format template string.
+
+These are good reasons to define a @dfn{variadic} function which can
+handle as many arguments as the caller chooses to pass.
+
+Some functions such as @code{open} take a fixed set of arguments, but
+occasionally ignore the last few. Strict adherence to ANSI C requires
+these functions to be defined as variadic; in practice, however, the GNU
+C compiler and most other C compilers let you define such a function to
+take a fixed set of arguments---the most it can ever use---and then only
+@emph{declare} the function as variadic (or not declare its arguments
+at all!).
+
+@node How Variadic
+@subsection How Variadic Functions are Defined and Used
+
+Defining and using a variadic function involves three steps:
+
+@itemize @bullet
+@item
+@emph{Define} the function as variadic, using an ellipsis
+(@samp{@dots{}}) in the argument list, and using special macros to
+access the variable arguments. @xref{Receiving Arguments}.
+
+@item
+@emph{Declare} the function as variadic, using a prototype with an
+ellipsis (@samp{@dots{}}), in all the files which call it.
+@xref{Variadic Prototypes}.
+
+@item
+@emph{Call} the function by writing the fixed arguments followed by the
+additional variable arguments. @xref{Calling Variadics}.
+@end itemize
+
+@menu
+* Variadic Prototypes:: How to make a prototype for a function
+ with variable arguments.
+* Receiving Arguments:: Steps you must follow to access the
+ optional argument values.
+* How Many Arguments:: How to decide whether there are more arguments.
+* Calling Variadics:: Things you need to know about calling
+ variable arguments functions.
+* Argument Macros:: Detailed specification of the macros
+ for accessing variable arguments.
+* Old Varargs:: The pre-ANSI way of defining variadic functions.
+@end menu
+
+@node Variadic Prototypes
+@subsubsection Syntax for Variable Arguments
+@cindex function prototypes (variadic)
+@cindex prototypes for variadic functions
+@cindex variadic function prototypes
+
+A function that accepts a variable number of arguments must be declared
+with a prototype that says so. You write the fixed arguments as usual,
+and then tack on @samp{@dots{}} to indicate the possibility of
+additional arguments. The syntax of ANSI C requires at least one fixed
+argument before the @samp{@dots{}}. For example,
+
+@smallexample
+int
+func (const char *a, int b, @dots{})
+@{
+ @dots{}
+@}
+@end smallexample
+
+@noindent
+outlines a definition of a function @code{func} which returns an
+@code{int} and takes two required arguments, a @code{const char *} and
+an @code{int}. These are followed by any number of anonymous
+arguments.
+
+@strong{Portability note:} For some C compilers, the last required
+argument must not be declared @code{register} in the function
+definition. Furthermore, this argument's type must be
+@dfn{self-promoting}: that is, the default promotions must not change
+its type. This rules out array and function types, as well as
+@code{float}, @code{char} (whether signed or not) and @w{@code{short int}}
+(whether signed or not). This is actually an ANSI C requirement.
+
+@node Receiving Arguments
+@subsubsection Receiving the Argument Values
+@cindex variadic function argument access
+@cindex arguments (variadic functions)
+
+Ordinary fixed arguments have individual names, and you can use these
+names to access their values. But optional arguments have no
+names---nothing but @samp{@dots{}}. How can you access them?
+
+@pindex stdarg.h
+The only way to access them is sequentially, in the order they were
+written, and you must use special macros from @file{stdarg.h} in the
+following three step process:
+
+@enumerate
+@item
+You initialize an argument pointer variable of type @code{va_list} using
+@code{va_start}. The argument pointer when initialized points to the
+first optional argument.
+
+@item
+You access the optional arguments by successive calls to @code{va_arg}.
+The first call to @code{va_arg} gives you the first optional argument,
+the next call gives you the second, and so on.
+
+You can stop at any time if you wish to ignore any remaining optional
+arguments. It is perfectly all right for a function to access fewer
+arguments than were supplied in the call, but you will get garbage
+values if you try to access too many arguments.
+
+@item
+You indicate that you are finished with the argument pointer variable by
+calling @code{va_end}.
+
+(In practice, with most C compilers, calling @code{va_end} does nothing
+and you do not really need to call it. This is always true in the GNU C
+compiler. But you might as well call @code{va_end} just in case your
+program is someday compiled with a peculiar compiler.)
+@end enumerate
+
+@xref{Argument Macros}, for the full definitions of @code{va_start},
+@code{va_arg} and @code{va_end}.
+
+Steps 1 and 3 must be performed in the function that accepts the
+optional arguments. However, you can pass the @code{va_list} variable
+as an argument to another function and perform all or part of step 2
+there.
+
+You can perform the entire sequence of the three steps multiple times
+within a single function invocation. If you want to ignore the optional
+arguments, you can do these steps zero times.
+
+You can have more than one argument pointer variable if you like. You
+can initialize each variable with @code{va_start} when you wish, and
+then you can fetch arguments with each argument pointer as you wish.
+Each argument pointer variable will sequence through the same set of
+argument values, but at its own pace.
+
+@strong{Portability note:} With some compilers, once you pass an
+argument pointer value to a subroutine, you must not keep using the same
+argument pointer value after that subroutine returns. For full
+portability, you should just pass it to @code{va_end}. This is actually
+an ANSI C requirement, but most ANSI C compilers work happily
+regardless.
+
+@node How Many Arguments
+@subsubsection How Many Arguments Were Supplied
+@cindex number of arguments passed
+@cindex how many arguments
+@cindex arguments, how many
+
+There is no general way for a function to determine the number and type
+of the optional arguments it was called with. So whoever designs the
+function typically designs a convention for the caller to tell it how
+many arguments it has, and what kind. It is up to you to define an
+appropriate calling convention for each variadic function, and write all
+calls accordingly.
+
+One kind of calling convention is to pass the number of optional
+arguments as one of the fixed arguments. This convention works provided
+all of the optional arguments are of the same type.
+
+A similar alternative is to have one of the required arguments be a bit
+mask, with a bit for each possible purpose for which an optional
+argument might be supplied. You would test the bits in a predefined
+sequence; if the bit is set, fetch the value of the next argument,
+otherwise use a default value.
+
+A required argument can be used as a pattern to specify both the number
+and types of the optional arguments. The format string argument to
+@code{printf} is one example of this (@pxref{Formatted Output Functions}).
+
+Another possibility is to pass an ``end marker'' value as the last
+optional argument. For example, for a function that manipulates an
+arbitrary number of pointer arguments, a null pointer might indicate the
+end of the argument list. (This assumes that a null pointer isn't
+otherwise meaningful to the function.) The @code{execl} function works
+in just this way; see @ref{Executing a File}.
+
+
+@node Calling Variadics
+@subsubsection Calling Variadic Functions
+@cindex variadic functions, calling
+@cindex calling variadic functions
+@cindex declaring variadic functions
+
+You don't have to write anything special when you call a variadic function.
+Just write the arguments (required arguments, followed by optional ones)
+inside parentheses, separated by commas, as usual. But you should prepare
+by declaring the function with a prototype, and you must know how the
+argument values are converted.
+
+In principle, functions that are @emph{defined} to be variadic must also
+be @emph{declared} to be variadic using a function prototype whenever
+you call them. (@xref{Variadic Prototypes}, for how.) This is because
+some C compilers use a different calling convention to pass the same set
+of argument values to a function depending on whether that function
+takes variable arguments or fixed arguments.
+
+In practice, the GNU C compiler always passes a given set of argument
+types in the same way regardless of whether they are optional or
+required. So, as long as the argument types are self-promoting, you can
+safely omit declaring them. Usually it is a good idea to declare the
+argument types for variadic functions, and indeed for all functions.
+But there are a few functions which it is extremely convenient not to
+have to declare as variadic---for example, @code{open} and
+@code{printf}.
+
+@cindex default argument promotions
+@cindex argument promotion
+Since the prototype doesn't specify types for optional arguments, in a
+call to a variadic function the @dfn{default argument promotions} are
+performed on the optional argument values. This means the objects of
+type @code{char} or @w{@code{short int}} (whether signed or not) are
+promoted to either @code{int} or @w{@code{unsigned int}}, as
+appropriate; and that objects of type @code{float} are promoted to type
+@code{double}. So, if the caller passes a @code{char} as an optional
+argument, it is promoted to an @code{int}, and the function should get
+it with @code{va_arg (@var{ap}, int)}.
+
+Conversion of the required arguments is controlled by the function
+prototype in the usual way: the argument expression is converted to the
+declared argument type as if it were being assigned to a variable of
+that type.
+
+@node Argument Macros
+@subsubsection Argument Access Macros
+
+Here are descriptions of the macros used to retrieve variable arguments.
+These macros are defined in the header file @file{stdarg.h}.
+@pindex stdarg.h
+
+@comment stdarg.h
+@comment ANSI
+@deftp {Data Type} va_list
+The type @code{va_list} is used for argument pointer variables.
+@end deftp
+
+@comment stdarg.h
+@comment ANSI
+@deftypefn {Macro} void va_start (va_list @var{ap}, @var{last-required})
+This macro initializes the argument pointer variable @var{ap} to point
+to the first of the optional arguments of the current function;
+@var{last-required} must be the last required argument to the function.
+
+@xref{Old Varargs}, for an alternate definition of @code{va_start}
+found in the header file @file{varargs.h}.
+@end deftypefn
+
+@comment stdarg.h
+@comment ANSI
+@deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
+The @code{va_arg} macro returns the value of the next optional argument,
+and modifies the value of @var{ap} to point to the subsequent argument.
+Thus, successive uses of @code{va_arg} return successive optional
+arguments.
+
+The type of the value returned by @code{va_arg} is @var{type} as
+specified in the call. @var{type} must be a self-promoting type (not
+@code{char} or @code{short int} or @code{float}) that matches the type
+of the actual argument.
+@end deftypefn
+
+@comment stdarg.h
+@comment ANSI
+@deftypefn {Macro} void va_end (va_list @var{ap})
+This ends the use of @var{ap}. After a @code{va_end} call, further
+@code{va_arg} calls with the same @var{ap} may not work. You should invoke
+@code{va_end} before returning from the function in which @code{va_start}
+was invoked with the same @var{ap} argument.
+
+In the GNU C library, @code{va_end} does nothing, and you need not ever
+use it except for reasons of portability.
+@refill
+@end deftypefn
+
+@node Variadic Example
+@subsection Example of a Variadic Function
+
+Here is a complete sample function that accepts a variable number of
+arguments. The first argument to the function is the count of remaining
+arguments, which are added up and the result returned. While trivial,
+this function is sufficient to illustrate how to use the variable
+arguments facility.
+
+@comment Yes, this example has been tested.
+@smallexample
+@include add.c.texi
+@end smallexample
+
+@node Old Varargs
+@subsubsection Old-Style Variadic Functions
+
+@pindex varargs.h
+Before ANSI C, programmers used a slightly different facility for
+writing variadic functions. The GNU C compiler still supports it;
+currently, it is more portable than the ANSI C facility, since support
+for ANSI C is still not universal. The header file which defines the
+old-fashioned variadic facility is called @file{varargs.h}.
+
+Using @file{varargs.h} is almost the same as using @file{stdarg.h}.
+There is no difference in how you call a variadic function;
+@xref{Calling Variadics}. The only difference is in how you define
+them. First of all, you must use old-style non-prototype syntax, like
+this:
+
+@smallexample
+tree
+build (va_alist)
+ va_dcl
+@{
+@end smallexample
+
+Secondly, you must give @code{va_start} just one argument, like this:
+
+@smallexample
+ va_list p;
+ va_start (p);
+@end smallexample
+
+These are the special macros used for defining old-style variadic
+functions:
+
+@comment varargs.h
+@comment Unix
+@deffn Macro va_alist
+This macro stands for the argument name list required in a variadic
+function.
+@end deffn
+
+@comment varargs.h
+@comment Unix
+@deffn Macro va_dcl
+This macro declares the implicit argument or arguments for a variadic
+function.
+@end deffn
+
+@comment varargs.h
+@comment Unix
+@deftypefn {Macro} void va_start (va_list @var{ap})
+This macro, as defined in @file{varargs.h}, initializes the argument
+pointer variable @var{ap} to point to the first argument of the current
+function.
+@end deftypefn
+
+The other argument macros, @code{va_arg} and @code{va_end}, are the same
+in @file{varargs.h} as in @file{stdarg.h}; see @ref{Argument Macros} for
+details.
+
+It does not work to include both @file{varargs.h} and @file{stdarg.h} in
+the same compilation; they define @code{va_start} in conflicting ways.
+
+@node Null Pointer Constant
+@section Null Pointer Constant
+@cindex null pointer constant
+
+The null pointer constant is guaranteed not to point to any real object.
+You can assign it to any pointer variable since it has type @code{void
+*}. The preferred way to write a null pointer constant is with
+@code{NULL}.
+
+@comment stddef.h
+@comment ANSI
+@deftypevr Macro {void *} NULL
+This is a null pointer constant.
+@end deftypevr
+
+You can also use @code{0} or @code{(void *)0} as a null pointer
+constant, but using @code{NULL} is cleaner because it makes the purpose
+of the constant more evident.
+
+If you use the null pointer constant as a function argument, then for
+complete portability you should make sure that the function has a
+prototype declaration. Otherwise, if the target machine has two
+different pointer representations, the compiler won't know which
+representation to use for that argument. You can avoid the problem by
+explicitly casting the constant to the proper pointer type, but we
+recommend instead adding a prototype for the function you are calling.
+
+@node Important Data Types
+@section Important Data Types
+
+The result of subtracting two pointers in C is always an integer, but the
+precise data type varies from C compiler to C compiler. Likewise, the
+data type of the result of @code{sizeof} also varies between compilers.
+ANSI defines standard aliases for these two types, so you can refer to
+them in a portable fashion. They are defined in the header file
+@file{stddef.h}.
+@pindex stddef.h
+
+@comment stddef.h
+@comment ANSI
+@deftp {Data Type} ptrdiff_t
+This is the signed integer type of the result of subtracting two
+pointers. For example, with the declaration @code{char *p1, *p2;}, the
+expression @code{p2 - p1} is of type @code{ptrdiff_t}. This will
+probably be one of the standard signed integer types (@w{@code{short
+int}}, @code{int} or @w{@code{long int}}), but might be a nonstandard
+type that exists only for this purpose.
+@end deftp
+
+@comment stddef.h
+@comment ANSI
+@deftp {Data Type} size_t
+This is an unsigned integer type used to represent the sizes of objects.
+The result of the @code{sizeof} operator is of this type, and functions
+such as @code{malloc} (@pxref{Unconstrained Allocation}) and
+@code{memcpy} (@pxref{Copying and Concatenation}) accept arguments of
+this type to specify object sizes.
+
+@strong{Usage Note:} @code{size_t} is the preferred way to declare any
+arguments or variables that hold the size of an object.
+@end deftp
+
+In the GNU system @code{size_t} is equivalent to either
+@w{@code{unsigned int}} or @w{@code{unsigned long int}}. These types
+have identical properties on the GNU system, and for most purposes, you
+can use them interchangeably. However, they are distinct as data types,
+which makes a difference in certain contexts.
+
+For example, when you specify the type of a function argument in a
+function prototype, it makes a difference which one you use. If the
+system header files declare @code{malloc} with an argument of type
+@code{size_t} and you declare @code{malloc} with an argument of type
+@code{unsigned int}, you will get a compilation error if @code{size_t}
+happens to be @code{unsigned long int} on your system. To avoid any
+possibility of error, when a function argument or value is supposed to
+have type @code{size_t}, never declare its type in any other way.
+
+@strong{Compatibility Note:} Implementations of C before the advent of
+ANSI C generally used @code{unsigned int} for representing object sizes
+and @code{int} for pointer subtraction results. They did not
+necessarily define either @code{size_t} or @code{ptrdiff_t}. Unix
+systems did define @code{size_t}, in @file{sys/types.h}, but the
+definition was usually a signed type.
+
+@node Data Type Measurements
+@section Data Type Measurements
+
+Most of the time, if you choose the proper C data type for each object
+in your program, you need not be concerned with just how it is
+represented or how many bits it uses. When you do need such
+information, the C language itself does not provide a way to get it.
+The header files @file{limits.h} and @file{float.h} contain macros
+which give you this information in full detail.
+
+@menu
+* Width of Type:: How many bits does an integer type hold?
+* Range of Type:: What are the largest and smallest values
+ that an integer type can hold?
+* Floating Type Macros:: Parameters that measure the floating point types.
+* Structure Measurement:: Getting measurements on structure types.
+@end menu
+
+@node Width of Type
+@subsection Computing the Width of an Integer Data Type
+@cindex integer type width
+@cindex width of integer type
+@cindex type measurements, integer
+
+The most common reason that a program needs to know how many bits are in
+an integer type is for using an array of @code{long int} as a bit vector.
+You can access the bit at index @var{n} with
+
+@smallexample
+vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
+@end smallexample
+
+@noindent
+provided you define @code{LONGBITS} as the number of bits in a
+@code{long int}.
+
+@pindex limits.h
+There is no operator in the C language that can give you the number of
+bits in an integer data type. But you can compute it from the macro
+@code{CHAR_BIT}, defined in the header file @file{limits.h}.
+
+@table @code
+@comment limits.h
+@comment ANSI
+@item CHAR_BIT
+This is the number of bits in a @code{char}---eight, on most systems.
+The value has type @code{int}.
+
+You can compute the number of bits in any data type @var{type} like
+this:
+
+@smallexample
+sizeof (@var{type}) * CHAR_BIT
+@end smallexample
+@end table
+
+@node Range of Type
+@subsection Range of an Integer Type
+@cindex integer type range
+@cindex range of integer type
+@cindex limits, integer types
+
+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 @samp{MIN} and @samp{MAX} macros in @file{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
+@samp{MAX} and @samp{MIN} macros for @code{char} and @w{@code{short
+int}} types have values of type @code{int}. The @samp{MAX} and
+@samp{MIN} macros for the other types have values of the same type
+described by the macro---thus, @code{ULONG_MAX} has type
+@w{@code{unsigned long int}}.
+
+@comment Extra blank lines make it look better.
+@table @code
+@comment limits.h
+@comment ANSI
+@item SCHAR_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed char}}.
+
+@comment limits.h
+@comment ANSI
+@item SCHAR_MAX
+@comment limits.h
+@comment ANSI
+@itemx UCHAR_MAX
+
+These are the maximum values that can be represented by a
+@w{@code{signed char}} and @w{@code{unsigned char}}, respectively.
+
+@comment limits.h
+@comment ANSI
+@item 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.
+
+@comment limits.h
+@comment ANSI
+@item 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.
+
+@comment limits.h
+@comment ANSI
+@item SHRT_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed
+short int}}. On most machines that the GNU C library runs on,
+@code{short} integers are 16-bit quantities.
+
+@comment limits.h
+@comment ANSI
+@item SHRT_MAX
+@comment limits.h
+@comment ANSI
+@itemx USHRT_MAX
+
+These are the maximum values that can be represented by a
+@w{@code{signed short int}} and @w{@code{unsigned short int}},
+respectively.
+
+@comment limits.h
+@comment ANSI
+@item INT_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed
+int}}. On most machines that the GNU C system runs on, an @code{int} is
+a 32-bit quantity.
+
+@comment limits.h
+@comment ANSI
+@item INT_MAX
+@comment limits.h
+@comment ANSI
+@itemx UINT_MAX
+
+These are the maximum values that can be represented by, respectively,
+the type @w{@code{signed int}} and the type @w{@code{unsigned int}}.
+
+@comment limits.h
+@comment ANSI
+@item LONG_MIN
+
+This is the minimum value that can be represented by a @w{@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}.
+
+@comment limits.h
+@comment ANSI
+@item LONG_MAX
+@comment limits.h
+@comment ANSI
+@itemx ULONG_MAX
+
+These are the maximum values that can be represented by a
+@w{@code{signed long int}} and @code{unsigned long int}, respectively.
+
+@comment limits.h
+@comment GNU
+@item LONG_LONG_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed
+long long int}}. On most machines that the GNU C system runs on,
+@w{@code{long long}} integers are 64-bit quantities.
+
+@comment limits.h
+@comment GNU
+@item LONG_LONG_MAX
+@comment limits.h
+@comment ANSI
+@itemx ULONG_LONG_MAX
+
+These are the maximum values that can be represented by a @code{signed
+long long int} and @code{unsigned long long int}, respectively.
+
+@comment limits.h
+@comment GNU
+@item WCHAR_MAX
+
+This is the maximum value that can be represented by a @code{wchar_t}.
+@xref{Wide Char Intro}.
+@end table
+
+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 Configuration}.
+
+@node Floating Type Macros
+@subsection Floating Type Macros
+@cindex floating type measurements
+@cindex measurements of floating types
+@cindex type measurements, floating
+@cindex limits, floating types
+
+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
+(@pxref{I/O on Streams}) and for calculating trigonometric and
+irrational functions (@pxref{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 @file{float.h} describes the format used by your
+machine.
+
+@menu
+* Floating Point Concepts:: Definitions of terminology.
+* Floating Point Parameters:: Details of specific macros.
+* IEEE Floating Point:: The measurements for one common
+ representation.
+@end menu
+
+@node Floating Point Concepts
+@subsubsection 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 @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
+@cindex sign (of floating point number)
+The @dfn{sign} is either @code{-1} or @code{1}.
+
+@item
+@cindex base (of floating point number)
+@cindex radix (of floating point number)
+The @dfn{base} or @dfn{radix} for exponentiation, an integer greater
+than @code{1}. This is a constant for a particular representation.
+
+@item
+@cindex exponent (of floating point number)
+The @dfn{exponent} to which the base is raised. The upper and lower
+bounds of the exponent value are constants for a particular
+representation.
+
+@cindex bias (of floating point number exponent)
+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.
+
+@item
+@cindex mantissa (of floating point number)
+@cindex significand (of floating point number)
+The @dfn{mantissa} or @dfn{significand}, an unsigned integer which is a
+part of each floating point number.
+
+@item
+@cindex precision (of floating point number)
+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 a particular representation.
+
+@cindex hidden bit (of floating point number mantissa)
+Many floating point representations have an implicit @dfn{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.
+@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.
+
+@cindex normalized floating point number
+We say that the floating point number is @dfn{normalized} if the
+fraction is at least @code{1/@var{b}}, where @var{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
+@dfn{denormal}; they contain less precision than the representation
+normally can hold.
+
+If the number is not normalized, then you can subtract @code{1} from the
+exponent while multiplying the mantissa by the base, and get another
+floating point number with the same value. @dfn{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 @code{1} from the exponent, so a number
+may be normalized even if its fraction is less than @code{1/@var{b}}.)
+
+@node Floating Point Parameters
+@subsubsection Floating Point Parameters
+
+@pindex float.h
+These macro definitions can be accessed by including the header file
+@file{float.h} in your program.
+
+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. (Currently GCC does not support @code{long double} as a distinct
+data type, so the values for the @samp{LDBL_} constants are equal to the
+corresponding constants for the @code{double} type.)@refill
+
+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 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.
+
+@table @code
+@comment float.h
+@comment ANSI
+@item FLT_ROUNDS
+This value characterizes the rounding mode for floating point addition.
+The following values indicate standard rounding modes:
+
+@need 750
+
+@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.
+
+On most machines, the value is @code{1}, in accordance with the IEEE
+standard for floating point.
+
+Here is a table showing how certain values round for each possible value
+of @code{FLT_ROUNDS}, if the other aspects of the representation match
+the IEEE single-precision standard.
+
+@smallexample
+ 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
+@end smallexample
+
+@comment float.h
+@comment ANSI
+@item 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.
+
+@comment float.h
+@comment ANSI
+@item FLT_MANT_DIG
+This is the number of base-@code{FLT_RADIX} digits in the floating point
+mantissa for the @code{float} data type. The following expression
+yields @code{1.0} (even though mathematically it should not) due to the
+limited number of mantissa digits:
+
+@smallexample
+float radix = FLT_RADIX;
+
+1.0f + 1.0f / radix / radix / @dots{} / radix
+@end smallexample
+
+@noindent
+where @code{radix} appears @code{FLT_MANT_DIG} times.
+
+@comment float.h
+@comment ANSI
+@item DBL_MANT_DIG
+@itemx LDBL_MANT_DIG
+This is the number of base-@code{FLT_RADIX} digits in the floating point
+mantissa for the data types @code{double} and @code{long double},
+respectively.
+
+@comment Extra blank lines make it look better.
+@comment float.h
+@comment ANSI
+@item 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 supposed to be at least @code{6}, to satisfy
+ANSI C.
+
+@comment float.h
+@comment ANSI
+@item DBL_DIG
+@itemx LDBL_DIG
+
+These are similar to @code{FLT_DIG}, but for the data types
+@code{double} and @code{long double}, respectively. The values of these
+macros are supposed to be at least @code{10}.
+
+@comment float.h
+@comment ANSI
+@item FLT_MIN_EXP
+This is the smallest possible exponent value for type @code{float}.
+More precisely, is the minimum negative integer such that the value
+@code{FLT_RADIX} raised to this power minus 1 can be represented as a
+normalized floating point number of type @code{float}.
+
+@comment float.h
+@comment ANSI
+@item DBL_MIN_EXP
+@itemx LDBL_MIN_EXP
+
+These are similar to @code{FLT_MIN_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ANSI
+@item FLT_MIN_10_EXP
+This is the minimum negative integer such that @code{10} raised to this
+power minus 1 can be represented as a normalized floating point number
+of type @code{float}. This is supposed to be @code{-37} or even less.
+
+@comment float.h
+@comment ANSI
+@item DBL_MIN_10_EXP
+@itemx LDBL_MIN_10_EXP
+These are similar to @code{FLT_MIN_10_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ANSI
+@item FLT_MAX_EXP
+This is the largest possible exponent value for type @code{float}. More
+precisely, this is the maximum positive integer such that value
+@code{FLT_RADIX} raised to this power minus 1 can be represented as a
+floating point number of type @code{float}.
+
+@comment float.h
+@comment ANSI
+@item DBL_MAX_EXP
+@itemx LDBL_MAX_EXP
+These are similar to @code{FLT_MAX_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ANSI
+@item FLT_MAX_10_EXP
+This is the maximum positive integer such that @code{10} raised to this
+power minus 1 can be represented as a normalized floating point number
+of type @code{float}. This is supposed to be at least @code{37}.
+
+@comment float.h
+@comment ANSI
+@item DBL_MAX_10_EXP
+@itemx LDBL_MAX_10_EXP
+These are similar to @code{FLT_MAX_10_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ANSI
+@item FLT_MAX
+
+The value of this macro is the maximum number representable in type
+@code{float}. It is supposed to be at least @code{1E+37}. The value
+has type @code{float}.
+
+The smallest representable number is @code{- FLT_MAX}.
+
+@comment float.h
+@comment ANSI
+@item DBL_MAX
+@itemx LDBL_MAX
+
+These are similar to @code{FLT_MAX}, but for the data types
+@code{double} and @code{long double}, respectively. The type of the
+macro's value is the same as the type it describes.
+
+@comment float.h
+@comment ANSI
+@item FLT_MIN
+
+The value of this macro is the minimum normalized positive floating
+point number that is representable in type @code{float}. It is supposed
+to be no more than @code{1E-37}.
+
+@comment float.h
+@comment ANSI
+@item DBL_MIN
+@itemx LDBL_MIN
+
+These are similar to @code{FLT_MIN}, but for the data types
+@code{double} and @code{long double}, respectively. The type of the
+macro's value is the same as the type it describes.
+
+@comment float.h
+@comment ANSI
+@item 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 supposed to
+be no greater than @code{1E-5}.
+
+@comment float.h
+@comment ANSI
+@item DBL_EPSILON
+@itemx LDBL_EPSILON
+
+These are similar to @code{FLT_EPSILON}, but for the data types
+@code{double} and @code{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 @code{1E-9}.
+@end table
+
+@node IEEE Floating Point
+@subsubsection IEEE Floating Point
+@cindex IEEE floating point representation
+@cindex floating point, IEEE
+
+Here is an example showing how the floating type measurements come out
+for the most common floating point representation, specified by the
+@cite{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
+@code{float} data type, appropriate values for the corresponding
+parameters are:
+
+@smallexample
+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 smallexample
+
+Here are the values for the @code{double} data type:
+
+@smallexample
+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 smallexample
+
+@node Structure Measurement
+@subsection Structure Field Offset Measurement
+
+You can use @code{offsetof} to measure the location within a structure
+type of a particular structure member.
+
+@comment stddef.h
+@comment ANSI
+@deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
+This expands to a integer constant expression that is the offset of the
+structure member named @var{member} in a the structure type @var{type}.
+For example, @code{offsetof (struct s, elem)} is the offset, in bytes,
+of the member @code{elem} in a @code{struct s}.
+
+This macro won't work if @var{member} is a bit field; you get an error
+from the C compiler in that case.
+@end deftypefn