This is Info file libc.info, produced by Makeinfo version 1.67 from the
input file libc.texinfo.

   This file documents the GNU C library.

   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
Library Reference Manual', for Version 2.00 Beta.

   Copyright (C) 1993, '94, '95, '96 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 translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.


File: libc.info,  Node: Utility Minimums,  Next: String Parameters,  Prev: Utility Limits,  Up: System Configuration

Minimum Values for Utility Limits
=================================

`_POSIX2_BC_BASE_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     value of `obase' in the `bc' utility.  Its value is `99'.

`_POSIX2_BC_DIM_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     size of an array in the `bc' utility.  Its value is `2048'.

`_POSIX2_BC_SCALE_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     value of `scale' in the `bc' utility.  Its value is `99'.

`_POSIX2_BC_STRING_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     size of a string constant in the `bc' utility.  Its value is
     `1000'.

`_POSIX2_COLL_WEIGHTS_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     number of weights that can necessarily be used in defining the
     collating sequence for a locale.  Its value is `2'.

`_POSIX2_EXPR_NEST_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     number of expressions nested within parenthesis when using the
     `expr' utility.  Its value is `32'.

`_POSIX2_LINE_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     size of a text line that the text utilities can handle.  Its value
     is `2048'.

`_POSIX2_EQUIV_CLASS_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     number of weights that can be assigned to an entry of the
     `LC_COLLATE' category `order' keyword in a locale definition.  Its
     value is `2'.  The GNU C library does not presently support locale
     definitions.


File: libc.info,  Node: String Parameters,  Prev: Utility Minimums,  Up: System Configuration

String-Valued Parameters
========================

   POSIX.2 defines a way to get string-valued parameters from the
operating system with the function `confstr':

 - Function: size_t confstr (int PARAMETER, char *BUF, size_t LEN)
     This function reads the value of a string-valued system parameter,
     storing the string into LEN bytes of memory space starting at BUF.
     The PARAMETER argument should be one of the `_CS_' symbols listed
     below.

     The normal return value from `confstr' is the length of the string
     value that you asked for.  If you supply a null pointer for BUF,
     then `confstr' does not try to store the string; it just returns
     its length.  A value of `0' indicates an error.

     If the string you asked for is too long for the buffer (that is,
     longer than `LEN - 1'), then `confstr' stores just that much
     (leaving room for the terminating null character).  You can tell
     that this has happened because `confstr' returns a value greater
     than or equal to LEN.

     The following `errno' error conditions are defined for this
     function:

    `EINVAL'
          The value of the PARAMETER is invalid.

   Currently there is just one parameter you can read with `confstr':

`_CS_PATH'
     This parameter's value is the recommended default path for
     searching for executable files.  This is the path that a user has
     by default just after logging in.

   The way to use `confstr' without any arbitrary limit on string size
is to call it twice: first call it to get the length, allocate the
buffer accordingly, and then call `confstr' again to fill the buffer,
like this:

     char *
     get_default_path (void)
     {
       size_t len = confstr (_CS_PATH, NULL, 0);
       char *buffer = (char *) xmalloc (len);
     
       if (confstr (_CS_PATH, buf, len + 1) == 0)
         {
           free (buffer);
           return NULL;
         }
     
       return buffer;
     }


File: libc.info,  Node: Language Features,  Next: Library Summary,  Prev: System Configuration,  Up: Top

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 `assert' to abort if
				 something "impossible" happens.
* Variadic Functions::          Defining functions with varying numbers
                                 of args.
* Null Pointer Constant::       The macro `NULL'.
* Important Data Types::        Data types for object sizes.
* Data Type Measurements::      Parameters of data type representations.


File: libc.info,  Node: Consistency Checking,  Next: Variadic Functions,  Up: Language Features

Explicitly Checking Internal Consistency
========================================

   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 kinds of checks are helpful in debugging
problems with the interfaces between different parts of the program,
for example.

   The `assert' macro, defined in the header file `assert.h', provides
a convenient way to abort the program while printing a message about
where in the program the error was detected.

   Once you think your program is debugged, you can disable the error
checks performed by the `assert' macro by recompiling with the macro
`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.

 - Macro: void assert (int EXPRESSION)
     Verify the programmer's belief that EXPRESSION should be nonzero
     at this point in the program.

     If `NDEBUG' is not defined, `assert' tests the value of
     EXPRESSION.  If it is false (zero), `assert' aborts the program
     (*note Aborting a Program::.) after printing a message of the form:

          `FILE':LINENUM: FUNCTION: Assertion `EXPRESSION' failed.

     on the standard error stream `stderr' (*note Standard Streams::.).
     The filename and line number are taken from the C preprocessor
     macros `__FILE__' and `__LINE__' and specify where the call to
     `assert' was written.  When using the GNU C compiler, the name of
     the function which calls `assert' is taken from the built-in
     variable `__PRETTY_FUNCTION__'; with older compilers, the function
     name and following colon are omitted.

     If the preprocessor macro `NDEBUG' is defined before `assert.h' is
     included, the `assert' macro is defined to do absolutely nothing.

     *Warning:* Even the argument expression EXPRESSION is not
     evaluated if `NDEBUG' is in effect.  So never use `assert' with
     arguments that involve side effects.  For example, `assert (++i >
     0);' is a bad idea, because `i' will not be incremented if
     `NDEBUG' is defined.

   Sometimes the "impossible" condition you want to check for is an
error return from an operating system function.  Then it is useful to
display not only where the program crashes, but also what error was
returned.  The `assert_perror' macro makes this easy.

 - Macro: void assert_perror (int ERRNUM)
     Similar to `assert', but verifies that ERRNUM is zero.

     If `NDEBUG' is defined, `assert_perror' tests the value of ERRNUM.
     If it is nonzero, `assert_perror' aborts the program after a
     printing a message of the form:

          `FILE':LINENUM: FUNCTION: ERROR TEXT

     on the standard error stream.  The file name, line number, and
     function name are as for `assert'.  The error text is the result of
     `strerror (ERRNUM)'.  *Note Error Messages::.

     Like `assert', if `NDEBUG' is defined before `assert.h' is
     included, the `assert_perror' macro does absolutely nothing.  It
     does not evaluate the argument, so ERRNUM should not have any side
     effects.  It is best for ERRNUM to be a just simple variable
     reference; often it will be `errno'.

     This macro is a GNU extension.

   *Usage note:* The `assert' facility is designed for detecting
*internal inconsistency*; it is not suitable for reporting invalid
input or improper usage by *the user* of the program.

   The information in the diagnostic messages printed by the `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 `assert' or `assert_perror' to print the error messages
for these eventualities.

   What's more, your program should not abort when given invalid input,
as `assert' would do--it should exit with nonzero status (*note Exit
Status::.) after printing its error messages, or perhaps read another
command or move on to the next input file.

   *Note Error Messages::, for information on printing error messages
for problems that *do not* represent bugs in the program.


File: libc.info,  Node: Variadic Functions,  Next: Null Pointer Constant,  Prev: Consistency Checking,  Up: Language Features

Variadic Functions
==================

   ISO C defines a syntax for declaring a function to take a variable
number or type of arguments.  (Such functions are referred to as
"varargs functions" or "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 `stdarg.h'.

   This section describes how to declare variadic functions, how to
write them, and how to call them properly.

   *Compatibility Note:* Many older C dialects provide a similar, but
incompatible, mechanism for defining functions with variable numbers of
arguments, using `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.


File: libc.info,  Node: Why Variadic,  Next: How Variadic,  Up: Variadic Functions

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 `foo' is declared with `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 `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 `printf' (*note 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 "variadic" function which can
handle as many arguments as the caller chooses to pass.

   Some functions such as `open' take a fixed set of arguments, but
occasionally ignore the last few.  Strict adherence to ISO 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
*declare* the function as variadic (or not declare its arguments at
all!).


File: libc.info,  Node: How Variadic,  Next: Variadic Example,  Prev: Why Variadic,  Up: Variadic Functions

How Variadic Functions are Defined and Used
-------------------------------------------

   Defining and using a variadic function involves three steps:

   * *Define* the function as variadic, using an ellipsis (`...') in
     the argument list, and using special macros to access the variable
     arguments.  *Note Receiving Arguments::.

   * *Declare* the function as variadic, using a prototype with an
     ellipsis (`...'), in all the files which call it.  *Note Variadic
     Prototypes::.

   * *Call* the function by writing the fixed arguments followed by the
     additional variable arguments.  *Note Calling Variadics::.

* 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-ISO way of defining variadic functions.


File: libc.info,  Node: Variadic Prototypes,  Next: Receiving Arguments,  Up: How Variadic

Syntax for Variable Arguments
.............................

   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 `...' to indicate the possibility of
additional arguments.  The syntax of ISO C requires at least one fixed
argument before the `...'.  For example,

     int
     func (const char *a, int b, ...)
     {
       ...
     }

outlines a definition of a function `func' which returns an `int' and
takes two required arguments, a `const char *' and an `int'.  These are
followed by any number of anonymous arguments.

   *Portability note:* For some C compilers, the last required argument
must not be declared `register' in the function definition.
Furthermore, this argument's type must be "self-promoting": that is,
the default promotions must not change its type.  This rules out array
and function types, as well as `float', `char' (whether signed or not)
and `short int' (whether signed or not).  This is actually an ISO C
requirement.


File: libc.info,  Node: Receiving Arguments,  Next: How Many Arguments,  Prev: Variadic Prototypes,  Up: How Variadic

Receiving the Argument Values
.............................

   Ordinary fixed arguments have individual names, and you can use these
names to access their values.  But optional arguments have no
names--nothing but `...'.  How can you access them?

   The only way to access them is sequentially, in the order they were
written, and you must use special macros from `stdarg.h' in the
following three step process:

  1. You initialize an argument pointer variable of type `va_list' using
     `va_start'.  The argument pointer when initialized points to the
     first optional argument.

  2. You access the optional arguments by successive calls to `va_arg'.
     The first call to `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.

  3. You indicate that you are finished with the argument pointer
     variable by calling `va_end'.

     (In practice, with most C compilers, calling `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 `va_end' just in case
     your program is someday compiled with a peculiar compiler.)

   *Note Argument Macros::, for the full definitions of `va_start',
`va_arg' and `va_end'.

   Steps 1 and 3 must be performed in the function that accepts the
optional arguments.  However, you can pass the `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 `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.

   *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 `va_end'.  This is actually an
ISO C requirement, but most ANSI C compilers work happily regardless.


File: libc.info,  Node: How Many Arguments,  Next: Calling Variadics,  Prev: Receiving Arguments,  Up: How Variadic

How Many Arguments Were Supplied
................................

   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 `printf' is one example of this (*note 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 `execl' function works in
just this way; see *Note Executing a File::.


File: libc.info,  Node: Calling Variadics,  Next: Argument Macros,  Prev: How Many Arguments,  Up: How Variadic

Calling 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 *defined* to be variadic must also
be *declared* to be variadic using a function prototype whenever you
call them.  (*Note 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, `open' and `printf'.

   Since the prototype doesn't specify types for optional arguments, in
a call to a variadic function the "default argument promotions" are
performed on the optional argument values.  This means the objects of
type `char' or `short int' (whether signed or not) are promoted to
either `int' or `unsigned int', as appropriate; and that objects of
type `float' are promoted to type `double'.  So, if the caller passes a
`char' as an optional argument, it is promoted to an `int', and the
function should get it with `va_arg (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.


File: libc.info,  Node: Argument Macros,  Next: Old Varargs,  Prev: Calling Variadics,  Up: How Variadic

Argument Access Macros
......................

   Here are descriptions of the macros used to retrieve variable
arguments.  These macros are defined in the header file `stdarg.h'.

 - Data Type: va_list
     The type `va_list' is used for argument pointer variables.

 - Macro: void va_start (va_list AP, LAST-REQUIRED)
     This macro initializes the argument pointer variable AP to point
     to the first of the optional arguments of the current function;
     LAST-REQUIRED must be the last required argument to the function.

     *Note Old Varargs::, for an alternate definition of `va_start'
     found in the header file `varargs.h'.

 - Macro: TYPE va_arg (va_list AP, TYPE)
     The `va_arg' macro returns the value of the next optional argument,
     and modifies the value of AP to point to the subsequent argument.
     Thus, successive uses of `va_arg' return successive optional
     arguments.

     The type of the value returned by `va_arg' is TYPE as specified in
     the call.  TYPE must be a self-promoting type (not `char' or
     `short int' or `float') that matches the type of the actual
     argument.

 - Macro: void va_end (va_list AP)
     This ends the use of AP.  After a `va_end' call, further `va_arg'
     calls with the same AP may not work.  You should invoke `va_end'
     before returning from the function in which `va_start' was invoked
     with the same AP argument.

     In the GNU C library, `va_end' does nothing, and you need not ever
     use it except for reasons of portability.



File: libc.info,  Node: Variadic Example,  Prev: How Variadic,  Up: Variadic Functions

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.

     #include <stdarg.h>
     #include <stdio.h>
     
     int
     add_em_up (int count,...)
     {
       va_list ap;
       int i, sum;
     
       va_start (ap, count);         /* Initialize the argument list. */
     
       sum = 0;
       for (i = 0; i < count; i++)
         sum += va_arg (ap, int);    /* Get the next argument value. */
     
       va_end (ap);                  /* Clean up. */
       return sum;
     }
     
     int
     main (void)
     {
       /* This call prints 16. */
       printf ("%d\n", add_em_up (3, 5, 5, 6));
     
       /* This call prints 55. */
       printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
     
       return 0;
     }


File: libc.info,  Node: Old Varargs,  Prev: Argument Macros,  Up: How Variadic

Old-Style Variadic Functions
............................

   Before ISO 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 ISO C facility, since support
for ISO C is still not universal.  The header file which defines the
old-fashioned variadic facility is called `varargs.h'.

   Using `varargs.h' is almost the same as using `stdarg.h'.  There is
no difference in how you call a variadic function; *Note Calling
Variadics::.  The only difference is in how you define them.  First of
all, you must use old-style non-prototype syntax, like this:

     tree
     build (va_alist)
          va_dcl
     {

   Secondly, you must give `va_start' just one argument, like this:

       va_list p;
       va_start (p);

   These are the special macros used for defining old-style variadic
functions:

 - Macro: va_alist
     This macro stands for the argument name list required in a variadic
     function.

 - Macro: va_dcl
     This macro declares the implicit argument or arguments for a
     variadic function.

 - Macro: void va_start (va_list AP)
     This macro, as defined in `varargs.h', initializes the argument
     pointer variable AP to point to the first argument of the current
     function.

   The other argument macros, `va_arg' and `va_end', are the same in
`varargs.h' as in `stdarg.h'; see *Note Argument Macros:: for details.

   It does not work to include both `varargs.h' and `stdarg.h' in the
same compilation; they define `va_start' in conflicting ways.


File: libc.info,  Node: Null Pointer Constant,  Next: Important Data Types,  Prev: Variadic Functions,  Up: Language Features

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
`void *'.  The preferred way to write a null pointer constant is with
`NULL'.

 - Macro: void * NULL
     This is a null pointer constant.

   You can also use `0' or `(void *)0' as a null pointer constant, but
using `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.


File: libc.info,  Node: Important Data Types,  Next: Data Type Measurements,  Prev: Null Pointer Constant,  Up: Language Features

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 `sizeof' also varies between
compilers.  ISO defines standard aliases for these two types, so you
can refer to them in a portable fashion.  They are defined in the
header file `stddef.h'.

 - Data Type: ptrdiff_t
     This is the signed integer type of the result of subtracting two
     pointers.  For example, with the declaration `char *p1, *p2;', the
     expression `p2 - p1' is of type `ptrdiff_t'.  This will probably
     be one of the standard signed integer types (`short int', `int' or
     `long int'), but might be a nonstandard type that exists only for
     this purpose.

 - Data Type: size_t
     This is an unsigned integer type used to represent the sizes of
     objects.  The result of the `sizeof' operator is of this type, and
     functions such as `malloc' (*note Unconstrained Allocation::.) and
     `memcpy' (*note Copying and Concatenation::.) accept arguments of
     this type to specify object sizes.

     *Usage Note:* `size_t' is the preferred way to declare any
     arguments or variables that hold the size of an object.

   In the GNU system `size_t' is equivalent to either `unsigned int' or
`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 `malloc' with an argument of type `size_t'
and you declare `malloc' with an argument of type `unsigned int', you
will get a compilation error if `size_t' happens to be `unsigned long
int' on your system.  To avoid any possibility of error, when a
function argument or value is supposed to have type `size_t', never
declare its type in any other way.

   *Compatibility Note:* Implementations of C before the advent of
ISO C generally used `unsigned int' for representing object sizes and
`int' for pointer subtraction results.  They did not necessarily define
either `size_t' or `ptrdiff_t'.  Unix systems did define `size_t', in
`sys/types.h', but the definition was usually a signed type.


File: libc.info,  Node: Data Type Measurements,  Prev: Important Data Types,  Up: Language Features

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 `limits.h' and `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.


File: libc.info,  Node: Width of Type,  Next: Range of Type,  Up: Data Type Measurements

Computing the Width of an Integer Data Type
-------------------------------------------

   The most common reason that a program needs to know how many bits
are in an integer type is for using an array of `long int' as a bit
vector.  You can access the bit at index N with

     vector[N / LONGBITS] & (1 << (N % LONGBITS))

provided you define `LONGBITS' as the number of bits in a `long int'.

   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
`CHAR_BIT', defined in the header file `limits.h'.

`CHAR_BIT'
     This is the number of bits in a `char'--eight, on most systems.
     The value has type `int'.

     You can compute the number of bits in any data type TYPE like this:

          sizeof (TYPE) * CHAR_BIT


File: libc.info,  Node: Range of Type,  Next: Floating Type Macros,  Prev: Width of Type,  Up: Data Type Measurements

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'.
     *Note 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 *Note System Configuration::.


File: libc.info,  Node: Floating Type Macros,  Next: Structure Measurement,  Prev: Range of Type,  Up: Data Type Measurements

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 (*note I/O on Streams::.) and for calculating trigonometric and
irrational functions (*note 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.

* Menu:

* Floating Point Concepts::     Definitions of terminology.
* Floating Point Parameters::   Details of specific macros.
* IEEE Floating Point::         The measurements for one common
                                 representation.


File: libc.info,  Node: Floating Point Concepts,  Next: Floating Point Parameters,  Up: Floating Type Macros

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'.)


File: libc.info,  Node: Floating Point Parameters,  Next: IEEE Floating Point,  Prev: Floating Point Concepts,  Up: Floating Type Macros

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 ISO 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 ISO 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
     ISO 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'.


File: libc.info,  Node: IEEE Floating Point,  Prev: Floating Point Parameters,  Up: Floating Type Macros

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


File: libc.info,  Node: Structure Measurement,  Prev: Floating Type Macros,  Up: Data Type Measurements

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.

