diff options
Diffstat (limited to 'gcc/doc/cpp.1')
| -rw-r--r-- | gcc/doc/cpp.1 | 721 |
1 files changed, 721 insertions, 0 deletions
diff --git a/gcc/doc/cpp.1 b/gcc/doc/cpp.1 new file mode 100644 index 00000000000..a22da8eeaf4 --- /dev/null +++ b/gcc/doc/cpp.1 @@ -0,0 +1,721 @@ +.\" Automatically generated by Pod::Man v1.32, Pod::Parser v1.13 +.\" +.\" 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 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. +. \" 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 "2002-01-26" "gcc-3.0.4" "GNU" +.SH "NAME" +cpp \- The C Preprocessor +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR] + [\fB\-I\fR\fIdir\fR...] [\fB\-W\fR\fIwarn\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, often known as \fIcpp\fR, is a \fImacro processor\fR +that is used automatically by the C compiler to transform your program +before 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 to be used only with C, \*(C+, and +Objective-C source code. In the past, it has been abused as a general +text processor. It will choke on input which does not obey C's lexical +rules. For example, apostrophes will be interpreted as the beginning of +character constants, and cause errors. Also, you cannot rely on it +preserving characteristics of the input which are not significant to +C\-family languages. If a Makefile is preprocessed, all the hard tabs +will be removed, and the Makefile will not work. +.PP +Having said that, you can often get away with using cpp on things which +are not C. Other Algol-ish programming languages are often safe +(Pascal, Ada, etc.) So is assembly, with caution. \fB\-traditional\fR +mode preserves more white space, and is otherwise more permissive. Many +of the problems can be avoided by writing C or \*(C+ style comments +instead of native language comments, and keeping macros simple. +.PP +Wherever possible, you should use a preprocessor geared to the language +you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro +facilities. Most high level programming languages have their own +conditional compilation and inclusion mechanism. If all else fails, +try a true general text processor, such as \s-1GNU\s0 M4. +.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. 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 +Unless otherwise noted, or the option ends in \fB=\fR, all options +which take an argument may have that argument appear either immediately +after the option, or with a space between option and argument: +\&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect. +.PP +Many options have multi-letter names; therefore multiple single-letter +options may \fInot\fR be grouped: \fB\-dM\fR is very different from +\&\fB\-d\ \-M\fR. +.IP "\fB\-D\fR \fIname\fR" 4 +.IX Item "-D name" +Predefine \fIname\fR as a macro, with definition \f(CW1\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 +If you wish to define a function-like macro on the command line, write +its argument list with surrounding parentheses before the equals sign +(if any). Parentheses are meaningful to most shells, so you will need +to quote the option. With \fBsh\fR and \fBcsh\fR, +\&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works. +.IP "\fB\-U\fR \fIname\fR" 4 +.IX Item "-U name" +Cancel any previous definition of \fIname\fR, either built in or +provided with a \fB\-D\fR option. +.Sp +All \fB\-imacros\fR \fIfile\fR and \fB\-include\fR \fIfile\fR options +are processed after all \fB\-D\fR and \fB\-U\fR options. +.IP "\fB\-undef\fR" 4 +.IX Item "-undef" +Do not predefine any system-specific macros. The common predefined +macros remain defined. +.IP "\fB\-I\fR \fIdir\fR" 4 +.IX Item "-I dir" +Add the directory \fIdir\fR to the list of directories to be searched +for header files. Directories named by \fB\-I\fR +are searched before the standard system include directories. +.Sp +It is dangerous to specify a standard system include directory in an +\&\fB\-I\fR option. This defeats the special treatment of system +headers. It can also defeat the repairs to +buggy system headers which \s-1GCC\s0 makes when it is installed. +.IP "\fB\-o\fR \fIfile\fR" 4 +.IX Item "-o file" +Write output to \fIfile\fR. This is the same as specifying \fIfile\fR +as the second non-option argument to \fBcpp\fR. \fBgcc\fR has a +different interpretation of a second non-option argument, so you must +use \fB\-o\fR to specify the output file. +.IP "\fB\-Wall\fR" 4 +.IX Item "-Wall" +Turns on all optional warnings which are desirable for normal code. At +present this is \fB\-Wcomment\fR and \fB\-Wtrigraphs\fR. Note that +many of the preprocessor's warnings are on by default and have no +options to control them. +.IP "\fB\-Wcomment\fR" 4 +.IX Item "-Wcomment" +.PD 0 +.IP "\fB\-Wcomments\fR" 4 +.IX Item "-Wcomments" +.PD +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. +(Both forms have the same effect.) +.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 +they do not affect the meaning of the program. +.IP "\fB\-Wtraditional\fR" 4 +.IX Item "-Wtraditional" +Warn about certain constructs that behave differently in traditional and +\&\s-1ISO\s0 C. Also warn about \s-1ISO\s0 C constructs that have no traditional C +equivalent, and problematic constructs which should be avoided. +.IP "\fB\-Wimport\fR" 4 +.IX Item "-Wimport" +Warn the first time \fB#import\fR is used. +.IP "\fB\-Wundef\fR" 4 +.IX Item "-Wundef" +Warn whenever an identifier which is not a macro is encountered in an +\&\fB#if\fR directive, outside of \fBdefined\fR. Such identifiers are +replaced with zero. +.IP "\fB\-Werror\fR" 4 +.IX Item "-Werror" +Make all warnings into hard errors. Source code which triggers warnings +will be rejected. +.IP "\fB\-Wsystem\-headers\fR" 4 +.IX Item "-Wsystem-headers" +Issue warnings for code in system headers. These are normally unhelpful +in finding bugs in your own code, therefore suppressed. If you are +responsible for the system library, you may want to see them. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +Suppress all warnings, including those which \s-1GNU\s0 \s-1CPP\s0 issues by default. +.IP "\fB\-pedantic\fR" 4 +.IX Item "-pedantic" +Issue all the mandatory diagnostics listed in the C standard. Some of +them are left out by default, since they trigger frequently on harmless +code. +.IP "\fB\-pedantic\-errors\fR" 4 +.IX Item "-pedantic-errors" +Issue all the mandatory diagnostics, and make all mandatory diagnostics +into errors. This includes mandatory diagnostics that \s-1GCC\s0 issues +without \fB\-pedantic\fR but treats as warnings. +.IP "\fB\-M\fR" 4 +.IX Item "-M" +Instead of outputting the result of preprocessing, output a rule +suitable for \fBmake\fR describing the dependencies of the main +source file. The preprocessor outputs one \fBmake\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. +.Sp +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. +The rule has no commands. +.IP "\fB\-MM\fR" 4 +.IX Item "-MM" +Like \fB\-M\fR, but mention only the files included with \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR or with \fB\-include\fR or \fB\-imacros\fR command line +options. System header files included with \f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\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 \fBmake\fR gives if you remove header +files without updating the \fIMakefile\fR to match. +.Sp +This is typical output: +.Sp +.Vb 1 +\& test.o: test.c test.h +.Ve +.Sp +.Vb 1 +\& test.h: +.Ve +.IP "\fB\-MT\fR \fItarget\fR" 4 +.IX Item "-MT target" +Change the target of the rule emitted by dependency generation. By +default \s-1CPP\s0 takes the name of the main input file, including any path, +deletes any file suffix such as \fB.c\fR, and appends the platform's +usual object suffix. The result is the target. +.Sp +An \fB\-MT\fR option will set the target to be exactly the string you +specify. 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 +For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give +.Sp +.Vb 1 +\& $(objpfx)foo.o: foo.c +.Ve +.IP "\fB\-MQ\fR \fItarget\fR" 4 +.IX Item "-MQ target" +Same as \fB\-MT\fR, but it quotes any characters which are special to +Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives +.Sp +.Vb 1 +\& $$(objpfx)foo.o: foo.c +.Ve +.Sp +The default target is automatically quoted, as if it were given with +\&\fB\-MQ\fR. +.IP "\fB\-MD\fR \fIfile\fR" 4 +.IX Item "-MD file" +.PD 0 +.IP "\fB\-MMD\fR \fIfile\fR" 4 +.IX Item "-MMD file" +.PD +\&\fB\-MD\fR \fIfile\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, and +\&\fB\-MMD\fR \fIfile\fR is equivalent to \fB\-MM \-MF\fR \fIfile\fR. +.Sp +Due to limitations in the compiler driver, you must use these switches +when you want to generate a dependency file as a side-effect of normal +compilation. +.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 +.ie n .IP """iso9899:1990""" 4 +.el .IP "\f(CWiso9899:1990\fR" 4 +.IX Item "iso9899:1990" +.PD 0 +.ie n .IP """c89""" 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. +.ie n .IP """iso9899:199409""" 4 +.el .IP "\f(CWiso9899:199409\fR" 4 +.IX Item "iso9899:199409" +The 1990 C standard, as amended in 1994. +.ie n .IP """iso9899:1999""" 4 +.el .IP "\f(CWiso9899:1999\fR" 4 +.IX Item "iso9899:1999" +.PD 0 +.ie n .IP """c99""" 4 +.el .IP "\f(CWc99\fR" 4 +.IX Item "c99" +.ie n .IP """iso9899:199x""" 4 +.el .IP "\f(CWiso9899:199x\fR" 4 +.IX Item "iso9899:199x" +.ie n .IP """c9x""" 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. +.ie n .IP """gnu89""" 4 +.el .IP "\f(CWgnu89\fR" 4 +.IX Item "gnu89" +The 1990 C standard plus \s-1GNU\s0 extensions. This is the default. +.ie n .IP """gnu99""" 4 +.el .IP "\f(CWgnu99\fR" 4 +.IX Item "gnu99" +.PD 0 +.ie n .IP """gnu9x""" 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\-I\-\fR" 4 +.IX Item "-I-" +Split the include path. Any directories specified with \fB\-I\fR +options before \fB\-I\-\fR are searched only for headers requested with +\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for +\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are +specified with \fB\-I\fR options after the \fB\-I\-\fR, those +directories are searched for all \fB#include\fR directives. +.Sp +In addition, \fB\-I\-\fR inhibits the use of the directory of the current +file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. +.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 directory of the current file, if appropriate) are searched. +.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\-include\fR \fIfile\fR" 4 +.IX Item "-include file" +Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first +line of the primary source file. However, the first directory searched +for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR +the directory containing the main source file. If not found there, it +is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search +chain as normal. +.Sp +If multiple \fB\-include\fR options are given, the files are included +in the order they appear on the command line. +.IP "\fB\-imacros\fR \fIfile\fR" 4 +.IX Item "-imacros file" +Exactly like \fB\-include\fR, except that any output produced by +scanning \fIfile\fR is thrown away. Macros it defines remain defined. +This allows you to acquire all the macros from a header without also +processing its declarations. +.Sp +All files specified by \fB\-imacros\fR are processed before all files +specified by \fB\-include\fR. +.IP "\fB\-idirafter\fR \fIdir\fR" 4 +.IX Item "-idirafter dir" +Search \fIdir\fR for header files, but do it \fIafter\fR all +directories specified with \fB\-I\fR and the standard system directories +have been exhausted. \fIdir\fR is treated as a system include directory. +.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" +.PD 0 +.IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4 +.IX Item "-iwithprefixbefore dir" +.PD +Append \fIdir\fR to the prefix specified previously with +\&\fB\-iprefix\fR, and add the resulting directory to the include search +path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR +would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would. +.Sp +Use of these options is discouraged. +.IP "\fB\-isystem\fR \fIdir\fR" 4 +.IX Item "-isystem dir" +Search \fIdir\fR for header files, after all directories specified by +\&\fB\-I\fR but before the standard system directories. Mark it +as a system directory, so that it gets the same special treatment as +is applied to the standard system directories. +.IP "\fB\-fpreprocessed\fR" 4 +.IX Item "-fpreprocessed" +Indicate to the preprocessor that the input file has already been +preprocessed. This suppresses things like macro expansion, trigraph +conversion, escaped newline splicing, and processing of most directives. +The preprocessor still recognizes and removes comments, so that you can +pass a file preprocessed with \fB\-C\fR to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. +.Sp +\&\fB\-fpreprocessed\fR is implicit if the input file has one of the +extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the +extensions that \s-1GCC\s0 uses for preprocessed files created by +\&\fB\-save\-temps\fR. +.IP "\fB\-ftabstop=\fR\fIwidth\fR" 4 +.IX Item "-ftabstop=width" +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. If the value is less than 1 or greater than 100, the option is +ignored. The default is 8. +.IP "\fB\-fno\-show\-column\fR" 4 +.IX Item "-fno-show-column" +Do not print column numbers in diagnostics. This may be necessary if +diagnostics are being scanned by a program that does not understand the +column numbers, such as \fBdejagnu\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" +Cancel an assertion with the predicate \fIpredicate\fR and answer +\&\fIanswer\fR. +.IP "\fB\-A\-\fR" 4 +.IX Item "-A-" +Cancel all predefined assertions and all assertions preceding it on +the command line. Also, undefine all predefined macros and all +macros preceding it on the command line. (This is a historical wart and +may change in the future.) +.IP "\fB\-dCHARS\fR" 4 +.IX Item "-dCHARS" +\&\fI\s-1CHARS\s0\fR is a sequence of one or more of the following characters, +and must not be preceded by a space. Other characters are interpreted +by the compiler proper, or reserved for future versions of \s-1GCC\s0, and so +are silently ignored. If you specify characters whose behavior +conflicts, the result is undefined. +.RS 4 +.IP "\fBM\fR" 4 +.IX Item "M" +Instead of the normal output, generate 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 \fIfoo.h\fR, the command +.Sp +.Vb 1 +\& touch foo.h; cpp -dM foo.h +.Ve +.Sp +will show all the predefined macros. +.IP "\fBD\fR" 4 +.IX Item "D" +Like \fBM\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 "\fBN\fR" 4 +.IX Item "N" +Like \fBD\fR, but emit only the macro names, not their expansions. +.IP "\fBI\fR" 4 +.IX Item "I" +Output \fB#include\fR directives in addition to the result of +preprocessing. +.RE +.RS 4 +.RE +.IP "\fB\-P\fR" 4 +.IX Item "-P" +Inhibit generation of linemarkers 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 +linemarkers. +.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. +.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, 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\-gcc\fR" 4 +.IX Item "-gcc" +Define the macros _\|_GNUC_\|_, _\|_GNUC_MINOR_\|_ and +_\|_GNUC_PATCHLEVEL_\|_. 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\-traditional\fR" 4 +.IX Item "-traditional" +Try to imitate the behavior of old-fashioned C, as opposed to \s-1ISO\s0 +C. +.IP "\fB\-trigraphs\fR" 4 +.IX Item "-trigraphs" +Process trigraph sequences. +.IP "\fB\-remap\fR" 4 +.IX Item "-remap" +Enable special code to work around file systems which only permit very +short file names, such as \s-1MS\-DOS\s0. +.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 \s-1GNU\s0 \s-1CPP\s0 permits \fB$\fR, a common extension. +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD 0 +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.IP "\fB\-\-target\-help\fR" 4 +.IX Item "--target-help" +.PD +Print text describing all the command line options instead of +preprocessing anything. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +Verbose mode. Print out \s-1GNU\s0 \s-1CPP\s0's version number at the beginning of +execution, and report the final form of the include path. +.IP "\fB\-H\fR" 4 +.IX Item "-H" +Print the name of each header file used, in addition to other normal +activities. Each name is indented to show how deep in the +\&\fB#include\fR stack it is. +.IP "\fB\-version\fR" 4 +.IX Item "-version" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Print out \s-1GNU\s0 \s-1CPP\s0's version number. With one dash, proceed to +preprocess as normal. With two dashes, exit immediately. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), +\&\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 copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +man page \fIgfdl\fR\|(7). +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). +.PP +(a) The \s-1FSF\s0's Front-Cover Text is: +.PP +.Vb 1 +\& A GNU Manual +.Ve +.PP +(b) The \s-1FSF\s0's Back-Cover Text is: +.PP +.Vb 3 +\& You have freedom to copy and modify this GNU Manual, like GNU +\& software. Copies published by the Free Software Foundation raise +\& funds for GNU development. +.Ve |