Chapter 15. Preprocessing Directives

In “How the C Compiler Works”, we outlined the eight steps in translation from C source to an executable program. In the first four of those steps, the C preprocessor prepares the source code for the actual compiler. The result is a modified source in which comments have been deleted and preprocessing directives have been replaced with the results of their execution.

This chapter describes the C preprocessing directives. Among these are directives to insert the contents of other source files; to identify sections of code to be compiled only under certain conditions; and to define macros, which are identifiers that the preprocessor replaces with another text.

Each preprocessor directive appears on a line by itself, beginning with the character #. Only space and tab characters may precede the # character on a line. A directive ends with the first newline character that follows its beginning. The shortest preprocessor directive is the null directive. This directive consists of a line that contains nothing but the character #, and possibly comments or whitespace characters. Null directives have no effect: the preprocessor removes them from the source file.

If a directive doesn’t fit on one text line, you can end the line with a backslash (\) and continue the directive on the next line. Here is an example:

#define MacroName  A long, \
long macro replacement value

The backslash must be the last character before the newline character. The preprocessor concatenates the lines by removing each backslash-and-newline pair that it encounters. Because the preprocessor also replaces each comment with a space, the backslash no longer has the same effect if you put a comment between the backslash and the newline character.

Spaces and tab characters may appear between the # character that introduces a directive and the directive name. (In the previous example, the directive name is define.)

You can verify the results of the C preprocessor, either by running the preprocessor as a separate program or by using a compiler option to perform only the preprocessing steps.

Inserting the Contents of Header Files

An #include directive instructs the preprocessor to insert the contents of a specified file in the place of the directive. There are two ways to specify the file to be inserted:

#include  <filename>
#include  "filename"

Use the first form, with angle brackets, when you include standard library header files or additional header files provided by the implementation. Here is an example:

#include <math.h>        // Prototypes of mathematical functions,
                         // with related types and macros.

Use the second form, with double quotation marks, to include source files specific to your programs. Files inserted by #include directives typically have names ending in .h, and contain function prototypes, macro definitions, and type definitions. These definitions can then be used in any program source file after the corresponding #include directive. Here is an example:

#include "myproject.h"   // Function prototypes, type definitions
                         // and macros used in my project.

You may use macros in an #include directive. If you do use a macro, the macro’s replacement must result in a correct #include directive. Example 15-1 demonstrates such #include directives.

Example 15-1. Macros in #include directives

#ifdef _DEBUG_
  #define MY_HEADER "myProject_dbg.h"
#else
  #define MY_HEADER "myProject.h"
#endif
#include MY_HEADER

If the macro _DEBUG_ is defined when this segment is preprocessed, then the preprocessor inserts the contents of myProject_dbg.h. If not, it inserts myProject.h. The #ifdef, #else, and #endif directives are described in detail in “Conditional Compiling”.

How the Preprocessor Finds Header Files

It is up to the given C implementation to define where the preprocessor searches for files specified in #include directives. Whether filenames are case-sensitive is also implementation-dependent. For files specified between angle brackets (<filename>), the preprocessor usually searches in certain system directories, such as /usr/local/include and /usr/include on Unix systems, for example.

For files specified in quotation marks ("filename"), the preprocessor usually looks in the current directory first, which is typically the directory containing the program’s other source files. If such a file is not found in the current directory, the preprocessor searches the system include directories as well. A filename may contain a directory path. If so, the preprocessor looks for the file only in the specified directory.

You can always specify your own search path for #include directives, either by using an appropriate command-line option in running the compiler, or by adding search paths to the contents of an environment variable, often named INCLUDE. Consult your compiler’s documentation.

Nested #include Directives

#include directives can be nested; that is, a source file inserted by an #include directive may in turn contain #include directives. The preprocessor permits at least 15 levels of nested includes.

Because header files sometimes include one another, it can easily happen that the same file is included more than once. For example, suppose the file myProject.h contains the line:

#include <stdio.h>

Then a source file that contains the following #include directives would include the file stdio.h twice, once directly and once indirectly:

#include <stdio.h>
#include "myProject.h"

However, you can easily guard the contents of a header file against multiple inclusions using the directives for conditional compiling (explained in “Conditional Compiling”). Example 15-2 demonstrates this usage.

Example 15-2. Preventing multiple inclusions

#ifndef INCFILE_H_
#define INCFILE_H_

/* ... The actual contents of the header file incfile.h are here ... */

#endif   /* INCFILE_H_ */

At the first occurrence of a directive to include the file incfile.h, the macro INCFILE_H_ is not yet defined. The preprocessor therefore inserts the contents of the block between #ifndef and #endif—including the definition of the macro INCFILE_H_. On subsequent insertions of incfile.h, the #ifndef condition is false, and the preprocessor discards the block up to #endif.

Defining and Using Macros

You can define macros in C using the preprocessor directive #define. This directive allows you to give a name to any text you want, such as a constant or a statement. Wherever the macro’s name appears in the source code after its definition, the preprocessor replaces it with that text.

A common use of macros is to define a name for a numeric constant:

#define ARRAY_SIZE 100
double data[ARRAY_SIZE];

These two lines define the macro name ARRAY_SIZE for the number 100, and then use the macro in a definition of the array data. Writing macro names in all capitals is a widely used convention that helps to distinguish them from variable names. This simple example also illustrates how macros can make a C program more flexible. It’s safe to assume that the length of an array like data will be used in several places in the program—to control for loops that iterate through the elements of the array, for example. In each instance, use the macro name instead of a number. Then, if a program maintainer ever needs to modify the size of the array, it needs to be changed in only one place: in the #define directive.

In the third translation step, the preprocessor parses the source file as a sequence of preprocessor tokens and whitespace characters (see “The C Compiler’s Translation Phases” in Chapter 1). If any token is a macro name, the preprocessor expands the macro; that is, it replaces the macro name with the text it has been defined to represent. Macro names that occur in string literals are not expanded, because a string literal is itself a single preprocessor token.

Preprocessor directives cannot be created by macro expansion. Even if a macro expansion results in a formally valid directive, the preprocessor doesn’t execute it.

You can define macros with or without parameters.

Macros Without Parameters

A macro definition with no parameters has the form:

#define macro_name replacement_text

Whitespace characters before and after replacement_text are not part of the replacement text. The replacement_text can also be empty. Here are some examples:

#define TITLE  "*** Examples of Macros Without Parameters ***"
#define BUFFER_SIZE  (4 * 512)
#define RANDOM  (-1.0 + 2.0*(double)rand() / RAND_MAX)

The standard function rand() returns a pseudorandom integer in the interval [0, RAND_MAX. The prototype of rand() and the definition of the macro RAND_MAX are contained in the standard header file stdlib.h.

The following statements illustrate one possible use of the preceding macros:

#include <stdio.h>
#include <stdlib.h>
/* ... */
// Display the title:
puts( TITLE );

// Set the stream fp to "fully buffered" mode, with a buffer of
// BUFFER_SIZE bytes.
// The macro _IOFBF is defined in stdio.h as 0.
static char myBuffer[BUFFER_SIZE];
setvbuf( fp, myBuffer, _IOFBF, BUFFER_SIZE );

// Fill the array data with ARRAY_SIZE random numbers in the range
// [-10.0, +10.0]:
for ( int i = 0; i < ARRAY_SIZE; ++i )
  data[i] = 10.0 * RANDOM;

Replacing each macro with its replacement text, the preprocessor produces the following statements:

puts( "*** Examples of Macros Without Parameters ***" );

static char myBuffer[(4 * 512)];
setvbuf( fp, myBuffer, 0, (4 * 512) );

for ( int i = 0; i < 100; ++i )
  data[i] = 10.0 * (-1.0 + 2.0*(double)rand() / 2147483647);

In this example, the implementation-dependent value of the macro RAND_MAX is 2,147,483,647. With a different compiler, the value of RAND_MAX may be different.

If you write a macro containing an expression with operators, you should always enclose the expression in parentheses to avoid unexpected effects of operator precedence when you use the macro. For example, the outer parentheses in the macro RANDOM ensure that the expression 10.0 * RANDOM yields the desired result. Without them, macro replacement would produce this expression instead:

10.0 * -1.0 + 2.0*(double)rand() / 2147483647

This expression yields a random number in the interval [-10.0, -8.0].

Macros with Parameters

You can also define macros with parameters. When the preprocessor expands such a macro, it incorporates arguments you specify for each use of the macro in the replacement text. Macros with parameters are often called function-like macros.

You can define a macro with parameters in either of the following ways:

#define macro_name( [parameter_list] ) replacement_text
#define macro_name( [parameter_list ,] ... ) replacement_text

The parameter_list is a comma-separated list of identifiers for the macro’s parameters. When you use such a macro, the comma-separated argument list must contain as many arguments as there are parameters in the macro definition. (However, C99 allows you to use “empty arguments,” as we will explain in a moment.) The ellipsis (…) stands for one or more additional arguments.

When defining a macro, you must make sure there are no whitespace characters between the macro name and the left parenthesis ((). If there is any space after the name, then the directive defines a macro without parameters whose replacement text begins with the left parenthesis.

The standard library usually includes macros, defined in stdio.h, to implement the well-known functions getchar() and putchar(). Their expansion values can vary from one implementation to another, but in any case, their definitions are similar to the following:

#define getchar()   getc(stdin)
#define putchar(x)  putc(x, stdout)

When you “call” a function-like macro, the preprocessor replaces each occurrence of a parameter in the replacement text with the corresponding argument. C99 allows you to leave blank the place of any argument in a macro call. In this case, the corresponding parameter is replaced with nothing; that is, it is deleted from the replacement text. However, this use of “empty arguments” is not yet supported by all compilers.

If an argument contains macros, these are ordinarily expanded before the argument is substituted into the replacement text. Arguments for parameters which are operands of the # or ## operators are treated specially. For details, see the subsequent subsections “The stringify operator” and “The token-pasting operator”. Here are some examples of function-like macros and their expansions:

#include <stdio.h>           // Contains the definition of putchar().
#define DELIMITER ':'
#define SUB(a,b)  (a-b)
putchar( DELIMITER );
putchar( str[i] );
int var = SUB( ,10);

If putchar(x) is defined as putc(x, stdout), then the preprocessor expands the last three lines as follows:

putc(':', stdout);
putc(str[i], stdout);
int var = (-10);

As the following example illustrates, you should generally enclose the parameters in parentheses wherever they occur in the replacement text. This ensures correct evaluation in case any argument is an expression:

#define DISTANCE( x, y )  ((x)>=(y) ? (x)-(y) : (y)-(x))
d = DISTANCE( a, b+0.5 );

This macro call expands to the following:

d = ((a)>=(b+0.5) ? (a)-(b+0.5) : (b+0.5)-(a));

Without the parentheses around the parameters x and y, the expansion would contain the expression a-b+0.5 instead of (a)-(b+0.5).

Variable numbers of arguments

The C99 standard lets you define macros with an ellipsis (…) at the end of the parameter list to represent optional arguments. You can then invoke such a macro with a variable number of arguments.

When you invoke a macro with optional arguments, the preprocessor groups all of the optional arguments, including the commas that separate them, into one argument. In the replacement text, the identifier __VA_ARGS__ represents this group of optional arguments. The identifier __VA_ARGS__ can be used only in the replacement text of a macro definition. __VA_ARGS__ behaves the same as any other macro parameter, except that it is replaced by all the remaining arguments in the argument list, rather than just one argument. Here is an example of a macro that takes a variable number of arguments:

// Assume we have opened a log file to write with file pointer fp_log.
//
#define printLog(...)  fprintf( fp_log, __VA_ARGS__ )
// Using the printLog macro:
printLog( "%s: intVar = %d\n", __func__, intVar );

The preprocessor replaces the macro call in the last line of this example with the following:

fprintf( fp_log, "%s: intVar = %d\n", __func__, intVar );

The predefined identifier __func__, used in any function, represents a string containing the name of that function (see “Identifiers”). Thus, the macro call in this example writes the current function name and the contents of the variable intVar to the log file.

The stringify operator

The unary operator # is commonly called the stringify operator (or sometimes the stringizing operator) because it converts a macro argument into a string. The operand of # must be a parameter in a macro replacement text. When a parameter name appears in the replacement text with a prefixed # character, the preprocessor places the corresponding argument in double quotation marks, forming a string literal. All characters in the argument value itself remain unchanged, with the following exceptions:

Any sequence of whitespace characters between tokens in the argument value is replaced with a single space character.
A backslash character (\) is prefixed to each double quotation mark character (") in the argument.
A backslash character is also prefixed to each existing backslash that occurs in a character constant or string literal in the argument, unless the existing backslash character introduces a universal character name (see “Universal Character Names” in Chapter 1).

The following example illustrates how you might use the # operator to make a single macro argument work both as a string and as an arithmetic expression in the replacement text:

#define printDBL( exp ) printf( #exp " = %f ", exp )
printDBL( 4 * atan(1.0));       // atan() is declared in math.h.

The macro call in the last line expands to this statement:

printf( "4 * atan(1.0)" " = %f ", 4 * atan(1.0));

Because the compiler merges adjacent string literals, this code is equivalent to the following:

printf( "4 * atan(1.0) = %f ", 4 * atan(1.0));

That statement would generate the following console output:

4 * atan(1.0) = 3.141593

The invocation of the showArgs macro in the following example illustrates how the # operator modifies whitespace characters, double quotation marks, and backslashes in macro arguments:

#define showArgs(...)  puts(#__VA_ARGS__)
showArgs( one\n,        "2\n", three );

The preprocessor replaces this macro with the following text:

puts("one\n, \"2\\n\", three");

This statement produces the following output:

one
, "2\n", three

The token-pasting operator

The operator ## is a binary operator, and can appear in the replacement text of any macro. It joins its left and right operands together into a single token, and for this reason is commonly called the token-pasting operator. If the resulting text also contains a macro name, the preprocessor performs macro replacement on it. Whitespace characters that occur before and after the ## operator are removed along with the operator itself.

Usually, at least one of the operands is a macro parameter. In this case, the argument value is first substituted for the parameter, but the macro expansion itself is postponed until after token-pasting. Here is an example:

#define TEXT_A "Hello, world!"
#define msg(x) puts( TEXT_ ## x )
msg(A);

Regardless of whether the identifier A has been defined as a macro name, the preprocessor first substitutes the argument A for the parameter x, and then performs the token-pasting operation. The result of these two steps is the following line:

puts( TEXT_A );

Now, because TEXT_A is a macro name, the subsequent macro replacement yields this statement:

puts( "Hello, world!" );

If a macro parameter is an operand of the ## operator and a given macro invocation contains no argument for that parameter, then the preprocessor uses a placeholder to represent the empty string substituted for the parameter. The result of token pasting between such a placeholder and any token is that token. Token-pasting between two placeholders results in one placeholder. When all the token-pasting operations have been carried out, the preprocessor removes any remaining placeholders. Here is an example of a macro call with an empty argument:

msg();

This call expands to the following line:

puts( TEXT_ );

If TEXT_ is not an identifier representing a string, the compiler will issue an error message.

The order of evaluation of the stringify and token-pasting operators # and ## is not specified. If the order matters, you can influence it by breaking a macro up into several macros.

Using Macros Within Macros

After argument substitution and execution of the # and ## operations, the preprocessor examines the resulting replacement text and expands any macros it contains. No macro can be expanded recursively, though; if the preprocessor encounters the name of any macro in the replacement text of the same macro, or in the replacement text of any other macro nested in it, that macro name is not expanded.

Similarly, even if expanding a macro yields a valid preprocessing directive, that directive is not executed. However, the preprocessor does process any _Pragma operators that occur in a completely expanded macro replacement (see “The _Pragma Operator”).

The following sample program prints a table of function values:

// fn_tbl.c: Display values of a function in tabular form.
//           This program uses nested macros.
// -------------------------------------------------------------
#include <stdio.h>
#include <math.h>       // Prototypes of the cos() and exp() functions.

#define PI          3.141593
#define STEP        (PI/8)
#define AMPLITUDE   1.0
#define ATTENUATION 0.1             // Attenuation in wave propagation.
#define DF(x)       exp(-ATTENUATION*(x))
#define FUNC(x)    (DF(x) * AMPLITUDE * cos(x))  // Attenuated
                                                 // oscillation.
// For the function display:
#define STR(s)  #s
#define XSTR(s) STR(s)       // Expand the macros in s, then stringify.

int main()
{
  double x = 0.0;

  printf( "\nFUNC(x) = %s\n", XSTR(FUNC(x)) );   // Print the function.

  printf("\n %10s %25s\n", "x", STR(y = FUNC(x)) );    // Table header.
  printf("-----------------------------------------\n");
  for ( ; x < 2*PI + STEP/2;  x += STEP )
    printf( "%15f %20f\n", x, FUNC(x) );

  return 0;
}

This example prints the following table:

FUNC(x) = (exp(-0.1*(x)) * 1.0 * cos(x))

          x               y = FUNC(x)
-----------------------------------------
       0.000000             1.000000
       0.392699             0.888302
...
       5.890487             0.512619
       6.283186             0.533488

Macro Scope and Redefinition

You cannot use a second #define directive to redefine an identifier that is currently defined as a macro, unless the new replacement text is identical to the existing macro definition. If the macro has parameters, the new parameter names must also be identical to the old ones.

To change the meaning of a macro, you must first cancel its current definition using the following directive:

#undef macro_name

After that point, the identifier macro_name is available for use in a new macro definition. If the specified identifier is not the name of a macro, the preprocessor ignores the #undef directive.

The names of several functions in the standard library are also defined as macros. For these functions, you can use the #undef directive if you want to make sure your program calls one of those functions and not the macro of the same name. You don’t need to specify a parameter list with the #undef directive, even when the macro you are undefining has parameters. Here is an example:

#include <ctype.h>
#undef isdigit           // Remove any macro definition with this name.
/* ... */
if ( isdigit(c) )        // Call the function isdigit().
/* ... */

The scope of a macro ends with the first #undef directive with its name, or if there is no #undef directive for that macro, then with the end of the translation unit in which it is defined.

Type-generic Macros

The C11 standard introduces the generic selection, which works somewhat like a switch statement for data types. A generic selection is equivalent to an expression selected from a list of possibilities depending on the type of another expression. (The exact mechanism is described in “Generic Selections (C11)”.) This means that C programmers now have a way to define their own type-generic macros like those provided by C99 for mathematical functions in the header tgmath.h.

A generic selection begins with the new keyword _Generic. The following example illustrates a possible implementation of the type-generic macro log10(x) from tgmath.h:

#define log10(X) _Generic((X), \
   long double: log10l, \
   float:       log10f, \
   default:     log10   \
   )(X)

The compiler selects one of the expressions log10l, log10f, or log10 depending on the type of the expression X. If the macro is called with an argument arg whose type is double or an integer type, the result of the generic selection is the default expression, so that the macro call ultimately results in the expression log10(arg).

Conditional Compiling

The conditional compiling directives instruct the preprocessor to retain or omit parts of the source code depending on specified conditions. You can use conditional compiling to adapt a program to different target systems, for example, without having to manage a variety of source files.

A conditional section begins with one of the directives #if, #ifdef, or #ifndef, and ends with the directive #endif. Any number of #elif directives, and at most one #else directive, may occur within the conditional section. A conditional section that begins with #if has the following form:

#if expression1
  [ group1 ]
[#elif expression2
  [ group2 ]]
...
[#elif expression(n)
  [ group(n) ]]
[#else
  [ group(n+1) ]]
#endif

The preprocessor evaluates the conditional expressions in sequence until it finds one whose value is nonzero, or “true.” The preprocessor retains the text in the corresponding group for further processing. If none of the expressions is true, and the conditional section contains an #else directive, then the text in the #else directive’s group is retained.

The token groups group1, group2, and so on consist of any C source code, and may include more preprocessing directives, including nested conditional compiling directives. Groups that the preprocessor does not retain for further processing are removed from the program at the end of the preprocessor phase.

The #if and #elif Directives

The expression that forms the condition of an #if or #elif directive must be an integer constant preprocessor expression. This is different from an ordinary integer constant expression (see “Constant Expressions”) in these respects:

You may not use the cast operator in an #if or #elif expression.
You may use the preprocessor operator defined (see “The defined Operator”).
After the preprocessor has expanded all macros and evaluated all defined expressions, it replaces all other identifiers or keywords in the expression with the character 0.
All signed values in the expression have the type intmax_t, and all unsigned values have the type uintmax_t. Character constants are subject to these rules as well. The types intmax_t and uintmax_t are defined in the header file stdint.h.
The preprocessor converts characters and escape sequences in character constants and string literals into the corresponding characters in the execution character set. Whether character constants have the same value in a preprocessor expression as in later phases of compiling is up to the given implementation, however.

The defined Operator

The unary operator defined can occur in the condition of an #if or #elif directive. Its form is one of the following:

defined identifier
defined (identifier)

These preprocessor expressions yield the value 1 if the specified identifier is a macro name—that is, if it has been defined in a #define directive and its definition hasn’t been canceled by an #undef directive. For any other identifier, the defined operator yields the value 0.

The advantage of the defined operation over the #ifdef and #ifndef directives is that you can use its value in a larger preprocessor expression. Here is an example:

#if defined( __unix__ ) && defined( __GNUC__ )
/* ... */
#endif

Most compilers provide predefined macros, like those used in this example, to identify the target system and the compiler. Thus, on a Unix system, the macro __unix__ is usually defined, and the macro __GNUC__ is defined if the compiler being used is GCC. Similarly, the Microsoft Visual C compiler on Windows automatically defines the macros _WIN32 and _MSC_VER.

The #ifdef and #ifndef Directives

You can also test whether a given macro is defined using the #ifdef and #ifndef directives. Their syntax is:

#ifdef identifier
#ifndef identifier

These are equivalent to the following #if directives:

#if defined identifier
#if !defined identifier

The conditional code following the #ifndef identifier is retained if identifier is not a macro name. Examples 15-1 and 15-2 illustrate possible uses of these directives.

Defining Line Numbers

The compiler includes line numbers and source filenames in warnings, error messages, and information provided to debugging tools. You can use the #line directive in the source file itself to change the compiler’s filename and line numbering information. The #line directive has the following syntax:

#line line_number ["filename"]

The next line after a #line directive has the number specified by line_number. If the directive also includes the optional string literal "filename", then the compiler uses the contents of that string as the name of the current source file.

The line_number must be a decimal constant greater than zero. Here is an example:

#line 1200 "primary.c"

The line containing the #line directive may also contain macros. If so, the preprocessor expands them before executing the #line directive. The #line directive must then be formally correct after macro expansion.

Programs can access the current line number and filename settings as values of the standard predefined macros __LINE__ and __FILE__:

printf( "This message was printed by line %d in the file %s.\n",
         __LINE__, __FILE__ );

The #line directive is typically used by programs that generate C source code as their output. By placing the corresponding input file line numbers in #line directives, such programs can make the C compiler’s error messages refer to the pertinent lines in the original source.

Generating Error Messages

The #error directive makes the preprocessor issue an error message, regardless of any actual formal error. Its syntax is:

#error [text]

If the optional text is present, it is included in the preprocessor’s error message. The compiler then stops processing the source file and exits as it would on encountering a fatal error. The text can be any sequence of preprocessor tokens. Any macros contained in it are not expanded. It is a good idea to use a string literal here to avoid problems with punctuation characters, such as single quotation marks.

The following example tests whether the standard macro __STDC__ is defined, and generates an error message if it is not:

#ifndef __STDC__
  #error  "This compiler does not conform to the ANSI C standard."
#endif

The #pragma Directive

The #pragma directive is a standard way to provide additional information to the compiler. This directive has the following form:

#pragma [tokens]

If the first token after #pragma is STDC, then the directive is a standard pragma. If not, then the effect of the #pragma directive is implementation-dependent. For the sake of portability, you should use #pragma directives sparingly.

If the preprocessor recognizes the specified tokens, it performs whatever action they stand for, or passes information on to the compiler. If the preprocessor doesn’t recognize the tokens, it must ignore the #pragma directive.

Recent versions of the GNU C compiler and Microsoft’s Visual C compiler both recognize the pragma pack(n), for example, which instructs the compiler to align structure members on certain byte boundaries. The following example uses pack(1) to specify that each structure member be aligned on a byte boundary:

#if defined( __GNUC__ ) || defined( _MSC_VER )
  #pragma pack(1)                          // Byte-aligned: no padding.
#endif

Single-byte alignment ensures that there are no gaps between the members of a structure. The argument n in a pack pragma is usually a small power of two. For example, pack(2) aligns structure members on even-numbered byte addresses, and pack(4) on four-byte boundaries. pack() with no arguments resets the alignment to the implementation’s default value.

C99 introduced the following three standard pragmas:

#pragma  STDC  FP_CONTRACT  on_off_switch
#pragma  STDC  FENV_ACCESS  on_off_switch
#pragma  STDC  CX_LIMITED_RANGE  on_off_switch

The value of the on_off_switch must be ON, OFF, or DEFAULT. The effects of these pragmas are discussed in “Mathematical Functions”.

The _Pragma Operator

You cannot construct a #pragma directive (or any other preprocessor directive) by means of a macro expansion. For cases where you would want to do that, C99 has also introduced the preprocessor operator _Pragma, which you can use with macros. Its syntax is as follows:

_Pragma (string_literal )

Here is how the _Pragma operator works. First, the string_literal operand is “de-stringized,” or converted into a sequence of preprocessor tokens, in this way: the quotation marks enclosing the string are removed; each sequence of a backslash followed by a double quotation mark (\") is replaced by a quotation mark alone ("); and each sequence of two backslash characters (\\) is replaced with a single backslash (\). Then the preprocessor interprets the resulting sequence of tokens as if it were the text of a #pragma directive.

The following line defines a helper macro, STR, which you can use to rewrite any #pragma directive using the _Pragma operator:

#define  STR(s)  #s             // This # is the "stringify" operator.

With this definition, the following two lines are equivalent:

#pragma tokens
_Pragma ( STR(tokens) )

The following example uses the _Pragma operator in a macro:

#define ALIGNMENT(n) _Pragma( STR(pack(n)) )
ALIGNMENT(2)

Macro replacement changes the ALIGNMENT(2) macro call to the following:

_Pragma( "pack(2)" )

The preprocessor then processes the line as it would the following directive:

#pragma pack(2)

Predefined Macros

Every compiler that conforms to the ISO C standard must define the following seven macros. Each of these macro names begins and ends with two underscore characters:

__DATE__: The replacement text is a string literal containing the compilation date in the format "Mmm dd yyyy" (example: "Mar 19 2006"). If the day of the month is less than 10, the tens place contains an additional space character.
__FILE__: A string literal containing the name of the current source file.
__LINE__: An integer constant whose value is the number of the line in the current source file that contains the __LINE__ macro reference, counting from the beginning of the file.
__TIME__: A string literal that contains the time of compilation, in the format "hh:mm:ss" (example: "08:00:59").
__STDC__: The integer constant 1, indicating that the compiler conforms to the ISO C standard.
__STDC_HOSTED__: The integer constant 1 if the current implementation is a hosted implementation; otherwise, the constant 0.
__STDC_VERSION__: The long integer constant 199901L if the compiler supports the C99 standard of January 1999, or 201112L if the compiler supports the C11 standard of December 2011.

The values of the __FILE__ and __LINE__ macros can be influenced by the #line directive. The values of all the other predefined macros remains constant throughout the compilation process.

The value of the constant __STDC_VERSION__ will be adjusted with each future revision of the international C standard.

Beginning with the C99 standard, C programs are executed either in a hosted or in a freestanding environment. Most C programs are executed in a hosted environment, which means that the C program runs under the control and with the support of an operating system. In this case, the constant __STDC_HOSTED__ has the value 1, and the full standard library is available.

A program in a freestanding environment runs without the support of an operating system, and therefore only minimal standard library resources are available to it (see “Execution Environments”).

Conditionally Defined Macros

Unlike the macros listed previously, the following standard macros are predefined only under certain conditions. If any of these macros is defined, it indicates that the implementation supports a certain IEC or ISO standard:

__STDC_IEC_559__: This constant is defined with the value 1 if the implementation’s real floating-point arithmetic conforms to the IEC 60559 standard.
__STDC_IEC_559_COMPLEX__: This constant is defined with the value 1 if the implementation’s complex floating-point arithmetic also conforms to the IEC 60559 standard.
__STDC_ISO_10646__: This long integer constant represents a date in the form yyyymmL (example: 199712L). This constant is defined if the encoding of wide characters with the type wchar_t conforms to the Unicode standard ISO/IEC 10646, including all supplements and corrections up to the year and month indicated by the macro’s value.

The C11 standard adds the following optional macros:

__STDC_MB_MIGHT_NEQ_WC__: This constant is defined with the value 1 if a character in the basic character set, when encoded in a wchar_t object, is not necessarily equal to its encoding in the corresponding character constant.
__STDC_UTF_16__: This constant is defined with the value 1 if characters of the type char16_t are encoded in UTF-16. If the type uses a different encoding, the macro is not defined.
__STDC_UTF_32__: This constant is defined with the value 1 if characters of the type char32_t are encoded in UTF-32. If the type uses a different encoding, the macro is not defined.
__STDC_ANALYZABLE__: This constant is defined with the value 1 if the implementation supports the analysis of runtime errors as specified in Annex L of the C11 standard.
__STDC_LIB_EXT1__: This constant is defined with the value 201112L if the implementation supports the new functions with bounds-checking specified in Annex K of the C11 standard. The names of these new function end in _s.
__STDC_NO_ATOMICS__: This constant is defined with the value 1 if the implementation does not include the types and functions for atomic memory access operations (that is, the header stdatomic.h is absent).
__STDC_NO_COMPLEX__: This constant is defined with the value 1 if the implementation does not support arithmetic with complex numbers (that is, the header complex.h is absent).
__STDC_NO_THREADS__: This constant is defined with the value 1 if the implementation does not support multithreading (that is, the header threads.h is absent).
__STDC_NO_VLA__: This constant is defined with the value 1 if the implementation does not support variable-length arrays.

You must not use any of the predefined macro names described in this section in a #define or #undef directive. Finally, the macro name __cplusplus is reserved for C++ compilers, and must not be defined when you compile a C source file.

Table of Contents for C in a Nutshell, 2nd Edition