cpp
PURPOSE
Performs file inclusion and macro substitution on C Lan-
guage source files.
SYNOPSIS
/lib/cpp [ option ... ] [ ifile [ ofile ] ]
DESCRIPTION
The cpp program is the C Language preprocessor. It reads
infile and writes to outfile (standard input and standard
output by default). Although you can use this pre-
processor by itself, it is best to use it through the cc
command, which by default sends a C Language source file
to cpp as the first pass in compilation.
The cpp program recognizes two special names, __LINE__
(the current line number) and __FILE__ (current file
name). These names can be used anywhere just as any
other defined name.
All cpp directive lines must begin with a hash sign (#).
These directives are:
#define name token-string
Replaces subsequent instances of name
with token-string.
#define name(arg, . . . ,arg) token-string
Replaces subsequent instances of the
sequence name (arg, . . . ,arg) with
token-string, where each occurrence
of an arg in token-string is replaced
by the corresponding token in the
comma-separated list. Note that
there must not be any space between
name and the left parenthesis.
#undef name Ignores the definition of name from
this point on.
#include "file"
#include <file> Includes at this point the contents
of file, which cpp then processes.
If you enclose file in double quota-
tion marks ("" ""), cpp searches
first in the directory of infile,
second in directories named with the
-I flag, and last in directories on a
standard list .
If you use the <file> notation, cpp
searches for file only in the
standard places. It does not search
the directory in which infile
resides.
#line num ["file"] Includes line control information for
the next pass of the C compiler. num
is the line number of the next line
and file is the file from which it
comes. If you omit "file", the
current file name remains 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 Places the subsequent lines in the
output only if name has been defined
by a previous #define and has not
been undefined by an intervening
#undef.
#ifndef name Places the subsequent lines in the
output only if name has not been
defined by a previous #define or has
been undefined by an intervening
#undef.
#if expr Places subsequent lines in the output
only if expr evaluates to nonzero.
All the binary nonassignment C opera-
tors, the "?:" operator, and the
unary "-", "!", and ~ operators are
legal in expr. The precedence of the
operators is the same as that defined
in the C Language. There is also a
unary operator defined, which can be
used in expr in these two forms:
defined (name)
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 expr. The sizeof
operator is not available.
#else Places subsequent lines in the output
only if the expression in the pre-
ceding #if directive evaluates to
False (and hence the lines following
the #if and preceding the #else have
been ignored).
You can nest the test directives and the possible #else
directives.
FLAGS
-C Copies source file comments to the output
file. If you omit this flag, cpp removes
all comments (except those found on cpp
directive lines).
-Dname[=def] Defines name as in a #define directive.
The default def is 1.
-Idir Looks first in dir, then looks in the
directories on the standard list for
#include files with names that do not begin
with a / (slash). See the previous dis-
cussion of #include.
-P Preprocesses input without producing line
control information for the next pass of
the C compiler.
-Uname Removes any initial definition of name,
where name is a reserved symbol predefined
by the preprocessor.
EXAMPLES
1. To display the text that the preprocessor sends to
the C compiler:
/lib/cpp pgm.c
This preprocesses "pgm.c" and displays the resulting
text at the work station. You may want to see the
preprocessor output when looking for errors in your
macro definitions.
2. To create a file containing more readable preproc-
essed text:
/lib/cpp -P -C pgm.c pgm.i
This preprocesses "pgm.c" and stores the result in
"pgm.i". It omits line numbering information
intended for the C compiler (-P), and includes
program comments (-C).
3. To predefine macro identifiers:
/lib/cpp -DBUFFERSIZE=512 -DDEBUG pgm.c pgm.i
This defines "BUFFERSIZE" with the value "512" and
"DEBUG" with the value "1" before preprocessing.
4. To use #include files located in nonstandard directo-
ries:
/lib/cpp -I/u/jim/include pgm.c
This looks in the current directory for quoted
#include files, then in "/u/jim/include", and then in
the standard directories. It looks in
"/u/jim/include" for angle-bracketed #include files
(< >) and then in the standard directories.
FILES
/usr/include Standard directory for #include files.
RELATED INFORMATION
The following commands: "cc" and "m4."