--- gcc/cpp.texinfo	2018/04/24 16:38:22	1.1.1.2
+++ gcc/cpp.texinfo	2018/04/24 16:53:47	1.1.1.8
@@ -4,7 +4,7 @@
 @ifinfo
 This file documents the GNU C Preprocessor.
 
-Copyright (C) 1987 Richard M. Stallman.
+Copyright (C) 1987, 1989 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -32,12 +32,12 @@ into another language, under the above c
 @sp 4
 @center First Edition
 @sp 1
-@center January 1987
+@center April 1989
 @sp 5
 @center Richard M. Stallman
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1987 Richard M. Stallman.
+Copyright @copyright{} 1987, 1989 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -93,9 +93,9 @@ ANSI Standard C requires the rejection o
 used by today's C programs.  Such incompatibility would be inconvenient for
 users, so the GNU C preprocessor is configured to accept these constructs
 by default.  Strictly speaking, to get ANSI Standard C, you must use the
-options @samp{-T}, @samp{-undef} and @samp{-pedantic}, but in practice the
-consequences of having strict ANSI Standard C make it undesirable to do
-this.  @xref{Invocation}.
+options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in
+practice the consequences of having strict ANSI Standard C make it
+undesirable to do this.  @xref{Invocation}.
 
 @menu
 * Global Actions::    Actions made uniformly on all input files.
@@ -185,8 +185,8 @@ write what looks like a trigraph with a
 Backslash-Newline is deleted as usual, but it is then too late to
 recognize the trigraph.
 
-This exception is relevant only if you use the @samp{-T} option to
-enable trigraph processing.  @xref{Invocation}.
+This exception is relevant only if you use the @samp{-trigraphs}
+option to enable trigraph processing.  @xref{Invocation}.
 @end itemize
 
 @node Commands, Header Files, Global Actions, Top
@@ -232,6 +232,13 @@ A header file is a file containing C dec
 the use of a header file in your program with the C preprocessor command
 @samp{#include}.
 
+@menu
+* Header Uses::         What header files are used for.
+* Include Syntax::      How to write @samp{#include} commands.
+* Include Operation::   What @samp{#include} does.
+* Once-Only::		Preventing multiple inclusion of one header file.
+@end menu
+
 @node Header Uses, Include Syntax, Header Files, Header Files
 @subsection Uses of Header Files
 
@@ -277,7 +284,9 @@ This variant is used for system header f
 named @var{file} in a list of directories specified by you, then in a
 standard list of system directories.  You specify directories to
 search for header files with the command option @samp{-I}
-(@pxref{Invocation}).
+(@pxref{Invocation}).  The option @samp{-nostdinc} inhibits searching
+the standard system directories; in this case only the directories
+you specify are searched.
 
 The parsing of this form of @samp{#include} is slightly special
 because comments are not recognized within the @samp{<@dots{}>}.
@@ -292,11 +301,12 @@ however, contain a @samp{<} character.
 
 @item #include "@var{file}"
 This variant is used for header files of your own program.  It
-searches for a file named @var{file} first in the current working
-directory, then in the same directories used for system header
-files.  The current working directory is tried first because it is
-presumed to be the location of the files of the program being
-compiled.
+searches for a file named @var{file} first in the current directory,
+then in the same directories used for system header files.  The
+current directory is the directory of the current input file.  It is
+tried first because it is presumed to be the location of the files
+that the current input file refers to.  (If the @samp{-I-} option is
+used, the special treatment of the current directory is inhibited.)
 
 The argument @var{file} may not contain @samp{"} characters.  If
 backslashes occur within @var{file}, they are considered ordinary text
@@ -321,7 +331,7 @@ porting the program to various operating
 necessary system header files are found in different places.
 @end table
 
-@node Include Operation,, Include Syntax, Header Files
+@node Include Operation, Once-Only, Include Syntax, Header Files
 @subsection How @samp{#include} Works
 
 The @samp{#include} command works by directing the C preprocessor to scan
@@ -374,6 +384,55 @@ The line following the @samp{#include} c
 separate line by the C preprocessor even if the included file lacks a final
 newline.
 
+@node Once-Only,, Include Operation, Header Files
+@subsection Once-Only Include Files
+@cindex repeated inclusion
+
+Very often, one header file includes another.  It can easily result that a
+certain header file is included more than once.  This may lead to errors,
+if the header file defines structure types or typedefs, and is certainly
+wasteful.  Therefore, we often wish to prevent multiple inclusion of a
+header file.
+
+The standard way to do this is to enclose the entire real contents of the
+file in a conditional, like this:
+
+@example
+#ifndef __FILE_FOO_SEEN__
+#define __FILE_FOO_SEEN__
+
+@var{the entire file}
+
+#endif /* __FILE_FOO_SEEN__ */
+@end example
+
+The macro @code{__FILE_FOO_SEEN__} indicates that the file has been
+included once already; its name should begin with @samp{__}, and should
+contain the name of the file to avoid accidental conflicts.
+
+One drawback of this method is that the preprocessor must scan the input
+file completely in order to determine that all of it is to be ignored.
+This makes compilation slower.  You can avoid the delay by inserting the
+following command near the beginning of file @emph{in addition to the
+conditionals described above}:
+
+@example
+#pragma once
+@end example
+
+This command tells the GNU C preprocessor to ignore any future commands
+to include the same file (whichever file the @samp{#pragma} appears in).
+
+You should not @emph{rely} on @samp{#pragma once} to prevent multiple
+inclusion of the file.  It is just a hint, and a nonstandard one at
+that.  Most C compilers will ignore it entirely.  For this reason, you
+still need the conditionals if you want to make certain that the file's
+contents are not included twice.
+
+Note that @samp{#pragma once} works by file name; if a file has more
+than one name, it can be included once under each name, even in GNU CC,
+despite @samp{#pragma once}.
+
 @node Macros, Conditionals, Header Files, Top
 @section Macros
 
@@ -563,10 +622,10 @@ example, @samp{min (min (a, b), c)} expa
 
 If you use the macro name followed by something other than an
 open-parenthesis (after ignoring any spaces, tabs and comments that
-follow), it is not a call to the macro, and the preprocessor does not
-change what you have written.  Therefore, it is possible for the same name
-to be a variable or function in your program as well as a macro, and you
-can choose in each instance whether to refer to the macro (if an actual
+follow), it is not a call to the macro, and the preprocessor leaves the
+name unaltered.  Therefore, it is possible for the same name to be a
+variable or function in your program as well as a macro, and you can
+choose in each instance whether to refer to the macro (if an actual
 argument list follows) or the variable or function (if an argument list
 does not follow).
 
@@ -643,6 +702,12 @@ GNU C extensions.
 This macro expands to the name of the current input file, in the form
 of a C string constant.
 
+@item __BASE_FILE__
+@findex __BASE_FILE__
+This macro expands to the name of the main input file, in the form
+of a C string constant.  This is the source file that was specified
+as an argument when the C compiler was invoked.
+
 @item __LINE__
 @findex __LINE__
 This macro expands to the current input line number, in the form of a
@@ -675,8 +740,8 @@ if a @samp{#line} command is used.  @xre
 @findex __DATE__
 This macro expands to a string constant that describes the date on
 which the preprocessor is being run.  The string constant contains
-eleven characters and looks like @samp{"Jan 29 1987"} or @samp{"Apr
-@ 1 1905"}.
+eleven characters and looks like @samp{"Jan 29 1987"} or @w{@samp{"Apr
+1 1905"}}.
 
 @item __TIME__
 @findex __TIME__
@@ -796,27 +861,37 @@ the system.  For example,
 @end table
 
 These predefined symbols are not only nonstandard, they are contrary to the
-ANSI standard because their names do not start with underscores.  However,
-the GNU C preprocessor would be useless if it did not predefine the same
-names that are normally predefined on the system and machine you are using.
-Even system header files check the predefined names and will generate
-incorrect declarations if they do not find the names that are expected.
+ANSI standard because their names do not start with underscores.
+Therefore, the option @samp{-ansi} inhibits the definition of these
+symbols.
+
+This tends to make @samp{-ansi} useless, since many programs depend on the
+customary nonstandard predefined symbols.  Even system header files check
+them and will generate incorrect declarations if they do not find the names
+that are expected.  You might think that the header files supplied for the
+Uglix computer would not need to test what machine they are running on,
+because they can simply assume it is the Uglix; but often they do, and they
+do so using the customary names.  As a result, very few C programs will
+compile with @samp{-ansi}.  We intend to avoid such problems on the GNU
+system.
+
+What, then, should you do in an ANSI C program to test the type of machine
+it is to run on?
+
+GNU C offers a parallel series of symbols for this purpose, whose names
+are made from the customary ones by adding @samp{__} at the beginning
+and end.  Thus, the symbol @code{__vax__} would be available on a vax,
+and so on.
 
 The set of nonstandard predefined names in the GNU C preprocessor is
 controlled by the macro @samp{CPP_PREDEFINES}, which should be a string
-containing @samp{-D} options, separated by spaces.  For example, on the Sun,
-the definition
+containing @samp{-D} options, separated by spaces.  For example, on the
+Sun 3, we use the following definition:
 
 @example
 #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
 @end example
 
-@noindent
-is used.
-
-The @samp{-ansi} option which requests complete support for ANSI C
-inhibits the definition of these predefined symbols.
-
 @node Stringification, Concatenation, Predefined, Macros
 @subsection Stringification
 
@@ -1020,8 +1095,8 @@ is useful to change the definition of a
 inhibit the warning by undefining the macro with @samp{#undef} before the
 second definition.
 
-In order for a reefinition to be trivial, the new definition must exactly match
-the one already in effect, with two possible exceptions:
+In order for a redefinition to be trivial, the new definition must
+exactly match the one already in effect, with two possible exceptions:
 
 @itemize @bullet
 @item
@@ -1039,7 +1114,7 @@ Recall that a comment counts as whitespa
 @subsection Pitfalls and Subtleties of Macros
 
 In this section we describe some special rules that apply to macros and
-macro expansion, and point out certain cases in which the rules have 
+macro expansion, and point out certain cases in which the rules have
 counterintuitive consequences that you must watch out for.
 
 @menu
@@ -1096,7 +1171,7 @@ above, each occurrence of a macro argume
 In addition, another pair of parentheses usually surround the entire macro
 definition.  Here is why it is best to write macros that way.
 
-Suppose you define a macro as follows
+Suppose you define a macro as follows,
 
 @example
 #define ceil_div(x, y) (x + y - 1) / y
@@ -1120,7 +1195,7 @@ a = (b & c + sizeof (int) - 1) / sizeof
 
 @noindent
 which does not do what is intended.  The operator-precedence rules of
-C make it equivalent to this:	
+C make it equivalent to this:
 
 @example
 a = (b & (c + sizeof (int) - 1)) / sizeof (int);
@@ -1184,7 +1259,7 @@ characters:
 @noindent
 Here Backslash-Newline is used to split the macro definition, which must
 be a single line, so that it resembles the way such C code would be
-layed out if not part of a macro definition.
+laid out if not part of a macro definition.
 
 A call to this macro might be @samp{SKIP_SPACES (p, lim)}.  Strictly
 speaking, the call expands to a compound statement, which is a complete
@@ -1208,7 +1283,7 @@ makes invalid C code.
 
 The definition of the macro @samp{SKIP_SPACES} can be altered to solve
 this problem, using a @samp{do @dots{} while} statement.  Here is how:
-  
+
 @example
 #define SKIP_SPACES (p, limit)     \
 do @{ register char *lim = (limit); \
@@ -1265,7 +1340,7 @@ intended.  We say that @samp{min} is an
 
 The best solution to this problem is to define @samp{min} in a way that
 computes the value of @samp{foo (z)} only once.  The C language offers no
-way standard way to do this, but it can be done with GNU C extensions as
+standard way to do this, but it can be done with GNU C extensions as
 follows:
 
 @example
@@ -1319,12 +1394,11 @@ after one step, at @samp{(4 + foo)}.  Th
 has the possibly useful effect of causing the program to add 4 to
 the value of @samp{foo} wherever @samp{foo} is referred to.
 
-In most cases, it is a bad idea to take advantage of this feature.
-A person reading the program who sees that @samp{foo} is a variable will
-not expect that it is a macro as well.  The reader will come across a
-the identifier @samp{foo} in the program and think its value should be
-that of the variable @samp{foo}, whereas in fact the value is four
-greater.
+In most cases, it is a bad idea to take advantage of this feature.  A
+person reading the program who sees that @samp{foo} is a variable will
+not expect that it is a macro as well.  The reader will come across the
+identifier @samp{foo} in the program and think its value should be that
+of the variable @samp{foo}, whereas in fact the value is four greater.
 
 The special rule for self-reference applies also to @dfn{indirect}
 self-reference.  This is the case where a macro @var{x} expands to use a
@@ -1380,10 +1454,7 @@ what happens.  The self-references that
 marked so that they will not expand in the second scan either.
 
 The prescan is not done when an argument is stringified or concatenated.
-(More precisely, stringification and concatenation use the argument as
-written, in un-prescanned form.  The same actual argument would be used in
-prescanned form if it is substituted elsewhere without stringification or
-concatenation.)  Thus,
+Thus,
 
 @example
 #define str(s) #s
@@ -1395,9 +1466,22 @@ str (foo)
 expands to @samp{"foo"}.  Once more, prescan has been prevented from
 having any noticeable effect.
 
+More precisely, stringification and concatenation use the argument as
+written, in un-prescanned form.  The same actual argument would be used in
+prescanned form if it is substituted elsewhere without stringification or
+concatenation.
+
+@example
+#define str(s) #s lose(s)
+#define foo 4
+str (foo)
+@end example
+
+expands to @samp{"foo" lose(4)}.
+
 You might now ask, ``Why mention the prescan, if it makes no difference?
-Why not skip it and make the preprocessor faster?''  The answer is that the
-prescan does make a difference in two special cases:
+And why not skip it and make the preprocessor faster?''  The answer is
+that the prescan does make a difference in three special cases:
 
 @itemize @bullet
 @item
@@ -1405,6 +1489,9 @@ Nested calls to a macro.
 
 @item
 Macros that call other macros that stringify or concatenate.
+
+@item
+Macros whose expansions contain unshielded commas.
 @end itemize
 
 We say that @dfn{nested} calls to a macro occur when a macro's actual
@@ -1420,6 +1507,52 @@ be expanded.  Here, the prescan cancels
 (in the medical, not computational, sense of the term) of the special
 rule for self-referential macros.
 
+But prescan causes trouble in certain other cases of nested macro calls.
+Here is an example:
+
+@example
+#define foo  a,b
+#define bar(x) lose(x)
+#define lose(x) (1 + (x))
+
+bar(foo)
+@end example
+
+@noindent
+We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which
+would then turn into @samp{(1 + (a,b))}.  But instead, @samp{bar(foo)}
+expands into @samp{lose(a,b)}, and you get an error because @code{lose}
+requires a single argument.  In this case, the problem is easily solved
+by the same parentheses that ought to be used to prevent misnesting of
+arithmetic operations:
+
+@example
+#define foo (a,b)
+#define bar(x) lose((x))
+@end example
+
+The problem is more serious when the operands of the macro are not
+expressions; for example, when they are statements.  Then parentheses
+are unacceptable because they would make for invalid C code:
+
+@example
+#define foo @{ int a, b; @dots{} @}
+@end example
+
+@noindent
+In GNU C you can shield the commas using the @samp{(@{@dots{}@})}
+construct which turns a compound statement into an expression:
+
+@example
+#define foo (@{ int a, b; @dots{} @})
+@end example
+
+Or you can rewrite the macro definition to avoid such commas:
+
+@example
+#define foo @{ int a; int b; @dots{} @}
+@end example
+
 There is also one case where prescan is useful.  It is possible
 to use prescan to expand an argument and then stringify it---if you use
 two levels of macros.  Let's add a new macro @samp{xstr} to the
@@ -1437,7 +1570,7 @@ difference is that the argument of @samp
 (because @samp{xstr} does not specify stringification or concatenation of
 the argument).  The result of prescan then forms the actual argument for
 @samp{str}.  @samp{str} uses its argument without prescan because it
-performs strigification; but it cannot prevent or undo the prescanning
+performs stringification; but it cannot prevent or undo the prescanning
 already done by @samp{xstr}.
 
 @node Cascaded Macros,, Argument Prescan, Macro Pitfalls
@@ -1503,6 +1636,8 @@ on the situation at the time of compilat
 @end menu
 
 @node Conditional Uses, Conditional Syntax, Conditionals, Conditionals
+@subsection Why Conditionals are Used
+
 Generally there are three kinds of reason to use a conditional.
 
 @itemize @bullet
@@ -1532,14 +1667,14 @@ reference.
 Most simple programs that are intended to run on only one machine will
 not need to use preprocessor conditionals.
 
-@node Conditional Syntax, Conditionals-Macros, Conditional Uses, Conditionals
+@node Conditional Syntax, Deleted Code, Conditional Uses, Conditionals
 @subsection Syntax of Conditionals
 
 @findex #if
 A conditional in the C preprocessor begins with a @dfn{conditional
-command}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.@xref{Conditionals},
-for info on @samp{#ifdef} and @samp{#ifndef}; only @samp{#if} is explained
-here.
+command}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
+@xref{Conditionals-Macros}, for info on @samp{#ifdef} and
+@samp{#ifndef}; only @samp{#if} is explained here.
 
 @menu
 * If: #if Command.     Basic conditionals using @samp{#if} and @samp{#endif}.
@@ -1609,7 +1744,7 @@ However, the @samp{#if}'s and @samp{#end
 @subsubsection The @samp{#else} Command
 
 @findex #else
-The @samp{#else} command can be added a conditional to provide alternative
+The @samp{#else} command can be added to a conditional to provide alternative
 text to be used if the condition is false.  This looks like
 
 @example
@@ -1860,8 +1995,9 @@ Predefined}.
 @section Miscellaneous Preprocessor Commands
 
 @findex #pragma
+@findex #ident
 @cindex null command
-This section describes two additional preprocesor commands.  They are
+This section describes three additional preprocessor commands.  They are
 not very useful, but are mentioned for completeness.
 
 The @dfn{null command} consists of a @samp{#} followed by a Newline, with
@@ -1874,10 +2010,13 @@ some old C programs contain such lines.
 
 The @samp{#pragma} command is specified in the ANSI standard to have an
 arbitrary implementation-defined effect.  In the GNU C preprocessor,
-@samp{#pragma} first attempts to run the game @code{rogue}; if that fails,
-it tries to run the game @code{hack}; if that fails, it tries to run
-GNU Emacs displaying the Tower of Hanoi; if that fails, it reports a
-fatal error.  In any case, preprocessing does not continue.
+@samp{#pragma} commands are ignored, except for @samp{#pragma once}
+(@pxref{Once-Only}).
+
+The @samp{#ident} command is supported for compatibility with certain
+other systems.  It is followed by a line of text.  On certain systems,
+the text is copied into a special place in the object file; on most
+systems, the text is ignored and this directive has no effect.
 
 @node Output, Invocation, Other Commands, Top
 @section C Preprocessor Output
@@ -1892,15 +2031,20 @@ Source file name and line number informa
 the form
 
 @example
-# @var{linenum} @var{filename}
+# @var{linenum} @var{filename} @var{flag}
 @end example
 
 @noindent
-which are inserted as needed into the middle of the input (but never within
-a string or character constant).  Such a line means that the following line
-originated in file @var{filename} at line @var{linenum}.
+which are inserted as needed into the middle of the input (but never
+within a string or character constant).  Such a line means that the
+following line originated in file @var{filename} at line @var{linenum}.
 
-@node Invocation,, Output, Top
+The third field, @var{flag}, may be a number, or may be absent.  It is
+@samp{1} for the beginning of a new source file, and @samp{2} for return
+to an old source file at the end of an included file.  It is absent
+otherwise.
+
+@node Invocation, Concept Index, Output, Top
 @section Invoking the C Preprocessor
 
 Most often when you use the C preprocessor you will not have to invoke it
@@ -1937,15 +2081,15 @@ Do not discard comments: pass them throu
 Comments appearing in arguments of a macro call will be copied to the
 output before the expansion of the macro call.
 
-@item -T
-@findex -T
+@item -trigraphs
+@findex -trigraphs
 Process ANSI standard trigraph sequences.  These are three-character
 sequences, all starting with @samp{??}, that are defined by ANSI C to
 stand for single characters.  For example, @samp{??/} stands for
-@samp{\}, so @samp{'??/n'} is a character constant for Newline.
+@samp{\}, so @samp{'??/n'} is a character constant for a newline.
 Strictly speaking, the GNU C preprocessor does not support all
-programs in ANSI Standard C unless @samp{-T} is used, but if you
-ever notice the difference it will be with relief.
+programs in ANSI Standard C unless @samp{-trigraphs} is used, but if
+you ever notice the difference it will be with relief.
 
 You don't want to know any more about trigraphs.
 
@@ -1964,6 +2108,27 @@ header file directories.  If you use mor
 the directories are scanned in left-to-right order; the standard
 system directories come after.
 
+@item -I-
+Any directories specified with @samp{-I} options before the @samp{-I-}
+option are searched only for the case of @samp{#include "@var{file}"};
+they are not searched for @samp{#include <@var{file}>}.
+
+If additional directories are specified with @samp{-I} options after
+the @samp{-I-}, these directories are searched for all @samp{#include}
+directives.
+
+In addition, the @samp{-I-} option inhibits the use of the current
+directory as the first search directory for @samp{#include "@var{file}"}.
+Therefore, the current directory is searched only if it is requested
+explicitly with @samp{-I.}.  Specifying both @samp{-I-} and @samp{-I.}
+allows you to control precisely which directories are searched before
+the current one and which are searched after.
+
+@item -nostdinc
+Do not search the standard system directories for header files.
+Only the directories you have specified with @samp{-I} options
+(and the current directory, if appropriate) are searched.
+
 @item -D @var{name}
 @findex -D
 Predefine @var{name} as a macro, with definition @samp{1}.