@cindex functions that never return
@cindex functions that have no side effects
@cindex functions in arbitrary sections
+@cindex functions that bahave like malloc
@cindex @code{volatile} applied to function
@cindex @code{const} applied to function
@cindex functions with @code{printf}, @code{scanf} or @code{strftime} style arguments
The keyword @code{__attribute__} allows you to specify special
attributes when making a declaration. This keyword is followed by an
-attribute specification inside double parentheses. Nine attributes,
+attribute specification inside double parentheses. Ten attributes,
@code{noreturn}, @code{const}, @code{format},
-@code{no_instrument_function}, @code{section},
-@code{constructor}, @code{destructor}, @code{unused} and @code{weak} are
+@code{no_instrument_function}, @code{section}, @code{constructor},
+@code{destructor}, @code{unused}, @code{weak} and @code{malloc} are
currently defined for functions. Other attributes, including
@code{section} are supported for variables declarations (@pxref{Variable
Attributes}) and for types (@pxref{Type Attributes}).
for ELF targets, and also for a.out targets when using the GNU assembler
and linker.
+@item malloc
+@cindex @code{malloc} attribute
+The @code{malloc} attribute is used to tell the compiler that a function
+may be treated as if it were the malloc function. The compiler assumes
+that calls to malloc result in a pointers that cannot alias anything.
+This will often improve optimization.
+
@item alias ("target")
@cindex @code{alias} attribute
The @code{alias} attribute causes the declaration to be emitted as an
If you need to map the entire contents of a module to a particular
section, consider using the facilities of the linker instead.
+@item shared
+@cindex @code{shared} variable attribute
+On Windows NT, in addition to nputting variable definitions in a named
+section, the section can also be shared among all running copies of an
+executable or DLL. For example, this small program defines shared data
+by putting it in a named section "shared" and marking the section
+shareable:
+
+@smallexample
+int foo __attribute__((section ("shared"), shared)) = 0;
+
+int
+main()
+@{
+ /* Read and write foo. All running copies see the same value. */
+ return 0;
+@}
+@end smallexample
+
+@noindent
+You may only use the @code{shared} attribute along with @code{section}
+attribute with a fully initialized global definition because of the way
+linkers work. See @code{section} attribute for more information.
+
+The @code{shared} attribute is only available on Windows NT.
+
@item transparent_union
This attribute, attached to a function parameter which is a union, means
that the corresponding argument may have the type of any union member,
@end example
@findex __extension__
-@samp{-pedantic} causes warnings for many GNU C extensions. You can
+@samp{-pedantic} and other options cause warnings for many GNU C extensions.
+You can
prevent such warnings within one expression by writing
@code{__extension__} before the expression. @code{__extension__} has no
effect aside from this.
@node Function Names
@section Function Names as Strings
-GNU CC predefines two string variables to be the name of the current function.
-The variable @code{__FUNCTION__} is the name of the function as it appears
-in the source. The variable @code{__PRETTY_FUNCTION__} is the name of
-the function pretty printed in a language specific fashion.
+GNU CC predefines two magic identifiers to hold the name of the current
+function. The identifier @code{__FUNCTION__} holds the name of the function
+as it appears in the source. The identifier @code{__PRETTY_FUNCTION__}
+holds the name of the function pretty printed in a language specific
+fashion.
These names are always the same in a C function, but in a C++ function
they may be different. For example, this program:
__PRETTY_FUNCTION__ = int a::sub (int)
@end smallexample
-These names are not macros: they are predefined string variables.
-For example, @samp{#ifdef __FUNCTION__} does not have any special
+The compiler automagically replaces the identifiers with a string
+literal containing the appropriate name. Thus, they are neither
+preprocessor macros, like @code{__FILE__} and @code{__LINE__}, nor
+variables. This means that they catenate with other string literals, and
+that they can be used to initialize char arrays. For example
+
+@smallexample
+char here[] = "Function " __FUNCTION__ " in " __FILE__;
+@end smallexample
+
+On the other hand, @samp{#ifdef __FUNCTION__} does not have any special
meaning inside a function, since the preprocessor does not do anything
special with the identifier @code{__FUNCTION__}.
+GNU CC also supports the magic word @code{__func__}, defined by the
+draft standard for C-99:
+
+@display
+The identifier @code{__func__} is implicitly declared by the translator
+as if, immediately following the opening brace of each function
+definition, the declaration
+
+@smallexample
+static const char __func__[] = "function-name";
+@end smallexample
+
+appeared, where function-name is the name of the lexically-enclosing
+function. This name is the unadorned name of the function.
+@end display
+
+By this definition, @code{__func__} is a variable, not a string literal.
+In particular, @code{__func__} does not catenate with other string
+literals.
+
+In @code{C++}, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} are
+variables, declared in the same way as @code{__func__}.
+
@node Return Address
@section Getting the Return or Frame Address of a Function
standard C library. These will always be treated as having the same
meaning as the C library function even if you specify the
@samp{-fno-builtin} (@pxref{C Dialect Options}) option. These functions
-correspond to the C library functions @code{alloca}, @code{ffs},
-@code{abs}, @code{fabsf}, @code{fabs}, @code{fabsl}, @code{labs},
-@code{memcpy}, @code{memcmp}, @code{strcmp}, @code{strcpy},
-@code{strlen}, @code{sqrtf}, @code{sqrt}, @code{sqrtl}, @code{sinf},
-@code{sin}, @code{sinl}, @code{cosf}, @code{cos}, and @code{cosl}.
+correspond to the C library functions @code{abort}, @code{abs},
+@code{alloca}, @code{cos}, @code{cosf}, @code{cosl}, @code{exit},
+@code{_exit}, @code{fabs}, @code{fabsf}, @code{fabsl}, @code{ffs},
+@code{labs}, @code{memcmp}, @code{memcpy}, @code{memset}, @code{sin},
+@code{sinf}, @code{sinl}, @code{sqrt}, @code{sqrtf}, @code{sqrtl},
+@code{strcmp}, @code{strcpy}, and @code{strlen}.
@findex __builtin_constant_p
You can use the builtin function @code{__builtin_constant_p} to
@menu
* Naming Results:: Giving a name to C++ function return values.
* Min and Max:: C++ Minimum and maximum operators.
+* Volatiles:: What constitutes an access to a volatile object.
+* Restricted Pointers:: C9X restricted pointers and references.
* C++ Interface:: You can use a single C++ header file for both
declarations and definitions.
* Template Instantiation:: Methods for ensuring that exactly one copy of
handle expressions with side-effects; @w{@samp{int min = i++ <? j++;}}
works correctly.
+@node Volatiles
+@section When is a Volatile Object Accessed?
+@cindex accessing volatiles
+@cindex volatile read
+@cindex volatile write
+@cindex volatile access
+
+Both the C and C++ standard have the concept of volatile objects. These
+are normally accessed by pointers and used for accessing hardware. The
+standards encourage compilers to refrain from optimizations on
+concerning accesses to volatile objects that it might perform on
+non-volatile objects. The C standard leaves it implementation defined
+as to what constitutes a volatile access. The C++ standard omits to
+specify this, except to say that C++ should behave in a similar manner
+to C with respect to volatiles, where possible. The minimum either
+standard specifies is that at a sequence point all previous access to
+volatile objects have stabilized and no subsequent accesses have
+occurred. Thus an implementation is free to reorder and combine
+volatile accesses which occur between sequence points, but cannot do so
+for accesses across a sequence point. The use of volatiles does not
+allow you to violate the restriction on updating objects multiple times
+within a sequence point.
+
+In most expressions, it is intuitively obvious what is a read and what is
+a write. For instance
+
+@example
+volatile int *dst = <somevalue>;
+volatile int *src = <someothervalue>;
+*dst = *src;
+@end example
+
+@noindent
+will cause a read of the volatile object pointed to by @var{src} and stores the
+value into the volatile object pointed to by @var{dst}. There is no
+guarantee that these reads and writes are atomic, especially for objects
+larger than @code{int}.
+
+Less obvious expressions are where something which looks like an access
+is used in a void context. An example would be,
+
+@example
+volatile int *src = <somevalue>;
+*src;
+@end example
+
+With C, such expressions are rvalues, and as rvalues cause a read of
+the object, gcc interprets this as a read of the volatile being pointed
+to. The C++ standard specifies that such expressions do not undergo
+lvalue to rvalue conversion, and that the type of the dereferenced
+object may be incomplete. The C++ standard does not specify explicitly
+that it is this lvalue to rvalue conversion which is responsible for
+causing an access. However, there is reason to believe that it is,
+because otherwise certain simple expressions become undefined. However,
+because it would surprise most programmers, g++ treats dereferencing a
+pointer to volatile object of complete type in a void context as a read
+of the object. When the object has incomplete type, g++ issues a
+warning.
+
+@example
+struct S;
+struct T @{int m;@};
+volatile S *ptr1 = <somevalue>;
+volatile T *ptr2 = <somevalue>;
+*ptr1;
+*ptr2;
+@end example
+
+In this example, a warning is issued for @code{*ptr1}, and @code{*ptr2}
+causes a read of the object pointed to. If you wish to force an error on
+the first case, you must force a conversion to rvalue with, for instance
+a static cast, @code{static_cast<S>(*ptr1)}.
+
+When using a reference to volatile, g++ does not treat equivalent
+expressions as accesses to volatiles, but instead issues a warning that
+no volatile is accessed. The rationale for this is that otherwise it
+becomes difficult to determine where volatile access occur, and not
+possible to ignore the return value from functions returning volatile
+references. Again, if you wish to force a read, cast the reference to
+an rvalue.
+
+@node Restricted Pointers
+@section Restricting Pointer Aliasing
+@cindex restricted pointers
+@cindex restricted references
+@cindex restricted this pointer
+
+As with gcc, g++ understands the C9X proposal of restricted pointers,
+specified with the @code{__restrict__}, or @code{__restrict} type
+qualifier. Because you cannot compile C++ by specifying the -flang-isoc9x
+language flag, @code{restrict} is not a keyword in C++.
+
+In addition to allowing restricted pointers, you can specify restricted
+references, which indicate that the reference is not aliased in the local
+context.
+
+@example
+void fn (int *__restrict__ rptr, int &__restrict__ rref)
+@{
+ @dots{}
+@}
+@end example
+
+@noindent
+In the body of @code{fn}, @var{rptr} points to an unaliased integer and
+@var{rref} refers to a (different) unaliased integer.
+
+You may also specify whether a member function's @var{this} pointer is
+unaliased by using @code{__restrict__} as a member function qualifier.
+
+@example
+void T::fn () __restrict__
+@{
+ @dots{}
+@}
+@end example
+
+@noindent
+Within the body of @code{T::fn}, @var{this} will have the effective
+definition @code{T *__restrict__ const this}. Notice that the
+interpretation of a @code{__restrict__} member function qualifier is
+different to that of @code{const} or @code{volatile} qualifier, in that it
+is applied to the pointer rather than the object. This is consistent with
+other compilers which implement restricted pointers.
+
+As with all outermost parameter qualifiers, @code{__restrict__} is
+ignored in function definition matching. This means you only need to
+specify @code{__restrict__} in a function definition, rather than
+in a function prototype as well.
+
@node C++ Interface
@section Declarations and Definitions in One Header
fptr p = (fptr)(a.*fp);
@end example
+For PMF constants (i.e. expressions of the form @samp{&Klasse::Member}),
+no object is needed to obtain the address of the function. They can be
+converted to function pointers directly:
+
+@example
+fptr p1 = (fptr)(&A::foo);
+@end example
+
You must specify @samp{-Wno-pmf-conversions} to use this extension.