Conditional Syntax#

A conditional in the C preprocessor begins with a conditional directive: #if, #ifdef or #ifndef.

Ifdef#

The simplest sort of conditional is

#ifdef MACRO

controlled text

#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. See 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 (see 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. See 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.

If#

The #if directive allows you to test the value of an arithmetic expression, rather than the mere existence of one macro. Its syntax is

#if expression

controlled text

#endif /* expression */

expression is a C expression of integer type, subject to stringent restrictions. It may contain

  • Integer constants.

  • Character constants, which are interpreted as they would be in normal code.

  • 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.

Defined#

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 -Wpedantic, since other compilers may handle it differently. The warning is also enabled by -Wextra, and can also be enabled individually with -Wexpansion-to-defined.

Else#

The #else directive can be added to a conditional to provide alternative text to be used if the condition fails. This is what it looks like:

#if expression
text-if-true
#else /* Not expression */
text-if-false
#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 opposite happens.

You can use #else with #ifdef and #ifndef, too.

Elif#

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.

__has_attribute#

The special operator __has_attribute (operand) may be used in #if and #elif expressions to test whether the attribute referenced by its operand is recognized by GCC. Using the operator in other contexts is not valid. In C code, if compiling for strict conformance to standards before C2x, operand must be a valid identifier. Otherwise, operand may be optionally introduced by the attribute-scope:: prefix. The attribute-scope prefix identifies the ‘namespace’ within which the attribute is recognized. The scope of GCC attributes is gnu or __gnu__. The __has_attribute operator by itself, without any operand or parentheses, acts as a predefined macro so that support for it can be tested in portable code. Thus, the recommended use of the operator is as follows:

#if defined __has_attribute
#  if __has_attribute (nonnull)
#    define ATTR_NONNULL __attribute__ ((nonnull))
#  endif
#endif

The first #if test succeeds only when the operator is supported by the version of GCC (or another compiler) being used. Only when that test succeeds is it valid to use __has_attribute as a preprocessor operator. As a result, combining the two tests into a single expression as shown below would only be valid with a compiler that supports the operator but not with others that don’t.

#if defined __has_attribute && __has_attribute (nonnull)   /* not portable */
...
#endif

__has_cpp_attribute#

The special operator __has_cpp_attribute (operand) may be used in #if and #elif expressions in C++ code to test whether the attribute referenced by its operand is recognized by GCC. __has_cpp_attribute (operand) is equivalent to __has_attribute (operand) except that when operand designates a supported standard attribute it evaluates to an integer constant of the form YYYYMM indicating the year and month when the attribute was first introduced into the C++ standard. For additional information including the dates of the introduction of current standard attributes, see SD-6: SG10 Feature Test Recommendations.

__has_c_attribute#

The special operator __has_c_attribute (operand) may be used in #if and #elif expressions in C code to test whether the attribute referenced by its operand is recognized by GCC in attributes using the [[]] syntax. GNU attributes must be specified with the scope gnu or __gnu__ with __has_c_attribute. When operand designates a supported standard attribute it evaluates to an integer constant of the form YYYYMM indicating the year and month when the attribute was first introduced into the C standard, or when the syntax of operands to the attribute was extended in the C standard.

__has_builtin#

The special operator __has_builtin (operand) may be used in constant integer contexts and in preprocessor #if and #elif expressions to test whether the symbol named by its operand is recognized as a built-in function by GCC in the current language and conformance mode. It evaluates to a constant integer with a nonzero value if the argument refers to such a function, and to zero otherwise. The operator may also be used in preprocessor #if and #elif expressions. The __has_builtin operator by itself, without any operand or parentheses, acts as a predefined macro so that support for it can be tested in portable code. Thus, the recommended use of the operator is as follows:

#if defined __has_builtin
#  if __has_builtin (__builtin_object_size)
#    define builtin_object_size(ptr) __builtin_object_size (ptr, 2)
#  endif
#endif
#ifndef builtin_object_size
#  define builtin_object_size(ptr)   ((size_t)-1)
#endif

__has_include#

The special operator __has_include (operand) may be used in #if and #elif expressions to test whether the header referenced by its operand can be included using the #include directive. Using the operator in other contexts is not valid. The operand takes the same form as the file in the #include directive (see Include Syntax) and evaluates to a nonzero value if the header can be included and to zero otherwise. Note that that the ability to include a header doesn’t imply that the header doesn’t contain invalid constructs or #error directives that would cause the preprocessor to fail.

The __has_include operator by itself, without any operand or parentheses, acts as a predefined macro so that support for it can be tested in portable code. Thus, the recommended use of the operator is as follows:

#if defined __has_include
#  if __has_include (<stdatomic.h>)
#    include <stdatomic.h>
#  endif
#endif

The first #if test succeeds only when the operator is supported by the version of GCC (or another compiler) being used. Only when that test succeeds is it valid to use __has_include as a preprocessor operator. As a result, combining the two tests into a single expression as shown below would only be valid with a compiler that supports the operator but not with others that don’t.

#if defined __has_include && __has_include ("header.h")   /* not portable */
...
#endif