CPP(1) — USER COMMANDS
NAME
cpp − the C language preprocessor
SYNOPSIS
/lib/cpp [ −P ] [ −C ] [ −Uname ] [ −Dname ] [ −Dname=def ] [ −Idir ] [ ifile [ ofile ] ]
DESCRIPTION
Cpp is the C language preprocessor which is invoked as the first pass of any C compilation using the cc(1) command (cpp may optionally be invoked as the first pass of a FORTRAN 77 or Pascal compilation — see f77(1) or pc(1)). Thus the output of cpp is designed to be in a form acceptable as input to the next pass of the compiler. The preferred way to invoke cpp is through the cc(1) command. 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.
OPTIONS
−P Preprocess the input without producing the line control information used by the next pass of the C compiler.
−C Pass all comments (except those which appear on cpp directive lines) through the preprocessor. By default, cpp strips out C-style comments.
−Uname
Remove any initial definition of name, where name is a reserved symbol that is predefined by the particular preprocessor. The current list of these possibly reserved symbols includes unix, sun and either mc68010 or mc68020 (depending on whether you are running on a Sun-2, or Sun-3 system, respectively).
operating system: ibm, gcos, os, tss, unix
hardware: interdata, pdp11, u370, u3b, vax, mc68000
UNIX System variant: RES, RT, sun
−Dname
Define name as 1 (one). This is the same as if a −Dname=1 option appeared on the cpp command line, or as if a #define name 1 line appeared in the source file that cpp is processing.
−Dname=def
Define name as if by a #define directive. This is the same as if a #define name def line appeared in the source file that cpp is processing.
−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 current source file, 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 ifile argument is not searched. See the section entitled DETAILS below, for exact details of the search order.
−R Allow recursive macros.
DIRECTIVES
All cpp directives start with lines begun by #. White space (blanks or tabs) can appear after the #. The directives are:
#define name
Replace subsequent instances of name with token-string.
#define name( arg, ..., arg) token-string
There can be no space between name and the ‘(’. Replace subsequent instances of name followed by a ‘(’, a list of comma-separated tokens, and a ‘(’ by token-string where each occurrence of an arg in the token-string is replaced by the corresponding token in the comma-separated list.
#undef name
Forget the definition of name (if any) from now on.
#include "filename"
#include
Include at this point the contents of filename (which is then run through cpp). When the <filename> notation is used, filename is only searched for in the standard places. See DETAILS below.
#line integer-constant "filename"
Generate line control information for the next pass of the C compiler. Integer-constant is interpreted as the line number of the next line and filename is interpreted as the file where it comes from. If "filename" is not given, the current filename is unchanged.
#endif comment
Ends a section of lines begun by a test directive (#if, #ifdef, or #ifndef). Each test directive must have a matching #endif. The comment can be used to associate the #endif with its opening #if.
#ifdef name
The lines following will appear in the output if and only if name has been the subject of a previous #define or a −D option without being the subject of an intervening #undef.
#ifndef name
The lines following will not appear in the output if and only if name has been the subject of a previous #define or a −D option without being the subject of an intervening #undef.
#if constant-expression
Lines following will appear in the output if and only if the constant-expression evaluates to nonzero. All binary non-assignment C operators, including &&, ||, and ,, are legal in constant-expression. The ?: operator, and the unary −, !, and ~ operators, are also 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 or defined name. This allows the effect 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.
#else commentary
Reverses for the following lines the notion of the test directive currently in effect. So if lines previous to this directive are ignored, the following lines will appear in the output, and vice versa. The commentary can be used to associate the #else with its opening #if.
The test directives and corresponding #else directives can be nested.
DETAILS
Directory search order for #include files is:
1.the directory of the file which contains the #include request (that is, #include is relative to the file being scanned when the request is made)
2.the directories specified by −I options, in left-to-right order.
3.the standard directory(s) (/usr/include for the Sun system).
Special Names: Two special names are understood by cpp. The name __LINE__ is defined as the current line number (a decimal integer) as known by cpp, and __FILE__ is defined as the current filename (a C string) as known by cpp. They can be used anywhere (including in macros) just as any other defined name.
A newline terminates a character constant or quoted string.
An escaped newline (that is, a backslash immediately followed by a newline) may be used in the body of a #define statement to continue the definition onto the next line. The escaped newline is not included in the macro body.
Comments are removed (unless the −C option is used on the command line). Comments are also ignored, except that a comment terminates a token.
Macro formal parameters are recognized in #define bodies even inside character constants and quoted strings. The output from:
#define abc(a) ’\a’
abc(xyz)
is the seven characters ’\xyz’ (space, single-quote, escape character, x, y, z, single-quote). Macro names are not recognized inside character constants or quoted strings during the regular scan. Thus:
#define abc xyz
printf("abc");
does not expand ‘abc’ in the second line, because it is inside a quoted string which is not part of a #define macro definition.
Macros are not expanded while processing a #define or #undef. Thus:
#define abc bletch
#define xyz abc
#undef abc
xyz
produces ‘abc’. The token appearing immediately after a #ifdef or #ifndef is not expanded.
Macros are not expanded during the scan which determines the actual parameters to another macro call. Thus:
#define reverse(first,second)second first
#define greeting hello
reverse(greeting,
#define greeting goodbye
)
produces ‘ goodbye’ (and warns about the redefinition of ‘greeting’).
Output consists of a copy of the input file, with modifications, plus lines of the form: #lineno "filename" — indicating the original source line number and filename of the following output line.
FILES
/usr/include standard directory for #include files
SEE ALSO
DIAGNOSTICS
The error messages produced by cpp are intended to be self-explanatory. The line number and filename where the error occurred are printed along with the diagnostic.
NOTES
When newline characters were found in argument lists for macros to be expanded, some previous versions of cpp put out the newlines as they were found and expanded. The current version of cpp replaces these newlines with blanks.
Sun Release 3.0β — Last change: 21 December 1985