CPP(1) C Programming Language Utilities CPP(1)
NAME
cpp - the C language preprocessor
SYNOPSIS
/sys5.3/usr/lib/cpp [option . . .] [ ifile [ ofile ] ]
DESCRIPTION
cpp is invoked as the first pass of any C compilation by the cc(1) com-
mand. 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.
Note: This discussion applies to the pre-ANSI SysV preprocessor. Ver-
sion 6.8 of Domain/C uses this preprocessor only if you compile with
/bin/cc with -A nansi specified, and if your systype is sys5.3. The ANSI
preprocessor is /usr/apollo/lib/cpp.
OPTIONS
-P Preprocesses the input without producing the line control informa-
tion used by the next pass of the C compiler.
-C Passes along C-style comments (except those found on cpp directive
lines). By default, cpp strips out C-style comments.
-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, unix, apollo, and aegis are defined.
-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 regard-
less of the order of the options.
-T Uses only the first eight characters to distinguish preprocessor
symbols. This option is included for backward compatibility.
-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.
-Ydir
Uses directory dir in place of the standard list of directories when
searching for #include files.
-H Prints, one per line on standard error, the path names of included
files.
-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/rdmb.h resolves to
/bsd4.3/usr/include/ndmb.h instead of /sys5.3/usr/include/ndmb.h.
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.
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.
#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
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. 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 permit-
ted 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 allows the utility of #ifdef
and #ifndef in a #if directive. Only these operators, integer con-
stants, 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.
#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 direc-
tive 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:
# debug
# eject
# list
# module
# nolist
# systype
# section
# attribute
# options
NOTES
Using cpp other than through the cc(1) command is not suggested. See
m4(1) for a general macro processor.
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 dif-
ferent 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), lint(1), m4(1). Domain C Language Reference.