All cpp directives start with a hash symbol (#) as the first character on a line. White space (SPACE or TAB characters) can appear after the initial # for proper indentation.

#define name token-string

Replace subsequent instances of name with token-string.

#define name(argument [, argument] ... ) token-string

There can be no space between name and the `('. Replace subsequent instances of name, followed by a parenthesized list of arguments, with token-string, where each occurrence of an argument in the token-string is replaced by the corresponding token in the comma-separated list. When a macro with arguments is expanded, the arguments are placed into the expanded token-string unchanged. After the entire token-string has been expanded, cpp re-starts its scan for names to expand at the beginning of the newly created token-string.

#undef name

Remove any definition for the symbol name. No additional tokens are permitted on the directive line after name.

#include "filename"

#include <filename>

Read in the contents of filename at this location. This data is processed by cpp as if it were part of the current file. When the <filename> notation is used, filename is only searched for in the standard ``include'' directories. See the -I and -Y options above for more detail. No additional tokens are permitted on the directive line after the final `"' or `>'.

#line integer-constant "filename"

Generate line control information for the next pass of the C compiler. integer-constant is interpreted as the line number of the next line and filename is interpreted as the file from where it comes. If "filename" is not given, the current filename is unchanged. No additional tokens are permitted on the directive line after the optional filename.

#if constant-expression

Subsequent lines up to the matching #else, #elif, or #endif directive, appear in the output only if constant-expression yields a nonzero value. All binary non-assignment C operators, including `&&', `||', and `,', are legal in constant-expression. The `?:' operator, and the unary `-', `!', and `~' operators, are also legal in constant-expression.

The precedence of these operators is the same as that for C. In addition, the unary operator defined, can be used in constant-expression in these two forms: `defined ( name )' or `defined name'. This allows the effect of #ifdef and #ifndef directives (described below) in the #if directive. Only these operators, integer constants, and names that are known by cpp should be used within constant-expression. In particular, the size of operator is not available.

#ifdef name

Subsequent lines up to the matching #else, #elif, or #endif appear in the output only if name has been defined, either with a #define directive or a -D option, and in the absence of an intervening #undef directive. Additional tokens after name on the directive line will be silently ignored.

#ifndef name

Subsequent lines up to the matching #else, #elif, or #endif appear in the output only if name has not been defined, or if its definition has been removed with an #undef directive. No additional tokens are permitted on the directive line after name.

#elif constant-expression

Any number of #elif directives may appear between an #if, #ifdef, or #ifndef directive and a matching #else or #endif directive. The lines following the #elif directive appear in the output only if all of the following conditions hold:

• The constant-expression in the preceding #if directive evaluated to zero, the name in the preceding #ifdef is not defined, or the name in the preceding #ifndef directive was defined.
• The constant-expression in all intervening #elif directives evaluated to zero.
• The current constant-expression evaluates to non-zero.

If the constant-expression evaluates to non-zero, subsequent #elif and #else directives are ignored up to the matching #endif. Any constant-expression allowed in an #if directive is allowed in an #elif directive.

#else

This inverts the sense of the conditional directive otherwise in effect. If the preceding conditional would indicate that lines are to be included, then lines between the #else and the matching #endif are ignored. If the preceding conditional indicates that lines would be ignored, subsequent lines are included in the output. Conditional directives and corresponding #else directives can be nested.

#endif

End a section of lines begun by one of the conditional directives #if, #ifdef, or #ifndef. Each such directive must have a matching #endif.

Formal parameters for macros are recognized in #define directive bodies, even when they occur inside character constants and quoted strings. For instance, the output from:

#define abc(a)|`|a| abc(xyz)

is:

# 1 "" |`|xyz|

The second line is a NEWLINE. The last seven characters are ``|`|xyz|'' (vertical-bar, backquote, vertical-bar, x, y, z, vertical-bar). Macro names are not recognized within character constants or quoted strings during the regular scan. Thus:

#define abc xyz printf("abc");

does not expand abc in the second line, since it is inside a quoted string that is not part of a #define macro definition.

Macros are not expanded while processing a #define or #undef. Thus:

#define abc zingo #define xyz abc #undef abc xyz

produces abc. The token appearing immediately after an #ifdef or #ifndef is not expanded.

Macros are not expanded during the scan which determines the actual parameters to another macro call. Thus:

#define reverse(first,second)second first #define greeting hello reverse(greeting, #define greeting goodbye )

produces `` #define hello goodbye hello''.

Output consists of a copy of the input file, with modifications, plus lines of the form:

#lineno " filename" "level"

indicating the original source line number and filename of the following output line and whether this is the first such line after an include file has been entered (level=1), the first such line after an include file has been exited (level=2), or any other such line (level is empty).

#include files are searched for in the following order:

1. The directory of the file that contains the #include request (that is, #include is relative to the file being scanned when the request is made).
2. The directories specified by -I options, in left-to-right order.
3. The standard directory(s) (/usr/include on UNIX systems).

Two special names are understood by cpp. The name __LINE__ is defined as the current line number (a decimal integer) as known by cpp, and __FILE__ is defined as the current filename (a C string) as known by cpp. They can be used anywhere (including in macros) just as any other defined name.

A NEWLINE character terminates a character constant or quoted string. An escaped NEWLINE (that is, a backslash immediately followed by a NEWLINE) may be used in the body of a #define statement to continue the definition onto the next line. The escaped NEWLINE is not included in the macro value.

Comments are removed (unless the -C option is used on the command line). Comments are also ignored, except that a comment terminates a token.