cpp(1)cpp(1)NAMEcpp - the C language preprocessor
SYNOPSIS
/usr/lib/cpp [option...] [ifile[ofile]]
OPTIONS
The cpp command recognizes the following options: Preprocess the input
without producing the line control information used by the next pass of
the C compiler. 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. Tell cpp not to issue warning messages. Set
the limit of nesting levels for include files. The default is 50. Sets
a limit on the number of errors that the compiler will flag. The
default is 30. Treat comments in the old way; delete them and replace
them with nothing. This is the default in -std0 mode.
The default in -std or -std0 mode is to replace comments with a
space. Cause cpp to expand __FILE__ to 'filename' instead of to
"filename" (the default). Remove any definition of name that
was previously defined with the -D option. The -U option is
ignored if it is specified without a name. Define name as if by
a #define directive. If the def argument is not specified, name
is defined as 1. If name is not specified, the -D option is
ignored. 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. Specify a search path for include files whose
names do not indicate a specific directory path (that is,
include files whose names do not begin with a /). The actual
search path depends upon the form of the #include directive used
for the file: If the #include" filename" form of the directive
is used, the C macro preprocessor searches for the file at the
following locations: first in the directory in which it found
the file that contains the directive, then in the search path
indicated by the -I option, and finally in the standard direc‐
tory, /usr/include. If the include <filename> form of the
directive is used, the preprocessor searches for the file first
in the search path indicated by the -I option, and then in the
standard directory, /usr/include.
You can specify multiple iterations of the -I[dir] option in the
cc command line. If no dir is specified in any iteration of the
-I[dir] option, the C macro preprocessor never searches the
standard directory, /usr/include, for #include files.
The -nocurrent_include option can also modify the search path.
Change the behavior of the #include "filename" directive to not
search the source file's directory for filename. This option
causes the #include "filename" directives to behave like
#include <filename> directives. This option allows makefiles to
control the search order for header files by using -I options.
Print, one per line on standard output, the path names of
included files. Each is prefixed with the last component name
of ifile and the suffix is changed to followed by a colon (:)
and a space (for example, hello.o: /usr/include/stdio.h). The
cpp command indents lines, as appropriate, to indicate where an
included file itself includes another included file. Produce a
dependency file, which has the suffix appended to the object
file name. This dependency file is created even if the object
file is not. The information and the format in the dependency
file is identical to that produced by the -M option. This option
allows dependency information to be generated at the same time
that a compilation is occurring. Ensures that the compiler's
assumptions about pointer sizes and data alignments are not in
conflict with the data values that were in effect when the sys‐
tem libraries were created.
The keywords for the -protect_headers option are as follows:
Enables the protect headers feature. Disables the protect head‐
ers feature. This is the default for all inputs. Cancels any
previous -protect_headers options and places the compiler's
default behavior in effect.
If more than one such switch appears on the command line, only
the last one is applied. See protect_headers_setup(8) for
details.
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. In addition, cpp reserves the names __DATE__ and
__TIME__ for future use.
All cpp directives start with lines beginning with #. The directives
are: Replace subsequent instances of name with token-string. Notice
that no space can be inserted between name and the “(” that follows it.
Replace subsequent instances of name followed by a “(”, a comma-sepa‐
rated list of unique identifiers, and a “)” with token-string, where
each occurrence of an arg in the token-string is replaced by the corre‐
sponding identifier 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. Cause the definition of name (if
any) to be forgotten from this point. This directive is transformed by
the preprocessor into the form __pragma(6, "string"). 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 description of the -I option for more
details. Cause cpp to generate line control information for the next
pass of the C compiler. The integer-constant is the line number of the
next line and filename is the file where it comes from. If filename is
not specified, the current file name is unchanged. End a section of
lines that begin with a test directive (#if, #ifdef, or #ifndef). Each
test directive must have a matching #endif. Lines following this
directive will appear in the output only if name has been the subject
of a previous #define without being the subject of an intervening
#undef. Lines following this directive will not appear in the output
if name has been the subject of a previous #define without being the
subject of an intervening #undef. Lines following this directive will
appear in the output only if the constant-expression evaluates to non-
zero. All binary non-assignment C operators, the ?: operator, and the
unary -, !, and ~ operators are all legal in constant-expression.
The precedence of the operators is the same as defined by the C
language. The unary operator defined can also be used in con‐
stant-expression in either of the following forms: defined(name)
or defined name. This allows the utility of #ifdef and #ifndef
in a #if directive.
Only those operators, integer constants, and names that are
known by cpp should be used in constant-expression. In particu‐
lar, the sizeof operator is not available.
For example, to test whether either of two symbols, foo and fum,
are defined, use the following directive:
#if defined(foo) || defined(fum) Reverses the notion of the test
directive that matches this directive. For example, if lines
previous to this directive are ignored, the lines following will
appear in the output. Similar to #else followed by #if, except
does not introduce another conditional level. The same restric‐
tions to the constant-expression for #if apply. For example:
#if foo==4 a="foo is four"; #elif foo==2 a="foo is two"; #else
a="foo is not four nor two"; #endif
The test directives and the possible #else directives can be
nested. Any number of #elif directives may occur between a test
directive and the corresponding #else or #endif.
DESCRIPTION
The cpp C language preprocessor performs initial text substitutions,
manipulations, conditional inclusion, and various other activities as
described by the C standard.
The preferred way to invoke cpp on C files is through the cc(1) com‐
mand. See m4(1) for a general macro processor.
The cpp preprocessor optionally accepts two file names as arguments:
Input to the preprocessor Output from the preprocessor
These files default to standard input and standard output if not sup‐
plied. Unless directed to do otherwise, cpp places the output file
(ofile) in the same directory in which the input file (ifile) resides.
The cpp preprocessor accepts C++-style end-of-line comments (//). This
means that everything following the two slashes (//) to the end of the
line in which they appear is considered to be a comment.
The cpp command does not predefine any macros other than the standard C
macros __LINE__, __FILE__, __DATE__, __TIME__, (and __STDC__ if appro‐
priate).
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.
ERRORS
The error messages produced by cpp are intended to be self-explanatory.
The line number and file name where the error occurred are printed
along with the diagnostic.
FILES
Standard directory for include files
SEE ALSO
Commands: cc(1), as(1), m4(1)cpp(1)