Go to the first, previous, next, last section, table of contents.
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.
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.
If NDEBUG is not defined, assert tests the value of
expression. If it is false (zero), assert aborts the
program (see section Aborting a Program) after printing a message of the
form:
`file':linenum: function: Assertion `expression' failed.
on the standard error stream stderr (see section 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.
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). See section 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 (see section Exit Status) after printing its error messages, or perhaps read another
command or move on to the next input file.
See section Error Messages, for information on printing error messages for problems that do not represent bugs in the program.
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'.
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 (see section 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!).
Defining and using a variadic function involves three steps:
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.
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:
va_list using
va_start. The argument pointer when initialized points to the
first optional argument.
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.
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.)
See section Argument Access 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.
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 (see section 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 section Executing a File.
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. (See section 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, 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.
Here are descriptions of the macros used to retrieve variable arguments. These macros are defined in the header file `stdarg.h'.
va_list is used for argument pointer variables.
See section Old-Style Variadic Functions, for an alternate definition of va_start
found in the header file `varargs.h'.
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.
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.
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;
}
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; See section 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 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:
The other argument macros, va_arg and va_end, are the same
in `varargs.h' as in `stdarg.h'; see section Argument Access 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.
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.
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.
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'.
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.
sizeof operator is of this type, and functions
such as malloc (see section Unconstrained Allocation) and
memcpy (see section 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.
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.
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
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
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
signed char.
SCHAR_MAX
UCHAR_MAX
signed char and unsigned char, respectively.
CHAR_MIN
char.
It's equal to SCHAR_MIN if char is signed, or zero
otherwise.
CHAR_MAX
char.
It's equal to SCHAR_MAX if char is signed, or
UCHAR_MAX otherwise.
SHRT_MIN
signed
short int. On most machines that the GNU C library runs on,
short integers are 16-bit quantities.
SHRT_MAX
USHRT_MAX
signed short int and unsigned short int,
respectively.
INT_MIN
signed
int. On most machines that the GNU C system runs on, an int is
a 32-bit quantity.
INT_MAX
UINT_MAX
signed int and the type unsigned int.
LONG_MIN
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
signed long int and unsigned long int, respectively.
LONG_LONG_MIN
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
signed
long long int and unsigned long long int, respectively.
WCHAR_MAX
wchar_t.
See section Wide Character Introduction.
The header file `limits.h' also defines some additional constants that parameterize various operating system and file system limits. These constants are described in section System Configuration Parameters.
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 Input/Output on Streams) and for calculating trigonometric and irrational functions (see section 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.
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:
-1 or 1.
1. This is a constant for a particular 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.)
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
-1
0
1
2
3
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
FLT_MANT_DIG
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 / ... / radixwhere
radix appears FLT_MANT_DIG times.
DBL_MANT_DIG
LDBL_MANT_DIG
FLT_RADIX digits in the floating point
mantissa for the data types double and long double,
respectively.
FLT_DIG
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
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
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
FLT_MIN_EXP, but for the data types
double and long double, respectively.
FLT_MIN_10_EXP
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
FLT_MIN_10_EXP, but for the data types
double and long double, respectively.
FLT_MAX_EXP
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
FLT_MAX_EXP, but for the data types
double and long double, respectively.
FLT_MAX_10_EXP
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
FLT_MAX_10_EXP, but for the data types
double and long double, respectively.
FLT_MAX
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
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
float. It is supposed
to be no more than 1E-37.
DBL_MIN
LDBL_MIN
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
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
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.
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
You can use offsetof to measure the location within a structure
type of a particular structure member.
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.
Go to the first, previous, next, last section, table of contents.