CPP(1) (C Programming Language Utilities) CPP(1)
NAME
cpp - the C language preprocessor
SYNOPSIS
LIBDIR/cpp [ option ... ] [ ifile [ ofile ] ]
DESCRIPTION
The C language preprocessor, cpp, is invoked as the first
pass of any C compilation by the cc(1) command. Thus cpp's
output is designed to be in a form 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 through the cc(1) command is not suggested, since
the functionality of cpp may someday be moved elsewhere.
See m4(1) for a general macro processor.
cpp optionally accepts two file names as arguments. Ifile
and ofile are respectively the input and output for the
preprocessor. They default to standard input and standard
output if not supplied.
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.
-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. On AT&T 3B2 and 3B5
Computers, unix and one of u3b2 or u3b5 are defined.
operating system: unix, dmert, gcos, ibm, os,
tss
hardware: interdata, pdp11, u370,
Page 1 May 1989
CPP(1) (C Programming Language Utilities) CPP(1)
u3b, u3b5, u3b2, u3b20d,
vax
UNIX system variant: RES, RT
lint(1): lint
-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 option and a
-D option, the name will be undefined regardless of the
order of the options.
-T The -T option forces cpp to use only the first eight
characters to distinguish preprocessor symbols and is
included for backward compatibility.
-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 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.
-Ydir
Use directory dir in place of the standard list of
directories when searching for #include files.
-H Print, one per line on standard error, the path names
of included files.
Two special names are understood by cpp. The name LINE
is defined as the current line number (as a decimal integer)
Page 2 May 1989
CPP(1) (C Programming Language Utilities) CPP(1)
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.
All cpp directive lines start with # in column 1. Any
number of blanks and tabs is 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"
Put string into the .comment section of an object file.
#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 and -Y options above for
more detail. No additional tokens are permitted on the
Page 3 May 1989
CPP(1) (C Programming Language Utilities) CPP(1)
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 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 permitted 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
Page 4 May 1989
CPP(1) (C Programming Language Utilities) CPP(1)
#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)
#elif constant-expression
An arbitrary number of #elif directives is allowed
between a #if, #ifdef, or #ifndef directive and a #else
or #endif directive. The lines following the #elif
directive will appear in the output if and only if the
preceding test directive evaluates to zero, all
intervening #elif directives evaluate to zero, and the
constant-expression evaluates to non-zero. If
constant-expression evaluates to non-zero, all
succeeding #elif and #else directives will be ignored.
Any constant-expression allowed in a #if directive is
allowed in a #elif directive.
#else
The lines following will appear in the output if and
only if the preceding test directive evaluates to zero,
and all intervening #elif directives evaluate 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,
usually /usr/include
LIBDIR usually /lib
SEE ALSO
Page 5 May 1989
CPP(1) (C Programming Language Utilities) CPP(1)
cc(1), lint(1), m4(1).
DIAGNOSTICS
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.
NOTES
The unsupported -W option enables the #class directive. If
it encounters a #class directive, cpp will exit with code 27
after finishing all other processing. This option provides
support for ``C with classes''.
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.
Page 6 May 1989