..

..

cpp is the standalone preprocessor that is automatically invoked by the cc (1) command. Although primarily intended for the C language, there are several options that support preprocessing of other languages.

cpp accepts two optional file name arguments. ifile and ofile are respectively the input and output for the preprocessor, defaulting to standard input and standard output if not specified. WARNING: this is a non-standard file argument syntax that is required by some C compiler implementations.

ansi The default dialect ansi provides a conforming implementation, with extensions, of the preprocessing translation stages defined in the ANSI C standard. Refer to this document for detailed descriptions. The macro __STDC__ is predefined in this dialect.

compatibility This dialect provides almost complete compatibility with the old (Reiser) cpp . Non-supported features of old cpp appear in the diagnostics when possible. The macro __STDC__ is not predefined in this dialect. Refer to the Compatibility section below for a description of differences between this and the ansi dialect.

The dialects may have a strict interpretation, controlled by the -D-S option. When the strict mode is in effect, warning diagnostics are issued when dialect extensions are used in non-hosted files (see the -I-H option below).

The macro __STDPP__ is predefined to be 1 in all dialects.

-A arg SVR4 assertion. arg is the name of assertion. This option is equivalent to the directive #assert arg.

-C Do not strip comments from the input files.

-D arg Additional cpp options accepted by most versions of cc (1). arg may be:

-E No effect. Provides compatibility with some versions of cc (1).

-H Print the included reference files in stderr. This is for System V compatibility.

-I arg Include file related options. arg may be:

-M Output the file dependencies in makefile assertion format. This is for BSD compatibility.

-P Preprocess without producing line control information.

-T Truncate macro names for compatibility with non-flexname (8 character) compilation systems. This is equivalent to pp:truncate pragma below.

-U name Equivalent to the directive #undef name.

-V Prints the cpp version in stderr.

-X dialect Set the System V standard preprocessing dialect to dialect . dialect may be one of:

-Y dir Set the standard include file directory to dir . -I-S dir is preferred.

The directives are:

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

#define " name(arg" ", ..., " "arg) token-string" Replace subsequent instances of name followed by a ( , a list of comma-separated set of tokens, and a ) by token-string , where each occurrence of an arg in the token-string is replaced by the expanded value of the corresponding set of tokens in the comma-separated list. The argument replaced token-string is then re-scanned for further macro replacement. Notice that there can be no space between name and ( in the definition. Formal arguments appearing in single or double quoted strings are replaced by the corresponding unexpanded actual argument text only in the compatibility dialect. Macro recursion is inhibited by not expanding a macro name appearing in its own definition.

#define " #predicate" ( argument ) Makes the assertion # predicate ( argument ) that may be tested only in #if or #elif directive expressions. predicate must be an identifier and argument may be any balanced parenthesis sequence of tokens not containing newline . The assertion in no way conflicts with the #define macro name space. Space character sequences in argument are canonicalized into single space characters and macro expansion is inhibited on both predicate and argument during predicate assertion and evaluation. Within #if expressions, #predicate(argument) evaluates to 1 if #define " #predicate" ( argument ) has been specified; otherwise it evaluates to 0. Likewise, #predicate(\|) evaluates to 1 if any assertion has been made on predicate . Multiple assertions on predicate are allowed, with all such assertions evaluating to 1 in #if expressions.

#macdef " name..." Defines the multi-line macro name . A matching #endmac ends the definition. Nesting is allowed. As with #define , name may have arguments. The definition body may contain directives; these directives are not executed until the macro is expanded.

#elif " constant-expression" Allows multiple alternate branches for the #if directive. constant-expression evaluation is the same as for #if .

#else Reverses the sense of the test directive matching this directive. If lines previous to this directive are ignored then the following lines will appear in the output.

#endif Ends a section of lines begun by a test directive ( #if , #ifdef , or #ifndef ). Each test directive must have a matching #endif .

#error [message] Emits message as a cpp error diagnostic and terminates preprocessing immediately. The default message is "user error" .

#if " constant-expression" Subsequent lines will appear in the output if and only if constant-expression evaluates to non-zero. All non-assignment C operators are valid in constant-expression . Operator precedence is the same as in the C language. Computations are done using "long int" and "unsigned long int" arithmetic on the host machine; floating point computations are not supported. Any macros in constant-expression are expanded before the expression is evaluated. The builtin predicate defined( name ) tests if the macro name name has been defined. The builtin predicate exists( file ) tests if file can be found using #include search rules. file must be enclosed in "\|" or <\|>. exists accepts additional optional quoted string arguments that are : separated lists of directories to search for the existence of file . The normal #include search rules are overridden in this case. The builtin predicate strcmp( token1,token2 ) compares the macro expanded string values of token1 and token2 using the strcmp (3) library function. Only these operators, functions, predicates, integer constants and names may be used in constant-expression . In particular, the sizeof and , (comma) operators are not valid in this context.

#ifdef " name" The lines following will appear in the output if name has been the subject of a previous #define without being the subject of an intervening #undef .

#ifndef " name" The lines following will not appear in the output if name has been the subject of a previous #define without being the subject of an intervening #undef .

#include " <filename>" The standard include directories (see the -I option above) are searched for a header identified uniquely by filename , and the directive is replaced by the entire contents of the header. If the allmultiple pragma is off then subsequent #include references to the header named by filename are ignored unless the header contains a #pragma multiple directive that was processed during the first inclusion of the header. Any macros on the directive line are first expanded before the directive is processed.

#include "filename" The directory of the including file (see the -I option above) is searched for a source file identified uniquely by filename , and the directive is replaced by the entire contents of the source file. If the allmultiple pragma is off then subsequent #include references to the source file named by filename are ignored unless the source file contains a #pragma multiple directive that was processed during the first inclusion of the source file. Any macros on the directive line are first expanded before the directive is processed. If the source file search fails then the directive is reprocessed as if it were #include " <filename>."

#let identifier = constant-expression Defines the macro identifier to be the value of the evaluated constant-expression , where constant-expression is the same as for the #if directive. Macro redefinition diagnostics are suppressed for macros defined by #let .

#line integer-constant ["filename"] Outputs line control information for the next pass. integer-constant is the line number of the next line and filename is the originating file. The current file name is set to filename if specified. Any macros on the directive line are first expanded before the directive is processed.

#pragma [pass:][no]option [args ...] Sets preprocessor and compiler control options. Use of #pragma should be limited to hosted files as the interpretation varies between compiler implementations. A warning diagnostic is issued when #pragma directive is encountered in a non-hosted file. This directive is completely ignored for non-hosted files in the "strict ansi" dialect. If pass is pp then the option is used and verified and is not passed on, else if pass is omitted then the option is used and passed on, otherwise the option is passed on and not used. #pragma arguments are not checked for macro expansions. If no is present then option is turned off. Pass specific pragmas should not omit pass: . Options specified on the command line override options in the default include file. The cpp specific options are:

#rename " oldname newname" Changes the name of the macro oldname to newname.

#undef " name" Remove the definition of the macro name (if any).

#undef " #predicate(argument)"

0

#undef " #predicate(\|)"

The first form removes the assertion of predicate(argument) , if any, while the second form removes all assertions on predicate .

#warning [message] Emits message as a cpp warning diagnostic and continues normal processing. The default message is "user warning" .

FILE The current file name. __FILE__ is defined to be #(FILE) for ANSI conformance.

LINE The current line number (not quoted). __LINE__ is defined to be #(LINE) for ANSI conformance.

DATE The current month, day and year ( "MMM DD YYYY" ). __DATE__ is defined to be #(DATE) for ANSI conformance.

TIME The current time ( "HH:MM:SS" ). __TIME__ is defined to be #(TIME) for ANSI conformance.

BASE The base name of FILE .

PATH The full path name of the most recent #include directive or exists predicate evaluation. __PATH__ is defined to be #(PATH) in deference to ANSI conformance.

VERSION The cpp version stamp. __VERSION__ is defined to be #(VERSION) in deference to ANSI conformance.

ARGC The number of arguments of a variable arguments macro. __ARGC__ is defined to be #(ARGC) for ANSI conformance.

getenv name The value of name as returned by the getenv (3) library call.

getmac name The definition of the preprocessor macro name . Notice that macro formal names appearing in macro definitions are replaced by internal format token sequences.

getopt option The setting for the option or pragma option .

getprd predicate The argument associated with predicate from the most recent assertion on predicate .

Proposed standard assertions for pp_default.h are:

system( system-name ) Defines the operating system name. Example values for system-name are unix , vms and msdos .

release( system-release ) Defines the operating system release name. Example values for system-release are hpux , bsd , svr4 , sun , uts , and xinu .

version( release-version ) Defines the operating system release version. Example values for release-version are 4.1c and 4.3 for release(bsd) , 8 and 9 for release(research) and 3.0 etc. for release(V) .

model( model-name ) Defines the hardware model or workstation name. Example values for model-name are apollo , sun , ibm-pc and unix-pc .

architecture( architecture-name ) Defines the processor architecture name. Example values for architecture-name are u3b , m68000 , ibm , pdp11 , and vax .

machine( architecture-version ) Defines the processor architecture version. Example values for architecture-version are 2 , 20 and 20s for architecture(3b) , 70 etc. for architecture(pdp11) and 750 , 780 and micro for architecture(vax) .

addressing( addressing-mode ) Defines the addressing mode, useful for PC compiler implementations. Example values for addressing-mode are: small , medium , large , segmented and unsegmented .

The new character escapes \ea, \ev and \ex... are converted to octal notation for compatibility with older passes. This will disappear as ANSI C support becomes more pervasive.

The \|::\| , \|.*\| and \|->*\| operators and \|// " ..." comments are recognized for the C++ language.

0.2i #assert and #unassert are supported by maps to "#define #" and "#assert #" .

0.2i the "disappearing comments" trick used to concatenate tokens within macro definitions (this trick does not work outside of macro definitions, but at least a diagnostic is produced). If pp:splicecat is set then the line splice sequence \enewline may also be used to concatenate tokens in macro definitions, otherwise \enewline translates to space.

0.2i vertical-tab is treated as space in directive lines

0.2i formfeed is treated as a newline character (although the line count is not incremented by formfeed )

0.2i macro formal arguments appearing within "\|" or '\|' quotes in macro definitions are replaced by the corresponding actual argument text

0.2i macro call arguments are not expanded before being placed in the macro body text

0.2i trailing characters in directives are silently ignored

0

1.5i /usr/include standard directory for #include files

1.5i /usr/local/include sometimes searched after the standard directory during initialization

1.5i pp_default.h predefined symbols and assertions

"American National Standard for Information Systems -- Programming Language C", ANSI X3.159-1989.

predefined , readonly and active macro diagnostics may surprise old cpp users.

AT&T Bell Laboratories

gsf@research.att.com