CPP(1) General Commands Manual CPP(1)
cpp - the C language preprocessor
/usr/lib/cpp [ -BCHMpPRT ] [ -undef ] [ -Dname ]
[ -Dname=def ] [ -Idirectory ] [ -Uname ]
[ -Ydirectory ] [ input-file [ output-file ] ]
cpp is the C language preprocessor. It is invoked as the first pass of
any C compilation started with the cc(1V) command; however, cpp can
also be used as a first-pass preprocessor for other Sun compilers.
Although cpp can be used as a macro processor, this is not normally
recommended, as its output is geared toward that which would be accept-
able as input to a compiler's second pass. Thus, the preferred way to
invoke cpp is through the cc(1V) command, or some other compilation
command. For general-purpose macro-processing, see m4(1V), and the
chapter on m4 in
cpp optionally accepts two filenames as arguments. input-file and out-
put-file are, respectively, the input and output files for the pre-
processor. They default to the standard input and the standard output.
-B Support the C++ comment indicator `//'. With this indicator
everything on the line after the // is treated as a comment.
-C Pass all comments (except those that appear on cpp directive
lines) through the preprocessor. By default, cpp strips out C-
-H Print the pathnames of included files, one per line on the stan-
-M Generate a list of makefile dependencies and write them to the
standard output. This list indicates that the object file which
would be generated from the input file depends on the input file
as well as the include files referenced.
-p Use only the first eight characters to distinguish preprocessor
symbols, and issue a warning if extra tokens appear at the end
of a line containing a directive.
-P Preprocess the input without producing the line control informa-
tion used by the next pass of the C compiler.
-R Allow recursive macros.
-T Use only the first eight characters for distinguishing different
preprocessor names. This option is included for backward com-
patibility with systems which always use only the first eight
-undef Remove initial definitions for all predefined symbols.
-Dname Define name as 1 (one). This is the same as if a -Dname=1
option appeared on the cpp command line, or as if a
#define name 1
line appeared in the source file that cpp is processing.
Define name as if by a #define directive. This is the same as
#define name def
line appeared in the source file that cpp is processing. 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.
Insert directory into the search path for #include files with
names not beginning with `/'. directory is inserted ahead of
the standard list of ``include'' directories. Thus, #include
files with names enclosed in double-quotes (") are searched for
first in the directory of the file with the #include line, then
in directories named with -I options, and lastly, in directories
from the standard list. For #include files with names enclosed
in angle-brackets (<<>>), the directory of the file with the
#include line is not searched. See Details below for exact
details of this search order.
-Uname Remove any initial definition of name, where name is a symbol
that is predefined by a particular preprocessor. Here is a par-
tial list of symbols that may be predefined, depending upon the
architecture of the system:
Operating System: ibm, gcos, os, tss and unix
Hardware: interdata, pdp11, u370, u3b, u3b2,
u3b5, u3b15, u3b20d, vax, ns32000,
iAPX286, i386, sparc , and sun
UNIX system variant:
RES, and RT
The lint(1V) command:
The symbols sun and unix are defined for all Sun systems, as is
the value returned by the mach command. For Sun-4 systems, this
value would be sparc.
Use directory directory in place of the standard list of direc-
tories when searching for #include files.
All cpp directives start with a hash symbol (#) as the first character
on a line. White space (SPACE or TAB characters) can appear after the
initial # for proper indentation.
#define name token-string
Replace subsequent instances of name with token-string.
#define name(argument [, argument] ... ) token-string
There can be no space between name and the `('. Replace subse-
quent instances of name, followed by a parenthesized list of
arguments, with token-string, where each occurrence of an argu-
ment in the token-string is replaced by the corresponding token
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.
Remove any definition for the symbol name. No additional tokens
are permitted on the directive line after name.
Read in the contents of filename at this location. This data is
processed by cpp as if it were part of the current file. When
the <<filename>> notation is used, filename is only searched for
in the standard ``include'' directories. See the -I and -Y
options above for more detail. No additional tokens are permit-
ted on the directive line after the final `"' or `>>'.
#line integer-constant "filename"
Generate line control information for the next pass of the C
compiler. integer-constant is interpreted as the line number of
the next line and filename is interpreted as the file from where
it comes. If "filename" is not given, the current filename is
unchanged. No additional tokens are permitted on the directive
line after the optional filename.
Subsequent lines up to the matching #else, #elif , or #endif
directive, appear in the output only if constant-expression
yields a nonzero value. All binary non-assignment C operators,
including `&&&&', `||', and `,', are legal in constant-expression.
The `?:' operator, and the unary `-', `!', and `~' operators,
are also legal in constant-expression.
The precedence of these operators is the same as that for C. In
addition, the unary operator defined, can be used in constant-
expression in these two forms: `defined ( name )' or `defined
name'. This allows the effect of #ifdef and #ifndef directives
(described below) in the #if directive. Only these operators,
integer constants, and names that are known by cpp should be
used within constant-expression. In particular, the size of
operator is not available.
Subsequent lines up to the matching #else, #elif, or #endif
appear in the output only if name has been defined, either with
a #define directive or a -D option, and in the absence of an
intervening #undef directive. No additional tokens are permit-
ted on the directive line after name.
Subsequent lines up to the matching #else, #elif, or #endif
appear in the output only if name has not been defined, or if
its definition has been removed with an #undef directive. No
additional tokens are permitted on the directive line after name
Any number of #elif directives may appear between an #if,
#ifdef, or #ifndef directive and a matching #else or #endif
directive. The lines following the #elif directive appear in
the output only if all of the following conditions hold:
o The constant-expression in the preceding #if directive
evaluated to zero, the name in the preceding #ifdef is
not defined, or the name in the preceding #ifndef
directive was defined.
o The constant-expression in all intervening #elif
directives evaluated to zero.
o The current constant-expression evaluates to non-zero.
If the constant-expression evaluates to non-zero, subsequent
#elif and #else directives are ignored up to the matching
#endif. Any constant-expression allowed in an #if directive is
allowed in an #elif directive.
#else This inverts the sense of the conditional directive otherwise in
effect. If the preceding conditional would indicate that lines
are to be included, then lines between the #else and the match-
ing #endif are ignored. If the preceding conditional indicates
that lines would be ignored, subsequent lines are included in
the output. Conditional directives and corresponding #else
directives can be nested.
#endif End a section of lines begun by one of the conditional direc-
tives #if, #ifdef, or #ifndef. Each such directive must have a
Formal parameters for macros are recognized in #define directive bod-
ies, even when they occur inside character constants and quoted
strings. For instance, the output from:
#define abc(a) |\a|
is the seven characters `` |`xyz|'' (SPACE, vertical-bar, backquote, x,
y, z, vertical-bar). Macro names are not recognized within character
constants or quoted strings during the regular scan. Thus:
#define abc xyz
does not expand abc in the second line, since it is inside a quoted
string that is not part of a #define macro definition.
Macros are not expanded while processing a #define or #undef. Thus:
#define abc zingo
#define xyz abc
produces abc. The token appearing immediately after an #ifdef or #ifn-
def is not expanded.
Macros are not expanded during the scan which determines the actual
parameters to another macro call. Thus:
#define reverse(first,second)second first
#define greeting hello
#define greeting goodbye
produces `` #define hello goodbye hello''.
Output consists of a copy of the input file, with modifications, plus
lines of the form:
#lineno " filename" "level"
indicating the original source line number and filename of the follow-
ing output line and whether this is the first such line after an
include file has been entered (level=1), the first such line after an
include file has been exited (level=2), or any other such line (level
Directory Search Order
#include files is:
1. The directory of the file that contains the #include request
(that is, #include is relative to the file being scanned
when the request is made).
2. The directories specified by -I options, in left-to-right
3. The standard directory(s) (/usr/include on UNIX systems).
Two special names are understood by cpp. The name __LINE__ is defined
as the current line number (a decimal integer) as known by cpp, and
__FILE__ is defined as the current filename (a C string) as known by
cpp. They can be used anywhere (including in macros) just as any other
A NEWLINE character terminates a character constant or quoted string.
An escaped NEWLINE (that is, a backslash immediately followed by a NEW-
LINE) may be used in the body of a #define statement to continue the
definition onto the next line. The escaped NEWLINE is not included in
the macro value.
Comments are removed (unless the -C option is used on the command
line). Comments are also ignored, except that a comment terminates a
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.
When NEWLINE characters were found in argument lists for macros to be
expanded, some previous versions of cpp put out the NEWLINE characters
as they were found and expanded. The current version of cpp replaces
them with SPACE characters.
Because the standard directory for included files may be different in
different environments, this form of #include directive:
should be used, rather than one with an absolute path, like:
cpp warns about the use of the absolute pathname.
While the compiler allows 8-bit strings and comments, 8-bits are not
allowed anywhere else. See cc(1V) for an explanation about why cc is
not 8-bit clean.
25 January 1988 CPP(1)