Preprocessing directives

A preprocessing directive begins with a preprocessing operator, #, on a logical line. Only white spaces are allowed to precede # on the same line. Preprocessing directives can be divided into the following categories:

• Macro definition and expansion

• File inclusion

• Conditional compilation

• Line control

• Assertions

• Version control

• Pragmas

• Error generation

• Predefined names

Preprocessing operators

The preprocessing operators are evaluated left to right, without any defined precedence.

#

A macro parameter preceded by the # preprocessing operator has its corresponding unexpanded argument tokens converted into a string literal. (Any double quotes and backslashes contained in character constants or part of string literals are escaped by a backslash). The # character is sometimes referred to as the ``stringizing'' operator. This rule applies only within function-like macros.

##

If a replacement token sequence contains a ## operator, the ## and any surrounding white space are deleted and adjacent tokens are concatenated, creating a new token. This occurs only when the macro is expanded. See ``Macro definition and expansion''.

Macro definition and expansion

• An object-like macro is defined with a line of the form:

  #define identifier token-sequence[opt]
  

  where identifier will be replaced with token-sequence wherever identifier appears in regular text.

• A function-like macro is defined with a line of the form:

  #define identifier (identifier-list[opt] ) token-sequence[opt]
  

  where the macro parameters are contained in the comma-separated identifier-list. The token-sequence following the identifier list determines the behavior of the macro, and is referred to as the replacement list. There can be no space between the identifier and the ``('' character. For example:

  #define FLM(a,b) a+b
  

  The replacement-list ``a+b'' determines that the two parameters ``a'' and ``b'' will be added.
  

• A function-like macro is invoked in normal text by using its identifier, followed by a ``('' token, a list of token sequences separated by commas, and a ``)'' token. For example:

  FLM(3,2)
  

• The arguments in the invocation (comma-separated token sequences) may be expanded, and they then replace the corresponding parameters in the replacement token sequence of the macro definition. Macro arguments in the invocation are not expanded if they are operands of # or ## operators in the replacement string. Otherwise, expansion does take place. For example, assume that M1 is defined as ``3'':

  #define M1 3
  

  When the function-like macro FLM is used, use of the # or ## operators will affect expansion (and the result), as follows:

  Definition	Invocation	Result	Expansion ?
  a+b	FLM(M1,2)	3+2	Yes, Yes
  #a	FLM(M1,2)	"M1"	No
  a##b	FLM(M1,2)	M12	No, No
  a+#a	FLM(M1,2)	3+"M1"	Yes, No

  In the last example line, the first ``a'' in ``a+#a'' is expanded, but the second ``a'' is not expanded because it is an operand of the # operator.

• The number of arguments in the invocation must match the number of parameters in the definition.

• A macro's definition, if any, can be eliminated with a line of the form:

  #undef identifier
  

  There is no effect if the definition does not exist.

File inclusion

• A line of the form:

  #include "filename"
  

  causes the entire line to be replaced with the contents of filename. The following directories are searched, in order.

  • The current directory (of the file containing the #include line).

  • Any directories named in -I options to the compiler, in order.

  • A list of standard places, typically, but not necessarily, /usr/include.
  
  

• A line of the form:

  #include <filename>
  

  causes the entire line to be replaced with contents of filename. The angle brackets surrounding filename indicate that filename is not searched for in the current directory.

• A third form allows an arbitrary number of preprocessing tokens to follow the #include, as in:

  #include preprocessing-tokens
  

  The preprocessing tokens are processed the same way as when they are used in normal text. Any defined macro name is replaced with its replacement list of preprocessing tokens. The preprocessing tokens must expand to match one of the first two forms ( < . . . > or ". . .").

• A filename beginning with a slash ``/'' indicates the absolute pathname of a file to include, no matter which form of #include is used.

• Any #include statements found in an included file cause recursive processing of the named file(s).

Conditional compilation

Different segments of a program may be compiled conditionally. Conditional compilation statements must observe the following sequence:

1. One of: #if or #ifdef or #ifndef.

2. Any number of optional #elif lines.

3. One optional #else line.

4. One #endif line.

• #if integral-constant-expression

  Is true if integral-constant-expression evaluates to non-zero.

  If true, tokens following the #if line are included.

  The integral-constant-expression following the #if is evaluated by following this sequence of steps:

  1. Any preprocessing tokens in the expression are expanded. Any use of the #define operator evaluates to ``1'' or ``0'' if its operand is, respectively, defined, or not.

  2. If any identifiers remain, they evaluate to ``0''.
     

  3. The remaining integral constant expression is evaluated. The constant expression must be made up of components that evaluate to an integral constant. In the context of a #if, the integral constant expression may not contain the sizeof operator, casts, or floating point constants.

     The following table shows how various types of constant expressions following a #if would be evaluated. Assume that name is not defined.

     Constant expression	Step 1	Step 2	Step 3
     !defined(__STDC__)	!1	!1	0
     3||name	3||name	3||0	1
     2 + name	2 + name	2 + 0	2

• #ifdef identifier

  Is true if identifier is currently defined by #define or by the -D option to the cc command line.

• #ifndef identifier

  Is true if identifier is not currently defined by #define (or has been undefined).

• #elif constant-expression

  Indicates alternate if-condition when all preceding if-conditions are false.

• #else

  Indicates alternate action when no preceding if or elif conditions are true. A comment may follow the else, but a token may not.

• #endif

  Terminates the current conditional. A comment may follow the endif but a token may not.

Line control

• Useful for programs that generate C programs.

• A line of the form

  #line  constant "filename"
  

  causes the compiler to believe, for the purposes of error diagnostics and debugging, that the line number of the next source line is equal to constant (which must be a decimal integer) and the current input file is filename (enclosed in double quotes). The quoted filename is optional. constant must be a decimal integer in the range 1 to MAXINT. MAXINT is defined in limits.h.

Assertions

A line of the form:

   #assert predicate (token-sequence)

   #assert predicate

The compiler provides the following predefined predicates by default:

   #assert machine ( i386 )
   #assert system ( unix )
   #assert cpu ( i386 )

An assertion may be tested in a #if statement with the following syntax:

   #if #predicate(non-empty token-list)

   #if #system(unix)

Version control

The #ident directive is used to help administer version control information.

   #ident "version"

Pragmas

• Preprocessing lines of the form

  #pragma pp-tokens
  

  specify implementation-defined actions.
  

• Six #pragmas are recognized by the compilation system:

     #pragma asm [full_optimization|partial_optimization] asm_func
     #pragma comment comment(argument)
     #pragma ident version
     #pragma int_to_unsigned identifier
     #pragma pack(n)
     #pragma weak identifier [= identifier2]
  

• The compiler ignores unrecognized pragmas.

For more information on pragmas, see ``Pragmas'' in ``ANSI implementation-defined behavior''.

Error generation

A preprocessing line consisting of:

   #error token-sequence

Predefined names

The following identifiers are predefined as object-like macros:

__LINE__	The current line number as a decimal constant.
__FILE__	A string literal representing the name of the file being compiled.
__DATE__	The date of compilation as a string literal in the form "Mmm dd yyyy."
__TIME__	The time of compilation, as a string literal in the form "hh:mm:ss."
__STDC__	The constant 1 under compilation mode -Xc. Under compilation mode -Xk, it is undefined. Under all other compilation modes, it is constant ``0''.
__USLC__	A positive integer constant; its definition signifies a USL C compilation system.

With the exception of __STDC__, these predefined names may not be undefined or redefined. Under compilation mode -Xt, __STDC__ may be undefined (#undef __STDC__) to cause a source file to think it is being compiled by a pre-ANSI C compiler.