NAME

cpp − the C language preprocessor

SYNOPSIS

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

DESCRIPTION

cpp is the C language preprocessor which is invoked as the first pass of any C compilation using the cc(1) command.  Thus the output of cpp 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 in this framework is not suggested.  The preferred way to invoke cpp is through the cc(1) command 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 respectively the input and output 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. 

−M Run only the macro preprocessor on the named C programs, requesting it to generate Makefile dependencies and send the result to the standard output. 

−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. 

−N Do not look in /usr/include by default when searching for missing include files. 

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

operating system: gcos, ibm, unix, vms

hardware: interdata, m68000, os, pdp11, tss, vax

The symbol sgi is also a reserved symbol. 

−Dname

−Dname=def
Define name as if by a #define directive.  If no =def is given, name is defined as 1. 

−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 in which the #include line appeared, 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 in which the #include line appeared is not searched automatically.  The maximum number of directories added due to −I options is currently sixteen. 

−p The input source is Pascal source.  cpp will strip C-style comments from the source, will ignore anything within Pascal-style comments, and will not put out blank lines for cpp directives found in included files.  Pascal programs may then include a file of macros and not alter the line numbers in the original source.  When the −p flag is used, cpp does not output line number directives. 

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 directives start with lines begun by #.  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 tokens, and a ) by token-string where each occurrence of an arg in the token-string is replaced by the corresponding token in the comma separated list. 

#undef name
Cause the definition of name (if any) to be forgotten from now on. 

#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. 

#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 where it comes from.  If “filename” is not given, the current file name is unchanged. 

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

#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. 

#ifndef name
The lines following will not 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. 

#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. 

#else Reverses the notion of the test directive which matches this directive.  If lines previous to this directive are ignored, the following lines will appear in the output, and vice versa. 

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

EXAMPLE

/lib/cpp −P −DXYZ −DMYFILE=myfile −I../include myprog.c myprog.i

would preprocess “myprog.c” writing to output file “myprog.i”, deleting output line numbers (−P ), and defining symbol XYZ to be null, symbol MYFILE to be “myfile” and using include files from ../include.

FILES

/usr/include standard directory for #include files

SEE ALSO

cc(1), m4(1). 

DIAGNOSTICS

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

NOTES

When newline characters were found in argument lists for macros to be expanded, previous versions of cpp put out the newlines as they were found and expanded.  The current version of cpp replaces these newlines with blanks to alleviate problems that the previous versions had when this occurred. 

Version 2.5r1  —  October 29, 1986