diff options
Diffstat (limited to 'gcc/cpp.1')
| -rw-r--r-- | gcc/cpp.1 | 338 |
1 files changed, 197 insertions, 141 deletions
@@ -73,7 +73,7 @@ .ds T' ' .ds PI \(*p 'br\} -.TH CPP 1 "gcc-2.95" "14/Jun/99" "GNU" +.TH CPP 1 "gcc-3.0" "1/Aug/2000" "GNU" .UC .if n .hy 0 .if n .na @@ -181,13 +181,20 @@ cpp [\fB\-P\fR] [\fB\-C\fR] [\fB\-gcc\fR] [\fB\-traditional\fR] .PP Only the most useful options are listed here; see below for the remainder. .SH "DESCRIPTION" -The C preprocessor is a \fImacro processor\fR 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 \fImacros\fR, -which are brief abbreviations for longer constructs. +The C preprocessor is a \fImacro processor\fR 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 +\fImacros\fR, which are brief abbreviations for longer constructs. .PP -The C preprocessor provides four separate facilities that you can use as -you see fit: +The C preprocessor is intended only for macro processing of C, \*(C+ and +Objective C source files. For macro processing of other files, you are +strongly encouraged to use alternatives like M4, which will likely give +you better results and avoid many problems. For example, normally the C +preprocessor does not preserve arbitrary whitespace verbatim, but +instead replaces each sequence with a single space. +.PP +For use on C\-like source files, the C preprocessor provides four +separate facilities that you can use as you see fit: .Ip "\(bu" 4 Inclusion of header files. These are files of declarations that can be substituted into your program. @@ -200,32 +207,27 @@ Conditional compilation. Using special preprocessing directives, you can include or exclude parts of the program according to various conditions. .Ip "\(bu" 4 -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. +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. This manual discusses the \s-1GNU\s0 C -preprocessor, the C Compatible Compiler Preprocessor. The \s-1GNU\s0 C -preprocessor provides a superset of the features of \s-1ANSI\s0 Standard C. -.PP -\s-1ANSI\s0 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 \s-1GNU\s0 C preprocessor is configured to accept these constructs -by default. Strictly speaking, to get \s-1ANSI\s0 Standard C, you must use the -options \fB\-trigraphs\fR, \fB\-undef\fR and \fB\-pedantic\fR, but in -practice the consequences of having strict \s-1ANSI\s0 Standard C make it -undesirable to do this. +preprocessor, which provides a small superset of the features of \s-1ISO\s0 +Standard C. .PP -The C preprocessor is designed for C\-like languages; you may run into -problems if you apply it to other kinds of languages, because it assumes -that it is dealing with C. For example, the C preprocessor sometimes -outputs extra white space to avoid inadvertent C token concatenation, -and this may cause problems with other languages. +In its default mode, the \s-1GNU\s0 C preprocessor does not do a few things +required by the standard. These are features which are rarely, if ever, +used, and may cause surprising changes to the meaning of a program which +does not expect them. To get strict \s-1ISO\s0 Standard C, you should use the +\fB\-std=c89\fR or \fB\-std=c99\fR options, depending on which version +of the standard you want. To get all the mandatory diagnostics, you +must also use \fB\-pedantic\fR. .SH "OPTIONS" The C preprocessor expects two file names as arguments, \fIinfile\fR and -\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any other -files it specifies with \fB#include\fR. All the output generated by the -combined input files is written in \fIoutfile\fR. +\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any +other files it specifies with \fB#include\fR. All the output generated +by the combined input files is written in \fIoutfile\fR. .PP Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as \fIinfile\fR means to read from standard input and as \fIoutfile\fR @@ -237,61 +239,69 @@ 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. .Ip "\fB\-P\fR" 4 -Inhibit generation of \fB#\fR\-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 -\fB#\fR\-lines. +Inhibit generation of \fB#\fR\-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 \fB#\fR\-lines. .Ip "\fB\-C\fR" 4 -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. +Do not discard comments. All comments are passed through to the output +file, except for comments in processed directives, which are deleted +along with the directive. Comments appearing in the expansion list of a +macro will be preserved, and appear in place wherever the macro is +invoked. +.Sp +You should be prepared for side effects when using \fB\-C\fR; it causes +the preprocessor to treat comments as tokens in their own right. For +example, macro redefinitions that were trivial when comments were +replaced by a single space might become significant when comments are +retained. Also, comments appearing at the start of what would be a +directive line have the effect of turning that line into an ordinary +source line, since the first token on the line is no longer a \fB#\fR. .Ip "\fB\-traditional\fR" 4 -Try to imitate the behavior of old-fashioned C, as opposed to \s-1ANSI\s0 C. -.Ip "\(bu" 8 -Traditional macro expansion pays no attention to singlequote or -doublequote characters; macro argument symbols are replaced by the +Try to imitate the behavior of old-fashioned C, as opposed to \s-1ISO\s0 C. +.RS 4 +.Ip "\(bu" 4 +Traditional macro expansion pays no attention to single-quote or +double-quote characters; macro argument symbols are replaced by the argument values even when they appear within apparent string or character constants. -.Ip "\(bu" 8 +.Ip "\(bu" 4 Traditionally, it is permissible for a macro expansion to end in the middle of a string or character constant. The constant continues into the text surrounding the macro call. -.Ip "\(bu" 8 +.Ip "\(bu" 4 However, traditionally the end of the line terminates a string or character constant, with no error. -.Ip "\(bu" 8 -In traditional C, a comment is equivalent to no text at all. (In \s-1ANSI\s0 +.Ip "\(bu" 4 +In traditional C, a comment is equivalent to no text at all. (In \s-1ISO\s0 C, a comment counts as whitespace.) -.Ip "\(bu" 8 +.Ip "\(bu" 4 Traditional C does not have the concept of a ``preprocessing number'\*(R'. It considers \fB1.0e+4\fR to be three tokens: \fB1.0e\fR, \fB+\fR, and \fB4\fR. -.Ip "\(bu" 8 +.Ip "\(bu" 4 A macro is not suppressed within its own definition, in traditional C. Thus, any macro that is used recursively inevitably causes an error. -.Ip "\(bu" 8 +.Ip "\(bu" 4 The character \fB#\fR has no special meaning within a macro definition in traditional C. -.Ip "\(bu" 8 +.Ip "\(bu" 4 In traditional C, the text at the end of a macro expansion can run together with the text after the macro call, to produce a single token. -(This is impossible in \s-1ANSI\s0 C.) -.Ip "\(bu" 8 -Traditionally, \fB\e\fR inside a macro argument suppresses the syntactic -significance of the following character. -.Sp -Use the \fB\-traditional\fR option when preprocessing Fortran code, -so that singlequotes and doublequotes -within Fortran comment lines -(which are generally not recognized as such by the preprocessor) -do not cause diagnostics -about unterminated character or string constants. +(This is impossible in \s-1ISO\s0 C.) +.Ip "\(bu" 4 +None of the \s-1GNU\s0 extensions to the preprocessor are available in +\fB\-traditional\fR mode. +.RE +.Ip "" 4 +Use the \fB\-traditional\fR option when preprocessing Fortran code, so +that single-quotes and double-quotes within Fortran comment lines (which +are generally not recognized as such by the preprocessor) do not cause +diagnostics about unterminated character or string constants. .Sp -However, this option does not prevent diagnostics -about unterminated comments -when a C\-style comment appears to start, but not end, -within Fortran-style commentary. +However, this option does not prevent diagnostics about unterminated +comments when a C\-style comment appears to start, but not end, within +Fortran-style commentary. .Sp So, the following Fortran comment lines are accepted with \fB\-traditional\fR: @@ -301,49 +311,77 @@ So, the following Fortran comment lines are accepted with \& C Neither is "20000000000, an octal constant \& C in some dialects of Fortran .Ve -However, this type of comment line will likely produce a diagnostic, -or at least unexpected output from the preprocessor, -due to the unterminated comment: +However, this type of comment line will likely produce a diagnostic, or +at least unexpected output from the preprocessor, due to the +unterminated comment: .Sp .Vb 2 \& C Some Fortran compilers accept /* as starting \& C an inline comment. .Ve -Note that \f(CWg77\fR automatically supplies -the \fB\-traditional\fR option -when it invokes the preprocessor. -However, a future version of \f(CWg77\fR -might use a different, more-Fortran-aware preprocessor -in place of \f(CWcpp\fR. +Note that \f(CWg77\fR automatically supplies the \fB\-traditional\fR +option when it invokes the preprocessor. However, a future version of +\f(CWg77\fR might use a different, more-Fortran-aware preprocessor in +place of \f(CWcpp\fR. .Ip "\fB\-trigraphs\fR" 4 -Process \s-1ANSI\s0 standard trigraph sequences. These are three-character -sequences, all starting with \fB??\fR, that are defined by \s-1ANSI\s0 C to +Process \s-1ISO\s0 standard trigraph sequences. These are three-character +sequences, all starting with \fB??\fR, that are defined by \s-1ISO\s0 C to stand for single characters. For example, \fB??/\fR stands for -\fB\e\fR, so \fB\*(R'??/n\*(R'\fR is a character constant for a newline. -Strictly speaking, the \s-1GNU\s0 C preprocessor does not support all -programs in \s-1ANSI\s0 Standard C unless \fB\-trigraphs\fR is used, but if -you ever notice the difference it will be with relief. +\fB\e\fR, so \fB\*(R'??/n\*(R'\fR is a character constant for a newline. By +default, \s-1GCC\s0 ignores trigraphs, but in standard-conforming modes it +converts them. See the \fB\-std\fR option. .Sp -You don't want to know any more about trigraphs. +The nine trigraph sequences are +.RS 4 +.PD 0 +.SP +.Ip "\fB??(\fR" 6 +-> \fB[\fR +.Ip "\fB??)\fR" 6 +-> \fB]\fR +.Ip "\fB??<\fR" 6 +-> \fB@{\fR +.Ip "\fB??>\fR" 6 +-> \fB@\fR} +.Ip "\fB??=\fR" 6 +-> \fB#\fR +.Ip "\fB??/\fR" 6 +-> \fB\e\fR +.Ip "\fB??\*(T'\fR" 6 +-> \fB^\fR +.Ip "\fB??!\fR" 6 +-> \fB|\fR +.Ip "\fB??\-\fR" 6 +-> \fB~\fR +.RE +.PD +.Ip "" 4 +Trigraph support is not popular, so many compilers do not implement it +properly. Portable code should not rely on trigraphs being either +converted or ignored. .Ip "\fB\-pedantic\fR" 4 -Issue warnings required by the \s-1ANSI\s0 C standard in certain cases such +Issue warnings required by the \s-1ISO\s0 C standard in certain cases such as when text other than a comment follows \fB#else\fR or \fB#endif\fR. .Ip "\fB\-pedantic-errors\fR" 4 Like \fB\-pedantic\fR, except that errors are produced rather than warnings. -.Ip "\fB\-Wtrigraphs\fR" 4 -Warn if any trigraphs are encountered. Currently this only works if you -have turned trigraphs on with \fB\-trigraphs\fR or \fB\-ansi\fR; in the -future this restriction will be removed. .Ip "\fB\-Wcomment\fR" 4 +.Ip "\fB\-Wcomments\fR" 4 +(Both forms have the same effect). Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR -comment, or whenever a Backslash-Newline appears in a \fB//\fR comment. +comment, or whenever a backslash-newline appears in a \fB//\fR comment. +.Ip "\fB\-Wtrigraphs\fR" 4 +Warn if any trigraphs are encountered. This option used to take effect +only if \fB\-trigraphs\fR was also specified, but now works independently. +.Ip "\fB\-Wwhite-space\fR" 4 +Warn about possible white space confusion, e.g. white space between a +backslash and a newline. .Ip "\fB\-Wall\fR" 4 -Requests both \fB\-Wtrigraphs\fR and \fB\-Wcomment\fR (but not -\fB\-Wtraditional\fR or \fB\-Wundef\fR). +Requests \fB\-Wcomment\fR, \fB\-Wtrigraphs\fR, and \fB\-Wwhite-space\fR +(but not \fB\-Wtraditional\fR or \fB\-Wundef\fR). .Ip "\fB\-Wtraditional\fR" 4 Warn about certain constructs that behave differently in traditional and -\s-1ANSI\s0 C. +\s-1ISO\s0 C. .Ip "\fB\-Wundef\fR" 4 Warn if an undefined identifier is evaluated in an \fB#if\fR directive. .Ip "\fB\-I \fIdirectory\fR\fR" 4 @@ -356,15 +394,15 @@ the directories are scanned in left-to-right order; the standard system directories come after. .Ip "\fB\-I-\fR" 4 Any directories specified with \fB\-I\fR options before the \fB\-I-\fR -option are searched only for the case of \fB#include \*(L"\fIfile\fB\*(R"\fR; -they are not searched for \fB#include <\fIfile\fB>\fR. +option are searched only for the case of \fB#include \*(L"\fIfile\fR\*(R"\fR; +they are not searched for \fB#include <\fIfile\fR>\fR. .Sp If additional directories are specified with \fB\-I\fR options after the \fB\-I-\fR, these directories are searched for all \fB#include\fR directives. .Sp In addition, the \fB\-I-\fR option inhibits the use of the current -directory as the first search directory for \fB#include \*(L"\fIfile\fB\*(R"\fR. +directory as the first search directory for \fB#include \*(L"\fIfile\fR\*(R"\fR. Therefore, the current directory is searched only if it is requested explicitly with \fB\-I.\fR. Specifying both \fB\-I-\fR and \fB\-I.\fR allows you to control precisely which directories are searched before @@ -375,8 +413,8 @@ Only the directories you have specified with \fB\-I\fR options (and the current directory, if appropriate) are searched. .Ip "\fB\-nostdinc++\fR" 4 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 the \*(C+ library.) +but do still search the other standard directories. (This option is +used when building the \*(C+ library.) .Ip "\fB\-remap\fR" 4 When searching for a header file in a directory, remap file names if a file named \fIheader.gcc\fR exists in that directory. This can be used @@ -402,15 +440,17 @@ wins. Do not predefine any nonstandard macros. .Ip "\fB\-gcc\fR" 4 Define the macros \fI_\|_GNUC_\|_\fR, \fI_\|_GNUC_MINOR_\|_\fR and -\fI_\|_GNUC_PATCHLEVEL_\|_\fR. These are defined automatically when you -use \fBgcc \-E\fR; you can turn them off in that case with \fB\-no-gcc\fR. +\fI_\|_GNUC_PATCHLEVEL_\|_\fR. These are defined automatically when you use +\fBgcc \-E\fR; you can turn them off in that case with \fB\-no-gcc\fR. .Ip "\fB\-A \fIpredicate\fR(\fIanswer\fR)\fR" 4 Make an assertion with the predicate \fIpredicate\fR and answer \fIanswer\fR. -.Sp -You can use \fB\-A-\fR to disable all predefined assertions; it also -undefines all predefined macros and all macros that preceded it on the -command line. +.Ip "\fB\-A \-\fIpredicate\fR(\fIanswer\fR)\fR" 4 +Disable an assertion with the predicate \fIpredicate\fR and answer +\fIanswer\fR. Specifying no predicate, by \fB\-A-\fR or \fB\-A \-\fR, +disables all predefined assertions and all assertions preceding it on +the command line; and also undefines all predefined macros and all +macros preceding it on the command line. .Ip "\fB\-dM\fR" 4 Instead of outputting the result of preprocessing, output a list of \fB#define\fR directives for all the macros defined during the @@ -427,19 +467,22 @@ Like \fB\-dM\fR except in two respects: it does \fInot\fR include the predefined macros, and it outputs \fIboth\fR the \fB#define\fR directives and the result of preprocessing. Both kinds of output go to the standard output file. +.Ip "\fB\-dN\fR" 4 +Like \fB\-dD\fR, but emit only the macro names, not their expansions. .Ip "\fB\-dI\fR" 4 -Output \fB#include\fR directives in addition to the result of preprocessing. +Output \fB#include\fR directives in addition to the result of +preprocessing. .Ip "\fB\-M [\-\s-1MG\s0]\fR" 4 Instead of outputting the result of preprocessing, output a rule -suitable for \f(CWmake\fR describing the dependencies of the main -source file. The preprocessor outputs one \f(CWmake\fR 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 \fB\e\fR\-newline. +suitable for \f(CWmake\fR describing the dependencies of the main source +file. The preprocessor outputs one \f(CWmake\fR 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 \fB\e\fR\-newline. .Sp -\fB\-\s-1MG\s0\fR says to treat missing header files as generated files and assume -they live in the same directory as the source file. It must be specified -in addition to \fB\-M\fR. +\fB\-\s-1MG\s0\fR says to treat missing header files as generated files and +assume they live in the same directory as the source file. It must be +specified in addition to \fB\-M\fR. .Sp This feature is used in automatic updating of makefiles. .Ip "\fB\-\s-1MM\s0 [\-\s-1MG\s0]\fR" 4 @@ -448,16 +491,16 @@ Like \fB\-M\fR but mention only the files included with \fB#include <\fIfile\fR>\fR are omitted. .Ip "\fB\-\s-1MD\s0 \fIfile\fR\fR" 4 Like \fB\-M\fR but the dependency information is written to \fIfile\fR. -This is in addition to compiling the file as specified---\fB\-\s-1MD\s0\fR does -not inhibit ordinary compilation the way \fB\-M\fR does. +This is in addition to compiling the file as specified --- \fB\-\s-1MD\s0\fR +does not inhibit ordinary compilation the way \fB\-M\fR does. .Sp When invoking \f(CWgcc\fR, do not specify the \fIfile\fR argument. \f(CWgcc\fR will create file names made by replacing \*(L".c\*(R" with \*(L".d\*(R" at the end of the input file names. .Sp In Mach, you can use the utility \f(CWmd\fR to merge multiple dependency -files into a single dependency file suitable for using with the \fBmake\fR -command. +files into a single dependency file suitable for using with the +\fBmake\fR command. .Ip "\fB\-\s-1MMD\s0 \fIfile\fR\fR" 4 Like \fB\-\s-1MD\s0\fR except mention only user header files, not system header files. @@ -480,15 +523,16 @@ in any of the directories in the main include path (the one that \fB\-I\fR adds to). .Ip "\fB\-iprefix \fIprefix\fR\fR" 4 Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR -options. +options. If the prefix represents a directory, you should include the +final \fB/\fR. .Ip "\fB\-iwithprefix \fIdir\fR\fR" 4 Add a directory to the second include path. The directory's name is -made by concatenating \fIprefix\fR and \fIdir\fR, where \fIprefix\fR -was specified previously with \fB\-iprefix\fR. +made by concatenating \fIprefix\fR and \fIdir\fR, where \fIprefix\fR was +specified previously with \fB\-iprefix\fR. .Ip "\fB\-isystem \fIdir\fR\fR" 4 Add a directory to the beginning of the second include path, marking it as a system directory, so that it gets the same special treatment as -is applied to the standard system directories. +is applied to the standard system directories. .Ip "\fB\-x c\fR" 4 .Ip "\fB\-x c++\fR" 4 .Ip "\fB\-x objective-c\fR" 4 @@ -514,39 +558,52 @@ added in the future. .Sp \fIstandard\fR may be one of: -.Ip "\f(CWiso9899:1990\fR" 8 -The \s-1ISO\s0 C standard from 1990. -.Ip "\f(CWiso9899:199409\fR" 8 -.Ip "\f(CWc89\fR" 8 -The 1990 C standard, as amended in 1994. \fBc89\fR is the customary -shorthand for this version of the standard. +.RS 4 +.PD 0 +.Sp +.Ip "\f(CWiso9899:1990\fR" 4 +.Ip "\f(CWc89\fR" 4 +.Ip +The \s-1ISO\s0 C standard from 1990. \fBc89\fR is the customary shorthand for +this version of the standard. .Sp The \fB\-ansi\fR option is equivalent to \fB\-std=c89\fR. -.Ip "\f(CWiso9899:199x\fR" 8 -.Ip "\f(CWc9x\fR" 8 -The revised \s-1ISO\s0 C standard, which is expected to be promulgated some -time in 1999. It has not been approved yet, hence the \fBx\fR. -.Ip "\f(CWgnu89\fR" 8 +.Sp +.Ip "\f(CWiso9899:199409\fR" 4 +The 1990 C standard, as amended in 1994. +.Sp +.Ip "\f(CWiso9899:1999\fR" 4 +.Ip "\f(CWc99\fR" 4 +.Ip "\f(CWiso9899:199x\fR" 4 +.Ip "\f(CWc9x\fR" 4 +.Ip +The revised \s-1ISO\s0 C standard, published in December 1999. Before +publication, this was known as C9X. +.Sp +.Ip "\f(CWgnu89\fR" 4 The 1990 C standard plus \s-1GNU\s0 extensions. This is the default. -.Ip "\f(CWgnu9x\fR" 8 -The 199x C standard plus \s-1GNU\s0 extensions. -.Ip "\fB\-Wp,\-lint\fR" 4 -Look for commands to the program checker \f(CWlint\fR embedded in -comments, and emit them preceded by \fB#pragma lint\fR. For example, -the comment \fB/* \s-1NOTREACHED\s0 */\fR becomes \fB#pragma lint -\s-1NOTREACHED\s0\fR. .Sp -Because of the clash with \fB\-l\fR, you must use the awkward syntax -above. In a future release, this option will be replaced by -\fB\-flint\fR or \fB\-Wlint\fR; we are not sure which yet. +.Ip "\f(CWgnu99\fR" 4 +.Ip "\f(CWgnu9x\fR" 4 +The 1999 C standard plus \s-1GNU\s0 extensions. +.PD +.RE +.Ip "\fB\-ftabstop=\s-1NUMBER\s0\fR" 4 +Set the distance between tabstops. This helps the preprocessor +report correct column numbers in warnings or errors, even if tabs appear +on the line. Values less than 1 or greater than 100 are ignored. The +default is 8. .Ip "\fB\-$\fR" 4 -Forbid the use of \fB$\fR in identifiers. The C standard does not -permit this, but it is a common extension. +Forbid the use of \fB$\fR in identifiers. The C standard allows +implementations to define extra characters that can appear in +identifiers. By default the \s-1GNU\s0 C preprocessor permits \fB$\fR, a +common extension. .SH "SEE ALSO" \fIgcc\fR\|(1), \fIas\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIcpp\fR, \fIgcc\fR, and \fIbinutils\fR. .SH "COPYRIGHT" -Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999 +Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of @@ -560,4 +617,3 @@ 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. -.rn }` '' |