@Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.
Œ

ˆ‰SEC492Št�”›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.
ˆ‰SEC493Št�”›Explicitly Checking Internal Consistency

‰IDX2151Š‰IDX2152Š‰IDX2153Š
@�”˜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.
‰IDX2154Š@�”˜The Hassert@ macro, defined in the header file H`assert.h'@, provides a convenient way to abort the program while printing a message about where in the program the error was detected.
‰IDX2155Š@�”˜Once you think your program is debugged, you can disable the error checks performed by the Hassert@ macro by recompiling with the macro HNDEBUG@ 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.

AMacro:@ void Dassert@ B(int Bexpression@)
Â‰IDX2156Š@�”˜Verify the programmer's belief that Bexpression@ should be nonzero at this point in the program.
If HNDEBUG@ is not defined, Hassert@ tests the value of Bexpression@. If it is false (zero), Hassert@ aborts the program (see section ‰ŠP�”›Aborting a Program@�”˜) after printing a message of the form: H`JfileH'@:Blinenum@: Bfunction@: Assertion `Bexpression@' failed.
on the standard error stream Hstderr@ (see section ‰ŠP�”›Standard Streams@�”˜). The filename and line number are taken from the C preprocessor macros H__FILE__@ and H__LINE__@ and specify where the call to Hassert@ was written. When using the GNU C compiler, the name of the function which calls Hassert@ is taken from the built-in variable H__PRETTY_FUNCTION__@; with older compilers, the function name and following colon are omitted.
If the preprocessor macro HNDEBUG@ is defined before H`assert.h'@ is included, the Hassert@ macro is defined to do absolutely nothing.
DWarning:@ Even the argument expression Bexpression@ is not evaluated if HNDEBUG@ is in effect. So never use Hassert@ with arguments that involve side effects. For example, Hassert (++i > 0);@ is a bad idea, because Hi@ will not be incremented if HNDEBUG@ 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 Hassert_perror@ macro makes this easy.

AMacro:@ void Dassert_perror@ B(int Berrnum@)
Â‰IDX2157Š@�”˜Similar to Hassert@, but verifies that Berrnum@ is zero.
If HNDEBUG@ is defined, Hassert_perror@ tests the value of Berrnum@. If it is nonzero, Hassert_perror@ aborts the program after a printing a message of the form: H`JfileH'@:Blinenum@: Bfunction@: Berror text@
on the standard error stream. The file name, line number, and function name are as for Hassert@. The error text is the result of Hstrerror (JerrnumH)@. See section ‰ŠP�”›Error Messages@�”˜.
Like Hassert@, if HNDEBUG@ is defined before H`assert.h'@ is included, the Hassert_perror@ macro does absolutely nothing. It does not evaluate the argument, so Berrnum@ should not have any side effects. It is best for Berrnum@ to be a just simple variable reference; often it will be Herrno@.
This macro is a GNU extension.À

DUsage note:@ The Hassert@ facility is designed for detecting Binternal inconsistency@; it is not suitable for reporting invalid input or improper usage by Bthe user@ of the program.
The information in the diagnostic messages printed by the Hassert@ 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 Hassert@ or Hassert_perror@ to print the error messages for these eventualities.
What's more, your program should not abort when given invalid input, as Hassert@ would do--it should exit with nonzero status (see section ‰ŠP�”›Exit Status@�”˜) after printing its error messages, or perhaps read another command or move on to the next input file.
See section ‰ŠP�”›Error Messages@�”˜, for information on printing error messages for problems that Bdo not@ represent bugs in the program.
ˆ‰SEC494Št�”›Variadic Functions

‰IDX2158Š‰IDX2159Š‰IDX2160Š
@�”˜ISO C defines a syntax for declaring a function to take a variable number or type of arguments. (Such functions are referred to as Bvarargs functions@ or Bvariadic 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 H`stdarg.h'@.
This section describes how to declare variadic functions, how to write them, and how to call them properly.
DCompatibility Note:@ Many older C dialects provide a similar, but incompatible, mechanism for defining functions with variable numbers of arguments, using H`varargs.h'@.
ˆ‰SEC495ŠT�”›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 H`foo'@ is declared with Hint 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 Hmalloc@ 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 Hprintf@ (see section ‰ŠP�”›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 Bvariadic@ function which can handle as many arguments as the caller chooses to pass.
Some functions such as Hopen@ 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 Bdeclare@ the function as variadic (or not declare its arguments at all!).
ˆ‰SEC496ŠT�”›How Variadic Functions are Defined and Used

@�”˜Defining and using a variadic function involves three steps: þÂ
• BDefine@ the function as variadic, using an ellipsis (H`...'@) in the argument list, and using special macros to access the variable arguments. See section ‰ŠP�”›Receiving the Argument Values@�”˜.
• BDeclare@ the function as variadic, using a prototype with an ellipsis (H`...'@), in all the files which call it. See section ‰ŠP�”›Syntax for Variable Arguments@�”˜.
• BCall@ the function by writing the fixed arguments followed by the additional variable arguments. See section ‰ŠP�”›Calling Variadic Functions@�”˜.Àð
ˆ‰SEC497ŠT�”›Syntax for Variable Arguments

‰IDX2161Š‰IDX2162Š‰IDX2163Š
@�”˜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 H`...'@ to indicate the possibility of additional arguments. The syntax of ISO C requires at least one fixed argument before the H`...'@. For example, int
func (const char *a, int b, ...)
{
...
}
outlines a definition of a function Hfunc@ which returns an Hint@ and takes two required arguments, a Hconst char *@ and an Hint@. These are followed by any number of anonymous arguments.
DPortability note:@ For some C compilers, the last required argument must not be declared Hregister@ in the function definition. Furthermore, this argument's type must be Bself-promoting@: that is, the default promotions must not change its type. This rules out array and function types, as well as Hfloat@, Hchar@ (whether signed or not) and Hshort int@ (whether signed or not). This is actually an ISO C requirement.
ˆ‰SEC498ŠT�”›Receiving the Argument Values

‰IDX2164Š‰IDX2165Š
@�”˜Ordinary fixed arguments have individual names, and you can use these names to access their values. But optional arguments have no names--nothing but H`...'@. How can you access them?
‰IDX2166Š@�”˜The only way to access them is sequentially, in the order they were written, and you must use special macros from H`stdarg.h'@ in the following three step process: þÂ
1. You initialize an argument pointer variable of type Hva_list@ using Hva_start@. The argument pointer when initialized points to the first optional argument.
2. You access the optional arguments by successive calls to Hva_arg@. The first call to Hva_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 Hva_end@. (In practice, with most C compilers, calling Hva_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 Hva_end@ just in case your program is someday compiled with a peculiar compiler.)Àð
See section ‰ŠP�”›Argument Access Macros@�”˜, for the full definitions of Hva_start@, Hva_arg@ and Hva_end@.
Steps 1 and 3 must be performed in the function that accepts the optional arguments. However, you can pass the Hva_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 Hva_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.
DPortability 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 Hva_end@. This is actually an ISO C requirement, but most ANSI C compilers work happily regardless.
ˆ‰SEC499ŠT�”›How Many Arguments Were Supplied

‰IDX2167Š‰IDX2168Š‰IDX2169Š
@�”˜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 Hprintf@ is one example of this (see section ‰ŠP�”›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 Hexecl@ function works in just this way; see section ‰ŠP�”›Executing a File@�”˜.
ˆ‰SEC500ŠT�”›Calling Variadic Functions

‰IDX2170Š‰IDX2171Š‰IDX2172Š
@�”˜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 Bdefined@ to be variadic must also be Bdeclared@ to be variadic using a function prototype whenever you call them. (See section ‰ŠP�”›Syntax for Variable Arguments@�”˜, 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, Hopen@ and Hprintf@.
‰IDX2173Š‰IDX2174Š@�”˜Since the prototype doesn't specify types for optional arguments, in a call to a variadic function the Bdefault argument promotions@ are performed on the optional argument values. This means the objects of type Hchar@ or Hshort int@ (whether signed or not) are promoted to either Hint@ or Hunsigned int@, as appropriate; and that objects of type Hfloat@ are promoted to type Hdouble@. So, if the caller passes a Hchar@ as an optional argument, it is promoted to an Hint@, and the function should get it with Hva_arg (JapH, 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.
ˆ‰SEC501ŠT�”›Argument Access Macros

@�”˜Here are descriptions of the macros used to retrieve variable arguments. These macros are defined in the header file H`stdarg.h'@. ‰IDX2175Š

A�”˜Data Type:@ Dva_list
Â‰IDX2176Š@�”˜The type Hva_list@ is used for argument pointer variables.À

AMacro:@ void Dva_start@ B(va_list Bap@, Blast-required@)
Â‰IDX2177Š@�”˜This macro initializes the argument pointer variable Bap@ to point to the first of the optional arguments of the current function; Blast-required@ must be the last required argument to the function.
See section ‰ŠP�”›Old-Style Variadic Functions@�”˜, for an alternate definition of Hva_start@ found in the header file H`varargs.h'@.À

AMacro:@ Btype@ Dva_arg@ B(va_list Bap@, Btype@)
Â‰IDX2178Š@�”˜The Hva_arg@ macro returns the value of the next optional argument, and modifies the value of Bap@ to point to the subsequent argument. Thus, successive uses of Hva_arg@ return successive optional arguments.
The type of the value returned by Hva_arg@ is Btype@ as specified in the call. Btype@ must be a self-promoting type (not Hchar@ or Hshort int@ or Hfloat@) that matches the type of the actual argument.À

AMacro:@ void Dva_end@ B(va_list Bap@)
Â‰IDX2179Š@�”˜This ends the use of Bap@. After a Hva_end@ call, further Hva_arg@ calls with the same Bap@ may not work. You should invoke Hva_end@ before returning from the function in which Hva_start@ was invoked with the same Bap@ argument.
In the GNU C library, Hva_end@ does nothing, and you need not ever use it except for reasons of portability.À

ˆ‰SEC502ŠT�”›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;
}
ˆ‰SEC503ŠT�”›Old-Style Variadic Functions

‰IDX2180Š@�”˜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 H`varargs.h'@.
Using H`varargs.h'@ is almost the same as using H`stdarg.h'@. There is no difference in how you call a variadic function; See section ‰ŠP�”›Calling Variadic Functions@�”˜. 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 Hva_start@ just one argument, like this: va_list p;
va_start (p);
These are the special macros used for defining old-style variadic functions:

AMacro:@ Dva_alist
Â‰IDX2181Š@�”˜This macro stands for the argument name list required in a variadic function.À

AMacro:@ Dva_dcl
Â‰IDX2182Š@�”˜This macro declares the implicit argument or arguments for a variadic function.À

AMacro:@ void Dva_start@ B(va_list Bap@)
Â‰IDX2183Š@�”˜This macro, as defined in H`varargs.h'@, initializes the argument pointer variable Bap@ to point to the first argument of the current function.À

The other argument macros, Hva_arg@ and Hva_end@, are the same in H`varargs.h'@ as in H`stdarg.h'@; see section ‰ŠP�”›Argument Access Macros@�”˜ for details.
It does not work to include both H`varargs.h'@ and H`stdarg.h'@ in the same compilation; they define Hva_start@ in conflicting ways.
ˆ‰SEC504Št�”›Null Pointer Constant

‰IDX2184Š
@�”˜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 Hvoid *@. The preferred way to write a null pointer constant is with HNULL@.

AMacro:@ void * DNULL
Â‰IDX2185Š@�”˜This is a null pointer constant.À

You can also use H0@ or H(void *)0@ as a null pointer constant, but using HNULL@ 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.
ˆ‰SEC505Št�”›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 Hsizeof@ 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 H`stddef.h'@. ‰IDX2186Š

A�”˜Data Type:@ Dptrdiff_t
Â‰IDX2187Š@�”˜This is the signed integer type of the result of subtracting two pointers. For example, with the declaration Hchar *p1, *p2;@, the expression Hp2 - p1@ is of type Hptrdiff_t@. This will probably be one of the standard signed integer types (Hshort int@, Hint@ or Hlong int@), but might be a nonstandard type that exists only for this purpose.À

AData Type:@ Dsize_t
Â‰IDX2188Š@�”˜This is an unsigned integer type used to represent the sizes of objects. The result of the Hsizeof@ operator is of this type, and functions such as Hmalloc@ (see section ‰ŠP�”›Unconstrained Allocation@�”˜) and Hmemcpy@ (see section ‰ŠP�”›Copying and Concatenation@�”˜) accept arguments of this type to specify object sizes.
DUsage Note:@ Hsize_t@ is the preferred way to declare any arguments or variables that hold the size of an object.À

In the GNU system Hsize_t@ is equivalent to either Hunsigned int@ or Hunsigned 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 Hmalloc@ with an argument of type Hsize_t@ and you declare Hmalloc@ with an argument of type Hunsigned int@, you will get a compilation error if Hsize_t@ happens to be Hunsigned long int@ on your system. To avoid any possibility of error, when a function argument or value is supposed to have type Hsize_t@, never declare its type in any other way.
DCompatibility Note:@ Implementations of C before the advent of ISO C generally used Hunsigned int@ for representing object sizes and Hint@ for pointer subtraction results. They did not necessarily define either Hsize_t@ or Hptrdiff_t@. Unix systems did define Hsize_t@, in H`sys/types.h'@, but the definition was usually a signed type.
ˆ‰SEC506Št�”›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 H`limits.h'@ and H`float.h'@ contain macros which give you this information in full detail.
ˆ‰SEC507ŠT�”›Computing the Width of an Integer Data Type

‰IDX2189Š‰IDX2190Š‰IDX2191Š
@�”˜The most common reason that a program needs to know how many bits are in an integer type is for using an array of Hlong int@ as a bit vector. You can access the bit at index Bn@ with vector[Bn@ / LONGBITS] & (1 << (Bn@ % LONGBITS))
provided you define HLONGBITS@ as the number of bits in a Hlong int@.
‰IDX2192Š@�”˜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 HCHAR_BIT@, defined in the header file H`limits.h'@.
HCHAR_BIT
Â@This is the number of bits in a Hchar@---eight, on most systems. The value has type Hint@. You can compute the number of bits in any data type Btype@ like this: sizeof (Btype@) * CHAR_BIT À

ˆ‰SEC508ŠT�”›Range of an Integer Type

‰IDX2193Š‰IDX2194Š‰IDX2195Š
@�”˜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 H`MIN'@ and H`MAX'@ macros in H`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 H`MAX'@ and H`MIN'@ macros for Hchar@ and Hshort int@ types have values of type Hint@. The H`MAX'@ and H`MIN'@ macros for the other types have values of the same type described by the macro--thus, HULONG_MAX@ has type Hunsigned long int@.
HSCHAR_MIN
Â@This is the minimum value that can be represented by a Hsigned char@.
ÀHSCHAR_MAX
Â
ÀHUCHAR_MAX
Â@These are the maximum values that can be represented by a Hsigned char@ and Hunsigned char@, respectively.
ÀHCHAR_MIN
Â@This is the minimum value that can be represented by a Hchar@. It's equal to HSCHAR_MIN@ if Hchar@ is signed, or zero otherwise.
ÀHCHAR_MAX
Â@This is the maximum value that can be represented by a Hchar@. It's equal to HSCHAR_MAX@ if Hchar@ is signed, or HUCHAR_MAX@ otherwise.
ÀHSHRT_MIN
Â@This is the minimum value that can be represented by a Hsigned short int@. On most machines that the GNU C library runs on, Hshort@ integers are 16-bit quantities.
ÀHSHRT_MAX
Â
ÀHUSHRT_MAX
Â@These are the maximum values that can be represented by a Hsigned short int@ and Hunsigned short int@, respectively.
ÀHINT_MIN
Â@This is the minimum value that can be represented by a Hsigned int@. On most machines that the GNU C system runs on, an Hint@ is a 32-bit quantity.
ÀHINT_MAX
Â
ÀHUINT_MAX
Â@These are the maximum values that can be represented by, respectively, the type Hsigned int@ and the type Hunsigned int@.
ÀHLONG_MIN
Â@This is the minimum value that can be represented by a Hsigned long int@. On most machines that the GNU C system runs on, Hlong@ integers are 32-bit quantities, the same size as Hint@.
ÀHLONG_MAX
Â
ÀHULONG_MAX
Â@These are the maximum values that can be represented by a Hsigned long int@ and Hunsigned long int@, respectively.
ÀHLONG_LONG_MIN
Â@This is the minimum value that can be represented by a Hsigned long long int@. On most machines that the GNU C system runs on, Hlong long@ integers are 64-bit quantities.
ÀHLONG_LONG_MAX
Â
ÀHULONG_LONG_MAX
Â@These are the maximum values that can be represented by a Hsigned long long int@ and Hunsigned long long int@, respectively.
ÀHWCHAR_MAX
Â@This is the maximum value that can be represented by a Hwchar_t@. See section ‰ŠP�”›Wide Character Introduction@�”˜.À

The header file H`limits.h'@ also defines some additional constants that parameterize various operating system and file system limits. These constants are described in section ‰ŠP�”›System Configuration Parameters@�”˜.
ˆ‰SEC509ŠT�”›Floating Type Macros

‰IDX2196Š‰IDX2197Š‰IDX2198Š‰IDX2199Š
@�”˜The specific representation of floating point numbers varies from machine to machine. Because floating point numbers are represented internally as approximate quantities, algorithms for manipulating floating point data often need to take account of the precise details of the machine's floating point representation.
Some of the functions in the C library itself need this information; for example, the algorithms for printing and reading floating point numbers (see section ‰ŠP�”›Input/Output on Streams@�”˜) and for calculating trigonometric and irrational functions (see section ‰ŠP�”›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 H`float.h'@ describes the format used by your machine.
ˆ‰SEC510ŠT�”›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 H123456.0@ could be expressed in exponential notation as H1.23456e+05@, a shorthand notation indicating that the mantissa H1.23456@ is multiplied by the base H10@ raised to power H5@.
More formally, the internal representation of a floating point number can be characterized in terms of the following parameters: þÂ
• ‰IDX2200Š@�”˜The Bsign@ is either H-1@ or H1@.
• ‰IDX2201Š‰IDX2202Š@�”˜The Bbase@ or Bradix@ for exponentiation, an integer greater than H1@. This is a constant for a particular representation.
• ‰IDX2203Š@�”˜The Bexponent@ to which the base is raised. The upper and lower bounds of the exponent value are constants for a particular representation. ‰IDX2204Š@�”˜Sometimes, in the actual bits representing the floating point number, the exponent is Bbiased@ 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.
• ‰IDX2205Š‰IDX2206Š@�”˜The Bmantissa@ or Bsignificand@, an unsigned integer which is a part of each floating point number.
• ‰IDX2207Š@�”˜The Bprecision@ of the mantissa. If the base of the representation is Bb@, then the precision is the number of base-Bb@ digits in the mantissa. This is a constant for a particular representation. ‰IDX2208Š@�”˜Many floating point representations have an implicit Bhidden 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 H1@. The mathematical value of a floating point number is then the product of this fraction, the sign, and the base raised to the exponent.
‰IDX2209Š@�”˜We say that the floating point number is Bnormalized@ if the fraction is at least H1/Jb@, where Bb@ 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 Bdenormal@; they contain less precision than the representation normally can hold.
If the number is not normalized, then you can subtract H1@ from the exponent while multiplying the mantissa by the base, and get another floating point number with the same value. BNormalization@ 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 H1@ from the exponent, so a number may be normalized even if its fraction is less than H1/Jb@.)
ˆ‰SEC511ŠT�”›Floating Point Parameters

‰IDX2210Š@�”˜These macro definitions can be accessed by including the header file H`float.h'@ in your program.
Macro names starting with H`FLT_'@ refer to the Hfloat@ type, while names beginning with H`DBL_'@ refer to the Hdouble@ type and names beginning with H`LDBL_'@ refer to the Hlong double@ type. (Currently GCC does not support Hlong double@ as a distinct data type, so the values for the H`LDBL_'@ constants are equal to the corresponding constants for the Hdouble@ type.)
Of these macros, only HFLT_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 H`#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.
HFLT_ROUNDS
Â@This value characterizes the rounding mode for floating point addition. The following values indicate standard rounding modes:
H-1
Ä@The mode is indeterminable.
ÂH0
Ä@Rounding is towards zero.
ÂH1
Ä@Rounding is to the nearest number.
ÂH2
Ä@Rounding is towards positive infinity.
ÂH3
Ä@Rounding is towards negative infinity.Â
Any other value represents a machine-dependent nonstandard rounding mode. On most machines, the value is H1@, in accordance with the IEEE standard for floating point. Here is a table showing how certain values round for each possible value of HFLT_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
ÀHFLT_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.
ÀHFLT_MANT_DIG
Â@This is the number of base-HFLT_RADIX@ digits in the floating point mantissa for the Hfloat@ data type. The following expression yields H1.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 Hradix@ appears HFLT_MANT_DIG@ times.
ÀHDBL_MANT_DIG
Â
ÀHLDBL_MANT_DIG
Â@This is the number of base-HFLT_RADIX@ digits in the floating point mantissa for the data types Hdouble@ and Hlong double@, respectively.
ÀHFLT_DIG
Â@This is the number of decimal digits of precision for the Hfloat@ data type. Technically, if Bp@ and Bb@ are the precision and base (respectively) for the representation, then the decimal precision Bq@ is the maximum number of decimal digits such that any floating point number with Bq@ base 10 digits can be rounded to a floating point number with Bp@ base Bb@ digits and back again, without change to the Bq@ decimal digits. The value of this macro is supposed to be at least H6@, to satisfy ISO C.
ÀHDBL_DIG
Â
ÀHLDBL_DIG
Â@These are similar to HFLT_DIG@, but for the data types Hdouble@ and Hlong double@, respectively. The values of these macros are supposed to be at least H10@.
ÀHFLT_MIN_EXP
Â@This is the smallest possible exponent value for type Hfloat@. More precisely, is the minimum negative integer such that the value HFLT_RADIX@ raised to this power minus 1 can be represented as a normalized floating point number of type Hfloat@.
ÀHDBL_MIN_EXP
Â
ÀHLDBL_MIN_EXP
Â@These are similar to HFLT_MIN_EXP@, but for the data types Hdouble@ and Hlong double@, respectively.
ÀHFLT_MIN_10_EXP
Â@This is the minimum negative integer such that H10@ raised to this power minus 1 can be represented as a normalized floating point number of type Hfloat@. This is supposed to be H-37@ or even less.
ÀHDBL_MIN_10_EXP
Â
ÀHLDBL_MIN_10_EXP
Â@These are similar to HFLT_MIN_10_EXP@, but for the data types Hdouble@ and Hlong double@, respectively.
ÀHFLT_MAX_EXP
Â@This is the largest possible exponent value for type Hfloat@. More precisely, this is the maximum positive integer such that value HFLT_RADIX@ raised to this power minus 1 can be represented as a floating point number of type Hfloat@.
ÀHDBL_MAX_EXP
Â
ÀHLDBL_MAX_EXP
Â@These are similar to HFLT_MAX_EXP@, but for the data types Hdouble@ and Hlong double@, respectively.
ÀHFLT_MAX_10_EXP
Â@This is the maximum positive integer such that H10@ raised to this power minus 1 can be represented as a normalized floating point number of type Hfloat@. This is supposed to be at least H37@.
ÀHDBL_MAX_10_EXP
Â
ÀHLDBL_MAX_10_EXP
Â@These are similar to HFLT_MAX_10_EXP@, but for the data types Hdouble@ and Hlong double@, respectively.
ÀHFLT_MAX
Â@The value of this macro is the maximum number representable in type Hfloat@. It is supposed to be at least H1E+37@. The value has type Hfloat@. The smallest representable number is H- FLT_MAX@.
ÀHDBL_MAX
Â
ÀHLDBL_MAX
Â@These are similar to HFLT_MAX@, but for the data types Hdouble@ and Hlong double@, respectively. The type of the macro's value is the same as the type it describes.
ÀHFLT_MIN
Â@The value of this macro is the minimum normalized positive floating point number that is representable in type Hfloat@. It is supposed to be no more than H1E-37@.
ÀHDBL_MIN
Â
ÀHLDBL_MIN
Â@These are similar to HFLT_MIN@, but for the data types Hdouble@ and Hlong double@, respectively. The type of the macro's value is the same as the type it describes.
ÀHFLT_EPSILON
Â@This is the minimum positive floating point number of type Hfloat@ such that H1.0 + FLT_EPSILON != 1.0@ is true. It's supposed to be no greater than H1E-5@.
ÀHDBL_EPSILON
Â
ÀHLDBL_EPSILON
Â@These are similar to HFLT_EPSILON@, but for the data types Hdouble@ and Hlong 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 H1E-9@.À

ˆ‰SEC512ŠT�”›IEEE Floating Point

‰IDX2211Š‰IDX2212Š
@�”˜Here is an example showing how the floating type measurements come out for the most common floating point representation, specified by the BIEEE 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 Hfloat@ 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 Hdouble@ 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
ˆ‰SEC513ŠT�”›Structure Field Offset Measurement

@�”˜You can use Hoffsetof@ to measure the location within a structure type of a particular structure member.

AMacro:@ size_t Doffsetof@ B(Btype@, Bmember@)
Â‰IDX2213Š@�”˜This expands to a integer constant expression that is the offset of the structure member named Bmember@ in a the structure type Btype@. For example, Hoffsetof (struct s, elem)@ is the offset, in bytes, of the member Helem@ in a Hstruct s@.
This macro won't work if Bmember@ is a bit field; you get an error from the C compiler in that case.À

Œ
Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.