diff options
Diffstat (limited to 'gcc/doc/cpp.1')
| -rw-r--r-- | gcc/doc/cpp.1 | 764 |
1 files changed, 764 insertions, 0 deletions
diff --git a/gcc/doc/cpp.1 b/gcc/doc/cpp.1 new file mode 100644 index 0000000..f3e227e --- /dev/null +++ b/gcc/doc/cpp.1 @@ -0,0 +1,764 @@ +.\" Automatically generated by Pod::Man version 1.1 +.\" Mon Feb 19 19:32:17 2001 +.\" +.\" Standard preamble: +.\" ====================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R + +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used +.\" to do unbreakable dashes and therefore won't be available. \*(C` and +.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr +.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and +.\" index entries marked with X<> in POD. Of course, you'll have to process +.\" the output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it +.\" makes way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +.bd B 3 +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ====================================================================== +.\" +.IX Title "CPP 1" +.TH CPP 1 "gcc-3.1" "2001-02-19" "GNU" +.UC +.SH "NAME" +cpp \- The C Preprocessor +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +cpp [\fB\-P\fR] [\fB\-C\fR] [\fB\-gcc\fR] [\fB\-traditional\fR] + [\fB\-undef\fR] [\fB\-trigraphs\fR] [\fB\-pedantic\fR] + [\fB\-W\fR\fIwarn\fR...] [\fB\-I\fR\fIdir\fR...] + [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR] + [\fB\-A\fR\fIpredicate\fR(\fIanswer\fR)] + [\fB\-M\fR|\fB\-MM\fR][\fB\-MG\fR][\fB\-MF\fR\fIfilename\fR] + [\fB\-MP\fR][\fB\-MQ\fR\fItarget\fR...][\fB\-MT\fR\fItarget\fR...] + [\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR] + \fIinfile\fR \fIoutfile\fR +.PP +Only the most useful options are listed here; see below for the remainder. +.SH "DESCRIPTION" +.IX Header "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. +.PP +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. +.Ip "\(bu" 4 +Macro expansion. You can define \fImacros\fR, which are abbreviations +for arbitrary fragments of C code, and then the C preprocessor will +replace the macros with their definitions throughout the program. +.Ip "\(bu" 4 +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. +.PP +C preprocessors vary in some details. This manual discusses the \s-1GNU\s0 C +preprocessor, which provides a small superset of the features of \s-1ISO\s0 +Standard C. +.PP +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" +.IX Header "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. +.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 +means to write to standard output. Also, if either file is omitted, it +means the same as if \fB-\fR had been specified for that file. +.PP +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. +.Ip "\fB\-P\fR" 4 +.IX Item "-P" +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 +.IX Item "-C" +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 +.IX Item "-traditional" +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" 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" 4 +However, traditionally the end of the line terminates a string or +character constant, with no error. +.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" 4 +Traditional C does not have the concept of a ``preprocessing number''. +It considers \fB1.0e+4\fR to be three tokens: \fB1.0e\fR, \fB+\fR, +and \fB4\fR. +.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" 4 +The character \fB#\fR has no special meaning within a macro definition +in traditional C. +.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-1ISO\s0 C.) +.Ip "\(bu" 4 +None of the \s-1GNU\s0 extensions to the preprocessor are available in +\&\fB\-traditional\fR mode. +.RE +.RS 4 +.Sp +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. +.Sp +So, the following Fortran comment lines are accepted with +\&\fB\-traditional\fR: +.Sp +.Vb 3 +\& C This isn't an unterminated character constant +\& 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: +.Sp +.Vb 2 +\& C Some Fortran compilers accept /* as starting +\& C an inline comment. +.Ve +Note that \f(CW\*(C`g77\*(C'\fR automatically supplies the \fB\-traditional\fR +option when it invokes the preprocessor. However, a future version of +\&\f(CW\*(C`g77\*(C'\fR might use a different, more-Fortran-aware preprocessor in +place of \f(CW\*(C`cpp\*(C'\fR. +.RE +.Ip "\fB\-trigraphs\fR" 4 +.IX Item "-trigraphs" +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'??/n'\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 +The nine trigraph sequences are +.RS 4 +.Ip "\fB??(\fR" 4 +.IX Item "??(" +-> \fB[\fR +.Ip "\fB??)\fR" 4 +.IX Item "??)" +-> \fB]\fR +.Ip "\fB??<\fR" 4 +.IX Item "??<" +-> \fB{\fR +.Ip "\fB??>\fR" 4 +.IX Item "??>" +-> \fB}\fR +.Ip "\fB??=\fR" 4 +.IX Item "??=" +-> \fB#\fR +.Ip "\fB??/\fR" 4 +.IX Item "??/" +-> \fB\e\fR +.Ip "\fB??'\fR" 4 +.IX Item "??'" +-> \fB^\fR +.Ip "\fB??!\fR" 4 +.IX Item "??!" +-> \fB|\fR +.Ip "\fB??-\fR" 4 +.IX Item "??-" +-> \fB~\fR +.RE +.RS 4 +.Sp +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. +.RE +.Ip "\fB\-pedantic\fR" 4 +.IX Item "-pedantic" +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 +.IX Item "-pedantic-errors" +Like \fB\-pedantic\fR, except that errors are produced rather than +warnings. +.Ip "\fB\-Wcomment\fR" 4 +.IX Item "-Wcomment" +.PD 0 +.Ip "\fB\-Wcomments\fR" 4 +.IX Item "-Wcomments" +.PD +(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. +.Ip "\fB\-Wtrigraphs\fR" 4 +.IX Item "-Wtrigraphs" +Warn if any trigraphs are encountered. This option used to take effect +only if \fB\-trigraphs\fR was also specified, but now works +independently. Warnings are not given for trigraphs within comments, as +we feel this is obnoxious. +.Ip "\fB\-Wwhite-space\fR" 4 +.IX Item "-Wwhite-space" +Warn about possible white space confusion, e.g. white space between a +backslash and a newline. +.Ip "\fB\-Wall\fR" 4 +.IX Item "-Wall" +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 +.IX Item "-Wtraditional" +Warn about certain constructs that behave differently in traditional and +\&\s-1ISO\s0 C. +.RS 4 +.Ip "\(bu" 4 +Macro parameters that appear within string literals in the macro body. +In traditional C macro replacement takes place within string literals, +but does not in \s-1ISO\s0 C. +.Ip "\(bu" 4 +In traditional C, some preprocessor directives did not exist. +Traditional preprocessors would only consider a line to be a directive +if the \fB#\fR appeared in column 1 on the line. Therefore +\&\fB\-Wtraditional\fR warns about directives that traditional C +understands but would ignore because the \fB#\fR does not appear as the +first character on the line. It also suggests you hide directives like +\&\fB#pragma\fR not understood by traditional C by indenting them. Some +traditional implementations would not recognise \fB#elif\fR, so it +suggests avoiding it altogether. +.Ip "\(bu" 4 +A function-like macro that appears without arguments. +.Ip "\(bu" 4 +The unary plus operator. +.Ip "\(bu" 4 +The `U' integer constant suffix. (Traditonal C does support the `L' +suffix on integer constants.) Note, these suffixes appear in macros +defined in the system headers of most modern systems, e.g. the _MIN/_MAX +macros in limits.h. Use of these macros can lead to spurious warnings +as they do not necessarily reflect whether the code in question is any +less portable to traditional C given that suitable backup definitions +are provided. +.RE +.RS 4 +.RE +.Ip "\fB\-Wundef\fR" 4 +.IX Item "-Wundef" +Warn if an undefined identifier is evaluated in an \fB#if\fR directive. +.Ip "\fB\-I\fR \fIdirectory\fR" 4 +.IX Item "-I directory" +Add the directory \fIdirectory\fR to the head 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 \fB\-I\fR option, +the directories are scanned in left-to-right order; the standard +system directories come after. +.Ip "\fB\-I-\fR" 4 +.IX Item "-I-" +Any directories specified with \fB\-I\fR options before the \fB\-I-\fR +option are searched only for the case of \fB#include "\fR\fIfile\fR\fB"\fR; +they are not searched for \fB#include <\fR\fIfile\fR\fB>\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 "\fR\fIfile\fR\fB"\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 +the current one and which are searched after. +.Ip "\fB\-nostdinc\fR" 4 +.IX Item "-nostdinc" +Do not search the standard system directories for header files. +Only the directories you have specified with \fB\-I\fR options +(and the current directory, if appropriate) are searched. +.Sp +By using both \fB\-nostdinc\fR and \fB\-I-\fR, you can limit the include-file +search path to only those directories you specify explicitly. +.Ip "\fB\-nostdinc++\fR" 4 +.IX Item "-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 the \*(C+ library.) +.Ip "\fB\-remap\fR" 4 +.IX Item "-remap" +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 +to work around limitations of file systems with file name restrictions. +The \fIheader.gcc\fR file should contain a series of lines with two +tokens on each line: the first token is the name to map, and the second +token is the actual name to use. +.Ip "\fB\-D\fR \fIname\fR" 4 +.IX Item "-D name" +Predefine \fIname\fR as a macro, with definition \fB1\fR. +.Ip "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4 +.IX Item "-D name=definition" +Predefine \fIname\fR as a macro, with definition \fIdefinition\fR. +There are no restrictions on the contents of \fIdefinition\fR, 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 \fB\-D\fR for the same \fIname\fR, the rightmost definition takes +effect. +.Sp +Any \fB\-D\fR and \fB\-U\fR options on the command line are processed in +order, and always before \fB\-imacros\fR \fIfile\fR, regardless of the +order in which they are written. +.Ip "\fB\-U\fR \fIname\fR" 4 +.IX Item "-U name" +Do not predefine \fIname\fR. +.Sp +Any \fB\-D\fR and \fB\-U\fR options on the command line are processed in +order, and always before \fB\-imacros\fR \fIfile\fR, regardless of the +order in which they are written. +.Ip "\fB\-undef\fR" 4 +.IX Item "-undef" +Do not predefine any nonstandard macros. +.Ip "\fB\-gcc\fR" 4 +.IX Item "-gcc" +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. +.Ip "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4 +.IX Item "-A predicate=answer" +Make an assertion with the predicate \fIpredicate\fR and answer +\&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR +\&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because +it does not use shell special characters. +.Ip "\fB\-A -\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4 +.IX Item "-A -predicate=answer" +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 +.IX Item "-dM" +Instead of outputting the result of preprocessing, output a list of +\&\fB#define\fR 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 \fBfoo.h\fR, the command +.Sp +.Vb 1 +\& touch foo.h; cpp -dM foo.h +.Ve +will show the values of any predefined macros. +.Ip "\fB\-dD\fR" 4 +.IX Item "-dD" +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 +.IX Item "-dN" +Like \fB\-dD\fR, but emit only the macro names, not their expansions. +.Ip "\fB\-dI\fR" 4 +.IX Item "-dI" +Output \fB#include\fR directives in addition to the result of +preprocessing. +.Ip "\fB\-M\fR" 4 +.IX Item "-M" +Instead of outputting the result of preprocessing, output a rule +suitable for \f(CW\*(C`make\*(C'\fR describing the dependencies of the main source +file. The preprocessor outputs one \f(CW\*(C`make\*(C'\fR rule containing the +object file name for that source file, a colon, and the names of all the +included files, including those coming from \fB\-include\fR or +\&\fB\-imacros\fR command line options. Unless specified explicitly (with +\&\fB\-MT\fR or \fB\-MQ\fR), the object file name consists of the basename +of the source file with any suffix replaced with object file suffix. +If there are many included files +then the rule is split into several lines using \fB\e\fR\-newline. +.Ip "\fB\-MM\fR" 4 +.IX Item "-MM" +Like \fB\-M\fR, but mention only the files included with \fB#include +"\fR\fIfile\fR\fB"\fR or with \fB\-include\fR or \fB\-imacros\fR command line +options. System header files included with \fB#include <\fR\fIfile\fR\fB>\fR +are omitted. +.Ip "\fB\-MF\fR \fIfile\fR" 4 +.IX Item "-MF file" +When used with \fB\-M\fR or \fB\-MM\fR, specifies a file to write the +dependencies to. This allows the preprocessor to write the preprocessed +file to stdout normally. If no \fB\-MF\fR switch is given, \s-1CPP\s0 sends +the rules to stdout and suppresses normal preprocessed output. +.Ip "\fB\-MG\fR" 4 +.IX Item "-MG" +When used with \fB\-M\fR or \fB\-MM\fR, \fB\-MG\fR says to treat missing +header files as generated files and assume they live in the same +directory as the source file. It suppresses preprocessed output, as a +missing header file is ordinarily an error. +.Sp +This feature is used in automatic updating of makefiles. +.Ip "\fB\-MP\fR" 4 +.IX Item "-MP" +This option instructs \s-1CPP\s0 to add a phony target for each dependency +other than the main file, causing each to depend on nothing. These +dummy rules work around errors \f(CW\*(C`make\*(C'\fR gives if you remove header +files without updating the \f(CW\*(C`Makefile\*(C'\fR to match. +.Sp +This is typical output:\- +.Sp +.Vb 1 +\& /tmp/test.o: /tmp/test.c /tmp/test.h +.Ve +.Vb 1 +\& /tmp/test.h: +.Ve +.Ip "\fB\-MQ\fR \fItarget\fR" 4 +.IX Item "-MQ target" +.PD 0 +.Ip "\fB\-MT\fR \fItarget\fR" 4 +.IX Item "-MT target" +.PD +By default \s-1CPP\s0 uses the main file name, including any path, and appends +the object suffix, normally ``.o'', to it to obtain the name of the +target for dependency generation. With \fB\-MT\fR you can specify a +target yourself, overriding the default one. +.Sp +If you want multiple targets, you can specify them as a single argument +to \fB\-MT\fR, or use multiple \fB\-MT\fR options. +.Sp +The targets you specify are output in the order they appear on the +command line. \fB\-MQ\fR is identical to \fB\-MT\fR, except that the +target name is quoted for Make, but with \fB\-MT\fR it isn't. For +example, \-MT '$(objpfx)foo.o' gives +.Sp +.Vb 1 +\& $(objpfx)foo.o: /tmp/foo.c +.Ve +but \-MQ '$(objpfx)foo.o' gives +.Sp +.Vb 1 +\& $$(objpfx)foo.o: /tmp/foo.c +.Ve +The default target is automatically quoted, as if it were given with +\&\fB\-MQ\fR. +.Ip "\fB\-H\fR" 4 +.IX Item "-H" +Print the name of each header file used, in addition to other normal +activities. +.Ip "\fB\-imacros\fR \fIfile\fR" 4 +.IX Item "-imacros file" +Process \fIfile\fR as input, discarding the resulting output, before +processing the regular input file. Because the output generated from +\&\fIfile\fR is discarded, the only effect of \fB\-imacros\fR \fIfile\fR +is to make the macros defined in \fIfile\fR available for use in the +main input. +.Ip "\fB\-include\fR \fIfile\fR" 4 +.IX Item "-include file" +Process \fIfile\fR as input, and include all the resulting output, +before processing the regular input file. +.Ip "\fB\-idirafter\fR \fIdir\fR" 4 +.IX Item "-idirafter dir" +Add the directory \fIdir\fR 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 +\&\fB\-I\fR adds to). +.Ip "\fB\-iprefix\fR \fIprefix\fR" 4 +.IX Item "-iprefix prefix" +Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR +options. If the prefix represents a directory, you should include the +final \fB/\fR. +.Ip "\fB\-iwithprefix\fR \fIdir\fR" 4 +.IX Item "-iwithprefix dir" +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. +.Ip "\fB\-isystem\fR \fIdir\fR" 4 +.IX Item "-isystem dir" +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. +.Ip "\fB\-x c\fR" 4 +.IX Item "-x c" +.PD 0 +.Ip "\fB\-x c++\fR" 4 +.IX Item "-x c++" +.Ip "\fB\-x objective-c\fR" 4 +.IX Item "-x objective-c" +.Ip "\fB\-x assembler-with-cpp\fR" 4 +.IX Item "-x assembler-with-cpp" +.PD +Specify the source language: C, \*(C+, Objective-C, or assembly. This has +nothing to do with standards conformance or extensions; it merely +selects which base syntax to expect. If you give none of these options, +cpp will deduce the language from the extension of the source file: +\&\fB.c\fR, \fB.cc\fR, \fB.m\fR, or \fB.S\fR. Some other common +extensions for \*(C+ and assembly are also recognized. If cpp does not +recognize the extension, it will treat the file as C; this is the most +generic mode. +.Sp +\&\fBNote:\fR Previous versions of cpp accepted a \fB\-lang\fR option +which selected both the language and the standards conformance level. +This option has been removed, because it conflicts with the \fB\-l\fR +option. +.Ip "\fB\-std=\fR\fIstandard\fR" 4 +.IX Item "-std=standard" +.PD 0 +.Ip "\fB\-ansi\fR" 4 +.IX Item "-ansi" +.PD +Specify the standard to which the code should conform. Currently cpp +only knows about the standards for C; other language standards will be +added in the future. +.Sp +\&\fIstandard\fR +may be one of: +.RS 4 +.if n .Ip "\f(CW""iso9899:1990""\fR" 4 +.el .Ip "\f(CWiso9899:1990\fR" 4 +.IX Item "iso9899:1990" +.PD 0 +.if n .Ip "\f(CW""c89""\fR" 4 +.el .Ip "\f(CWc89\fR" 4 +.IX Item "c89" +.PD +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. +.if n .Ip "\f(CW""iso9899:199409""\fR" 4 +.el .Ip "\f(CWiso9899:199409\fR" 4 +.IX Item "iso9899:199409" +The 1990 C standard, as amended in 1994. +.if n .Ip "\f(CW""iso9899:1999""\fR" 4 +.el .Ip "\f(CWiso9899:1999\fR" 4 +.IX Item "iso9899:1999" +.PD 0 +.if n .Ip "\f(CW""c99""\fR" 4 +.el .Ip "\f(CWc99\fR" 4 +.IX Item "c99" +.if n .Ip "\f(CW""iso9899:199x""\fR" 4 +.el .Ip "\f(CWiso9899:199x\fR" 4 +.IX Item "iso9899:199x" +.if n .Ip "\f(CW""c9x""\fR" 4 +.el .Ip "\f(CWc9x\fR" 4 +.IX Item "c9x" +.PD +The revised \s-1ISO\s0 C standard, published in December 1999. Before +publication, this was known as C9X. +.if n .Ip "\f(CW""gnu89""\fR" 4 +.el .Ip "\f(CWgnu89\fR" 4 +.IX Item "gnu89" +The 1990 C standard plus \s-1GNU\s0 extensions. This is the default. +.if n .Ip "\f(CW""gnu99""\fR" 4 +.el .Ip "\f(CWgnu99\fR" 4 +.IX Item "gnu99" +.PD 0 +.if n .Ip "\f(CW""gnu9x""\fR" 4 +.el .Ip "\f(CWgnu9x\fR" 4 +.IX Item "gnu9x" +.PD +The 1999 C standard plus \s-1GNU\s0 extensions. +.RE +.RS 4 +.RE +.Ip "\fB\-ftabstop=NUMBER\fR" 4 +.IX Item "-ftabstop=NUMBER" +Set the distance between tab stops. 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 +.IX Item "-$" +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" +.IX Header "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" +.IX Header "COPYRIGHT" +Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2001 +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 also 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. |