4.2. Conditional Syntax
A conditional in the C preprocessor begins with a conditional
directive: #if, #ifdef or #ifndef.
The simplest sort of conditional is
#endif /* MACRO */
This block is called a conditional group. controlled text
will be included in the output of the preprocessor if and only if
MACRO is defined. We say that the conditional succeeds if
MACRO is defined, fails if it is not.
The controlled text inside of a conditional can include
preprocessing directives. They are executed only if the conditional
succeeds. You can nest conditional groups inside other conditional
groups, but they must be completely nested. In other words,
#endif always matches the nearest #ifdef (or
#ifndef, or #if). Also, you cannot start a conditional
group in one file and end it in another.
Even if a conditional fails, the controlled text inside it is
still run through initial transformations and tokenization. Therefore,
it must all be lexically valid C. Normally the only way this matters is
that all comments and string literals inside a failing conditional group
must still be properly ended.
The comment following the #endif is not required, but it is a
good practice if there is a lot of controlled text, because it
helps people match the #endif to the corresponding #ifdef.
Older programs sometimes put MACRO directly after the
#endif without enclosing it in a comment. This is invalid code
according to the C standard. CPP accepts it with a warning. It
never affects which #ifndef the #endif matches.
Sometimes you wish to use some code if a macro is not defined.
You can do this by writing #ifndef instead of #ifdef.
One common use of #ifndef is to include code only the first
time a header file is included. Section 2.4 Once-Only Headers.
Macro definitions can vary between compilations for several reasons.
Here are some samples.
Some macros are predefined on each kind of machine
(Section 3.7.3 System-specific Predefined Macros). This allows you to provide
code specially tuned for a particular machine.
System header files define more macros, associated with the features
they implement. You can test these macros with conditionals to avoid
using a system feature on a machine where it is not implemented.
Macros can be defined or undefined with the -D and -U
command line options when you compile the program. You can arrange to
compile the same source file into two different programs by choosing a
macro name to specify which program you want, writing conditionals to
test whether or how this macro is defined, and then controlling the
state of the macro with command line options, perhaps set in the
Makefile. Chapter 12 Invocation.
Your program might have a special header file (often called
config.h) that is adjusted when the program is compiled. It can
define or not define macros depending on the features of the system and
the desired capabilities of the program. The adjustment can be
automated by a tool such as autoconf, or done by hand.
The #if directive allows you to test the value of an arithmetic
expression, rather than the mere existence of one macro. Its syntax is
#endif /* expression */
expression is a C expression of integer type, subject to stringent
restrictions. It may contain
Character constants, which are interpreted as they would be in normal
Arithmetic operators for addition, subtraction, multiplication,
division, bitwise operations, shifts, comparisons, and logical
operations (&& and ||). The latter two obey the usual
short-circuiting rules of standard C.
Macros. All macros in the expression are expanded before actual
computation of the expression's value begins.
Uses of the defined operator, which lets you check whether macros
are defined in the middle of an #if.
Identifiers that are not macros, which are all considered to be the
number zero. This allows you to write #if MACRO instead of
#ifdef MACRO, if you know that MACRO, when defined, will
always have a nonzero value. Function-like macros used without their
function call parentheses are also treated as zero.
In some contexts this shortcut is undesirable. The -Wundef
option causes GCC to warn whenever it encounters an identifier which is
not a macro in an #if.
The preprocessor does not know anything about types in the language.
Therefore, sizeof operators are not recognized in #if, and
neither are enum constants. They will be taken as identifiers
which are not macros, and replaced by zero. In the case of
sizeof, this is likely to cause the expression to be invalid.
The preprocessor calculates the value of expression. It carries
out all calculations in the widest integer type known to the compiler;
on most machines supported by GCC this is 64 bits. This is not the same
rule as the compiler uses to calculate the value of a constant
expression, and may give different results in some cases. If the value
comes out to be nonzero, the #if succeeds and the controlled
text is included; otherwise it is skipped.
The special operator defined is used in #if and
#elif expressions to test whether a certain name is defined as a
macro. defined name and defined (name) are
both expressions whose value is 1 if name is defined as a macro at
the current point in the program, and 0 otherwise. Thus, #if
defined MACRO is precisely equivalent to #ifdef MACRO.
defined is useful when you wish to test more than one macro for
existence at once. For example,
#if defined (__vax__) || defined (__ns16000__)
would succeed if either of the names __vax__ or
__ns16000__ is defined as a macro.
Conditionals written like this:
#if defined BUFSIZE && BUFSIZE >= 1024
can generally be simplified to just #if BUFSIZE >= 1024,
since if BUFSIZE is not defined, it will be interpreted as having
the value zero.
If the defined operator appears as a result of a macro expansion,
the C standard says the behavior is undefined. GNU cpp treats it as a
genuine defined operator and evaluates it normally. It will warn
wherever your code uses this feature if you use the command-line option
-pedantic, since other compilers may handle it differently.
The #else directive can be added to a conditional to provide
alternative text to be used if the condition fails. This is what it
#else /* Not expression */
#endif /* Not expression */
If expression is nonzero, the text-if-true is included and
the text-if-false is skipped. If expression is zero, the
You can use #else with #ifdef and #ifndef, too.
One common case of nested conditionals is used to check for more than two
possible alternatives. For example, you might have
#if X == 1
#else /* X != 1 */
#if X == 2
#else /* X != 2 */
#endif /* X != 2 */
#endif /* X != 1 */
Another conditional directive, #elif, allows this to be
abbreviated as follows:
#if X == 1
#elif X == 2
#else /* X != 2 and X != 1*/
#endif /* X != 2 and X != 1*/
#elif stands for "else if". Like #else, it goes in the
middle of a conditional group and subdivides it; it does not require a
matching #endif of its own. Like #if, the #elif
directive includes an expression to be tested. The text following the
#elif is processed only if the original #if-condition
failed and the #elif condition succeeds.
More than one #elif can go in the same conditional group. Then
the text after each #elif is processed only if the #elif
condition succeeds after the original #if and all previous
#elif directives within it have failed.
#else is allowed after any number of #elif directives, but
#elif may not follow #else.