cpp(1) cpp(1)
NAME
cpp - the C language preprocessor
SYNOPSIS
/lib/cpp [-C] [-Dname[=def]] [-Idir] [-P] [-Uname] [-
M[prefix]] [-Y] [ifile [ofile]]
DESCRIPTION
cpp is the C language preprocessor that is invoked as the
first pass of any C compilation using the cc(1) command.
The output of cpp is acceptable as input to the next pass of
the C compiler. As the C language evolves, cpp and the rest
of the C compilation package will be modified to follow
these changes. Therefore, the use of cpp other than in this
framework is not suggested. The preferred way to invoke cpp
is through the cc(1) command because the functionality of
cpp may someday be moved elsewhere. See m4(1) for a general
macro processor.
cpp optionally accepts two filenames as arguments. The in-
put for the preprocessor is ifile, which is also known as
the source file, and the output is ofile. If not supplied,
ifile and ofile default to standard input and standard out-
put, except in the case of the -M option, which requires
ifile to be present and have a suffix.
The following flag options to cpp are recognized:
-C Pass along all comments except those found on cpp
directive lines. By default, cpp strips C-style com-
ments.
-Dname
-Dname=def
Define name as if by a #define directive. If no =def
is given, name is defined as 1.
-Idir
Search for #include files (whose names do not begin
with /) in dir before looking in the directories on the
standard list. When this flag option is used, #include
files whose names are enclosed in "" (double quotes)
are searched for first in the directory of the ifile
argument, then in directories named in -I flag options,
and last in directories on a standard list, which, at
present, consists of /usr/include. If the -Y option
(see below) is specified, the standard list is not
searched. For #include files whose names are enclosed
in <>, the directory of the ifile argument is not
searched, unless -I. is specified.
-M[prefix]
April, 1990 1
cpp(1) cpp(1)
Generate make dependency statements from the #include
(see below) statements contained in ifile. The depen-
dency statements can later be incorporated into a
description file for use by make in determining the
#include files on which ifile depends. The dependency
statements are of the form:
target: include1 [include2 ...]
where target is a name created by subsituting the suf-
fix of ifile with '.o'. For example, if the name of
ifile is main.c, target will be main.o. If prefix is
present and the #include file in ifile is found in the
standard list, prefix is applied as shown below:
target: prefix/include1 [prefix/include2 ...]
For example, if the source file main.c includes
<stdio.h> and the -M option is used, the following
dependency statement is generated:
main.o: /usr/include/stdio.h
If -M'$(INC)' is specified, the following dependency
statement is generated:
main.o: $(INC)/stdio.h
Only unique #include files are kept; duplicates are
discarded. The resulting ofile will contain only
dependency statements. Error messages are written on
standard error. If cpp is invoked with the -M option
and ifile does not have a suffix, cpp exits with an er-
ror message.
-P Turn off the default production of line control infor-
mation. Line control information is used by the next
pass of the C compiler to generate useful error mes-
sages about the line on which an error occurred. Line
control lines have the form
# lineno file
where lineno is the line number within the file at
which cpp found the line. Line control information is
useful because, as cpp reads each #include file and
writes its contents to ofile, synchronization between
the text lines in ifile and the text lines in ofile is
lost. For example, if the following ifile is compiled
without line control information
#include <stdio.h>
2 April, 1990
cpp(1) cpp(1)
main()
{
x =) 2;
}
the C compiler will generate the following error mes-
sage:
"", line 157: x undefined
"", line 157: syntax error
To the C compiler, having included stdio.h in ofile,
line 157 is the true line number at which the error oc-
curred. With line control information enabled, which
is the default, cc can display the correct line number
as shown below:
"", line 5: x undefined
"", line 5: syntax error
-Uname
Remove any initial definition of name, where name is a
reserved symbol that is predefined by the particular
preprocessor. The list of reserved symbols is shown
below:
operating system: unix
hardware: m68k
UNIX(Reg.) System variant:
_SYSV_SOURCE _BSD_SOURCE
_AUX_SOURCE
-Y Prevent cpp from searching the standard list, which at
present consists of /usr/include, when processing #in-
clude files. This option is useful when used in con-
junction with the -I option. When cpp cannot find a
#include file in the directories specified by one or
more -I options, its normal behavior is to search the
standard list. If the -Y option is used in addition to
the -I option and cpp cannot find a #include file in
the directory specified by one or more -I options, cpp
writes an error message on standard error, does not
search the standard list, and continues processing.
Thus, use of the -Y option insures that cpp does not
silently include the wrong #include file in cases where
the -I option is incorrectly specified or the desired
#include file is erroneously missing from the specified
directory.
April, 1990 3
cpp(1) cpp(1)
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
filename (as a C string) as known by cpp. They can be used
anywhere, including in macros, just as any other defined
name.
All cpp directives start with lines begun by #. The direc-
tives are:
#define name token-string
Replace subsequent instances of name with token-string.
#define name( arg, ..., arg ) token-string
Replace subsequent instances of name followed by a left
parenthesis [(], a list of comma-separated tokens, and
a right parenthesis [)] by token-string where each oc-
currence of arg in the token-string is replaced by the
corresponding token in the comma-separated list. No-
tice that there can be no space between name and the
left parenthesis [(].
#undef name
Cause the definition of name, if any, to be undefined.
#include "filename"
#include <filename>
Include at this point the contents of filename, which
will then be run through cpp. When the <filename> no-
tation is used, filename is only searched for in the
standard places. See the -I flag option above for more
detail.
#line integer-constant "filename"
Cause cpp to generate line-control information for the
next pass of the C compiler. The line number of the
next line is integer-constant, and filename is the file
where it comes from. If "filename" is not given, the
current filename is unchanged.
#endif
End a section of lines begun by a test directive (#if,
#ifdef, or #ifndef). Each test directive must have a
matching #endif.
#ifdef name
Displays the lines following in the output if and only
if name was the subject of a previous #define without
being the subject of an intervening #undef.
#ifndef name
Does not display the lines following in the output if
4 April, 1990
cpp(1) cpp(1)
and only if name has been the subject of a previous
#define without being the subject of an intervening
#undef.
#if constant-expression
Displays the lines following in the output if and only
if constant-expression evaluates to nonzero. All
binary nonassignment C operators, the ?: operator, the
unary -, !, and ~ operators are legal in constant-
expression. The precedence of the operators is the
same as defined by the C language. There is also a
unary operator defined that can be used in constant-
expression in these two forms: defined ( name ) or
defined name. This allows the utility of #ifdef and
#ifndef in an #if directive. Only these operators, in-
teger constants, and names that are known by cpp should
be used in constant-expression. In particular, the
sizeof operator is not available.
#elif constant-expression
Displays the lines following the output if and only if
constant-expression is true and the preceding #if
constant-expression with which the subject #elif is
paired is false. The formation of constant-expression
is subject to the restrictions described for #if above.
#else
Reverse the notion of the test directive that matches
this directive. If lines previous to this directive
are ignored, the lines following appear in the output.
If lines previous to this directive are not ignored,
the lines following do not appear in the output.
#ident ...
This directive is maintained for historical reasons,
but does not cause cpp to do any special processing nor
to generate any output to ofile.
#pragma ...
Lines beginning with this directive are written to
ofile without modification.
The test directives and the possible #else directives can be
nested.
FILES
/lib/cpp
/usr/include
SEE ALSO
cc(1), m4(1), make(1).
April, 1990 5
``Other Programming Tools'' in A/UX Programming Languages
and Tools, Volume 2.
DIAGNOSTICS
The error and warning messages produced by cpp are self-
explanatory and are written to standard output. The line
number and filename where the error occurred are printed
with the diagnostic. If ifile is a relative pathname, cpp
also prints the absolute path of ifile in the form:
ifile(absolute path):message
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 ver-
sion of cpp replaces these newlines with blanks to alleviate
problems that the previous versions had when this occurred.
6 April, 1990