-@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
the number of dynamic relocations that are needed, and by consequence,
allows the data to be read-only.
+The @code{&&foo} expressions for the same label might have different values
+if the containing function is inlined or cloned. If a program relies on
+them being always the same, @code{__attribute__((__noinline__))} should
+be used to prevent inlining. If @code{&&foo} is used
+in a static variable initializer, inlining is forbidden.
+
@node Nested Functions
@section Nested Functions
@cindex nested functions
@item interrupt
@cindex interrupt handler functions
-Use this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, m68k, MS1,
+Use this attribute on the ARM, AVR, CRX, M32C, M32R/D, m68k, MS1,
and Xstormy16 ports to indicate that the specified function is an
interrupt handler. The compiler will generate function entry and exit
sequences suitable for use in an interrupt handler when this attribute
@item l1_text
@cindex @code{l1_text} function attribute
This attribute specifies a function to be placed into L1 Instruction
-SRAM. The function will be put into a specific section named @code{.l1.text}.
+SRAM@. The function will be put into a specific section named @code{.l1.text}.
With @option{-mfdpic}, function calls with a such function as the callee
or caller will use inlined PLT.
@item naked
@cindex function without a prologue/epilogue code
-Use this attribute on the ARM, AVR, C4x, IP2K and SPU ports to indicate that
+Use this attribute on the ARM, AVR, 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.
@cindex @code{noinline} function attribute
This function attribute prevents a function from being considered for
inlining.
+@c Don't enumerate the optimizations by name here; we try to be
+@c future-compatible with this mechanism.
+If the function does not have side-effects, there are optimizations
+other than inlining that causes function calls to be optimized away,
+although the function call is live. To keep such calls from being
+optimized away, put
+@smallexample
+asm ("");
+@end smallexample
+(@pxref{Extended Asm}) in the called function, to serve as a special
+side-effect.
@item nonnull (@var{arg-index}, @dots{})
@cindex @code{nonnull} function attribute
macro of the same name. For example, you may use @code{__aligned__}
instead of @code{aligned}.
-You may specify type attributes either in a @code{typedef} declaration
-or in an enum, struct or union type declaration or definition.
+You may specify type attributes in an enum, struct or union type
+declaration or definition, or for other types in a @code{typedef}
+declaration.
For an enum, struct or union type, you may specify attributes either
between the enum, struct or union tag and the name of the type, or
as follows:
@smallexample
-typedef union
+typedef union __attribute__ ((__transparent_union__))
@{
int *__ip;
union wait *__up;
- @} wait_status_ptr_t __attribute__ ((__transparent_union__));
+ @} wait_status_ptr_t;
pid_t wait (wait_status_ptr_t);
@end smallexample
@end deftypefn
There are built-in functions added for many common string operation
-functions, e.g. for @code{memcpy} @code{__builtin___memcpy_chk}
+functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
built-in is provided. This built-in has an additional last argument,
which is the number of bytes remaining in object the @var{dest}
argument points to or @code{(size_t) -1} if the size is not known.
@end smallexample
The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
-etc. functions and can contain implementation specific flags on what
+etc.@: functions and can contain implementation specific flags on what
additional security measures the checking function might take, such as
handling @code{%n} differently.
@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
These have just one additional argument, @var{flag}, right before
format string @var{fmt}. If the compiler is able to optimize them to
-@code{fputc} etc. functions, it will, otherwise the checking function
+@code{fputc} etc.@: functions, it will, otherwise the checking function
should be called and the @var{flag} argument passed to it.
@node Other Builtins
when testing pointer or floating-point values.
@end deftypefn
+@deftypefn {Built-in Function} void __builtin_trap (void)
+This function causes the program to exit abnormally. GCC implements
+this function by using a target-dependent mechanism (such as
+intentionally executing an illegal instruction) or by calling
+@code{abort}. The mechanism used may vary from release to release so
+you should not rely on any particular implementation.
+@end deftypefn
+
@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end})
This function is used to flush the processor's instruction cache for
the region of memory between @var{begin} inclusive and @var{end}
entire vector register, interpreting it as a 128-bit integer, these use mode
@code{TI}.
-In the 64-bit mode, x86-64 family of processors uses additional built-in
+In 64-bit mode, the x86-64 family of processors uses additional built-in
functions for efficient use of @code{TF} (@code{__float128}) 128-bit
floating point and @code{TC} 128-bit complex floating point values.
-The following floating point built-in functions are made available in the
-64-bit mode. All of them implement the function that is part of the name.
+The following floating point built-in functions are available in 64-bit
+mode. All of them implement the function that is part of the name.
@smallexample
__float128 __builtin_fabsq (__float128)
v8qi __builtin_ia32_packsswb (v4hi, v4hi)
v4hi __builtin_ia32_packssdw (v2si, v2si)
v8qi __builtin_ia32_packuswb (v4hi, v4hi)
+
+v4hi __builtin_ia32_psllw (v4hi, v4hi)
+v2si __builtin_ia32_pslld (v2si, v2si)
+v1di __builtin_ia32_psllq (v1di, v1di)
+v4hi __builtin_ia32_psrlw (v4hi, v4hi)
+v2si __builtin_ia32_psrld (v2si, v2si)
+v1di __builtin_ia32_psrlq (v1di, v1di)
+v4hi __builtin_ia32_psraw (v4hi, v4hi)
+v2si __builtin_ia32_psrad (v2si, v2si)
+v4hi __builtin_ia32_psllwi (v4hi, int)
+v2si __builtin_ia32_pslldi (v2si, int)
+v1di __builtin_ia32_psllqi (v1di, int)
+v4hi __builtin_ia32_psrlwi (v4hi, int)
+v2si __builtin_ia32_psrldi (v2si, int)
+v1di __builtin_ia32_psrlqi (v1di, int)
+v4hi __builtin_ia32_psrawi (v4hi, int)
+v2si __builtin_ia32_psradi (v2si, int)
+
@end smallexample
The following built-in functions are made available either with
void __builtin_ia32_storedqu (char *, v16qi)
unsigned long long __builtin_ia32_pmuludq (v2si, v2si)
v2di __builtin_ia32_pmuludq128 (v4si, v4si)
-v8hi __builtin_ia32_psllw128 (v8hi, v2di)
-v4si __builtin_ia32_pslld128 (v4si, v2di)
-v2di __builtin_ia32_psllq128 (v4si, v2di)
-v8hi __builtin_ia32_psrlw128 (v8hi, v2di)
-v4si __builtin_ia32_psrld128 (v4si, v2di)
+v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
+v4si __builtin_ia32_pslld128 (v4si, v4si)
+v2di __builtin_ia32_psllq128 (v2di, v2di)
+v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
+v4si __builtin_ia32_psrld128 (v4si, v4si)
v2di __builtin_ia32_psrlq128 (v2di, v2di)
-v8hi __builtin_ia32_psraw128 (v8hi, v2di)
-v4si __builtin_ia32_psrad128 (v4si, v2di)
+v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
+v4si __builtin_ia32_psrad128 (v4si, v4si)
v2di __builtin_ia32_pslldqi128 (v2di, int)
v8hi __builtin_ia32_psllwi128 (v8hi, int)
v4si __builtin_ia32_pslldi128 (v4si, int)
* Weak Pragmas::
* Diagnostic Pragmas::
* Visibility Pragmas::
+* Push/Pop Macro Pragmas::
@end menu
@node ARM Pragmas
declarations.
@end table
-@c Describe c4x pragmas here.
@c Describe h8300 pragmas here.
@c Describe sh pragmas here.
@c Describe v850 pragmas here.
Increase the minimum alignment of each @var{variable} to @var{alignment}.
This is the same as GCC's @code{aligned} attribute @pxref{Variable
Attributes}). Macro expansion occurs on the arguments to this pragma
-when compiling C and Objective-C. It does not currently occur when
+when compiling C and Objective-C@. It does not currently occur when
compiling C++, but this is a bug which may be fixed in a future
release.
@node Structure-Packing Pragmas
@subsection Structure-Packing Pragmas
-For compatibility with Win32, GCC supports a set of @code{#pragma}
-directives which change the maximum alignment of members of structures
-(other than zero-width bitfields), unions, and classes subsequently
-defined. The @var{n} value below always is required to be a small power
-of two and specifies the new alignment in bytes.
+For compatibility with Microsoft Windows compilers, GCC supports a
+set of @code{#pragma} directives which change the maximum alignment of
+members of structures (other than zero-width bitfields), unions, and
+classes subsequently defined. The @var{n} value below always is required
+to be a small power of two and specifies the new alignment in bytes.
@enumerate
@item @code{#pragma pack(@var{n})} simply sets the new alignment.
@code{#pragma pack(pop)}.
@end enumerate
-Some targets, e.g. i386 and powerpc, support the @code{ms_struct}
+Some targets, e.g.@: i386 and powerpc, support the @code{ms_struct}
@code{#pragma} which lays out a structure as the documented
@code{__attribute__ ((ms_struct))}.
@enumerate
Modifies the disposition of a diagnostic. Note that not all
diagnostics are modifiable; at the moment only warnings (normally
-controlled by @samp{-W...}) can be controlled, and not all of them.
+controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
Use @option{-fdiagnostics-show-option} to determine which diagnostics
are controllable and which option controls them.
@end table
+
+@node Push/Pop Macro Pragmas
+@subsection Push/Pop Macro Pragmas
+
+For compatibility with Microsoft Windows compilers, GCC supports
+@samp{#pragma push_macro(@var{"macro_name"})}
+and @samp{#pragma pop_macro(@var{"macro_name"})}.
+
+@table @code
+@item #pragma push_macro(@var{"macro_name"})
+@cindex pragma, push_macro
+This pragma saves the value of the macro named as @var{macro_name} to
+the top of the stack for this macro.
+
+@item #pragma pop_macro(@var{"macro_name"})
+@cindex pragma, pop_macro
+This pragma sets the value of the macro named as @var{macro_name} to
+the value on top of the stack for this macro. If the stack for
+@var{macro_name} is empty, the value of the macro remains unchanged.
+@end table
+
+For example:
+
+@smallexample
+#define X 1
+#pragma push_macro("X")
+#undef X
+#define X -1
+#pragma pop_macro("X")
+int x [X];
+@end smallexample
+
+In this example, the definition of X as 1 is saved by @code{#pragma
+push_macro} and restored by @code{#pragma pop_macro}.
+
@node Unnamed Fields
@section Unnamed struct/union fields within structs/unions
@cindex struct
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 when the value is unused as
-GCC would do for an equivalent type in C. When the object has incomplete
+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.