675 lines
15 KiB
Plaintext
675 lines
15 KiB
Plaintext
.\" Copyright (c) 1991, 1992, 1993 Free Software Foundation \-*-Text-*-
|
|
.\" See section COPYING for conditions for redistribution
|
|
.TH cpp 1 "30apr1993" "GNU Tools" "GNU Tools"
|
|
.SH NAME
|
|
cccp, cpp \- The GNU C-Compatible Compiler Preprocessor.
|
|
.SH SYNOPSIS
|
|
.hy 0
|
|
.na
|
|
.TP
|
|
.B cccp
|
|
.RB "[\|" \-$ "\|]"
|
|
.RB "[\|" \-A \c
|
|
.I predicate\c
|
|
.RB [ (\c
|
|
.I value\c
|
|
.BR ) ]\|]
|
|
.RB "[\|" \-C "\|]"
|
|
.RB "[\|" \-D \c
|
|
.I name\c
|
|
.RB [ =\c
|
|
.I definition\c
|
|
\&]\|]
|
|
.RB "[\|" \-dD "\|]"
|
|
.RB "[\|" \-dM "\|]"
|
|
.RB "[\|" "\-I\ "\c
|
|
.I directory\c
|
|
\&\|]
|
|
.RB "[\|" \-H "\|]"
|
|
.RB "[\|" \-I\- "\|]"
|
|
.RB "[\|" "\-imacros\ "\c
|
|
.I file\c
|
|
\&\|]
|
|
.RB "[\|" "\-include\ "\c
|
|
.I file\c
|
|
\&\|]
|
|
.RB "[\|" "\-idirafter\ "\c
|
|
.I dir\c
|
|
\&\|]
|
|
.RB "[\|" "\-iprefix\ "\c
|
|
.I prefix\c
|
|
\&\|]
|
|
.RB "[\|" "\-iwithprefix\ "\c
|
|
.I dir\c
|
|
\&\|]
|
|
.RB "[\|" \-lang\-c "\|]"
|
|
.RB "[\|" \-lang\-c++ "\|]"
|
|
.RB "[\|" \-lang\-objc "\|]"
|
|
.RB "[\|" \-lang\-objc++ "\|]"
|
|
.RB "[\|" \-lint "\|]"
|
|
.RB "[\|" \-M\ [ \-MG "\|]]"
|
|
.RB "[\|" \-MM\ [ \-MG "\|]]"
|
|
.RB "[\|" \-MD\ \c
|
|
.I file\ \c
|
|
\&\|]
|
|
.RB "[\|" \-MMD\ \c
|
|
.I file\ \c
|
|
\&\|]
|
|
.RB "[\|" \-nostdinc "\|]"
|
|
.RB "[\|" \-nostdinc++ "\|]"
|
|
.RB "[\|" \-P "\|]"
|
|
.RB "[\|" \-pedantic "\|]"
|
|
.RB "[\|" \-pedantic\-errors "\|]"
|
|
.RB "[\|" \-traditional "\|]"
|
|
.RB "[\|" \-trigraphs "\|]"
|
|
.RB "[\|" \-U \c
|
|
.I name\c
|
|
\&\|]
|
|
.RB "[\|" \-undef "\|]"
|
|
.RB "[\|" \-Wtrigraphs "\|]"
|
|
.RB "[\|" \-Wcomment "\|]"
|
|
.RB "[\|" \-Wall "\|]"
|
|
.RB "[\|" \-Wtraditional "\|]"
|
|
.br
|
|
.RB "[\|" \c
|
|
.I infile\c
|
|
.RB | \- "\|]"
|
|
.RB "[\|" \c
|
|
.I outfile\c
|
|
.RB | \- "\|]"
|
|
.ad b
|
|
.hy 1
|
|
.SH DESCRIPTION
|
|
The C preprocessor is a \c
|
|
.I macro processor\c
|
|
\& that is used automatically by
|
|
the C compiler to transform your program before actual compilation. It is
|
|
called a macro processor because it allows you to define \c
|
|
.I macros\c
|
|
\&,
|
|
which are brief abbreviations for longer constructs.
|
|
|
|
The C preprocessor provides four separate facilities that you can use as
|
|
you see fit:
|
|
.TP
|
|
\(bu
|
|
Inclusion of header files. These are files of declarations that can be
|
|
substituted into your program.
|
|
.TP
|
|
\(bu
|
|
Macro expansion. You can define \c
|
|
.I macros\c
|
|
\&, which are abbreviations
|
|
for arbitrary fragments of C code, and then the C preprocessor will
|
|
replace the macros with their definitions throughout the program.
|
|
.TP
|
|
\(bu
|
|
Conditional compilation. Using special preprocessing directives, you
|
|
can include or exclude parts of the program according to various
|
|
conditions.
|
|
.TP
|
|
\(bu
|
|
Line control. If you use a program to combine or rearrange source files into
|
|
an intermediate file which is then compiled, you can use line control
|
|
to inform the compiler of where each source line originally came from.
|
|
.PP
|
|
C preprocessors vary in some details. For a full explanation of the
|
|
GNU C preprocessor, see the
|
|
.B info
|
|
file `\|\c
|
|
.B cpp.info\c
|
|
\&\|', or the manual
|
|
.I The C Preprocessor\c
|
|
\&. Both of these are built from the same documentation source file, `\|\c
|
|
.B cpp.texinfo\c
|
|
\&\|'. The GNU C
|
|
preprocessor provides a superset of the features of ANSI Standard C.
|
|
|
|
ANSI Standard C requires the rejection of many harmless constructs commonly
|
|
used by today's C programs. Such incompatibility would be inconvenient for
|
|
users, so the GNU C preprocessor is configured to accept these constructs
|
|
by default. Strictly speaking, to get ANSI Standard C, you must use the
|
|
options `\|\c
|
|
.B \-trigraphs\c
|
|
\&\|', `\|\c
|
|
.B \-undef\c
|
|
\&\|' and `\|\c
|
|
.B \-pedantic\c
|
|
\&\|', but in
|
|
practice the consequences of having strict ANSI Standard C make it
|
|
undesirable to do this.
|
|
|
|
Most often when you use the C preprocessor you will not have to invoke it
|
|
explicitly: the C compiler will do so automatically. However, the
|
|
preprocessor is sometimes useful individually.
|
|
|
|
When you call the preprocessor individually, either name
|
|
(\c
|
|
.B cpp\c
|
|
\& or \c
|
|
.B cccp\c
|
|
\&) will do\(em\&they are completely synonymous.
|
|
|
|
The C preprocessor expects two file names as arguments, \c
|
|
.I infile\c
|
|
\& and
|
|
\c
|
|
.I outfile\c
|
|
\&. The preprocessor reads \c
|
|
.I infile\c
|
|
\& together with any other
|
|
files it specifies with `\|\c
|
|
.B #include\c
|
|
\&\|'. All the output generated by the
|
|
combined input files is written in \c
|
|
.I outfile\c
|
|
\&.
|
|
|
|
Either \c
|
|
.I infile\c
|
|
\& or \c
|
|
.I outfile\c
|
|
\& may be `\|\c
|
|
.B \-\c
|
|
\&\|', which as \c
|
|
.I infile\c
|
|
\&
|
|
means to read from standard input and as \c
|
|
.I outfile\c
|
|
\& means to write to
|
|
standard output. Also, if \c
|
|
.I outfile\c
|
|
\& or both file names are omitted,
|
|
the standard output and standard input are used for the omitted file names.
|
|
.SH OPTIONS
|
|
Here is a table of command options accepted by the C preprocessor.
|
|
These options can also be given when compiling a C program; they are
|
|
passed along automatically to the preprocessor when it is invoked by
|
|
the compiler.
|
|
.TP
|
|
.B \-P
|
|
Inhibit generation of `\|\c
|
|
.B #\c
|
|
\&\|'-lines with line-number information in
|
|
the output from the preprocessor. This might be
|
|
useful when running the preprocessor on something that is not C code
|
|
and will be sent to a program which might be confused by the
|
|
`\|\c
|
|
.B #\c
|
|
\&\|'-lines.
|
|
.TP
|
|
.B \-C
|
|
Do not discard comments: pass them through to the output file.
|
|
Comments appearing in arguments of a macro call will be copied to the
|
|
output before the expansion of the macro call.
|
|
.TP
|
|
.B \-traditional
|
|
Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
|
|
.TP
|
|
.B \-trigraphs
|
|
Process ANSI standard trigraph sequences. These are three-character
|
|
sequences, all starting with `\|\c
|
|
.B ??\c
|
|
\&\|', that are defined by ANSI C to
|
|
stand for single characters. For example, `\|\c
|
|
.B ??/\c
|
|
\&\|' stands for
|
|
`\|\c
|
|
.BR "\e" "\|',"
|
|
so `\|\c
|
|
.B '??/n'\c
|
|
\&\|' is a character constant for a newline.
|
|
Strictly speaking, the GNU C preprocessor does not support all
|
|
programs in ANSI Standard C unless `\|\c
|
|
.B \-trigraphs\c
|
|
\&\|' is used, but if
|
|
you ever notice the difference it will be with relief.
|
|
|
|
You don't want to know any more about trigraphs.
|
|
.TP
|
|
.B \-pedantic
|
|
Issue warnings required by the ANSI C standard in certain cases such
|
|
as when text other than a comment follows `\|\c
|
|
.B #else\c
|
|
\&\|' or `\|\c
|
|
.B #endif\c
|
|
\&\|'.
|
|
.TP
|
|
.B \-pedantic\-errors
|
|
Like `\|\c
|
|
.B \-pedantic\c
|
|
\&\|', except that errors are produced rather than
|
|
warnings.
|
|
.TP
|
|
.B \-Wtrigraphs
|
|
Warn if any trigraphs are encountered (assuming they are enabled).
|
|
.TP
|
|
.B \-Wcomment
|
|
.TP
|
|
.B \-Wcomments
|
|
Warn whenever a comment-start sequence `\|\c
|
|
.B /*\c
|
|
\&\|' appears in a comment.
|
|
(Both forms have the same effect).
|
|
.TP
|
|
.B \-Wall
|
|
Requests both `\|\c
|
|
.B \-Wtrigraphs\c
|
|
\&\|' and `\|\c
|
|
.B \-Wcomment\c
|
|
\&\|' (but not
|
|
`\|\c
|
|
.B \-Wtraditional\c
|
|
\&\|').
|
|
.TP
|
|
.B \-Wtraditional
|
|
Warn about certain constructs that behave differently in traditional and
|
|
ANSI C.
|
|
.TP
|
|
.BI "\-I " directory\c
|
|
\&
|
|
Add the directory \c
|
|
.I directory\c
|
|
\& to the end of the list of
|
|
directories to be searched for header files.
|
|
This can be used to override a system header file, substituting your
|
|
own version, since these directories are searched before the system
|
|
header file directories. If you use more than one `\|\c
|
|
.B \-I\c
|
|
\&\|' option,
|
|
the directories are scanned in left-to-right order; the standard
|
|
system directories come after.
|
|
.TP
|
|
.B \-I\-
|
|
Any directories specified with `\|\c
|
|
.B \-I\c
|
|
\&\|' options before the `\|\c
|
|
.B \-I\-\c
|
|
\&\|'
|
|
option are searched only for the case of `\|\c
|
|
.B #include "\c
|
|
.I file\c
|
|
\&"\c
|
|
\&\|';
|
|
they are not searched for `\|\c
|
|
.B #include <\c
|
|
.I file\c
|
|
\&>\c
|
|
\&\|'.
|
|
|
|
If additional directories are specified with `\|\c
|
|
.B \-I\c
|
|
\&\|' options after
|
|
the `\|\c
|
|
.B \-I\-\c
|
|
\&\|', these directories are searched for all `\|\c
|
|
.B #include\c
|
|
\&\|'
|
|
directives.
|
|
|
|
In addition, the `\|\c
|
|
.B \-I\-\c
|
|
\&\|' option inhibits the use of the current
|
|
directory as the first search directory for `\|\c
|
|
.B #include "\c
|
|
.I file\c
|
|
\&"\c
|
|
\&\|'.
|
|
Therefore, the current directory is searched only if it is requested
|
|
explicitly with `\|\c
|
|
.B \-I.\c
|
|
\&\|'. Specifying both `\|\c
|
|
.B \-I\-\c
|
|
\&\|' and `\|\c
|
|
.B \-I.\c
|
|
\&\|'
|
|
allows you to control precisely which directories are searched before
|
|
the current one and which are searched after.
|
|
.TP
|
|
.B \-nostdinc
|
|
Do not search the standard system directories for header files.
|
|
Only the directories you have specified with `\|\c
|
|
.B \-I\c
|
|
\&\|' options
|
|
(and the current directory, if appropriate) are searched.
|
|
.TP
|
|
.B \-nostdinc++
|
|
Do not search for header files in the C++ specific standard
|
|
directories, but do still search the other standard directories.
|
|
(This option is used when building libg++.)
|
|
.TP
|
|
.BI "\-D " "name"\c
|
|
\&
|
|
Predefine \c
|
|
.I name\c
|
|
\& as a macro, with definition `\|\c
|
|
.B 1\c
|
|
\&\|'.
|
|
.TP
|
|
.BI "\-D " "name" = definition
|
|
\&
|
|
Predefine \c
|
|
.I name\c
|
|
\& as a macro, with definition \c
|
|
.I definition\c
|
|
\&.
|
|
There are no restrictions on the contents of \c
|
|
.I definition\c
|
|
\&, but if
|
|
you are invoking the preprocessor from a shell or shell-like program
|
|
you may need to use the shell's quoting syntax to protect characters
|
|
such as spaces that have a meaning in the shell syntax. If you use more than
|
|
one `\|\c
|
|
.B \-D\c
|
|
\&\|' for the same
|
|
.I name\c
|
|
\&, the rightmost definition takes effect.
|
|
.TP
|
|
.BI "\-U " "name"\c
|
|
\&
|
|
Do not predefine \c
|
|
.I name\c
|
|
\&. If both `\|\c
|
|
.B \-U\c
|
|
\&\|' and `\|\c
|
|
.B \-D\c
|
|
\&\|' are
|
|
specified for one name, the `\|\c
|
|
.B \-U\c
|
|
\&\|' beats the `\|\c
|
|
.B \-D\c
|
|
\&\|' and the name
|
|
is not predefined.
|
|
.TP
|
|
.B \-undef
|
|
Do not predefine any nonstandard macros.
|
|
.TP
|
|
.BI "\-A " "name(" value )
|
|
Assert (in the same way as the \c
|
|
.B #assert\c
|
|
\& directive)
|
|
the predicate \c
|
|
.I name\c
|
|
\& with tokenlist \c
|
|
.I value\c
|
|
\&. Remember to escape or quote the parentheses on
|
|
shell command lines.
|
|
|
|
You can use `\|\c
|
|
.B \-A-\c
|
|
\&\|' to disable all predefined assertions; it also
|
|
undefines all predefined macros.
|
|
.TP
|
|
.B \-dM
|
|
Instead of outputting the result of preprocessing, output a list of
|
|
`\|\c
|
|
.B #define\c
|
|
\&\|' directives for all the macros defined during the
|
|
execution of the preprocessor, including predefined macros. This gives
|
|
you a way of finding out what is predefined in your version of the
|
|
preprocessor; assuming you have no file `\|\c
|
|
.B foo.h\c
|
|
\&\|', the command
|
|
.sp
|
|
.br
|
|
touch\ foo.h;\ cpp\ \-dM\ foo.h
|
|
.br
|
|
.sp
|
|
will show the values of any predefined macros.
|
|
.TP
|
|
.B \-dD
|
|
Like `\|\c
|
|
.B \-dM\c
|
|
\&\|' except in two respects: it does \c
|
|
.I not\c
|
|
\& include the
|
|
predefined macros, and it outputs \c
|
|
.I both\c
|
|
\& the `\|\c
|
|
.B #define\c
|
|
\&\|'
|
|
directives and the result of preprocessing. Both kinds of output go to
|
|
the standard output file.
|
|
.PP
|
|
.TP
|
|
.BR \-M\ [ \-MG ]
|
|
Instead of outputting the result of preprocessing, output a rule
|
|
suitable for \c
|
|
.B make\c
|
|
\& describing the dependencies of the main
|
|
source file. The preprocessor outputs one \c
|
|
.B make\c
|
|
\& rule containing
|
|
the object file name for that source file, a colon, and the names of
|
|
all the included files. If there are many included files then the
|
|
rule is split into several lines using `\|\c
|
|
.B \\\\\c
|
|
\&\|'-newline.
|
|
|
|
`\|\c
|
|
.B \-MG\c
|
|
\&\|' says to treat missing header files as generated files and assume \c
|
|
they live in the same directory as the source file. It must be specified \c
|
|
in addition to `\|\c
|
|
.B \-M\c
|
|
\&\|'.
|
|
|
|
This feature is used in automatic updating of makefiles.
|
|
.TP
|
|
.BR \-MM\ [ \-MG ]
|
|
Like `\|\c
|
|
.B \-M\c
|
|
\&\|' but mention only the files included with `\|\c
|
|
.B #include
|
|
"\c
|
|
.I file\c
|
|
\&"\c
|
|
\&\|'. System header files included with `\|\c
|
|
.B #include
|
|
<\c
|
|
.I file\c
|
|
\&>\c
|
|
\&\|' are omitted.
|
|
.TP
|
|
.BI \-MD\ file
|
|
Like `\|\c
|
|
.B \-M\c
|
|
\&\|' but the dependency information is written to `\|\c
|
|
.I file\c
|
|
\&\|'. This is in addition to compiling the file as
|
|
specified\(em\&`\|\c
|
|
.B \-MD\c
|
|
\&\|' does not inhibit ordinary compilation the way
|
|
`\|\c
|
|
.B \-M\c
|
|
\&\|' does.
|
|
|
|
When invoking gcc, do not specify the `\|\c
|
|
.I file\c
|
|
\&\|' argument. Gcc will create file names made by replacing `\|\c
|
|
.B .c\c
|
|
\&\|' with `\|\c
|
|
.B .d\c
|
|
\&\|' at the end of the input file names.
|
|
|
|
In Mach, you can use the utility \c
|
|
.B md\c
|
|
\& to merge multiple files
|
|
into a single dependency file suitable for using with the `\|\c
|
|
.B make\c
|
|
\&\|'
|
|
command.
|
|
.TP
|
|
.BI \-MMD\ file
|
|
Like `\|\c
|
|
.B \-MD\c
|
|
\&\|' except mention only user header files, not system
|
|
header files.
|
|
.TP
|
|
.B \-H
|
|
Print the name of each header file used, in addition to other normal
|
|
activities.
|
|
.TP
|
|
.BI "\-imacros " "file"\c
|
|
\&
|
|
Process \c
|
|
.I file\c
|
|
\& as input, discarding the resulting output, before
|
|
processing the regular input file. Because the output generated from
|
|
\c
|
|
.I file\c
|
|
\& is discarded, the only effect of `\|\c
|
|
.B \-imacros \c
|
|
.I file\c
|
|
\&\c
|
|
\&\|' is to
|
|
make the macros defined in \c
|
|
.I file\c
|
|
\& available for use in the main
|
|
input. The preprocessor evaluates any `\|\c
|
|
.B \-D\c
|
|
\&\|' and `\|\c
|
|
.B \-U\c
|
|
\&\|' options
|
|
on the command line before processing `\|\c
|
|
.B \-imacros \c
|
|
.I file\c
|
|
\&\|' \c
|
|
\&.
|
|
.TP
|
|
.BI "\-include " "file"
|
|
Process
|
|
.I file
|
|
as input, and include all the resulting output,
|
|
before processing the regular input file.
|
|
.TP
|
|
.BI "-idirafter " "dir"\c
|
|
\&
|
|
Add the directory \c
|
|
.I dir\c
|
|
\& to the second include path. The directories
|
|
on the second include path are searched when a header file is not found
|
|
in any of the directories in the main include path (the one that
|
|
`\|\c
|
|
.B \-I\c
|
|
\&\|' adds to).
|
|
.TP
|
|
.BI "-iprefix " "prefix"\c
|
|
\&
|
|
Specify \c
|
|
.I prefix\c
|
|
\& as the prefix for subsequent `\|\c
|
|
.B \-iwithprefix\c
|
|
\&\|'
|
|
options.
|
|
.TP
|
|
.BI "-iwithprefix " "dir"\c
|
|
\&
|
|
Add a directory to the second include path. The directory's name is
|
|
made by concatenating \c
|
|
.I prefix\c
|
|
\& and \c
|
|
.I dir\c
|
|
\&, where \c
|
|
.I prefix\c
|
|
\&
|
|
was specified previously with `\|\c
|
|
.B \-iprefix\c
|
|
\&\|'.
|
|
.TP
|
|
.B \-lang-c
|
|
.TP
|
|
.B \-lang-c++
|
|
.TP
|
|
.B \-lang-objc
|
|
.TP
|
|
.B \-lang-objc++
|
|
Specify the source language. `\|\c
|
|
.B \-lang-c++\c
|
|
\&\|' makes the preprocessor
|
|
handle C++ comment syntax, and includes extra default include
|
|
directories for C++, and `\|\c
|
|
.B \-lang-objc\c
|
|
\&\|' enables the Objective C
|
|
`\|\c
|
|
.B #import\c
|
|
\&\|' directive. `\|\c
|
|
.B \-lang-c\c
|
|
\&\|' explicitly turns off both of
|
|
these extensions, and `\|\c
|
|
.B \-lang-objc++\c
|
|
\&\|' enables both.
|
|
|
|
These options are generated by the compiler driver \c
|
|
.B gcc\c
|
|
\&, but not
|
|
passed from the `\|\c
|
|
.B gcc\c
|
|
\&\|' command line.
|
|
.TP
|
|
.B \-lint
|
|
Look for commands to the program checker \c
|
|
.B lint\c
|
|
\& embedded in
|
|
comments, and emit them preceded by `\|\c
|
|
.B #pragma lint\c
|
|
\&\|'. For example,
|
|
the comment `\|\c
|
|
.B /* NOTREACHED */\c
|
|
\&\|' becomes `\|\c
|
|
.B #pragma lint
|
|
NOTREACHED\c
|
|
\&\|'.
|
|
|
|
This option is available only when you call \c
|
|
.B cpp\c
|
|
\& directly;
|
|
\c
|
|
.B gcc\c
|
|
\& will not pass it from its command line.
|
|
.TP
|
|
.B \-$
|
|
Forbid the use of `\|\c
|
|
.B $\c
|
|
\&\|' in identifiers. This was formerly required for strict conformance
|
|
to the C Standard before the standard was corrected. \c
|
|
|
|
This option is available only when you call \c
|
|
.B cpp\c
|
|
\& directly;
|
|
.B gcc\c
|
|
\& will not pass it from its command line.
|
|
.SH "SEE ALSO"
|
|
.RB "`\|" Cpp "\|'"
|
|
entry in
|
|
.B info\c
|
|
\&;
|
|
.I The C Preprocessor\c
|
|
, Richard M. Stallman.
|
|
.br
|
|
.BR gcc "(" 1 ");"
|
|
.RB "`\|" Gcc "\|'"
|
|
entry in
|
|
.B info\c
|
|
\&;
|
|
.I
|
|
Using and Porting GNU CC (for version 2.0)\c
|
|
, Richard M. Stallman.
|
|
.SH COPYING
|
|
Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
.PP
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
.PP
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
.PP
|
|
Permission is granted to copy and distribute translations of this
|
|
manual into another language, under the above conditions for modified
|
|
versions, except that this permission notice may be included in
|
|
translations approved by the Free Software Foundation instead of in
|
|
the original English.
|