cpp doc update

Zack Weinberg zack@rabi.columbia.edu
Mon Jun 14 17:29:00 GMT 1999


I just committed a doc update for cpp; text is appended.  The changes to
cpp.texi are uninteresting; the major point of the patch is to bring the
manpage in sync with the info file.  This was done with the aid of a cheesy
perl script - which is now living over in contrib/ - and `pod2man', plus
some hand-hacking (pod2man is buggy).  I looked at doing the same for
gcc.man, but it would take major surgery on invoke.texi to get a decent
manpage out the other end.

Please cc me directly on comments, I'm not on the list right now.

zw

Index: cpp.texi
===================================================================
RCS file: /cvs/egcs/egcs/gcc/cpp.texi,v
retrieving revision 1.10
diff -u -r1.10 cpp.texi
--- cpp.texi	1999/05/27 23:44:43	1.10
+++ cpp.texi	1999/06/15 00:17:33
@@ -16,8 +16,7 @@
 @ifinfo
 This file documents the GNU C Preprocessor.
 
-Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1997, 1998, 1999
-Free Software Foundation, Inc.
+Copyright 1987, 1989, 1991-1999 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -42,7 +41,7 @@
 @titlepage
 @c @finalout
 @title The C Preprocessor
-@subtitle Last revised September 1998
+@subtitle Last revised May 1999
 @subtitle for GCC version 2
 @author Richard M. Stallman
 @page
@@ -51,7 +50,8 @@
 C Language manual.
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1987, 1989, 1991-1998
+@c man begin COPYRIGHT
+Copyright @copyright{} 1987, 1989, 1991-1999
 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
@@ -65,11 +65,13 @@
 
 Permission is granted to copy and distribute translations of this manual
 into another language, under the above conditions for modified versions.
+@c man end
 @end titlepage
 @page
 
 @node Top, Global Actions,, (DIR)
 @chapter The C Preprocessor
+@c man begin DESCRIPTION
 
 The C preprocessor is a @dfn{macro processor} that is used automatically by
 the C compiler to transform your program before actual compilation.  It is
@@ -117,6 +119,7 @@
 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.
+@c man end
 
 @menu
 * Global Actions::    Actions made uniformly on all input files.
@@ -2516,15 +2519,35 @@
 explicitly: the C compiler will do so automatically.  However, the
 preprocessor is sometimes useful on its own.
 
+@ignore
+@c man begin SYNOPSIS
+cpp [@samp{-P}] [@samp{-C}] [@samp{-gcc}] [@samp{-traditional}]
+    [@samp{-undef}] [@samp{-trigraphs}] [@samp{-pedantic}]
+    [@samp{-W}@var{warn}...] [@samp{-I}@var{dir}...]
+    [@samp{-D}@var{macro}[=@var{defn}]...] [@samp{-U}@var{macro}]
+    [@samp{-A}@var{predicate}(@var{answer})]
+    [@samp{-M}|@samp{-MM}|@samp{-MD}|@samp{-MMD} [@samp{-MG}]]
+    [@samp{-x} @var{language}] [@samp{-std=}@var{standard}]
+    @var{infile} @var{outfile}
+
+Only the most useful options are listed here; see below for the remainder.
+@c man end
+@c man begin SEEALSO
+gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and
+@file{binutils}.
+@c man end
+@end ignore
+
+@c man begin OPTIONS
 The C preprocessor expects two file names as arguments, @var{infile} and
 @var{outfile}.  The preprocessor reads @var{infile} together with any other
 files it specifies with @samp{#include}.  All the output generated by the
 combined input files is written in @var{outfile}.
 
-Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile}
-means to read from standard input and as @var{outfile} means to write to
-standard output.  Also, if @var{outfile} or both file names are omitted,
-the standard output and standard input are used for the omitted file names.
+Either @var{infile} or @var{outfile} may be @samp{-}, which as
+@var{infile} means to read from standard input and as @var{outfile}
+means to write to standard output.  Also, if either file is omitted, it
+means the same as if @samp{-} had been specified for that file.
 
 @cindex options
 Here is a table of command options accepted by the C preprocessor.
@@ -2751,8 +2774,8 @@
 @item -U @var{name}
 @findex -U
 Do not predefine @var{name}.  If both @samp{-U} and @samp{-D} are
-specified for one name, the @samp{-U} beats the @samp{-D} and the name
-is not predefined.
+specified for one name, whichever one appears later on the command line
+wins.
 
 @item -undef
 @findex -undef
@@ -2952,8 +2975,8 @@
 @findex -$
 Forbid the use of @samp{$} in identifiers.  The C standard does not
 permit this, but it is a common extension.
-
 @end table
+@c man end
 
 @node Concept Index, Index, Invocation, Top
 @unnumbered Concept Index
Index: cpp.1
===================================================================
RCS file: /cvs/egcs/egcs/gcc/cpp.1,v
retrieving revision 1.3
diff -u -r1.3 cpp.1
--- cpp.1	1998/12/16 20:54:27	1.3
+++ cpp.1	1999/06/15 00:17:34
@@ -1 +1,563 @@
-.so man1/cccp.1
+.rn '' }`
+.de Sh
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.de Vb
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve
+.ft R
+
+.fi
+..
+'''
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(*W-|\(bv\*(Tr
+.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" ""
+'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
+'''   \*(L" and \*(R", except that they are used on ".xx" lines,
+'''   such as .IP and .SH, which do another additional levels of
+'''   double-quote interpretation
+.ds M" """
+.ds S" """
+.ds N" """""
+.ds T" """""
+.ds L' '
+.ds R' '
+.ds M' '
+.ds S' '
+.ds N' '
+.ds T' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds M" ``
+.ds S" ''
+.ds N" ``
+.ds T" ''
+.ds L' `
+.ds R' '
+.ds M' `
+.ds S' '
+.ds N' `
+.ds T' '
+.ds PI \(*p
+'br\}
+.TH CPP 1 "gcc-2.95" "14/Jun/99" "GNU"
+.UC
+.if n .hy 0
+.if n .na
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.de CQ          \" put $1 in typewriter font
+.ft CW
+'if n "\c
+'if t \\&\\$1\c
+'if n \\&\\$1\c
+'if n \&"
+\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
+'.ft R
+..
+.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
+.	\" AM - accent mark definitions
+.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 ? ?
+.	ds ! !
+.	ds /
+.	ds q
+.\}
+.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 ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+.\}
+.	\" 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 v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
+.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
+.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
+.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+.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
+.ds oe o\h'-(\w'o'u*4/10)'e
+.ds Oe O\h'-(\w'O'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 v \h'-1'\o'\(aa\(ga'
+.	ds _ \h'-1'^
+.	ds . \h'-1'.
+.	ds 3 3
+.	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
+.	ds oe oe
+.	ds Oe OE
+.\}
+.rm #[ #] #H #V #F C
+.SH "NAME"
+cpp \- The C Preprocessor
+.SH "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\-MD\fR|\fB\-MMD\fR [\fB\-MG\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"
+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:
+.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, 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.  
+.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.
+.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.
+.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
+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.
+.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
+argument values even when they appear within apparent string or
+character constants.
+.Ip "\(bu" 8
+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
+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
+C, a comment counts as whitespace.)
+.Ip "\(bu" 8
+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
+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
+The character \fB#\fR has no special meaning within a macro definition
+in traditional C.
+.Ip "\(bu" 8
+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.
+.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(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
+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.
+.Sp
+You don't want to know any more about trigraphs.
+.Ip "\fB\-pedantic\fR" 4
+Issue warnings required by the \s-1ANSI\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
+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\-Wall\fR" 4
+Requests both \fB\-Wtrigraphs\fR and \fB\-Wcomment\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.
+.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
+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
+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.
+.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.
+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
+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.
+.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.)
+.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
+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 \fIname\fR\fR" 4
+Predefine \fIname\fR as a macro, with definition \fB1\fR.
+.Ip "\fB\-D \fIname\fR=\fIdefinition\fR\fR" 4
+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.
+.Ip "\fB\-U \fIname\fR\fR" 4
+Do not predefine \fIname\fR.  If both \fB\-U\fR and \fB\-D\fR are
+specified for one name, whichever one appears later on the command line
+wins.
+.Ip "\fB\-undef\fR" 4
+Do not predefine any nonstandard macros.
+.Ip "\fB\-gcc\fR" 4
+Define the macros \fI_\|_GNUC_\|_\fR and \fI_\|_GNUC_MINOR_\|_\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\-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
+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
+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\-dI\fR" 4
+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.
+.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.
+.Sp
+This feature is used in automatic updating of makefiles.
+.Ip "\fB\-\s-1MM\s0 [\-\s-1MG\s0]\fR" 4
+Like \fB\-M\fR but mention only the files included with \fB#include
+\*(L"\fIfile\fR\*(R"\fR.  System header 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.
+.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.
+.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.
+.Ip "\fB\-H\fR" 4
+Print the name of each header file used, in addition to other normal
+activities.
+.Ip "\fB\-imacros \fIfile\fR\fR" 4
+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 \fIfile\fR\fR
+is to make the macros defined in \fIfile\fR available for use in the
+main input.
+.Ip "\fB\-include \fIfile\fR\fR" 4
+Process \fIfile\fR as input, and include all the resulting output,
+before processing the regular input file.  
+.Ip "\fB\-idirafter \fIdir\fR\fR" 4
+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 \fIprefix\fR\fR" 4
+Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR
+options.
+.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.
+.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.
+.Ip "\fB\-x c\fR" 4
+.Ip "\fB\-x c++\fR" 4
+.Ip "\fB\-x objective-c\fR" 4
+.Ip "\fB\-x assembler-with-cpp\fR" 4
+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=\fIstandard\fR\fR" 4
+.Ip "\fB\-ansi\fR" 4
+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:
+.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.
+.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
+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 "\fB\-$\fR" 4
+Forbid the use of \fB$\fR in identifiers.  The C standard does not
+permit this, but it is 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-1999
+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.
+.rn }` ''


More information about the Gcc-patches mailing list