* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
* Long Long:: Double-word integers---@code{long long int}.
* Complex:: Data types for complex numbers.
-* Decimal Float:: Decimal Floating Point.
+* Decimal Float:: Decimal Floating Types.
* Hex Floats:: Hexadecimal floating-point constants.
* Zero Length:: Zero-length arrays.
* Variable Length:: Arrays whose length is computed at run time.
examine and set these two fictitious variables with your debugger.
@node Decimal Float
-@section Decimal Floating Point
-@cindex decimal floating point
+@section Decimal Floating Types
+@cindex decimal floating types
@cindex @code{_Decimal32} data type
@cindex @code{_Decimal64} data type
@cindex @code{_Decimal128} data type
@cindex @code{DD} integer suffix
@cindex @code{DL} integer suffix
-GNU C supports decimal floating point types in addition to the
-standard floating-point types. This extension supports decimal
-floating-point arithmetic as defined in IEEE-754R, the proposed
-revision of IEEE-754. The C language extension is defined in ISO/IEC
-DTR 24732, Draft 5. Support for this functionality will change when
-it is accepted into the C standard and might change for new drafts
-of the proposal. Calling conventions for any target might also change.
-Not all targets support decimal floating point.
+As an extension, the GNU C compiler supports decimal floating types as
+defined in the N1176 draft of ISO/IEC WDTR24732. Support for decimal
+floating types in GCC will evolve as the draft technical report changes.
+Calling conventions for any target might also change. Not all targets
+support decimal floating types.
-Support for decimal floating point includes the arithmetic operators
+The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
+@code{_Decimal128}. They use a radix of ten, unlike the floating types
+@code{float}, @code{double}, and @code{long double} whose radix is not
+specified by the C standard but is usually two.
+
+Support for decimal floating types includes the arithmetic operators
add, subtract, multiply, divide; unary arithmetic operators;
relational operators; equality operators; and conversions to and from
-integer and other floating-point types. Use a suffix @samp{df} or
+integer and other floating types. Use a suffix @samp{df} or
@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
@code{_Decimal128}.
-Passing a decimal floating-point value as an argument to a function
-without a prototype is undefined.
+GCC support of decimal float as specified by the draft technical report
+is incomplete:
+
+@itemize @bullet
+@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
+rather than the result value specified by the draft technical report.
+@end itemize
Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
are supported by the DWARF2 debug information format.
This attribute specifies how a particular function is called on
ARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options})
command line switch and @code{#pragma long_calls} settings. The
-@code{long_call} attribute causes the compiler to always call the
-function by first loading its address into a register and then using the
-contents of that register. The @code{short_call} attribute always places
+@code{long_call} attribute indicates that the function might be far
+away from the call site and require a different (more expensive)
+calling sequence. The @code{short_call} attribute always places
the offset to the function from the call site into the @samp{BL}
instruction directly.
@item longcall/shortcall
@cindex functions called via pointer on the RS/6000 and PowerPC
-On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute causes
-the compiler to always call this function via a pointer, just as it would if
-the @option{-mlongcall} option had been specified. The @code{shortcall}
-attribute causes the compiler not to do this. These attributes override
-both the @option{-mlongcall} switch and, on the RS/6000 and PowerPC, the
-@code{#pragma longcall} setting.
+On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute
+indicates that the function might be far away from the call site and
+require a different (more expensive) calling sequence. The
+@code{shortcall} attribute indicates that the function is always close
+enough for the shorter calling sequence to be used. These attributes
+override both the @option{-mlongcall} switch and, on the RS/6000 and
+PowerPC, the @code{#pragma longcall} setting.
@xref{RS/6000 and PowerPC Options}, for more information on whether long
calls are necessary.
variable number of arguments will continue to pass all of their
floating point arguments on the stack.
+@item force_align_arg_pointer
+@cindex @code{force_align_arg_pointer} attribute
+On the Intel x86, the @code{force_align_arg_pointer} attribute may be
+applied to individual function definitions, generating an alternate
+prologue and epilogue that realigns the runtime stack. This supports
+mixing legacy codes that run with a 4-byte aligned stack with modern
+codes that keep a 16-byte stack for SSE compatibility. The alternate
+prologue and epilogue are slower and bigger than the regular ones, and
+the alternate prologue requires a scratch register; this lowers the
+number of registers available if used in conjunction with the
+@code{regparm} attribute. The @code{force_align_arg_pointer}
+attribute is incompatible with nested functions; this is considered a
+hard error.
+
@item returns_twice
@cindex @code{returns_twice} attribute
The @code{returns_twice} attribute tells the compiler that a function may
@item visibility ("@var{visibility_type}")
@cindex @code{visibility} attribute
-The @code{visibility} attribute on ELF targets causes the declaration
-to be emitted with default, hidden, protected or internal visibility.
+This attribute affects the linkage of the declaration to which it is attached.
+There are four supported @var{visibility_type} values: default,
+hidden, protected or internal visibility.
@smallexample
void __attribute__ ((visibility ("protected")))
int i __attribute__ ((visibility ("hidden")));
@end smallexample
-See the ELF gABI for complete details, but the short story is:
+The possible values of @var{visibility_type} correspond to the
+visibility settings in the ELF gABI.
@table @dfn
@c keep this list of visibilities in alphabetical order.
@item default
-Default visibility is the normal case for ELF@. This value is
-available for the visibility attribute to override other options
-that may change the assumed visibility of symbols.
+Default visibility is the normal case for the object file format.
+This value is available for the visibility attribute to override other
+options that may change the assumed visibility of entities.
+
+On ELF, default visibility means that the declaration is visible to other
+modules and, in shared libraries, means that the declared entity may be
+overridden.
+
+On Darwin, default visibility means that the declaration is visible to
+other modules.
+
+Default visibility corresponds to ``external linkage'' in the language.
@item hidden
-Hidden visibility indicates that the symbol will not be placed into
-the dynamic symbol table, so no other @dfn{module} (executable or
-shared library) can reference it directly.
+Hidden visibility indicates that the entity declared will have a new
+form of linkage, which we'll call ``hidden linkage''. Two
+declarations of an object with hidden linkage refer to the same object
+if they are in the same shared object.
@item internal
Internal visibility is like hidden visibility, but with additional
-processor specific semantics. Unless otherwise specified by the psABI,
-GCC defines internal visibility to mean that the function is @emph{never}
-called from another module. Note that hidden symbols, while they cannot
-be referenced directly by other modules, can be referenced indirectly via
-function pointers. By indicating that a symbol cannot be called from
-outside the module, GCC may for instance omit the load of a PIC register
-since it is known that the calling function loaded the correct value.
+processor specific semantics. Unless otherwise specified by the
+psABI, GCC defines internal visibility to mean that a function is
+@emph{never} called from another module. Compare this with hidden
+functions which, while they cannot be referenced directly by other
+modules, can be referenced indirectly via function pointers. By
+indicating that a function cannot be called from outside the module,
+GCC may for instance omit the load of a PIC register since it is known
+that the calling function loaded the correct value.
@item protected
-Protected visibility indicates that the symbol will be placed in the
-dynamic symbol table, but that references within the defining module
-will bind to the local symbol. That is, the symbol cannot be overridden
-by another module.
+Protected visibility is like default visibility except that it
+indicates that references within the defining module will bind to the
+definition in that module. That is, the declared entity cannot be
+overridden by another module.
@end table
-Not all ELF targets support this attribute.
+All visibilities are supported on many, but not all, ELF targets
+(supported when the assembler supports the @samp{.visibility}
+pseudo-op). Default visibility is supported everywhere. Hidden
+visibility is supported on Darwin targets.
+
+The visibility attribute should be applied only to declarations which
+would otherwise have external linkage. The attribute should be applied
+consistently, so that the same entity should not be declared with
+different settings of the attribute.
+
+In C++, the visibility attribute applies to types as well as functions
+and objects, because in C++ types have linkage. A class must not have
+greater visibility than its non-static data member types and bases,
+and class members default to the visibility of their class. Also, a
+declaration without explicit visibility is limited to the visibility
+of its type.
+
+In C++, you can mark member functions and static member variables of a
+class with the visibility attribute. This is useful if if you know a
+particular method or static member variable should only be used from
+one shared object; then you can mark it hidden while the rest of the
+class has default visibility. Care must be taken to avoid breaking
+the One Definition Rule; for example, it is usually not useful to mark
+an inline method as hidden without marking the whole class as hidden.
+
+A C++ namespace declaration can also have the visibility attribute.
+This attribute applies only to the particular namespace body, not to
+other definitions of the same namespace; it is equivalent to using
+@samp{#pragma GCC visibility} before and after the namespace
+definition (@pxref{Visibility Pragmas}).
+
+In C++, if a template argument has limited visibility, this
+restriction is implicitly propagated to the template instantiation.
+Otherwise, template instantiations and specializations default to the
+visibility of their template.
+
+If both the template and enclosing class have explicit visibility, the
+visibility from the template is used.
@item warn_unused_result
@cindex @code{warn_unused_result} attribute
An attribute specifier list may appear as part of a @code{struct},
@code{union} or @code{enum} specifier. It may go either immediately
after the @code{struct}, @code{union} or @code{enum} keyword, or after
-the closing brace. It is ignored if the content of the structure, union
-or enumerated type is not defined in the specifier in which the
-attribute specifier list is used---that is, in usages such as
-@code{struct __attribute__((foo)) bar} with no following opening brace.
+the closing brace. The former syntax is preferred.
Where attribute specifiers follow the closing brace, they are considered
to relate to the structure, union or enumerated type defined, not to any
enclosing declaration the type specifier appears in, and the type
to be possibly unused. GCC will not produce a warning for this
variable.
+@item used
+This attribute, attached to a variable, means that the variable must be
+emitted even if it appears that the variable is not referenced.
+
@item vector_size (@var{bytes})
This attribute specifies the vector size for the variable, measured in
bytes. For example, the declaration:
by a constructor. In this case, the static initialization and destruction
code for the object is emitted in each translation defining the object,
but the calls to the constructor and destructor are protected by a
-link-once guard variable.
+link-once guard variable.
The @code{selectany} attribute is only available on Microsoft Windows
targets. You can use @code{__declspec (selectany)} as a synonym for
addresses).
@end table
+@anchor{i386 Variable Attributes}
@subsection i386 Variable Attributes
Two attributes are currently defined for i386 configurations:
Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
compilers to match the native Microsoft compiler.
+
+The Microsoft structure layout algorithm is fairly simple with the exception
+of the bitfield packing:
+
+The padding and alignment of members of structures and whether a bit field
+can straddle a storage-unit boundary
+
+@enumerate
+@item Structure members are stored sequentially in the order in which they are
+declared: the first member has the lowest memory address and the last member
+the highest.
+
+@item Every data object has an alignment-requirement. The alignment-requirement
+for all data except structures, unions, and arrays is either the size of the
+object or the current packing size (specified with either the aligned attribute
+or the pack pragma), whichever is less. For structures, unions, and arrays,
+the alignment-requirement is the largest alignment-requirement of its members.
+Every object is allocated an offset so that:
+
+offset % alignment-requirement == 0
+
+@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation
+unit if the integral types are the same size and if the next bit field fits
+into the current allocation unit without crossing the boundary imposed by the
+common alignment requirements of the bit fields.
+@end enumerate
+
+Handling of zero-length bitfields:
+
+MSVC interprets zero-length bitfields in the following ways:
+
+@enumerate
+@item If a zero-length bitfield is inserted between two bitfields that would
+normally be coalesced, the bitfields will not be coalesced.
+
+For example:
+
+@smallexample
+struct
+ @{
+ unsigned long bf_1 : 12;
+ unsigned long : 0;
+ unsigned long bf_2 : 12;
+ @} t1;
+@end smallexample
+
+The size of @code{t1} would be 8 bytes with the zero-length bitfield. If the
+zero-length bitfield were removed, @code{t1}'s size would be 4 bytes.
+
+@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the
+alignment of the zero-length bitfield is greater than the member that follows it,
+@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield.
+
+For example:
+
+@smallexample
+struct
+ @{
+ char foo : 4;
+ short : 0;
+ char bar;
+ @} t2;
+
+struct
+ @{
+ char foo : 4;
+ short : 0;
+ double bar;
+ @} t3;
+@end smallexample
+
+For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1.
+Accordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length
+bitfield will not affect the alignment of @code{bar} or, as a result, the size
+of the structure.
+
+Taking this into account, it is important to note the following:
+
+@enumerate
+@item If a zero-length bitfield follows a normal bitfield, the type of the
+zero-length bitfield may affect the alignment of the structure as whole. For
+example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a
+normal bitfield, and is of type short.
+
+@item Even if a zero-length bitfield is not followed by a normal bitfield, it may
+still affect the alignment of the structure:
+
+@smallexample
+struct
+ @{
+ char foo : 6;
+ long : 0;
+ @} t4;
+@end smallexample
+
+Here, @code{t4} will take up 4 bytes.
+@end enumerate
+
+@item Zero-length bitfields following non-bitfield members are ignored:
+
+@smallexample
+struct
+ @{
+ char foo;
+ long : 0;
+ char bar;
+ @} t5;
+@end smallexample
+
+Here, @code{t5} will take up 2 bytes.
+@end enumerate
@end table
+@subsection PowerPC Variable Attributes
+
+Three attributes currently are defined for PowerPC configurations:
+@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
+
+For full documentation of the struct attributes please see the
+documentation in the @xref{i386 Variable Attributes}, section.
+
+For documentation of @code{altivec} attribute please see the
+documentation in the @xref{PowerPC Type Attributes}, section.
+
@subsection Xstormy16 Variable Attributes
One attribute is currently defined for xstormy16 configurations:
@cindex type attributes
The keyword @code{__attribute__} allows you to specify special
-attributes of @code{struct} and @code{union} types when you define such
-types. This keyword is followed by an attribute specification inside
-double parentheses. Six attributes are currently defined for types:
-@code{aligned}, @code{packed}, @code{transparent_union}, @code{unused},
-@code{deprecated} and @code{may_alias}. Other attributes are defined for
-functions (@pxref{Function Attributes}) and for variables
-(@pxref{Variable Attributes}).
+attributes of @code{struct} and @code{union} types when you define
+such types. This keyword is followed by an attribute specification
+inside double parentheses. Seven attributes are currently defined for
+types: @code{aligned}, @code{packed}, @code{transparent_union},
+@code{unused}, @code{deprecated}, @code{visibility}, and
+@code{may_alias}. Other attributes are defined for functions
+(@pxref{Function Attributes}) and for variables (@pxref{Variable
+Attributes}).
You may also specify any one of these attributes with @samp{__}
preceding and following its keyword. This allows you to use these
macro of the same name. For example, you may use @code{__aligned__}
instead of @code{aligned}.
-You may specify the @code{aligned} and @code{transparent_union}
-attributes either in a @code{typedef} declaration or just past the
-closing curly brace of a complete enum, struct or union type
-@emph{definition} and the @code{packed} attribute only past the closing
-brace of a definition.
+You may specify type attributes either in a @code{typedef} declaration
+or in an enum, struct or union type declaration or definition.
-You may also specify attributes between the enum, struct or union
-tag and the name of the type rather than after the closing brace.
+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
+just past the closing curly brace of the @emph{definition}. The
+former syntax is preferred.
@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.
@item packed
This attribute, attached to @code{struct} or @code{union} type
-definition, specifies that each member of the structure or union is
-placed to minimize the memory required. When attached to an @code{enum}
-definition, it indicates that the smallest integral type should be used.
+definition, specifies that each member (other than zero-width bitfields)
+of the structure or union is placed to minimize the memory required. When
+attached to an @code{enum} definition, it indicates that the smallest
+integral type should be used.
@opindex fshort-enums
Specifying this attribute for @code{struct} and @code{union} types is
@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
above in recent GCC versions.
+@item visibility
+In C++, attribute visibility (@pxref{Function Attributes}) can also be
+applied to class, struct, union and enum types. Unlike other type
+attributes, the attribute must appear between the initial keyword and
+the name of the type; it cannot appear after the body of the type.
+
+Note that the type visibility is applied to vague linkage entities
+associated with the class (vtable, typeinfo node, etc.). In
+particular, if a class is thrown as an exception in one shared object
+and caught in another, the class must have default visibility.
+Otherwise the two shared objects will be unable to use the same
+typeinfo node and exception handling will break.
+
@subsection ARM Type Attributes
On those ARM targets that support @code{dllimport} (such as Symbian
@code{__attribute__} instead of @code{__declspec} if you prefer, but
most Symbian OS code uses @code{__declspec}.)
+@anchor{i386 Type Attributes}
@subsection i386 Type Attributes
Two attributes are currently defined for i386 configurations:
double parentheses: for example, @samp{__attribute__ ((aligned (16),
packed))}.
+@anchor{PowerPC Type Attributes}
+@subsection PowerPC Type Attributes
+
+Three attributes currently are defined for PowerPC configurations:
+@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
+
+For full documentation of the struct attributes please see the
+documentation in the @xref{i386 Type Attributes}, section.
+
+The @code{altivec} attribute allows one to declare AltiVec vector data
+types supported by the AltiVec Programming Interface Manual. The
+attribute requires an argument to specify one of three vector types:
+@code{vector__}, @code{pixel__} (always followed by unsigned short),
+and @code{bool__} (always followed by unsigned).
+
+@smallexample
+__attribute__((altivec(vector__)))
+__attribute__((altivec(pixel__))) unsigned short
+__attribute__((altivec(bool__))) unsigned
+@end smallexample
+
+These attributes mainly are intended to support the @code{__vector},
+@code{__pixel}, and @code{__bool} AltiVec keywords.
+
@node Inline
@section An Inline Function is As Fast As a Macro
@cindex inline functions
value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
@code{*@var{ptr}}.
-The ``bool'' version returns true if the comparison is successful and
+The ``bool'' version returns true if the comparison is successful and
@var{newval} was written. The ``val'' version returns the contents
of @code{*@var{ptr}} before the operation.
This builtin is not a full barrier, but rather an @dfn{acquire barrier}.
This means that references after the builtin cannot move to (or be
speculated to) before the builtin, but previous memory stores may not
-be globally visible yet, and previous memory loads may not yet be
+be globally visible yet, and previous memory loads may not yet be
satisfied.
@item void __sync_lock_release (@var{type} *ptr, ...)
@smallexample
#define foo(x) \
(@{ \
- typeof (x) tmp; \
+ typeof (x) tmp = (x); \
if (__builtin_types_compatible_p (typeof (x), long double)) \
tmp = foo_long_double (tmp); \
else if (__builtin_types_compatible_p (typeof (x), double)) \
truncated to fit the significand field provided. The significand is
forced to be a quiet NaN@.
-This function, if given a string literal, is evaluated early enough
-that it is considered a compile-time constant.
+This function, if given a string literal all of which would have been
+consumed by strtol, is evaluated early enough that it is considered a
+compile-time constant.
@end deftypefn
@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
* Structure-Packing Pragmas::
* Weak Pragmas::
* Diagnostic Pragmas::
+* Visibility Pragmas::
@end menu
@node ARM 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,
-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.
+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}
+@code{#pragma} which lays out a structure as the documented
+@code{__attribute__ ((ms_struct))}.
+@enumerate
+@item @code{#pragma ms_struct on} turns on the layout for structures
+declared.
+@item @code{#pragma ms_struct off} turns off the layout for structures
+declared.
+@item @code{#pragma ms_struct reset} goes back to the default layout.
+@end enumerate
+
@node Weak Pragmas
@subsection Weak Pragmas
@cindex pragma, weak
This pragma declares @var{symbol} to be weak, as if the declaration
had the attribute of the same name. The pragma may appear before
-or after the declaration of @var{symbol}, but must appear before
+or after the declaration of @var{symbol}, but must appear before
either its first use or its definition. It is not an error for
@var{symbol} to never be defined at all.
@end table
+@node Visibility Pragmas
+@subsection Visibility Pragmas
+
+@table @code
+@item #pragma GCC visibility push(@var{visibility})
+@itemx #pragma GCC visibility pop
+@cindex pragma, visibility
+
+This pragma allows the user to set the visibility for multiple
+declarations without having to give each a visibility attribute
+@xref{Function Attributes}, for more information about visibility and
+the attribute syntax.
+
+In C++, @samp{#pragma GCC visibility} affects only namespace-scope
+declarations. Class members and template specializations are not
+affected; if you want to override the visibility for a particular
+member or instantiation, you must use an attribute.
+
+@end table
+
@node Unnamed Fields
@section Unnamed struct/union fields within structs/unions
@cindex struct
projects / gcc.git / blobdiff