CbC/CbC_gcc: gcc/doc/cpp.texi comparison

comparison gcc/doc/cpp.texi @ 145:1830386684a0

gcc-9.2.0

author	anatofuz
date	Thu, 13 Feb 2020 11:34:05 +0900
parents	84e7813d76e9
children

comparison

equal deleted inserted replaced

-:84e7813d76e9
+:1830386684a0
 @include gcc-common.texi
 @copying
 @c man begin COPYRIGHT
-Copyright @copyright{} 1987-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1987-2020 Free Software Foundation, Inc.
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation.  A copy of
 the license is included in the
 selected execution character set.  All other escapes are replaced by
 the character in the source character set that they represent, then
 converted to the execution character set, just like unescaped
 characters.
-In identifiers, characters outside the ASCII range can only be
+In identifiers, characters outside the ASCII range can be specified
-specified with the @samp{\u} and @samp{\U} escapes, not used
+with the @samp{\u} and @samp{\U} escapes or used directly in the input
-directly.  If strict ISO C90 conformance is specified with an option
+encoding.  If strict ISO C90 conformance is specified with an option
 such as @option{-std=c90}, or @option{-fno-extended-identifiers} is
-used, then those escapes are not permitted in identifiers.
+used, then those constructs are not permitted in identifiers.
 @node Initial processing
 @section Initial processing
 The preprocessor performs a series of textual transformations on its
 In the 1999 C standard, identifiers may contain letters which are not
 part of the ``basic source character set'', at the implementation's
 discretion (such as accented Latin letters, Greek letters, or Chinese
 ideograms).  This may be done with an extended character set, or the
-@samp{\u} and @samp{\U} escape sequences.  GCC only accepts such
+@samp{\u} and @samp{\U} escape sequences.
-characters in the @samp{\u} and @samp{\U} forms.
 As an extension, GCC treats @samp{$} as a letter.  This is for
 compatibility with some systems, such as VMS, where @samp{$} is commonly
 used in system-defined function and object names.  @samp{$} is not a
 letter in strictly conforming mode, or if you specify the @option{-$}
 Digraph:        <%  %>  <:  :>  %:  %:%:
 Punctuator:      @{   @}   [   ]   #    ##
 @end smallexample
 @cindex other tokens
-Any other single character is considered ``other''.  It is passed on to
+Any other single byte is considered ``other'' and passed on to the
-the preprocessor's output unmolested.  The C compiler will almost
+preprocessor's output unchanged.  The C compiler will almost certainly
-certainly reject source code containing ``other'' tokens.  In ASCII, the
+reject source code containing ``other'' tokens.  In ASCII, the only
-only other characters are @samp{@@}, @samp{$}, @samp{`}, and control
+``other'' characters are @samp{@@}, @samp{$}, @samp{`}, and control
 characters other than NUL (all bits zero).  (Note that @samp{$} is
-normally considered a letter.)  All characters with the high bit set
+normally considered a letter.)  All bytes with the high bit set
-(numeric range 0x7F--0xFF) are also ``other'' in the present
+(numeric range 0x7F--0xFF) that were not succesfully interpreted as
-implementation.  This will change when proper support for international
+part of an extended character in the input encoding are also ``other''
-character sets is added to GCC@.
+in the present implementation.
 NUL is a special case because of the high probability that its
 appearance is accidental, and because it may be invisible to the user
 (many terminals do not display NUL at all).  Within comments, NULs are
 silently ignored, just as any other character would be.  In running
 prevent the file from ever being read again, by either @samp{#import} or
 @samp{#include}.  You should not rely on this; do not use both
 @samp{#import} and @samp{#include} to refer to the same header file.
 Another way to prevent a header file from being included more than once
-is with the @samp{#pragma once} directive.  If @samp{#pragma once} is
+is with the @samp{#pragma once} directive (@pxref{Pragmas}).
-seen when scanning a header file, that file will never be read again, no
-matter what.
 @samp{#pragma once} does not have the problems that @samp{#import} does,
 but it is not recognized by all preprocessors, so you cannot rely on it
 in a portable program.
 @node Computed Includes
 tells GCC to consider the rest of the current include file a system
 header, no matter where it was found.  Code that comes before the
 @samp{#pragma} in the file is not affected.  @code{@w{#pragma GCC
 system_header}} has no effect in the primary source file.
 @end itemize
+On some targets, such as RS/6000 AIX, GCC implicitly surrounds all
+system headers with an @samp{extern "C"} block when compiling as C++.
 @node Macros
 @chapter Macros
 A @dfn{macro} is a fragment of code which has been given a name.
 * Ifdef::
 * If::
 * Defined::
 * Else::
 * Elif::
+* @code{__has_attribute}::
+* @code{__has_cpp_attribute}::
+* @code{__has_builtin}::
+* @code{__has_include}::
 @end menu
 @node Ifdef
 @subsection Ifdef
 @findex #ifdef
 @samp{#elif} directives within it have failed.
 @samp{#else} is allowed after any number of @samp{#elif} directives, but
 @samp{#elif} may not follow @samp{#else}.
+@node @code{__has_attribute}
+@subsection @code{__has_attribute}
+@cindex @code{__has_attribute}
+The special operator @code{__has_attribute (@var{operand})} may be used
+in @samp{#if} and @samp{#elif} expressions to test whether the attribute
+referenced by its @var{operand} is recognized by GCC.  Using the operator
+in other contexts is not valid.  In C code, @var{operand} must be
+a valid identifier.  In C++ code, @var{operand} may be optionally
+introduced by the @code{@var{attribute-scope}::} prefix.
+The @var{attribute-scope} prefix identifies the ``namespace'' within
+which the attribute is recognized.  The scope of GCC attributes is
+@samp{gnu} or @samp{__gnu__}.  The @code{__has_attribute} operator by
+itself, without any @var{operand} or parentheses, acts as a predefined
+macro so that support for it can be tested in portable code.  Thus,
+the recommended use of the operator is as follows:
+@smallexample
+#if defined __has_attribute
+#  if __has_attribute (nonnull)
+#    define ATTR_NONNULL __attribute__ ((nonnull))
+#  endif
+#endif
+@end smallexample
+The first @samp{#if} test succeeds only when the operator is supported
+by the version of GCC (or another compiler) being used.  Only when that
+test succeeds is it valid to use @code{__has_attribute} as a preprocessor
+operator.  As a result, combining the two tests into a single expression as
+shown below would only be valid with a compiler that supports the operator
+but not with others that don't.
+@smallexample
+#if defined __has_attribute && __has_attribute (nonnull)   /* not portable */
+@dots{}
+#endif
+@end smallexample
+@node @code{__has_cpp_attribute}
+@subsection @code{__has_cpp_attribute}
+@cindex @code{__has_cpp_attribute}
+The special operator @code{__has_cpp_attribute (@var{operand})} may be used
+in @samp{#if} and @samp{#elif} expressions in C++ code to test whether
+the attribute referenced by its @var{operand} is recognized by GCC.
+@code{__has_cpp_attribute (@var{operand})} is equivalent to
+@code{__has_attribute (@var{operand})} except that when @var{operand}
+designates a supported standard attribute it evaluates to an integer
+constant of the form @code{YYYYMM} indicating the year and month when
+the attribute was first introduced into the C++ standard.  For additional
+information including the dates of the introduction of current standard
+attributes, see @w{@uref{https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations/,
+SD-6: SG10 Feature Test Recommendations}}.
+@node @code{__has_builtin}
+@subsection @code{__has_builtin}
+@cindex @code{__has_builtin}
+The special operator @code{__has_builtin (@var{operand})} may be used in
+constant integer contexts and in preprocessor @samp{#if} and @samp{#elif}
+expressions to test whether the symbol named by its @var{operand} is
+recognized as a built-in function by GCC in the current language and
+conformance mode.  It evaluates to a constant integer with a nonzero
+value if the argument refers to such a function, and to zero otherwise.
+The operator may also be used in preprocessor @samp{#if} and @samp{#elif}
+expressions.  The @code{__has_builtin} operator by itself, without any
+@var{operand} or parentheses, acts as a predefined macro so that support
+for it can be tested in portable code.  Thus, the recommended use of
+the operator is as follows:
+@smallexample
+#if defined __has_builtin
+#  if __has_builtin (__builtin_object_size)
+#    define builtin_object_size(ptr) __builtin_object_size (ptr, 2)
+#  endif
+#endif
+#ifndef builtin_object_size
+#  define builtin_object_size(ptr)   ((size_t)-1)
+#endif
+@end smallexample
+@node @code{__has_include}
+@subsection @code{__has_include}
+@cindex @code{__has_include}
+The special operator @code{__has_include (@var{operand})} may be used in
+@samp{#if} and @samp{#elif} expressions to test whether the header referenced
+by its @var{operand} can be included using the @samp{#include} directive.  Using
+the operator in other contexts is not valid.  The @var{operand} takes
+the same form as the file in the @samp{#include} directive (@pxref{Include
+Syntax}) and evaluates to a nonzero value if the header can be included and
+to zero otherwise.  Note that that the ability to include a header doesn't
+imply that the header doesn't contain invalid constructs or @samp{#error}
+directives that would cause the preprocessor to fail.
+The @code{__has_include} operator by itself, without any @var{operand} or
+parentheses, acts as a predefined macro so that support for it can be tested
+in portable code.  Thus, the recommended use of the operator is as follows:
+@smallexample
+#if defined __has_include
+#  if __has_include (<stdatomic.h>)
+#    include <stdatomic.h>
+#  endif
+#endif
+@end smallexample
+The first @samp{#if} test succeeds only when the operator is supported
+by the version of GCC (or another compiler) being used.  Only when that
+test succeeds is it valid to use @code{__has_include} as a preprocessor
+operator.  As a result, combining the two tests into a single expression
+as shown below would only be valid with a compiler that supports the operator
+but not with others that don't.
+@smallexample
+#if defined __has_include && __has_include ("header.h")   /* not portable */
+@dots{}
+#endif
+@end smallexample
 @node Deleted Code
 @section Deleted Code
 @cindex commenting out code
 If you replace or delete a part of the program but want to keep the old
 idea of the directory containing the current file.
 @node Pragmas
 @chapter Pragmas
+@cindex pragma directive
 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.  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
+pragmas.  Most GNU-defined, supported pragmas have been given a
 @code{GCC} prefix.
 @cindex @code{_Pragma}
 C99 introduced the @code{@w{_Pragma}} operator.  This feature addresses a
 major problem with @samp{#pragma}: being a directive, it cannot be
 a warning diagnostic with the text @samp{message}.  The message
 contained in the pragma must be a single string literal.  Similarly,
 @code{#pragma GCC error "message"} issues an error message.  Unlike
 the @samp{#warning} and @samp{#error} directives, these pragmas can be
 embedded in preprocessor macros using @samp{_Pragma}.
+@item #pragma once
+If @code{#pragma once} is seen when scanning a header file, that
+file will never be read again, no matter what.  It is a less-portable
+alternative to using @samp{#ifndef} to guard the contents of header files
+against multiple inclusions.
 @end ftable
 @node Other Directives
 @chapter Other Directives
 @anchor{Identifier characters}
 The C and C++ standards allow identifiers to be composed of @samp{_}
 and the alphanumeric characters.  C++ also allows universal character
 names.  C99 and later C standards permit both universal character
-names and implementation-defined characters.
+names and implementation-defined characters.  In both C and C++ modes,
+GCC accepts in identifiers exactly those extended characters that
+correspond to universal character names permitted by the chosen
+standard.
 GCC allows the @samp{$} character in identifiers as an extension for
 most targets.  This is true regardless of the @option{std=} switch,
 since this extension cannot conflict with standards-conforming
 programs.  When preprocessing assembler, however, dollars are not

Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/cpp.texi @ 145:1830386684a0