[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Conditionals

A conditional is a directive that instructs the preprocessor to select whether or not to include a chunk of code in the final token stream passed to the compiler. Preprocessor conditionals can test arithmetic expressions, or whether a name is defined as a macro, or both simultaneously using the special defined operator.

A conditional in the C preprocessor resembles in some ways an if statement in C, but it is important to understand the difference between them. The condition in an if statement is tested during the execution of your program. Its purpose is to allow your program to behave differently from run to run, depending on the data it is operating on. The condition in a preprocessing conditional directive is tested when your program is compiled. Its purpose is to allow different code to be included in the program depending on the situation at the time of compilation.

However, the distinction is becoming less clear. Modern compilers often do test if statements when a program is compiled, if their conditions are known not to vary at run time, and eliminate code which can never be executed. If you can count on your compiler to do this, you may find that your program is more readable if you use if statements with constant conditions (perhaps determined by macros). Of course, you can only use this to exclude code, not type definitions or other preprocessing directives, and you can only do it if the code remains syntactically valid when it is not to be used.

GCC version 3 eliminates this kind of never-executed code even when not optimizing. Older versions did it only when optimizing.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Conditional Uses

There are three general reasons to use a conditional.

Simple programs that do not need system-specific logic or complex debugging hooks generally will not need to use preprocessing conditionals.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Conditional Syntax

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.1 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 section Once-Only Headers.

Macro definitions can vary between compilations for several reasons. Here are some samples.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.2 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

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.3 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 `-pedantic', since other compilers may handle it differently.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Deleted Code

If you replace or delete a part of the program but want to keep the old code around for future reference, you often cannot simply comment it out. Block comments do not nest, so the first comment inside the old code will end the commenting-out. The probable result is a flood of syntax errors.

One way to avoid this problem is to use an always-false conditional instead. For instance, put #if 0 before the deleted code and #endif after it. This works even if the code being turned off contains conditionals, but they must be entire conditionals (balanced `#if' and `#endif').

Some people use #ifdef notdef instead. This is risky, because notdef might be accidentally defined as a macro, and then the conditional would succeed. #if 0 can be counted on to fail.

Do not use #if 0 for comments which are not C code. Use a real comment, instead. The interior of #if 0 must consist of complete tokens; in particular, single-quote characters must balance. Comments often contain unbalanced single-quote characters (known in English as apostrophes). These confuse #if 0. They don't confuse `/*'.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on March, 29 2011 using texi2html 1.76.