cpp(1)
NAME
cpp - the C language preprocessor
SYNOPSIS
/usr/lib/cpp [-BCHMpPRT] [-undef] [-Dname] [ -Dname = def]
[-Idirectory] [-Uname] [-Ydirectory] [ input-file [output-
file]]
DESCRIPTION
cpp is the C language preprocessor. It is invoked as the
first pass of any C compilation started with the cc(1B) com-
mand. However, cpp can also be used as a first-pass prepro-
cessor 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 acceptable as input to a compiler's second
pass. Thus, the preferred way to invoke cpp is through the
cc(1B) command, or some other compilation command. For
general-purpose macro-processing, see m4(1).
cpp optionally accepts two filenames as arguments. input-
file and output-file are, respectively, the input and output
files for the preprocessor. They default to the standard
input and the standard output.
OPTIONS
The following options are supported:
-B Supports the C++ comment indicator `//'. With this
indicator, everything on the line after the // is
treated as a comment.
-C Passes all comments (except those that appear on cpp
directive lines) through the preprocessor. By default,
cpp strips out C-style comments.
-H Prints the pathnames of included files, one per line
on the standard error.
-M Generates 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 Uses 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 direc-
tive.
-P Preprocesses the input without producing the line
control information used by the next pass of the C
compiler.
-R Allows recursive macros.
-T Uses only the first eight characters for distinguish-
ing different preprocessor names. This option is
included for backward compatibility with systems which
always use only the first eight characters.
-undef
Removes initial definitions for all predefined sym-
bols.
-Dname
Defines 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 process-
ing.
-Dname=def
Defines name as if by a #define directive. This is the
same as if a
#define name def
line appeared in the source file that cpp is process-
ing. 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.
-Idirectory
Inserts 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
Removes any initial definition of name, where name is
a symbol that is predefined by a particular preproces-
sor. Here is a partial 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 command:
lint
The symbols sun, sparc and unix are defined for all Sun
systems.
-Ydirectory
Uses directory in place of the standard list of direc-
tories when searching for #include files.
USAGE
Directives
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 subsequent instances of name, followed by a
parenthesized list of arguments, with token-string,
where each occurrence of an argument 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.
#undef name
Remove any definition for the symbol name. No addi-
tional tokens are permitted on the directive line
after name.
#include "filename"
#include <filename>
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 per-
mitted 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 inter-
preted 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.
#if constant-expression
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 `?:' opera-
tor, 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 particu-
lar, the size of operator is not available.
#ifdef name
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. Additional tokens after name on the direc-
tive line will be silently ignored.
#ifndef 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.
#elif constant-expression
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 fol-
lowing 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, sub-
sequent #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 matching #endif are
ignored. If the preceding conditional indicates that
lines would be ignored, subsequent lines are included
in the output. Conditional directives and correspond-
ing #else directives can be nested.
#endif
End a section of lines begun by one of the conditional
directives #if, #ifdef, or #ifndef. Each such direc-
tive must have a matching #endif.
Macros
Formal parameters for macros are recognized in #define
directive bodies, even when they occur inside character con-
stants and quoted strings. For instance, the output from:
#define abc(a)|`|a|
abc(xyz)
is:
# 1 ""
|`|xyz|
The second line is a NEWLINE. The last seven characters are
``|`|xyz|'' (vertical-bar, backquote, vertical-bar, x, y, z,
vertical-bar). Macro names are not recognized within charac-
ter constants or quoted strings during the regular scan.
Thus:
#define abc xyz
printf("abc");
does not expand abc in the second line, since it is inside a
quoted string that is not part of a #define macro defini-
tion.
Macros are not expanded while processing a #define or
#undef. Thus:
#define abc zingo
#define xyz abc
#undef abc
xyz
produces abc. The token appearing immediately after an
#ifdef or #ifndef 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
reverse(greeting,
#define greeting goodbye
)
produces `` #define hello goodbye hello''.
Output
Output consists of a copy of the input file, with modifica-
tions, plus lines of the form:
#lineno " filename" "level"
indicating the original source line number and filename of
the following 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 is empty).
Details
This section contains usage details.
Directory Search Order
#include files are searched for in the following order:
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
order.
3. The standard directory(s) (/usr/include on UNIX systems).
Special Names
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 any-
where (including in macros) just as any other defined name.
Newline Characters
A NEWLINE character terminates a character constant or
quoted string. An escaped NEWLINE (that is, a backslash
immediately followed by a NEWLINE) 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
Comments are removed (unless the -C option is used on the
command line). Comments are also ignored, except that a com-
ment terminates a token.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
non-zero
An error occurred.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWsprot |
|_____________________________|_____________________________|
SEE ALSO
cc(1B), m4(1), attributes(5)
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, 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> charac-
ters.
Because the standard directory for included files may be
different in different environments, this form of #include
directive:
#include <file.h>
should be used, rather than one with an absolute path, like:
#include "/usr/include/file.h"
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.
Man(1) output converted with
man2html