'\" te
.\" Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
.TH cpp 1 "7 Dec 2010" "SunOS 5.11" "User Commands"
.SH NAME
cpp \- the C language preprocessor
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/cpp\fR [\fB-BCHMpPRT\fR] [\fB-undef\fR] [\fB-D\fR\fIname\fR] [\fB-D\fR\fIname\fR = \fIdef\fR] 
     [\fB-I\fR\fIdirectory\fR] [\fB-U\fR\fIname\fR] [\fB-Y\fR\fIdirectory\fR] 
     [\fIinput-file\fR [\fIoutput-file\fR]]
.fi

.SH DESCRIPTION
.sp
.LP
\fBcpp\fR is the C language preprocessor. \fBcpp\fR also used as a first-pass preprocessor for other Sun compilers.
.sp
.LP
Although \fBcpp\fR can be used as a macro processor, this is not normally recommended, as its output is geared toward that which would be acceptable as input to a compiler's second pass. Thus, the preferred way to invoke \fBcpp\fR is through a compilation command. For general-purpose macro-processing, see \fBm4\fR(1). 
.sp
.LP
\fBcpp\fR optionally accepts two filenames as arguments. \fIinput-file\fR and \fIoutput-file\fR are, respectively, the input and output files for the preprocessor. They default to the standard input and the standard output.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-B\fR\fR
.ad
.RS 15n
.rt  
Supports the C++ comment indicator \fB/\|/\fR. With this indicator, everything on the line after the \fB/\|/\fR is treated as a comment.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-C\fR\fR
.ad
.RS 15n
.rt  
Passes all comments (except those that appear on  \fBcpp\fR directive lines) through the preprocessor. By default, \fBcpp\fR strips out C-style comments.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-H\fR\fR
.ad
.RS 15n
.rt  
Prints the pathnames of included files, one per line on the standard error.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-M\fR\fR
.ad
.RS 15n
.rt  
Generates a list of makefile dependencies and write them to the standard output. This list indicates that the object file which would be generated from the input file depends on the input file as well as the include files referenced.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-p\fR\fR
.ad
.RS 15n
.rt  
Uses only the first eight characters to distinguish preprocessor symbols, and issue a warning if extra tokens appear at the end of a line containing a directive.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-P\fR\fR
.ad
.RS 15n
.rt  
Preprocesses the input without producing the line control information used by the next pass of the C compiler.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-R\fR\fR
.ad
.RS 15n
.rt  
Allows recursive macros.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-T\fR\fR
.ad
.RS 15n
.rt  
Uses only the first eight characters for distinguishing different preprocessor names. This option is included for backward compatibility with systems which always use only the first eight characters.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-undef\fR\fR
.ad
.RS 15n
.rt  
Removes initial definitions for all predefined symbols.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D\fR\fIname\fR\fR
.ad
.RS 15n
.rt  
Defines \fIname\fR as \fB1\fR (one). This is the same as if a \fB-D\fR\fIname\fR\fB=1\fR option appeared on the  \fBcpp\fR command line, or as if a
.sp
.in +2
.nf
\fB#define\fR \fIname\fR \fB1\fR
.fi
.in -2
.sp

line appeared in the source file that \fBcpp\fR is processing.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D\fR\fIname\fR\fB=\fR\fIdef\fR\fR
.ad
.RS 15n
.rt  
Defines \fIname\fR as if by a \fB#define\fR directive. This is the same as if a
.sp
.in +2
.nf
\fB#define\fR \fIname\fR \fBdef\fR
.fi
.in -2
.sp

line appeared in the source file that  \fBcpp\fR is processing. The \fB-D\fR option has lower precedence than the \fB-U\fR option. That is, if the same name is used in both a \fB-U\fR option and a \fB-D\fR option, the name will be undefined regardless of the order of the options.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I\fR\fIdirectory\fR\fR
.ad
.RS 15n
.rt  
Inserts \fIdirectory\fR into the search path for \fB#include\fR files with names not beginning with \fB/\fR. \fIdirectory\fR is inserted ahead of the standard list of \fBinclude\fR directories. Thus, \fB#include\fR files with names enclosed in double-quotes (\fB"\fR) are searched for first in the directory of the file with the \fB#include\fR line, then in directories named with \fB-I\fR options, and lastly, in directories from the standard list. For \fB#include\fR files with names enclosed in angle-brackets (\fB<\|>\fR), the directory of the file with the \fB#include\fR line is not searched. See \fBDetails\fR below for exact details of this search order.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-U\fR\fIname\fR\fR
.ad
.RS 15n
.rt  
Removes any initial definition of \fIname\fR, where \fIname\fR is a symbol that is predefined by a particular preprocessor. Here is a partial list of symbols that may be predefined, depending upon  the architecture of the system: 
.sp
.ne 2
.mk
.na
\fBOperating System:\fR
.ad
.RS 24n
.rt  
\fBibm\fR, \fBgcos\fR, \fBos\fR, \fBtss\fR and \fBunix\fR
.RE

.sp
.ne 2
.mk
.na
\fBHardware:\fR
.ad
.RS 24n
.rt  
\fBinterdata\fR, \fBu3b20d\fR, \fBns32000\fR, \fBi386\fR, \fBsparc\fR, and \fBsun\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fBUNIX system variant:\fR\fR
.ad
.RS 24n
.rt  
\fBRES\fR, and \fBRT\fR
.RE

.sp
.ne 2
.mk
.na
\fBThe \fBlint\fR command:\fR
.ad
.RS 24n
.rt  
\fBlint\fR
.RE

The symbols  \fBsun\fR, \fBsparc\fR and \fBunix\fR are defined for all Sun systems.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-Y\fR\fIdirectory\fR\fR
.ad
.RS 15n
.rt  
Uses \fIdirectory\fR in place of the standard list of directories when searching for \fB#include\fR files.
.RE

.SH USAGE
.SS "Directives"
.sp
.LP
All \fBcpp\fR directives start with a hash symbol (\fB#\fR) as the first character on a line. White space (SPACE or TAB characters) can appear after the initial \fB#\fR for proper indentation.
.sp
.ne 2
.mk
.na
\fB\fB#define\fR \fIname token-string\fR\fR
.ad
.sp .6
.RS 4n
Replace subsequent instances of \fIname\fR with \fItoken-string\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#define\fR \fIname\fR\fB(\fR\fIargument\fR [\fB,\fR \fIargument\fR] .\|.\|. \fB)\fR \fItoken-string\fR\fR
.ad
.sp .6
.RS 4n
There can be no space between \fIname\fR and the  `\fB(\fR'. Replace subsequent instances of \fIname\fR, followed by a parenthesized list of arguments, with \fItoken-string\fR, where each occurrence of an \fIargument\fR in the \fItoken-string\fR is replaced by the corresponding token in the comma-separated list. When a macro with arguments is expanded, the arguments are placed into the expanded \fItoken-string\fR unchanged. After the entire \fItoken-string\fR has been expanded, \fBcpp\fR re-starts its scan for names to expand at the beginning of the newly created \fItoken-string\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#undef\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Remove any definition for the symbol \fIname\fR. No additional tokens are permitted on the directive line after \fIname\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#include "\fR\fIfilename\fR\fB"\fR\fR
.ad
.br
.na
\fB\fB#include\fR \fB<\fR\fIfilename\fR\fB>\fR\fR
.ad
.sp .6
.RS 4n
Read in the contents of \fIfilename\fR at this location. This data is processed by \fBcpp\fR as if it were part of the current file. When the \fB<\fR\fIfilename\fR\fB>\fR notation is used, \fIfilename\fR is only searched for in the standard \fBinclude\fR directories. See the \fB-I\fR and \fB-Y\fR options above for more detail. No additional tokens are permitted on the directive line after the final \fB"\fR or \fB>\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#line\fR \fIinteger-constant\fR\fB"\fR \fIfilename\fR\fB"\fR\fR
.ad
.sp .6
.RS 4n
Generate line control information for the next pass of the C compiler. \fIinteger-constant\fR is interpreted as the line number of the next line and \fIfilename\fR is interpreted as the file from where it comes. If \fB"\fR\fIfilename\fR\fB"\fR is not given, the current filename is unchanged. No additional tokens are permitted on the directive line after the optional \fIfilename\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#if\fR \fIconstant-expression\fR\fR
.ad
.sp .6
.RS 4n
Subsequent lines up to the matching \fB#else\fR, \fB#elif\fR, or \fB#endif\fR directive, appear in the output only if \fIconstant-expression\fR yields a nonzero value. All binary non-assignment C operators, including  \fB&&\fR, \fB|\||\fR, and \fB,\fR, are legal in \fIconstant-expression\fR. The \fB?:\fRoperator, and the unary \fB\(mi\fR, \fB!\fR, and \fB~\fR operators, are also legal in \fIconstant-expression\fR.
.sp
The precedence of these operators is the same as that for C. In addition, the unary operator \fBdefined\fR, can be used in \fIconstant-expression\fR in these two forms: `\fBdefined (\fR \fIname\fR \fB)'\fR or `\fBdefined\fR \fIname\fR'. This allows the effect of \fB#ifdef\fR and \fB#ifndef\fR directives (described below) in the \fB#if\fR directive. Only these operators, integer constants, and names that are known by \fBcpp\fR should be used within \fIconstant-expression\fR. In particular, the \fBsize\fR \fBof\fR operator is not available.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#ifdef\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Subsequent lines up to the matching \fB#else\fR, \fB#elif\fR, or \fB#endif\fR appear in the output only if \fIname\fR has been defined, either with a \fB#define\fR directive or a \fB-D\fR option, and in the absence of an intervening \fB#undef\fR directive. Additional tokens after \fIname\fR on the directive line will be silently ignored.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#ifndef\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Subsequent lines up to the matching \fB#else\fR, \fB#elif\fR, or \fB#endif\fR appear in the output only if \fIname\fR has \fInot\fR been defined, or if its definition has been removed with an \fB#undef\fR directive. No additional tokens are permitted on the directive line after \fIname\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#elif\fR \fIconstant-expression\fR\fR
.ad
.sp .6
.RS 4n
Any number of \fB#elif\fR directives may appear between an \fB#if\fR, \fB#ifdef\fR, or \fB#ifndef\fR directive and a matching \fB#else\fR or \fB#endif\fR directive. The lines following the \fB#elif\fR directive appear in the output only if all of the following conditions hold: 
.RS +4
.TP
.ie t \(bu
.el o
The \fIconstant-expression\fR in the preceding \fB#if\fR directive evaluated to zero, the \fIname\fR in the preceding \fB#ifdef\fR is not defined, or the \fIname\fR in the preceding \fB#ifndef\fR directive \fIwas\fR defined.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fIconstant-expression\fR in all intervening \fB#elif\fR directives evaluated to zero.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The current \fIconstant-expression\fR evaluates to non-zero.
.RE
If the \fIconstant-expression\fR evaluates to non-zero, subsequent \fB#elif\fR and \fB#else\fR directives are ignored up to the matching \fB#endif\fR. Any \fIconstant-expression\fR allowed in an \fB#if\fR directive is allowed in an \fB#elif\fR directive.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#else\fR\fR
.ad
.sp .6
.RS 4n
This inverts the sense of the conditional directive otherwise in effect.  If the preceding conditional would indicate that lines are to be included, then lines between the  \fB#else\fR and the matching \fB#endif\fR are ignored.  If the preceding conditional indicates that lines would be ignored, subsequent lines are included in the output. Conditional directives and corresponding \fB#else\fR directives can be nested.
.RE

.sp
.ne 2
.mk
.na
\fB\fB#endif\fR\fR
.ad
.sp .6
.RS 4n
End a section of lines begun by one of the conditional directives \fB#if\fR, \fB#ifdef\fR, or \fB#ifndef\fR. Each such directive must have a matching \fB#endif\fR.
.RE

.SS "Macros"
.sp
.LP
Formal parameters for macros are recognized in  \fB#define\fR directive bodies, even when they occur inside character constants and quoted strings. For instance, the output from:
.sp
.in +2
.nf
#define abc(a)|`|a|
abc(xyz) 
.fi
.in -2
.sp

.sp
.LP
is:
.sp
.in +2
.nf
# 1 ""
|`|xyz |
.fi
.in -2
.sp

.sp
.LP
The second line is a  NEWLINE. The last seven characters are \fB|`|xyz|\fR (vertical-bar, back quote, vertical-bar, x, y, z, vertical-bar). Macro names are not recognized within character constants or quoted strings during the regular scan. Thus:
.sp
.in +2
.nf
#define abc xyz
printf("abc");
.fi
.in -2
.sp

.sp
.LP
does not expand \fBabc\fR in the second line, since it is inside a quoted string that is not part of a  \fB#define\fR macro definition.
.sp
.LP
Macros are not expanded while processing a  \fB#define\fR or \fB#undef\fR. Thus:
.sp
.in +2
.nf
#define abc zingo
#define xyz abc
#undef abc
xyz
.fi
.in -2
.sp

.sp
.LP
produces \fBabc\fR. The token appearing immediately after an \fB#ifdef\fR or \fB#ifndef\fR is not expanded.
.sp
.LP
Macros are not expanded during the scan which determines the actual parameters to another macro call. 
.sp
.in +2
.nf
#define reverse(first,second)second first
#define greeting hello
reverse(greeting,
#define greeting goodbye
)
.fi
.in -2
.sp

.sp
.LP
produces  
.sp
.in +2
.nf
#define hello goodbye  hello
.fi
.in -2
.sp

.SS "Output"
.sp
.LP
Output consists of a copy of the input file, with modifications, plus lines of the form:
.sp
.in +2
.nf
\fB#\fR\fIlineno\fR \fB"\fR \fIfilename\fR\fB"\fR \fB"\fR\fIlevel\fR\fB"\fR
.fi
.in -2
.sp

.sp
.LP
indicating the original source line number and filename of the following output line and whether this is the first such line after an include file has been entered (\fIlevel\fR=\fB1\fR), the first such line after an include file has been exited (\fIlevel\fR=\fB2\fR), or any other such line (\fIlevel\fR is empty).
.SS "Details"
.sp
.LP
This section contains usage details.
.SS "\fIDirectory Search Order\fR"
.sp
.LP
\fB#include\fR files are searched for in the following order:
.RS +4
.TP
1.
The directory of the file that contains the  \fB#include\fR request (that is,  \fB#include\fR is relative to the file being scanned when the request is made).
.RE
.RS +4
.TP
2.
The directories specified by \fB-I\fR options, in left-to-right order.
.RE
.RS +4
.TP
3.
The standard directory(s) (\fB/usr/include\fR on \fBUNIX\fR systems).
.RE
.SS "\fISpecial Names\fR"
.sp
.LP
Two special names are understood by \fBcpp\fR. The name \fB_ _LINE_ _\fR is defined as the current line number (a decimal integer) as known by \fBcpp\fR, and \fB_ _FILE_ _\fR is defined as the current filename (a C string) as known by \fBcpp\fR. They can be used anywhere (including in macros) just as any other defined name.
.SS "\fINewline Characters\fR"
.sp
.LP
A  NEWLINE character 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  \fB#define\fR statement to continue the definition onto the next line. The escaped NEWLINE is not included in the macro value.
.SS "\fIComments\fR"
.sp
.LP
Comments are removed (unless the \fB-C\fR option is used on the command line). Comments are also ignored, except that a comment terminates a token.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 12n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fBnon-zero\fR
.ad
.RS 12n
.rt  
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitydeveloper/build/make
.TE

.SH SEE ALSO
.sp
.LP
\fBm4\fR(1), \fBattributes\fR(5)
.SH DIAGNOSTICS
.sp
.LP
The error messages produced by \fBcpp\fR are intended to be self-explanatory.  The line number and filename where the error occurred are printed along with the diagnostic.
.SH NOTES
.sp
.LP
When NEWLINE characters were found in argument lists for macros to be expanded, some previous versions of \fBcpp\fR put out the NEWLINE characters as they were found and expanded. The current version of \fBcpp\fR replaces them with  SPACE characters.
.sp
.LP
Because the standard directory for included files may be different in different environments, this form of \fB#include\fR directive:
.sp
.in +2
.nf
\fB#include <file.h>\fR
.fi
.in -2

.sp
.LP
should be used, rather than one with an absolute path, like:
.sp
.in +2
.nf
\fB#include "/usr/include/file.h"\fR
.fi
.in -2

.sp
.LP
\fBcpp\fR warns about the use of the absolute pathname.
.sp
.LP
While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else.