NAME

cpp − the C language preprocessor

SYNOPSIS

lib/cpp [ option ...  ] [ ifile [ ofile ] ]

DESCRIPTION

The C language preprocessor, cpp, is invoked as the first pass of any C compilation by the cc(1) command. Thus cpp’s output is designed to be in a form acceptable as input to the next pass of the C compiler. As the C language evolves, cpp and the rest of the C compilation package will be modified to follow these changes.  Therefore, the use of cpp other than through the cc(1) command is not suggested, since the functionality of cpp may someday be moved elsewhere.  See m4(1) for a general macro processor.

cpp optionally accepts two file names as arguments.  Ifile and ofile are the input and output, respectively, for the preprocessor.  They default to standard input and standard output if not supplied. 

The following options to cpp are recognized:

−P Preprocess the input without producing the line control information used by the next pass of the C compiler. 

−C By default, cpp strips C-style comments.  If the −C option is specified, all comments (except those found on cpp directive lines) are passed along. 

−Uname
Remove any initial definition of name, where name is a reserved symbol that is predefined by the particular preprocessor.  Following is the current list of these reserved symbols:

operating system: unix

hardware: mips

manufacturer: ardent

language: LANGUAGE_C for C

−Dname

−Dname=def
Define name with value def as if by a #define.  If no =def is given, name is defined with value 1.  The −D option has lower precedence than the −U option.  That is, if the same name is used in both a −U option and a −D option, the name will be undefined regardless of the order of the options. 

−I Do not search the standard places for #include files. 

−Idir Change the algorithm for searching for #include files whose names do not begin with / to look in dir before looking in the directories on the standard list.  Thus, #include files whose names are enclosed in "" will be searched for first in the directory of the file with the #include line, then in directories named in −I options, and last in directories on a standard list.  For #include files whose names are enclosed in <>, the directory of the file with the #include line is not searched. 

−H Print, one per line on standard error, the path names of included files. 

−i Compute a #ident control line for the input file and every included file giving a cyclic redundancy checksum for the file contents. 

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

All cpp directive lines start with # in column 1.  Any number of blanks and tabs is allowed between the # and the directive.  The directives are:

#define name
Replace subsequent instances of name with token-string.

#define name( arg, ..., arg ) token-string
Notice that there can be no space between name and the (.  Replace subsequent instances of name followed by a (, a list of comma-separated sets of tokens, and a ) followed by token-string, where each occurrence of an arg in the token-string is replaced by the corresponding set of tokens 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
Cause the definition of name (if any) to be forgotten from now on.  No additional tokens are permitted on the directive line after name. 

#ident "string"
Put string into the .comment section of an object file. 

#include "filename"

#include
Include at this point the contents of filename (which will then be run through cpp). When the <filename> notation is used, filename is only searched for in the standard places.  See the −I option above for more detail.  No additional tokens are permitted on the directive line after the final " or >. 

#line integer-constant "filename"
Causes cpp to generate line control information for the next pass of the C compiler.  Integer-constant is the line number of the next line and filename is the file from which it comes.  If "filename" is not given, the current file name is unchanged.  No additional tokens are permitted on the directive line after the optional filename. 

#endif
Ends a section of lines begun by a test directive (#if, #ifdef, or #ifndef).  Each test directive must have a matching #endif.  No additional tokens are permitted on the directive line. 

#ifdef name
The lines following will appear in the output if and only if name has been the subject of a previous #define without being the subject of an intervening #undef.  No additional tokens are permitted on the directive line after name.

#ifndef name
The lines following will appear in the output if and only if name has not been the subject of a previous #define.  No additional tokens are permitted on the directive line after name.

#if constant-expression
Lines following will appear in the output if and only if the constant-expression evaluates to non-zero.  All binary non-assignment C operators, the ?: operator, the unary −, !, and ~ operators are all legal in constant-expression. The precedence of the operators is the same as defined by the C language. There is also a unary operator defined, which can be used in constant-expression in these two forms: defined or defined name. This allows the utility of #ifdef and #ifndef in a #if directive.  Only these operators, integer constants, and names which are known by cpp should be used in constant-expression. In particular, the sizeof operator is not available. 

To test whether either of two symbols, foo and fum, are defined, use

#if defined(foo) || defined(fum)

#elif constant-expression
An arbitrary number of #elif directives is allowed between a #if, #ifdef, or #ifndef directive and a #else or #endif directive.  The lines following the #elif directive will appear in the output if and only if the preceding test directive evaluates to zero, all intervening #elif directives evaluate to zero, and the constant-expression evaluates to non-zero.  If constant-expression evaluates to non-zero, all succeeding #elif and #else directives will be ignored.  Any constant-expression allowed in a #if directive is allowed in a #elif directive. 

#else The lines following will appear in the output if and only if the preceding test directive evaluates to zero, and all intervening #elif directives evaluate to zero.  No additional tokens are permitted on the directive line. 

The test directives and the possible #else directives can be nested. 

#pragma
name The name specifies a compiler optimization that is to be overridden.  Additional details appear in the Programmer’s Guide . 

FILES

INCDIR standard directory list for #include files, usually /usr/include

LIBDIR usually /lib

SEE ALSO

cc(1), lint(1), m4(1). 

DIAGNOSTICS

The error messages produced by cpp are intended to be self-explanatory.  The line number and file name where the error occurred are printed along with the diagnostic. 

NOTES

Because the standard directory for included files may be different in different environments, this form of #include directive: #include <file.h> should be used, rather than one with an absolute path, like: #include "/usr/include/file.h" cpp warns about the use of the absolute pathname. 

September 02, 1992