.C File Format – Preprocessor

Directives

A directive is a line whose first token, after any white space, is #. It ends at the next new-line, unless that new-line was spliced with a backslash in phase 2. White space and comments may stand before and after the #. The tokens of a directive are not macro-expanded unless the directive says so.

Clause numbers are from C17. The directives marked C23 are not in C17.

Including files

# include <h-char-sequence> new-line
# include "q-char-sequence" new-line
# include pp-tokens new-line

The whole directive is replaced by the contents of the named file, which then goes through phases 1 to 4 (C17 6.10.2). The search rules are implementation-defined:

• <name> searches a list of places for a header. A standard library header need not be a file at all.
• "name" first searches in an implementation-defined way, then falls back to the <name> search. Compilers look first in the directory of the file containing the directive.
• In the third form the tokens are macro-expanded and must then match one of the first two forms.

An implementation must support at least 15 levels of nested includes. Include guards prevent repeated inclusion, as shown on the File structure page.

const unsigned char icon[] = {
#embed "icon.png"
};

const char text[] = {
#embed "message.txt" if_empty('N', 'o', 'n', 'e') suffix(, 0)
};

Macros

# define identifier replacement-list new-line
# define identifier lparen [identifier-list] ) replacement-list new-line
# define identifier lparen ... ) replacement-list new-line
# define identifier lparen identifier-list , ... ) replacement-list new-line
# undef identifier new-line

lparen is a ( with no white space before it. This one space is what separates the two kinds of macro: #define F(x) ... is function-like and #define F (x) ... is object-like, replacing F with (x) ....

A macro may be defined again only with an identical definition (C17 6.10.3). To change it, use #undef first; #undef of an undefined name does nothing. The macro stays defined until #undef or the end of the translation unit, and macro definitions are not affected by block scope.

#define foo foo + 1
foo          /* becomes foo + 1, with no further expansion of foo */

#define STR(x)  #x
#define XSTR(x) STR(x)
STR(__LINE__)   /* becomes "__LINE__" */
XSTR(__LINE__)  /* becomes "12" on line 12: XSTR's argument is expanded first */

#define MAKE_GETTER(name) int get_##name(void) { return name; }
MAKE_GETTER(width)   /* int get_width(void) { return width; } */

#define LOG(fmt, ...)  fprintf(stderr, fmt, __VA_ARGS__)
#define SHOW(...)      puts(#__VA_ARGS__)
#define CALL(f, ...)   f(0 __VA_OPT__(,) __VA_ARGS__)     /* C23 */

CALL(g)         /* g(0)       */
CALL(g, 1, 2)   /* g(0, 1, 2) */

#define SQUARE(x)  x * x          /* wrong */
SQUARE(1 + 2)                     /* 1 + 2 * 1 + 2, which is 5 */

#define SQUARE2(x)  ((x) * (x))   /* better */
SQUARE2(i++)                      /* i is evaluated twice: undefined behaviour */

#define SWAP(a, b)  do { int t = (a); (a) = (b); (b) = t; } while (0)
if (x) SWAP(a, b); else g();      /* the do-while makes it one statement */

Conditional inclusion

if-section:
    if-group {elif-group} [else-group] endif-line

if-group:
    # if constant-expression new-line [group]
    # ifdef identifier new-line [group]
    # ifndef identifier new-line [group]

elif-group:  # elif constant-expression new-line [group]
             # elifdef identifier new-line [group]        (C23)
             # elifndef identifier new-line [group]       (C23)

else-group:  # else new-line [group]
endif-line:  # endif new-line

The controlling expression is an integer constant expression with these changes (C17 6.10.1):

• defined name and defined(name) evaluate to 1 or 0.
• Macros in the expression are expanded.
• Any identifier left over, including keywords, is replaced by 0. Because of this, misspelled macros silently test false. In C23 the identifier true is replaced by 1.
• Signed values act as intmax_t and unsigned values as uintmax_t.

Casts, sizeof and enumeration constants cannot be used. Character constants are allowed, but need not match their value in the program.

Skipped groups are not processed, apart from tracking nested conditional directives. Their text must still be valid preprocessing tokens.

#if defined(__linux__) && __STDC_VERSION__ >= 201112L
#include <threads.h>
#elif defined(_WIN32)
#include <windows.h>
#else
#error "unsupported platform"
#endif

Line control

# line digit-sequence new-line
# line digit-sequence "s-char-sequence" new-line
# line pp-tokens new-line

#line changes what __LINE__ and __FILE__ report, and what the compiler shows in its messages. The number applies to the following line. The digit sequence may not be zero or greater than 2147483647 (C17 6.10.4). Tools that generate C, such as parser generators, use it to point diagnostics at the original source file.

Error and warning

#error produces a diagnostic that includes its tokens. Since C99 the implementation must then not translate the file successfully. #warning (C23) also produces a message but lets translation continue.

Pragmas

# pragma [pp-tokens] new-line
_Pragma ( string-literal )

A pragma is an implementation-defined instruction. An unknown pragma is ignored by the language, though a compiler may warn (C17 6.10.6). The tokens are not macro-expanded unless the compiler says otherwise, and never when STDC follows pragma.

The _Pragma operator (C99) has the same meaning but is an expression of the preprocessor, so a macro can produce it (C17 6.10.9).

The first three take ON, OFF or DEFAULT.

Predefined macros

These names are defined by the implementation (C17 6.10.8). They may not be redefined or removed with #define or #undef.

These are defined only if the feature condition holds:

C23 also defines version macros for individual headers, such as __STDC_VERSION_STDBIT_H__. __func__ is not a macro; it is a predefined identifier that exists only after preprocessing. Compilers add many macros of their own, such as __GNUC__ and _MSC_VER.