| .\" 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. |