From patchwork Mon Dec 19 20:09:16 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 88515 Delivered-To: patch@linaro.org Received: by 10.140.20.101 with SMTP id 92csp1354202qgi; Mon, 19 Dec 2016 12:09:53 -0800 (PST) X-Received: by 10.107.59.9 with SMTP id i9mr18912201ioa.176.1482178193927; Mon, 19 Dec 2016 12:09:53 -0800 (PST) Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id p201si14121558ioe.103.2016.12.19.12.09.53 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 19 Dec 2016 12:09:53 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-return-444797-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) client-ip=209.132.180.131; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org; spf=pass (google.com: domain of gcc-patches-return-444797-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=gcc-patches-return-444797-patch=linaro.org@gcc.gnu.org DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=XbQ4pkzl1pzA/dv2rg1MvmzimzTII7rxa2rVwGFzZBBCxdqu7R 3zBJkhJFWUmms1WqczBAGro+ApYS9JEYQWdOo+0ZH2chBmZTglABbXLbFw7mXmzd TArAIuIw+mA6273ZAV91j7a/K5e6SAGve87msUrit2cLafZ8ckYN4/0eA= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; s= default; bh=mfrpa85eGXY2FsLczZdUR8v01jY=; b=dq3CsBkgwbv7MuSXZfe5 AashQGqfAYrT+Gnt2LdRFlfsvYCJ5iTSvUd4aAPXfLeW+EitNNRzawBNDDTwgnG3 EQLErCgLq6sj7Yh2fceXu/NqKPDXBI0DZZoZMNmknOX8+wFICnJLFfUKCN85KRVq 7B0iSOfD3uR2bvR9zWCzqFA= Received: (qmail 50257 invoked by alias); 19 Dec 2016 20:09:35 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 50242 invoked by uid 89); 19 Dec 2016 20:09:34 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.6 required=5.0 tests=AWL, BAYES_50, RCVD_IN_DNSWL_NONE, SPF_PASS, URIBL_RED autolearn=ham version=3.3.2 spammy=continued, minimize, ancient, swallowing X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 19 Dec 2016 20:09:23 +0000 Received: from svr-orw-mbx-03.mgc.mentorg.com ([147.34.90.203]) by relay1.mentorg.com with esmtp id 1cJ4FM-0002Fn-P7 from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Mon, 19 Dec 2016 12:09:20 -0800 Received: from [127.0.0.1] (147.34.91.1) by svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) with Microsoft SMTP Server (TLS) id 15.0.1210.3; Mon, 19 Dec 2016 12:09:17 -0800 To: "gcc-patches@gcc.gnu.org" From: Sandra Loosemore Subject: [doc, committed] CPP manual cleanup, part 1 Message-ID: <58583E6C.8090805@codesourcery.com> Date: Mon, 19 Dec 2016 13:09:16 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.5.1 MIME-Version: 1.0 X-ClientProxiedBy: svr-orw-mbx-01.mgc.mentorg.com (147.34.90.201) To svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) I've checked in this patch to do some initial cleanup of bit-rotten content in the CPP manual. I've rewritten some passages that made it sound like C99 support is a brand-new thing, and removed text that describes how the preprocessor used to work in ancient versions of GCC. This is all routine cleanup.... I've done no checking on whether the remaining documentation is correct, whether the set of documented features corresponds to those currently implemented, etc. -Sandra Index: gcc/doc/cpp.texi =================================================================== --- gcc/doc/cpp.texi (revision 243537) +++ gcc/doc/cpp.texi (working copy) @@ -163,7 +163,6 @@ Implementation Details * Implementation-defined behavior:: * Implementation limits:: * Obsolete Features:: -* Differences from previous versions:: Obsolete Features @@ -523,8 +522,8 @@ with an optional period, a required deci with any sequence of letters, digits, underscores, periods, and exponents. Exponents are the two-character sequences @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and -@samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are new -to C99. They are used for hexadecimal floating-point constants.) +@samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are +used for hexadecimal floating-point constants.) The purpose of this unusual definition is to isolate the preprocessor from the full complexity of numeric constants. It does not have to @@ -562,10 +561,8 @@ closing quote or angle bracket. The pre file in different places depending on which form you use. @xref{Include Operation}. -No string literal may extend past the end of a line. Older versions -of GCC accepted multi-line string constants. You may use continued -lines instead, or string constant concatenation. @xref{Differences -from previous versions}. +No string literal may extend past the end of a line. You may use continued +lines instead, or string constant concatenation. @cindex punctuators @cindex digraphs @@ -1754,39 +1751,23 @@ eprintf ("success!\n") The above explanation is ambiguous about the case where the only macro parameter is a variable arguments parameter, as it is meaningless to try to distinguish whether no argument at all is an empty argument or -a missing argument. In this case the C99 standard is clear that the -comma must remain, however the existing GCC extension used to swallow -the comma. So CPP retains the comma when conforming to a specific C -standard, and drops it otherwise. +a missing argument. +CPP retains the comma when conforming to a specific C +standard. Otherwise the comma is dropped as an extension to the standard. -C99 mandates that the only place the identifier @code{@w{__VA_ARGS__}} +The C standard +mandates that the only place the identifier @code{@w{__VA_ARGS__}} can appear is in the replacement list of a variadic macro. It may not be used as a macro name, macro argument name, or within a different type of macro. It may also be forbidden in open text; the standard is ambiguous. We recommend you avoid using it except for its defined purpose. -Variadic macros are a new feature in C99. GNU CPP has supported them -for a long time, but only with a named variable argument -(@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}). If you are -concerned with portability to previous versions of GCC, you should use -only named variable arguments. On the other hand, if you are concerned -with portability to other conforming implementations of C99, you should -use only @code{@w{__VA_ARGS__}}. - -Previous versions of CPP implemented the comma-deletion extension -much more generally. We have restricted it in this release to minimize -the differences from C99. To get the same effect with both this and -previous versions of GCC, the token preceding the special @samp{##} must -be a comma, and there must be white space between that comma and -whatever comes immediately before it: - -@smallexample -#define eprintf(format, args@dots{}) fprintf (stderr, format , ##args) -@end smallexample - -@noindent -@xref{Differences from previous versions}, for the gory details. +Variadic macros became a standard part of the C language with C99. +GNU CPP previously supported them +with a named variable argument +(@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}), which +is still supported for backward compatibility. @node Predefined Macros @section Predefined Macros @@ -1854,7 +1835,7 @@ processing moves to the line after the @ A @samp{#line} directive changes @code{__LINE__}, and may change @code{__FILE__} as well. @xref{Line Control}. -C99 introduces @code{__func__}, and GCC has provided @code{__FUNCTION__} +C99 introduced @code{__func__}, and GCC has provided @code{__FUNCTION__} for a long time. Both of these are strings containing the name of the current function (there are slight semantic differences; see the GCC manual). Neither of them is a macro; the preprocessor does not know the @@ -1971,14 +1952,11 @@ The GNU Fortran compiler defines this. These macros are defined by all GNU compilers that use the C preprocessor: C, C++, Objective-C and Fortran. Their values are the major version, minor version, and patch level of the compiler, as integer -constants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3, -@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These +constants. For example, GCC version @var{x}.@var{y}.@var{z} +defines @code{__GNUC__} to @var{x}, @code{__GNUC_MINOR__} to @var{y}, +and @code{__GNUC_PATCHLEVEL__} to @var{z}. These macros are also defined if you invoke the preprocessor directly. -@code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the -widely-used development snapshots leading up to 3.0 (which identify -themselves as GCC 2.96 or 2.97, depending on which snapshot you have). - If all you need to know is whether or not your program is being compiled by GCC, or a non-GCC compiler that claims to accept the GNU C dialects, you can simply test @code{__GNUC__}. If you need to write code @@ -2021,9 +1999,8 @@ testing @code{@w{(__GNUC__ && __cplusplu GCC defines this macro if and only if the @option{-ansi} switch, or a @option{-std} switch specifying strict conformance to some version of ISO C or ISO C++, was specified when GCC was invoked. It is defined to @samp{1}. -This macro exists primarily to direct GNU libc's header files to -restrict their definitions to the minimal set found in the 1989 C -standard. +This macro exists primarily to direct GNU libc's header files to use only +definitions found in standard C. @item __BASE_FILE__ This macro expands to the name of the main input file, in the form @@ -2071,17 +2048,13 @@ definitions of any functions declared @c @item __GNUC_STDC_INLINE__ GCC defines this macro if functions declared @code{inline} will be -handled according to the ISO C99 standard. Object files will contain +handled according to the ISO C99 or later standards. Object files will contain externally visible definitions of all functions declared @code{extern inline}. They will not contain definitions of any functions declared @code{inline} without @code{extern}. If this macro is defined, GCC supports the @code{gnu_inline} function -attribute as a way to always get the gnu90 behavior. Support for -this and @code{__GNUC_GNU_INLINE__} was added in GCC 4.1.3. If -neither macro is defined, an older version of GCC is being used: -@code{inline} functions will be compiled in gnu90 mode, and the -@code{gnu_inline} function attribute will not be recognized. +attribute as a way to always get the gnu90 behavior. @item __CHAR_UNSIGNED__ GCC defines this macro if and only if the data type @code{char} is @@ -2600,18 +2573,8 @@ preprocessor will only complain if the d Occasionally it is convenient to use preprocessor directives within the arguments of a macro. The C and C++ standards declare that -behavior in these cases is undefined. - -Versions of CPP prior to 3.2 would reject such constructs with an -error message. This was the only syntactic difference between normal -functions and function-like macros, so it seemed attractive to remove -this limitation, and people would often be surprised that they could -not use macros in this way. Moreover, sometimes people would use -conditional compilation in the argument list to a normal library -function like @samp{printf}, only to find that after a library upgrade -@samp{printf} had changed to be a function-like macro, and their code -would no longer compile. So from version 3.2 we changed CPP to -successfully process arbitrary directives within macro arguments in +behavior in these cases is undefined. GNU CPP +processes arbitrary directives within macro arguments in exactly the same way as it would have processed the directive were the function-like macro invocation not present. @@ -3128,9 +3091,6 @@ course, you can only use this to exclude other preprocessing directives, and you can only do it if the code remains syntactically valid when it is not to be used. -GCC version 3 eliminates this kind of never-executed code even when -not optimizing. Older versions did it only when optimizing. - @menu * Conditional Uses:: * Conditional Syntax:: @@ -3560,10 +3520,6 @@ file it specifies, until something else constant: backslash escapes are interpreted. This is different from @samp{#include}. -Previous versions of CPP did not interpret escapes in @samp{#line}; -we have changed it because the standard requires they be interpreted, -and most other compilers do. - @item #line @var{anything else} @var{anything else} is checked for macro calls, which are expanded. The result should match one of the above two forms. @@ -3572,60 +3528,21 @@ The result should match one of the above @samp{#line} directives alter the results of the @code{__FILE__} and @code{__LINE__} predefined macros from that point on. @xref{Standard Predefined Macros}. They do not have any effect on @samp{#include}'s -idea of the directory containing the current file. This is a change -from GCC 2.95. Previously, a file reading - -@smallexample -#line 1 "../src/gram.y" -#include "gram.h" -@end smallexample - -would search for @file{gram.h} in @file{../src}, then the @option{-I} -chain; the directory containing the physical source file would not be -searched. In GCC 3.0 and later, the @samp{#include} is not affected by -the presence of a @samp{#line} referring to a different directory. - -We made this change because the old behavior caused problems when -generated source files were transported between machines. For instance, -it is common practice to ship generated parsers with a source release, -so that people building the distribution do not need to have yacc or -Bison installed. These files frequently have @samp{#line} directives -referring to the directory tree of the system where the distribution was -created. If GCC tries to search for headers in those directories, the -build is likely to fail. - -The new behavior can cause failures too, if the generated file is not -in the same directory as its source and it attempts to include a header -which would be visible searching from the directory containing the -source file. However, this problem is easily solved with an additional -@option{-I} switch on the command line. The failures caused by the old -semantics could sometimes be corrected only by editing the generated -files, which is difficult and error-prone. +idea of the directory containing the current file. @node Pragmas @chapter Pragmas The @samp{#pragma} directive is the method specified by the C standard for providing additional information to the compiler, beyond what is -conveyed in the language itself. Three forms of this directive -(commonly known as @dfn{pragmas}) are specified by the 1999 C standard. -A C compiler is free to attach any meaning it likes to other pragmas. - -GCC has historically preferred to use extensions to the syntax of the -language, such as @code{__attribute__}, for this purpose. However, GCC -does define a few pragmas of its own. These mostly have effects on the -entire translation unit or source file. - -In GCC version 3, all GNU-defined, supported pragmas have been given a -@code{GCC} prefix. This is in line with the @code{STDC} prefix on all -pragmas defined by C99. For backward compatibility, pragmas which were -recognized by previous versions are still recognized without the -@code{GCC} prefix, but that usage is deprecated. Some older pragmas are -deprecated in their entirety. They are not recognized with the -@code{GCC} prefix. @xref{Obsolete Features}. +conveyed in the language itself. The forms of this directive +(commonly known as @dfn{pragmas}) specified by C standard are prefixed with +@code{STDC}. A C compiler is free to attach any meaning it likes to other +pragmas. All GNU-defined, supported pragmas have been given a +@code{GCC} prefix. @cindex @code{_Pragma} -C99 introduces the @code{@w{_Pragma}} operator. This feature addresses a +C99 introduced the @code{@w{_Pragma}} operator. This feature addresses a major problem with @samp{#pragma}: being a directive, it cannot be produced as the result of macro expansion. @code{@w{_Pragma}} is an operator, much like @code{sizeof} or @code{defined}, and can be embedded @@ -3772,7 +3689,7 @@ to become a single space, with the excep non-directive line is preceded with sufficient spaces that it appears in the same column in the preprocessed output that it appeared in the original source file. This is so the output is easy to read. -@xref{Differences from previous versions}. CPP does not insert any +CPP does not insert any whitespace where there was none in the original source, except where necessary to prevent an accidental token paste. @@ -3829,16 +3746,18 @@ the directive name. @chapter Traditional Mode Traditional (pre-standard) C preprocessing is rather different from -the preprocessing specified by the standard. When GCC is given the +the preprocessing specified by the standard. When the preprocessor +is invoked with the @option{-traditional-cpp} option, it attempts to emulate a traditional -preprocessor. +preprocessor. -GCC versions 3.2 and later only support traditional mode semantics in -the preprocessor, and not in the compiler front ends. This chapter -outlines the traditional preprocessor semantics we implemented. +This mode is not useful for compiling C code with GCC, +but is intended for use with non-C preprocessing applications. Thus +traditional mode semantics are supported only when invoking +the preprocessor explicitly, and not in the compiler front ends. The implementation does not correspond precisely to the behavior of -earlier versions of GCC, nor to any true traditional preprocessor. +early pre-standard versions of GCC, nor to any true traditional preprocessor. After all, inconsistencies among traditional implementations were a major motivation for C standardization. However, we intend that it should be compatible with true traditional preprocessors in all ways @@ -4105,14 +4024,12 @@ affects its user-visible behavior. You reliance on behavior described here, as it is possible that it will change subtly in future implementations. -Also documented here are obsolete features and changes from previous -versions of CPP@. +Also documented here are obsolete features still supported by CPP@. @menu * Implementation-defined behavior:: * Implementation limits:: * Obsolete Features:: -* Differences from previous versions:: @end menu @node Implementation-defined behavior @@ -4139,9 +4056,9 @@ be controlled using the @option{-fexec-c @anchor{Identifier characters} The C and C++ standards allow identifiers to be composed of @samp{_} -and the alphanumeric characters. C++ and C99 also allow universal -character names, and C99 further permits implementation-defined -characters. +and the alphanumeric characters. C++ also allows universal character +names. C99 and later C standards permit both universal character +names and implementation-defined characters. GCC allows the @samp{$} character in identifiers as an extension for most targets. This is true regardless of the @option{std=} switch, @@ -4174,8 +4091,8 @@ at a time, shifting the previous value l target character, and then or-ing in the bit-pattern of the new character truncated to the width of a target character. The final bit-pattern is given type @code{int}, and is therefore signed, -regardless of whether single characters are signed or not (a slight -change from versions 3.1 and earlier of GCC)@. If there are more +regardless of whether single characters are signed or not. +If there are more characters in the constant than would fit in the target @code{int} the compiler issues a warning, and the excess leading characters are ignored. @@ -4363,96 +4280,6 @@ no effect. You can also make or cancel assertions using command-line options. @xref{Invocation}. -@node Differences from previous versions -@section Differences from previous versions -@cindex differences from previous versions - -This section details behavior which has changed from previous versions -of CPP@. We do not plan to change it again in the near future, but -we do not promise not to, either. - -The ``previous versions'' discussed here are 2.95 and before. The -behavior of GCC 3.0 is mostly the same as the behavior of the widely -used 2.96 and 2.97 development snapshots. Where there are differences, -they generally represent bugs in the snapshots. - -@itemize @bullet - -@item -I- deprecated - -This option has been deprecated in 4.0. @option{-iquote} is meant to -replace the need for this option. - -@item Order of evaluation of @samp{#} and @samp{##} operators - -The standard does not specify the order of evaluation of a chain of -@samp{##} operators, nor whether @samp{#} is evaluated before, after, or -at the same time as @samp{##}. You should therefore not write any code -which depends on any specific ordering. It is possible to guarantee an -ordering, if you need one, by suitable use of nested macros. - -An example of where this might matter is pasting the arguments @samp{1}, -@samp{e} and @samp{-2}. This would be fine for left-to-right pasting, -but right-to-left pasting would produce an invalid token @samp{e-2}. - -GCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly -left to right. Older versions evaluated all @samp{#} operators first, -then all @samp{##} operators, in an unreliable order. - -@item The form of whitespace between tokens in preprocessor output - -@xref{Preprocessor Output}, for the current textual format. This is -also the format used by stringification. Normally, the preprocessor -communicates tokens directly to the compiler's parser, and whitespace -does not come up at all. - -Older versions of GCC preserved all whitespace provided by the user and -inserted lots more whitespace of their own, because they could not -accurately predict when extra spaces were needed to prevent accidental -token pasting. - -@item Optional argument when invoking rest argument macros - -As an extension, GCC permits you to omit the variable arguments entirely -when you use a variable argument macro. This is forbidden by the 1999 C -standard, and will provoke a pedantic warning with GCC 3.0. Previous -versions accepted it silently. - -@item @samp{##} swallowing preceding text in rest argument macros - -Formerly, in a macro expansion, if @samp{##} appeared before a variable -arguments parameter, and the set of tokens specified for that argument -in the macro invocation was empty, previous versions of CPP would -back up and remove the preceding sequence of non-whitespace characters -(@strong{not} the preceding token). This extension is in direct -conflict with the 1999 C standard and has been drastically pared back. - -In the current version of the preprocessor, if @samp{##} appears between -a comma and a variable arguments parameter, and the variable argument is -omitted entirely, the comma will be removed from the expansion. If the -variable argument is empty, or the token before @samp{##} is not a -comma, then @samp{##} behaves as a normal token paste. - -@item @samp{#line} and @samp{#include} - -The @samp{#line} directive used to change GCC's notion of the -``directory containing the current file'', used by @samp{#include} with -a double-quoted header file name. In 3.0 and later, it does not. -@xref{Line Control}, for further explanation. - -@item Syntax of @samp{#line} - -In GCC 2.95 and previous, the string constant argument to @samp{#line} -was treated the same way as the argument to @samp{#include}: backslash -escapes were not honored, and the string ended at the second @samp{"}. -This is not compliant with the C standard. In GCC 3.0, an attempt was -made to correct the behavior, so that the string was treated as a real -string constant, but it turned out to be buggy. In 3.1, the bugs have -been fixed. (We are not fixing the bugs in 3.0 because they affect -relatively few people and the fix is quite invasive.) - -@end itemize - @node Invocation @chapter Invocation @cindex invocation