@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@item
Translation time data type (TTDT) is not supported.
-@item
-Characteristics of decimal floating types are defined in header file
-@file{decfloat.h} rather than @file{float.h}.
-
@item
When the value of a decimal floating type cannot be represented in the
integer type to which it is being converted, the result is undefined
duration by compound literals (which is not possible in ISO C99, because
the initializer is not a constant).
It is handled as if the object was initialized only with the bracket
-enclosed list if compound literal's and object types match.
+enclosed list if the types of the compound literal and the object match.
The initializer list of the compound literal must be constant.
If the object being initialized has array type of unknown size, the size is
determined by compound literal size.
@code{section}, @code{constructor}, @code{destructor}, @code{used},
@code{unused}, @code{deprecated}, @code{weak}, @code{malloc},
@code{alias}, @code{warn_unused_result}, @code{nonnull},
-@code{gnu_inline} and @code{externally_visible}. Several other
-attributes are defined for functions on particular target systems. Other
-attributes, including @code{section} are supported for variables declarations
-(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}).
+@code{gnu_inline} and @code{externally_visible}, @code{hot}, @code{cold}.
+Several other attributes are defined for functions on particular target
+systems. Other attributes, including @code{section} are supported for
+variables declarations (@pxref{Variable Attributes}) and for types (@pxref{Type
+Attributes}).
You may also specify attributes with @samp{__} preceding and following
each keyword. This allows you to use them in header files without
@item gnu_inline
@cindex @code{gnu_inline} function attribute
-This attribute on an inline declaration results in the old GNU C89
-inline behavior even in the ISO C99 mode.
+This attribute should be used with a function which is also declared
+with the @code{inline} keyword. It directs GCC to treat the function
+as if it were defined in gnu89 mode even when compiling in C99 or
+gnu99 mode.
+
+If the function is declared @code{extern}, then this definition of the
+function is used only for inlining. In no case is the function
+compiled as a standalone function, not even if you take its address
+explicitly. Such an address becomes an external reference, as if you
+had only declared the function, and had not defined it. This has
+almost the effect of a macro. The way to use this is to put a
+function definition in a header file with this attribute, and put
+another copy of the function, without @code{extern}, in a library
+file. The definition in the header file will cause most calls to the
+function to be inlined. If any uses of the function remain, they will
+refer to the single copy in the library. Note that the two
+definitions of the functions need not be precisely the same, although
+if they do not have the same effect your program may behave oddly.
+
+If the function is neither @code{extern} nor @code{static}, then the
+function is compiled as a standalone function, as well as being
+inlined where possible.
+
+This is how GCC traditionally handled functions declared
+@code{inline}. Since ISO C99 specifies a different semantics for
+@code{inline}, this function attribute is provided as a transition
+measure and as a useful feature in its own right. This attribute is
+available in GCC 4.1.3 and later. It is available if either of the
+preprocessor macros @code{__GNUC_GNU_INLINE__} or
+@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
+Function is As Fast As a Macro}.
@cindex @code{flatten} function attribute
@item flatten
@item constructor
@itemx destructor
+@itemx constructor (@var{priority})
+@itemx destructor (@var{priority})
@cindex @code{constructor} function attribute
@cindex @code{destructor} function attribute
The @code{constructor} attribute causes the function to be called
initializing data that will be used implicitly during the execution of
the program.
+You may provide an optional integer priority to control the order in
+which constructor and destructor functions are run. A constructor
+with a smaller priority number runs before a constructor with a larger
+priority number; the opposite relationship holds for destructors. So,
+if you have a constructor that allocates a resource and a destructor
+that deallocates the same resource, both functions typically have the
+same priority. The priorities for constructor and destructor
+functions are the same as those specified for namespace-scope C++
+objects (@pxref{C++ Attributes}).
+
These attributes are not currently implemented for Objective-C@.
@item deprecated
Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@.
+On ARMv7-M the interrupt type is ignored, and the attribute means the function
+may be called with a word aligned stack pointer.
+
@item interrupt_handler
@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors
Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to
@item naked
@cindex function without a prologue/epilogue code
-Use this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the
-specified function does not need prologue/epilogue sequences generated by
+Use this attribute on the ARM, AVR, C4x, IP2K and SPU ports to indicate that
+the specified function does not need prologue/epilogue sequences generated by
the compiler. It is up to the programmer to provide these sequences.
@item near
The attribute @code{pure} is not implemented in GCC versions earlier
than 2.96.
+@item hot
+@cindex @code{hot} function attribute
+The @code{hot} attribute is used to inform the compiler that a function is a
+hot spot of the compiled program. The function is optimized more aggressively
+and on many target it is placed into special subsection of the text section so
+all hot functions appears close together improving locality.
+
+When profile feedback is available, via @option{-fprofile-use}, hot functions
+are automatically detected and this attribute is ignored.
+
+The @code{hot} attribute is not implemented in GCC versions earlier than 4.3.
+
+@item cold
+@cindex @code{cold} function attribute
+The @code{cold} attribute is used to inform the compiler that a function is
+unlikely executed. The function is optimized for size rather than speed and on
+many targets it is placed into special subsection of the text section so all
+cold functions appears close together improving code locality of non-cold parts
+of program. The paths leading to call of cold functions within code are marked
+as unlikely by the branch prediction mechanizm. It is thus useful to mark
+functions used to handle unlikely conditions, such as @code{perror}, as cold to
+improve optimization of hot functions that do call marked functions in rare
+occasions.
+
+When profile feedback is available, via @option{-fprofile-use}, hot functions
+are automatically detected and this attribute is ignored.
+
+The @code{hot} attribute is not implemented in GCC versions earlier than 4.3.
+
@item regparm (@var{number})
@cindex @code{regparm} attribute
@cindex functions that are passed arguments in registers on the 386
@item sseregparm
@cindex @code{sseregparm} attribute
On the Intel 386 with SSE support, the @code{sseregparm} attribute
-causes the compiler to pass up to 8 floating point arguments in
+causes the compiler to pass up to 3 floating point arguments in
SSE registers instead of on the stack. Functions that take a
variable number of arguments will continue to pass all of their
floating point arguments on the stack.
This is useful, for example, when the function is referenced only in
inline assembly.
+@item version_id
+@cindex @code{version_id} attribute on IA64 HP-UX
+This attribute, attached to a global variable or function, renames a
+symbol to contain a version string, thus allowing for function level
+versioning. HP-UX system header files may use version level functioning
+for some system calls.
+
+@smallexample
+extern int foo () __attribute__((version_id ("20040821")));
+@end smallexample
+
+Calls to @var{foo} will be mapped to calls to @var{foo@{20040821@}}.
+
@item visibility ("@var{visibility_type}")
@cindex @code{visibility} attribute
This attribute affects the linkage of the declaration to which it is attached.
For documentation of @code{altivec} attribute please see the
documentation in the @xref{PowerPC Type Attributes}, section.
+@subsection SPU Variable Attributes
+
+The SPU supports the @code{spu_vector} attribute for variables. For
+documentation of this attribute please see the documentation in the
+@xref{SPU Type Attributes}, section.
+
@subsection Xstormy16 Variable Attributes
One attribute is currently defined for xstormy16 configurations:
These attributes mainly are intended to support the @code{__vector},
@code{__pixel}, and @code{__bool} AltiVec keywords.
+@anchor{SPU Type Attributes}
+@subsection SPU Type Attributes
+
+The SPU supports the @code{spu_vector} attribute for types. This attribute
+allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
+Language Extensions Specification. It is intended to support the
+@code{__vector} keyword.
+
+
@node Inline
@section An Inline Function is As Fast As a Macro
@cindex inline functions
into their callers with the option @option{-finline-functions}.
GCC implements three different semantics of declaring a function
-inline. One is available with @option{-std=gnu89} or when @code{gnu_inline}
-attribute is present on all inline declarations, another when
-@option{-std=c99} or @option{-std=gnu99}, and the third is used when
-compiling C++.
+inline. One is available with @option{-std=gnu89} or
+@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
+on all inline declarations, another when @option{-std=c99} or
+@option{-std=gnu99} (without @option{-fgnu89-inline}), and the third
+is used when compiling C++.
To declare a function inline, use the @code{inline} keyword in its
declaration, like this:
* MIPS Paired-Single Support::
* PowerPC AltiVec Built-in Functions::
* SPARC VIS Built-in Functions::
+* SPU Built-in Functions::
@end menu
@node Alpha Built-in Functions
v8hi __builtin_ia32_pabsw128 (v8hi)
@end smallexample
+The following built-in functions are available when @option{-msse4a} is used.
+
+@smallexample
+void _mm_stream_sd (double*,__m128d);
+Generates the @code{movntsd} machine instruction.
+void _mm_stream_ss (float*,__m128);
+Generates the @code{movntss} machine instruction.
+__m128i _mm_extract_si64 (__m128i, __m128i);
+Generates the @code{extrq} machine instruction with only SSE register operands.
+__m128i _mm_extracti_si64 (__m128i, int, int);
+Generates the @code{extrq} machine instruction with SSE register and immediate operands.
+__m128i _mm_insert_si64 (__m128i, __m128i);
+Generates the @code{insertq} machine instruction with only SSE register operands.
+__m128i _mm_inserti_si64 (__m128i, __m128i, int, int);
+Generates the @code{insertq} machine instruction with SSE register and immediate operands.
+@end smallexample
+
The following built-in functions are available when @option{-m3dnow} is used.
All of them generate the machine instruction that is part of the name.
int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
@end smallexample
+@node SPU Built-in Functions
+@subsection SPU Built-in Functions
+
+GCC provides extensions for the SPU processor as described in the
+Sony/Toshiba/IBM SPU Language Extensions Specification, which can be
+found at @uref{http://cell.scei.co.jp/} or
+@uref{http://www.ibm.com/developerworks/power/cell/}. GCC's
+implementation differs in several ways.
+
+@itemize @bullet
+
+@item
+The optional extension of specifying vector constants in parentheses is
+not supported.
+
+@item
+A vector initializer requires no cast if the vector constant is of the
+same type as the variable it is initializing.
+
+@item
+If @code{signed} or @code{unsigned} is omitted, the signedness of the
+vector type is the default signedness of the base type. The default
+varies depending on the operating system, so a portable program should
+always specify the signedness.
+
+@item
+By default, the keyword @code{__vector} is added. The macro
+@code{vector} is defined in @code{<spu_intrinsics.h>} and can be
+undefined.
+
+@item
+GCC allows using a @code{typedef} name as the type specifier for a
+vector type.
+
+@item
+For C, overloaded functions are implemented with macros so the following
+does not work:
+
+@smallexample
+ spu_add ((vector signed int)@{1, 2, 3, 4@}, foo);
+@end smallexample
+
+Since @code{spu_add} is a macro, the vector constant in the example
+is treated as four separate arguments. Wrap the entire argument in
+parentheses for this to work.
+
+@item
+The extended version of @code{__builtin_expect} is not supported.
+
+@end itemize
+
+@emph{Note:} Only the interface described in the aforementioned
+specification is supported. Internally, GCC uses built-in functions to
+implement the required functionality, but these are not supported and
+are subject to change without notice.
+
@node Target Format Checks
@section Format Checks Specific to Particular Target Machines
@cindex pragma, diagnostic
Modifies the disposition of a diagnostic. Note that not all
-diagnostics are modifyiable; at the moment only warnings (normally
+diagnostics are modifiable; at the moment only warnings (normally
controlled by @samp{-W...}) can be controlled, and not all of them.
Use @option{-fdiagnostics-show-option} to determine which diagnostics
are controllable and which option controls them.
@example
#pragma GCC diagnostic warning "-Wformat"
-#pragma GCC diagnostic error "-Walways-true"
-#pragma GCC diagnostic ignored "-Walways-true"
+#pragma GCC diagnostic error "-Wformat"
+#pragma GCC diagnostic ignored "-Wformat"
@end example
Note that these pragmas override any command line options. Also,
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
-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
+standards encourage compilers to refrain from optimizations concerning
+accesses to 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 accesses to
volatile objects have stabilized and no subsequent accesses have
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
+@xref{Qualifiers implementation, , Volatile qualifier and the C compiler}.
-@smallexample
-volatile int *dst = @var{somevalue};
-volatile int *src = @var{someothervalue};
-*dst = *src;
-@end smallexample
-
-@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,
+The behavior differs slightly between C and C++ in the non-obvious cases:
@smallexample
volatile int *src = @var{somevalue};
*src;
@end smallexample
-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
+With C, such expressions are rvalues, and GCC interprets this either as a
+read of the volatile object being pointed to or only as request to evaluate
+the side-effects. 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
+that it is this lvalue to rvalue conversion which may be 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.
-
-@smallexample
-struct S;
-struct T @{int m;@};
-volatile S *ptr1 = @var{somevalue};
-volatile T *ptr2 = @var{somevalue};
-*ptr1;
-*ptr2;
-@end smallexample
-
-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)}.
+pointer to volatile object of complete type when the value is unused as
+GCC would do for an equivalent type in C. When the object has incomplete
+type, G++ issues a warning; if you wish to force an error, you must
+force a conversion to rvalue with, for instance, a static cast.
When using a reference to volatile, G++ does not treat equivalent
expressions as accesses to volatiles, but instead issues a warning that
The implicit typename extension has been deprecated and is now
removed from G++.
-The use of default arguments in function pointers, function typedefs and
+The use of default arguments in function pointers, function typedefs
and other places where they are not permitted by the standard is
deprecated and will be removed from a future version of G++.
projects / gcc.git / blobdiff