--- gcc/cpp.texinfo 2018/04/24 16:38:22 1.1.1.2 +++ gcc/cpp.texinfo 2018/04/24 16:51:55 1.1.1.6 @@ -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 +searches for a file named @var{file} first in the current directory, then in the same directories used for system header -files. The current working directory is tried first because it is +files. The current directory is tried first because it is presumed to be the location of the files of the program being -compiled. +compiled. (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,48 @@ 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. + +A superior way which works only in GNU C is to include the following +command in the file, preferably at the beginning: + +@example +#pragma once +@end example + +This command tells the preprocessor to ignore any future commands to +include the same file (whichever file the command appears in). The +advantage of this is that it saves the preprocessor from even having to +reread the file. + +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, despite +@samp{#pragma once}. + @node Macros, Conditionals, Header Files, Top @section Macros @@ -643,6 +695,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 +733,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 +854,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 not +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 will 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 @@ -1120,7 +1188,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); @@ -1380,10 +1448,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 +1460,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 +1483,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 +1501,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 @@ -1503,6 +1630,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 @@ -1860,8 +1989,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 preprocesor 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 +2004,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} 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 @@ -1937,15 +2070,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 +2097,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}.