CPP(1) BSD CPP(1)
NAME
cpp - the C language preprocessor
SYNOPSIS
/usr/apollo/lib/cpp [option . . .] [ ifile [ ofile ] ]
/usr/lib/cpp [option . . .] [ ifile [ ofile ] ]
DESCRIPTION
cpp is invoked as the first pass of any C compilation by the cc(1)
command. Therefore, 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 are modified to follow
these changes.
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.
By default, the cc command invokes the ANSI C preprocessor,
/usr/apollo/lib/cpp. If you specify the -A nansi option and your systype
is set to bsd4.3, cc invokes the non-ANSI BSD preprocessor,
/bsd4.3/usr/lib/cpp. If you specify the -A nansi option and your systype
is set to sys5.3, cc invokes the non-ANSI SysV preprocessor,
/sys5.3/usr/lib/cpp. You can also invoke a non-ANSI preprocessor with
the option -Yp,/usr/lib.
Most programs will compile successfully with the ANSI preprocessor.
Occasionally the use of an obsolete feature (such as macro names embedded
in quoted strings) will require you to use one of the non-ANSI
preprocessors.
The cc command recognizes the following options and passes them to the
preprocessor: -C, -D, -H (non-ANSI SysV and ANSI preprocessors only), -I,
-M (non-ANSI BSD preprocessor only), -P, -U. You can pass the following
options to the preprocessor by specifying the -Wp option to the cc
command: -t, -T (non-ANSI SysV preprocessor only), -Y (non-ANSI SysV and
ANSI preprocessors only).
OPTIONS
-C Passes along C-style comments (except those found on cpp directive
lines). By default, cpp strips out C-style comments.
-Dname
-Dname=def
Defines name with value def as if by a #define. If no =def is
given, name is defined with value 1. 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.
-H Prints, one per line on standard error, the pathnames of included
files. The ANSI preprocessor indents the list of included files to
show how the #include directives are nested; the non-ANSI SysV
preprocessor does not indent the list. This option is not valid
with the non-ANSI BSD preprocessor.
-Idir
Changes the algorithm for searching for #include files whose names
do not begin with a slash (/) to look in dir before looking in the
directories on the standard list. Thus, #include files whose names
are enclosed in double quotes ("") are searched for first in the
directory of the file with the #include line, then in directories
named in -I options, and last in /usr/include. For #include files
whose names are enclosed in angle brackets (<>), the directory of
the file with the #include line is not searched.
-M Runs only the macro preprocessor on the named C programs, requesting
it to generate Makefile dependencies and send the result to standard
output. This option is valid only with the non-ANSI BSD
preprocessor.
-P Preprocesses the input without producing the line control
information used by the next pass of the C compiler.
-tsys
Sets the environment variable SYSTYPE to sys while cpp is running.
This option is useful for setting the resolution of systype-
dependent links. For example, if your systype is sys5.3 and you
specify -tbsd4.3, the file /usr/include/ndbm.h resolves to
/bsd4.3/usr/include/ndbm.h instead of /sys5.3/usr/include/ndbm.h.
-T Uses only the first eight characters to distinguish preprocessor
symbols. This option is valid only with the non-ANSI SysV
preprocessor.
-Uname
Removes 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 Apollo
computers, _ISP__M68K, _ISP__A88K, _ISP__PA_RISC, _BFMT__COFF, unix,
apollo, and aegis are defined.
-Ydir
Uses directory dir in place of the standard list of directories when
searching for #include files. This option is not valid with the
non-ANSI BSD preprocessor.
Other 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. __DATE__ is defined as the current date (as a C string), and
__TIME__ is defined as the current time (as a C string). __STDC__
expands to 1 if the compiler being used conforms to the ANSI C standard.
__STDCPP__ expands to 1 if the ANSI C preprocessor is being used. These
names can be used anywhere (including in macros) just as any other
defined name.
DIRECTIVES
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. The ANSI preprocessor
recognizes two operators, ## and #, in #define directives. The
macro concatenation operator ## pastes together the two arguments on
either side of it. The stringizing operator # changes any macro
argument that follows it into a character 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"
This directive is obsolete; the preprocessor accepts it, but it has
no effect.
#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
directive line after the final " or >.
#line integer-constant ["filename"]
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 from which 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".
#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 following lines appear in the output only if name has been the
subject of a previous #define and not the subject of an intervening
#undef. No additional tokens are permitted on the directive line
after name.
#ifndef name
The following lines appear in the output 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
The following lines appear in the output 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. Operator precedence 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 operator provides the
functionality 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)
#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 #elif appear in the output 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. The
#elif directive is not recognized by the non-ANSI BSD preprocessor.
#else
The following lines appear in the output 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. In
addition, the following directives are recognized by cpp and passed to
the Domain/C compiler. All except #pragma are obsolete; do not use them
in new programs.
# pragma
# debug
# eject
# list
# module
# nolist
# systype
# section
# attribute
# options
NOTES
If you want your code to be portable to other vendors' systems, be aware
that the standard directory for include files may be different in
different environments. Use the following form of the #include
directive:
#include <file.h>
rather than one with an absolute path, like:
#include "/usr/include/file.h"
DIAGNOSTICS
The error messages produced by cpp are intended to be self-explanatory.
The file name and line number where the error occurred are printed along
with the diagnostic.
SEE ALSO
cc(1), m4(1). Domain/C Language Reference.