.TH cpp "" "" Command
.PC "C preprocessor"
\fB/lib/cpp [\fIoption\^.\^.\^.\fB] [\fIfile\^.\^.\^.\fB]\fR
.PP
.HS
.SH Options:
.IC "\fB\-C\fR"
Do not suppress comments
.IC "\fB\-D\fIVARIABLE\fB[=\fIvalue\^\fB]\fR"
Define \fIVARIABLE\fR; if
.I value
is not defined, the default value is one
.IC \fB\-E\fR
Strip file line-number information
.IC "\fB\-I \fIdir\fR"
Search \fIdir\fR for header files
.IC "\fB\-o \fIfile\fR"
Write output into \fIfile\fR
.IC "\fB\-P\fR
Remove file and line-number information
.IC "\fB\-Q\fR"
Suppress all messages
.IC "\fB\-U\fIVARIABLE\fR"
Undefine \fIVARIABLE\fR
.IC "\fB\-V\fR"
Print verbose information
.IC "\fB\-VCPLUS\fR"
Suppress C++-style on-line comments
.HE
The command
.B cpp
calls the C preprocessor to perform C preprocessing.
It performs the operations described in section 3.8 of the
ANSI Standard; these include file inclusion, conditional code selection,
constant definition, and macro definition.
See the entry on
.B "C preprocessor"
for a full description of C's preprocessing language.
.PP
Normally,
.B cpp
is used to preprocess C programs, but it can be used as
a simple macro processor for other types of files as well.
For example, the X utility
.B imake
uses
.B cpp
to help build makefiles.
.PP
.B cpp
reads each input
.IR file ,
processes directives, and writes its product on
.BR stdout .
If the option
.B \-E
is not used,
.B cpp
also writes into its output statements of the form \fB#line\fIn filename\^\fR,
so the parser can connect its error messages and
debugger output with the original line numbers in your source files.
.SH Options
.B cpp
recognizes the following options:
.IP \fB\-C\fR
Do not suppress comments.
Normally,
.B cpp
strips all comments from C code before it invokes the parsing phase,
.BR cc0 .
.IP \fB\-D\fIVARIABLE\fB[=\fIvalue\^\fB]\fR
Define
.I VARIABLE
for the preprocessor at compilation time.
If
.I value
is not defined,
.I VARIABLE
is set to one.
For example, the command
.DM
	cc -DLIMIT=20 foo.c
.DE
.IP
tells the preprocessor to define the variable
.B LIMIT
to be 20.
The C preprocessor acts as though the directive
.B "#define LIMIT 20"
were included in all source code.
.IP \fB\-E\fR
Strip all line-number information from the source code.
This option is used to preprocess assembly-language files or other
sources, and should not be used with the other compiler phases.
.IP "\fB\-I\fIdirectory\fR"
C allows two types of
.B #include
directives in a C program, i.e., \fB#include "file.h"\fR and
.BR "#include <file.h>" .
The
.B \-I
option tells \fBcpp\fR to search a specific
directory for the files you have named in your \fB#include\fR
directives, in addition to the directories that it searches by default.
You can have more than one \fB\-I\fR option on your \fBcpp\fR command line.
.IP "\fB\-o \fIfile\fR"
Write output into
.IR file .
If this option is missing,
.B cpp
writes its output onto \fBstdout\fR, which may be redirected.
.IP \fB\-P\fR
Strip all file and line-number information from the C code.
This is identical to the \fB\-E\fR option, defined above.
.IP \fB\-Q\fR
Suppress all messages.
.IP \fB\-U\fIVARIABLE\fR
Undefine
.IR VARIABLE ,
as if an
.B #undef
directive were included in the source program.
This is used to undefine the variables that
.B cpp
defines by default.
.IP \fB\-V\fR
Print verbose messages.
.IP \fB\-VCPLUS\fR
Suppress C++-style online comments.
.PP
.II CPPHEAD
.II CPPTAIL
.B cpp
reads the environmental variables
.B CPPHEAD
and
.B CPPTAIL
and appends their contents to, respectively, the beginning and the end of the
command
.BR cpp .
.SH "See Also"
.Xr "C preprocessor," c_preproc
.Xr "cc," cc
.Xr "commands" commands
.SH Diagnostics
.II "cpp^error messages"
.II "C preprocessor^error messages"
.II "error messages^cpp"
The following gives the error messages returned by
.BR cpp .
The messages are in alphabetical order.
Each is marked as to whether it is a
.IR fatal ,
.IR error ,
or
.I warning
condition.
A fatal message usually indicates a condition that caused
the compiler to terminate execution.
Fatal errors from the later phases of compilation often cannot
be fixed, and may indicate problems in the compiler or assembler.
An error message points to a condition in the source code
that the compiler cannot resolve.
This almost always occurs when the program does something illegal, e.g.,
has unbalanced braces.
.Ip "\fIstring\fR argument mismatch \fI(error)\fR"
The argument \fIstring\fR does not match the type declared
in the function's prototype.
Either the function prototype or the argument should be changed.
.Ip "#assert failure \fI(error)\fR"
The condition being tested in a \fB#assert\fR statement has failed.
.Ip "## at beginning of macro \fI(error)\fR"
Macro replacement lists may contain tokens that are
separated by
.BR ## ,
but
.B ##
cannot appear at the beginning or the end of the list.
The tokens on either side of the \fB##\fR are pasted together into one token.
.Ip "## at end of macro \fI(error)\fR"
Macro replacement lists may contain tokens that are
separated by
.BR ## ,
but
.B ##
cannot appear at the beginning or the end of the list.
The tokens on either side of the
.B ##
are pasted together into one token.
.Ip "\fIstring\fR: cannot create \fI(fatal)\fR"
The preprocessor
.B cpp
cannot create the output file \fIstring\fR that it was asked to create.
This often is due to a problem with the output device;
check and make sure that it is not full and that it is working correctly.
.Ip "\fIstring\fR: cannot open \fI(fatal)\fR"
The compiler cannot open the file \fIstring\fR of source code that it was
asked to read.
.B cpp
may not have been told the correct directory in which this file is to be
found; check that the file is located correctly,
and that the
.B \-I
options, if any, are correct.
.Ip "cannot open include file \fIstring\fR \fI(fatal)\fR"
The program asked for file
.IR string ,
which was not found in the same directory as the source file,
nor in the default
.B include
directory specified by the
environmental variable
.BR INCDIR ,
nor in any of the directories named in
.B \-I
options given to the
.B cc
command.
.Ip "conditional stack overflow \fI(fatal)\fR"
A series of \fB#if\fR expressions is nested so deeply that it overflowed the
allotted stack space.
You should simplify this code.
.Ip "#define argument mismatch \fI(warning)\fR"
The definition of an argument in a
.B #define
instruction does not match its subsequent use.
One or the other should be changed.
.Ip "#elif used without #if or #ifdef \fI(error)\fR"
An
.B #elif
instruction must be preceded by an
.BR #if ,
.BR #ifdef ,
or
.B #ifndef
control line.
.Ip "#elif used after #else \fI(error)\fR"
An
.B #elif
instruction cannot be preceded by an
.B #else
instruction.
.Ip "#else used without #if or #ifdef \fI(error)\fR"
An
.B #else
control line must be preceded by an
.BR #if ,
.BR #ifdef ,
or
.B #ifndef
control line.
.Ip "#endif used without #if or #ifdef \fI(error)\fR"
An
.B #endif
instruction must be preceded by an
.BR #if ,
.BR #ifdef ,
or
.B #ifndef
instruction.
.Ip "EOF in comment \fI(fatal)\fR"
Your source file appears to end in mid-comment.
The file of source code may have been truncated, or you failed to
close a comment; make sure that each open-comment symbol \*(Ql/*\*(Qr
is balanced with a close-comment symbol \*(Ql*/\*(Qr.
.Ip "EOF in macro \fIstring\fR invocation \fI(error)\fR"
Your source file appears to end in a macro call.
The source file may be been truncated.
.Ip "EOF in midline \fI(warning)\fR"
Check to see that your source file has not been truncated accidentally.
.Ip "EOF in string \fI(error)\fR"
Your file appears to end in the middle of a quoted string literal.
Check to see that your source file has not been truncated accidentally.
.Ip "#error: \fIstring\fR \fI(fatal)\fR"
An
.B #error
control line has been expanded,
printing the remaining tokens on the line and terminating the program.
.Ip "error in #define syntax \fI(error)\fR"
The syntax of a
.B #define
statement is incorrect.
See the Lexicon entry for
.B #define
for more information.
.Ip "error in #include syntax \fI(error)\fR"
An
.B #include
directive must be followed by a string enclosed
by either quotation marks (``\ '') or angle brackets (<>).
Anything else is illegal.
.Ip "identifier \fIstring\fR has too many arguments \fI(error)\fR"
Too many actual parameters have been provided.
.Ip "illegal control line \fI(error)\fR"
A \*(Ql#\*(Qr is followed by a word that the compiler does not recognize.
.Ip "illegal cpp character (\fIn\fR decimal) \fI(error)\fR"
The character noted cannot be processed by
.BR cpp .
It may be a control character or a non-ASCII character.
.Ip "illegal use of defined \fI(error)\fR"
The construction \fBdefined(\fItoken\fB)\fR or \fBdefined\fI token\fR
is legal only in \fB#if\fR, \fB#elif\fR, or \fB#assert\fR expressions.
.Ip "\fIstring\fR in #if \fI(error)\fR"
A syntax error occurred in a
.B #if
declaration.
.I string
describes the error in detail.
.Ip "include stack overflow \fI(fatal)\fR"
A set of \fB#include\fR statements is nested so deeply that
the allotted stack space cannot hold them.
Examines the files for a loop.
You should try to fold some of the header files into one, instead
of having them call each other.
.Ip "macro body too long \fI(fatal)\fR"
The size of the macro in question exceeds
the limit designed into the preprocessor.
Try to shorten or split the macro.
.Ip "macro expansion buffer overflow in \fIstring\fR \fI(fatal)\fR"
The \*(CO C compiler uses a static buffer space to expand preprocessor macros.
In some extreme cases, a macro will exhaust this space, thus causing the
C compiler to exit with this message.
Try to shorten the macro, or break it up.
See the Lexicon entry for
.B cpp
for suggestions on how to use an alternative C preprocessor to expand
huge macros.
.Ip "macro \fIstring\fR redefined \fI(error)\fR"
The program redefined the macro
.IR string .
.Ip "macro \fIstring\fR requires arguments \fI(error)\fR"
The macro calls for arguments that the program has not supplied.
.Ip "macros nested \fInumber\fR deep, loop likely \fI(error)\fR"
Macros call each other
.I number
times; you may have inadvertently created an infinite loop.
Try to simplify the program.
.Ip "missing #endif \fI(error)\fR"
An
.BR #if ,
.BR #ifdef ,
or
.B #ifndef
instruction was not closed with an
.B #endif
instruction.
.Ip "missing output file \fI(fatal)\fR"
The preprocessor
.B cpp
found a
.B \-o
option that was not followed by a file name for the output file.
.Ip "multiple #else's \fI(error)\fR"
An \fB#if\fR, \fB#ifdef\fR, or \fB#ifndef\fR expression can be
followed by no more than one \fB#else\fR expression.
.Ip "nested comment \fI(warning)\fR"
The comment introducer sequence \*(Ql/*\*(Qr has been detected within a comment.
Comments do not nest.
.Ip "new line in \fIstring\fR literal \fI(error)\fR"
A newline character appears in the middle of a string.
If you wish to embed a newline within a string, use the character
constant `\en'.
If you wish to continue the string on a new line, insert a backslash
\*(Ql\e\*(Qr before the new line.
.Ip "newline in macro argument \fI(warning)\fR"
A macro argument contains a newline character.
This may create trouble when the program is run.
.Ip "out of space \fI(fatal)\fR"
The compiler ran out of space while attempting to compile the program.
To remove this error, examine your source and break up
any functions that are extraordinarily large.
.Ip "parameter must follow # \fI(error)\fR"
Macro replacement lists may contain \fB#\fR followed
by a macro parameter name.
The macro argument is converted to a string literal.
.Ip "preprocessor assertion failure \fI(warning)\fR"
A \fB#assert\fR directive that was tested by the preprocessor
.B cpp
was found to be false.
.Ip "\fIstring\fR redefined \fI(error)\fR"
\fBcpp\fR macros should not be redefined.
You should check to see that you are not \fB#include\fRing two
different versions of a file somehow, or attempting to use the same
macro name for two different purposes.
.Ip "too many arguments in a macro \fI(fatal)\fR"
The program uses more than the allowed ten arguments with a macro.
.Ip "too many directories in include list \fI(fatal)\fR"
The program uses more than the allowed ten
.B #include
directories.
.Ip "\fIstring\fR: unknown option \fI(fatal)\fR"
The preprocessor
.B cpp
does not recognize the option
.IR string .
Try
re-typing the
.B cc
command line.
.SH Notes
The \*(CO C compiler uses a static buffer space to expand preprocessor macros.
Some programs that make especially intensive use of the C processor's
macro facility may die during compilation with the message
.DM
	macro expansion buffer overflow
.DE
.PP
This means that the program has exhaused the compiler's ability to process
macros.
You may wish to use an alternative preprocessor, such as the one that comes
with
.BR gcc ,
as described below.
.PP
The \*(CO C compiler combines the preprocessor
.B cpp
with the parser
.BR cc0 .
The file
.B /lib/cpp
is simply a link to the C compiler
.BR /lib/cc0 .
Thus, there is no way to specify an alternative version of the preprocessor
through the
.B cc
command.
You can get around, this however, by linking the alternative preprocessor
to a file named
.B cc0
in a directory other than
.BR /lib ,
then calling the alternative version via
.BR cc .
For example, to have
.B gcc
preprocess program
.BR hugemacro.c ,
do the following.
First, type the following commands to link the
.B gcc
preprocess to a file named
.BR cc0 :
.DM
	su root
	cd /usr/local/lib/gcc-lib/i386-coh/2.3.2
	ln cpp cc0
.DE
.PP
Then, to preprocess and compile
.BR hugemacro.c ,
type the following:
.DM
	cc -t0 -B/usr/local/lib/gcc-lib/i386-coh/2.3.2 -E hugemacro.c > tmp.c
	cc tmp.c
	rm tmp.c
.DE
.PP
You may wish to embed the above into your
.BR makefile ,
or write it into a shell script.
