--- gcc/cpp.texinfo 2018/04/24 16:50:39 1.1.1.5 +++ gcc/cpp.texinfo 2018/04/24 16:55:39 1.1.1.9 @@ -1,10 +1,11 @@ \input texinfo @setfilename cpp.info @settitle The C Preprocessor +@setchapternewpage odd @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 @@ -30,14 +31,13 @@ into another language, under the above c @sp 6 @center @titlefont{The C Preprocessor} @sp 4 -@center First Edition -@sp 1 -@center January 1987 +@center Last revised July 1990 +@center for GCC version 1.38 @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 @@ -294,12 +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 -directory, then in the same directories used for system header -files. The current directory is tried first because it is -presumed to be the location of the files of the program being -compiled. (If the @samp{-I-} option is used, the special treatment -of the current directory is inhibited.) +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 @@ -324,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 @@ -377,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 @@ -566,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). @@ -646,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 @@ -799,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 @@ -1023,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 @@ -1042,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 @@ -1099,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 @@ -1187,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 @@ -1211,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); \ @@ -1268,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 @@ -1322,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 @@ -1499,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 @@ -1565,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 @@ -1594,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}. @@ -1671,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 @@ -1922,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 @@ -1936,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 @@ -1954,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}. + +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,, Output, Top +@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 @@ -1999,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.