CPP(1) CPP(1)
NAME
cpp - the C language preprocessor
SYNOPSIS
LIBDIR/cpp [ option | file ] ...
DESCRIPTION
cpp is a K&R C language preprocessor designed for standalone use and to
be invoked as the first pass of all FORTRAN compilations and any K&R mode
C compilation with the -mp option. Thus, cpp's output is designed to be
in a form acceptable as input to the next pass of the C compiler.
Standalone use of cpp on C code is not suggested, since the functionality
of cpp has been incorporated into the C front-end. See m4(1) for a more
general macro processor.
This is a K&R C language preprocessor, not an ISO/ANSI C language
preprocessor: it is useful for those needing the old preprocessor. The #
operator, sometimes called the stringize operator, is not recognized as
such by cpp. The ## operator, sometimes called the pasting operator, is
not recognized as such by cpp. And the #elif command is not recognized
by cpp. There are other differences between this and ISO/ANSI C
preprocessors.
cpp optionally accepts any sequence of flags and input file names. The
input files are processed in order; if no input file names are given, the
standard input is used. The results of preprocessing the input file(s)
are sent to the standard output.
The following options to cpp are recognized:
-P Preprocess the input without producing the line control
information used by the next pass of the C compiler.
-C 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.
-M Run only the macro preprocessor on the named C programs,
requesting it to generate Makefile dependencies and send the
result to the standard output.
-MDupdate filename
Similar to the -M option, but stores the resulting Makefile
dependencies in filename rather than sending them to the standard
output. cpp with the -MDupdate option updates only the lines in
filename that end with a distinctive make comment and begin with
the target name (as described under the -MDtarget option)
followed by a colon.
Page 1
CPP(1) CPP(1)
-MDtarget name
When the -MDupdate option has been used, this option causes name
to be used as the target name for the first source file. By
default, the target name for a source file is the same as the
source file name with a `.o' suffix.
-Uname Remove any initial definition of name, where name is a reserved
symbol that is predefined by the particular preprocessor.
Following is the current list of these possibly reserved symbols.
The symbols __EDG, sgi, unix, and mips are always predefined by
cpp. The symbol __EXTENSIONS__ is predefined to indicate this is
not an ANSI cpp and to allow extensions in ANSI C include files.
The compiler drivers, as(1), cc(1), CC(1), pc(1), and f77(1)
predefine many other symbols during preprocessing. See their
respective man pages for complete lists of the symbols that they
define.
-Dname
-Dname=def
Define name with value def as if by a #define. If no =def is
given, name is defined with value 1. The -D option has lower
precedence than the -U option. That is, if the same name is used
in both a -U options and a -D option, the name will be undefined
regardless of the order of the options.
-Idir Change the algorithm for searching for #include files whose names
do not begin with / to look in dir before looking in the
directories on the standard list. Thus #include files whose
names are enclosed in "" will be searched for first in the
directory of the file with the #include line, then in the
directories named in -I options, and last in directories on a
standard list. For #include files whose names are enclosed in
<>, the directory of the file with the #include line is not
searched. If -I is given with no dir, cpp is instructed to
suppress the search of the standard list of include directories.
This standard list consists only of /usr/include.
-maxrecdepth=num
Set the maximum nesting depth of calls to a single macro to num.
The default value is 300.
Four special names are understood by cpp. The name LINE is defined
as the current line number (as a decimal integer) as known by cpp,
FILE is defined as the current file name (as a C string) as known by
cpp, DATE is defined as a C string containing the current date
(printed in the form "Dec 31 1999"), and TIME is defined as a C
string containing the current time in hh:mm:ss format. They can be used
anywhere (including in macros) just as any other defined name.
Page 2
CPP(1) CPP(1)
All cpp directive lines start with # in column 1. Any number of blanks
and tabs are allowed between the # and the directive. The directives
are:
#define name token-string
Replace subsequent instances of name with token-string.
#define name( arg, ..., arg ) token-string
Notice that there can be no space between name and the (. Replace
subsequent instances of name followed by a (, a list of comma-
separated sets of tokens, and a ) followed by token-string, where
each occurrence of an arg in the token-string is replaced by the
corresponding set of tokens 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
Cause the definition of name (if any) to be forgotten from now on.
No additional tokens are permitted on the directive line after name.
#ident "string"
The string and the directive are silently swallowed. No output is
produced for this directive.
#pragma
The directive and whatever follows it on the line is passed to the
output in a slightly modified form which is not documented. The
form may change in a future release.
#pragma once
If this directive appears in an included file, the file will never
be included again, even if there is another #include of this file.
No tokens or comments are permitted after the ``once'' keyword.
Using #pragma once is more efficient than using macro wrappers,
because the included file is not rescanned, but it may not be
portable to third-party preprocessors.
#include "filename"
#include <filename>
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 -I option above
for more detail. No additional tokens are permitted on the
directive line after the final " or >.
#line integer-constant filename
Causes cpp to generate line control information for the next pass of
the C compiler. Integer-constant is the line number of the next
Page 3
CPP(1) CPP(1)
line and filename is the file from which it comes. If "filename" is
not given, the current file name is unchanged. No additional tokens
are premitted on the directive line after the optional filename.
#endif
Ends a section of lines begun by a test directive (#if, #ifdef, or
#ifndef). Each test directive must have a matching #endif. No
additional tokens are permitted on the directive line.
#ifdef name
The lines following will appear in the output if and only if name
has been the subject of a previous #define without being the subject
of an intervening #undef. No additional tokens are permitted on the
directive line after name.
#ifndef name
The lines following will appear in the output if and only if name
has not been the subject of a previous #define. No additional
tokens are permitted on the directive line after name.
#if constant-expression
Lines following will appear in the output if and only if the
constant-expression evaluates to non-zero. All binary non-
assignment C operators, the ?: operator, the unary -, !, and ~
operators are all 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, which can be used in constant-
expression in these two forms: defined ( name ) or 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 constant-expression. In particular, the
sizeof operator is not available.
To test whether either of two symbols, foo and fum, are defined,
use:
#if defined(foo) || defined(fum)
#else
The lines following will appear in the output if and only if the
preceding test directive evaluates to zero. No additional tokens
are permitted on the directive line.
The test directives and the possible #else directives can be nested.
FILES
INCDIR standard directory list for #include files,
/usr/include
LIBDIR /usr/lib
Page 4
CPP(1) CPP(1)
SEE ALSO
cc(1), line(1), m4(1), unifdef(1)
Page 5