7577 lines
296 KiB
Plaintext
7577 lines
296 KiB
Plaintext
@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001,2002,
|
|
@c 2003 Free Software Foundation, Inc.
|
|
@c This is part of the GCC manual.
|
|
@c For copying conditions, see the file gcc.texi.
|
|
|
|
@node C Implementation
|
|
@chapter C Implementation-defined behavior
|
|
@cindex implementation-defined behavior, C language
|
|
|
|
A conforming implementation of ISO C is required to document its
|
|
choice of behavior in each of the areas that are designated
|
|
``implementation defined.'' The following lists all such areas,
|
|
along with the section number from the ISO/IEC 9899:1999 standard.
|
|
|
|
@menu
|
|
* Translation implementation::
|
|
* Environment implementation::
|
|
* Identifiers implementation::
|
|
* Characters implementation::
|
|
* Integers implementation::
|
|
* Floating point implementation::
|
|
* Arrays and pointers implementation::
|
|
* Hints implementation::
|
|
* Structures unions enumerations and bit-fields implementation::
|
|
* Qualifiers implementation::
|
|
* Preprocessing directives implementation::
|
|
* Library functions implementation::
|
|
* Architecture implementation::
|
|
* Locale-specific behavior implementation::
|
|
@end menu
|
|
|
|
@node Translation implementation
|
|
@section Translation
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{How a diagnostic is identified (3.10, 5.1.1.3).}
|
|
|
|
Diagnostics consist of all the output sent to stderr by GCC.
|
|
|
|
@item
|
|
@cite{Whether each nonempty sequence of white-space characters other than
|
|
new-line is retained or replaced by one space character in translation
|
|
phase 3 (5.1.1.2).}
|
|
@end itemize
|
|
|
|
@node Environment implementation
|
|
@section Environment
|
|
|
|
The behavior of these points are dependent on the implementation
|
|
of the C library, and are not defined by GCC itself.
|
|
|
|
@node Identifiers implementation
|
|
@section Identifiers
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{Which additional multibyte characters may appear in identifiers
|
|
and their correspondence to universal character names (6.4.2).}
|
|
|
|
@item
|
|
@cite{The number of significant initial characters in an identifier
|
|
(5.2.4.1, 6.4.2).}
|
|
|
|
For internal names, all characters are significant. For external names,
|
|
the number of significant characters are defined by the linker; for
|
|
almost all targets, all characters are significant.
|
|
|
|
@end itemize
|
|
|
|
@node Characters implementation
|
|
@section Characters
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{The number of bits in a byte (3.6).}
|
|
|
|
@item
|
|
@cite{The values of the members of the execution character set (5.2.1).}
|
|
|
|
@item
|
|
@cite{The unique value of the member of the execution character set produced
|
|
for each of the standard alphabetic escape sequences (5.2.2).}
|
|
|
|
@item
|
|
@cite{The value of a @code{char} object into which has been stored any
|
|
character other than a member of the basic execution character set (6.2.5).}
|
|
|
|
@item
|
|
@cite{Which of @code{signed char} or @code{unsigned char} has the same range,
|
|
representation, and behavior as ``plain'' @code{char} (6.2.5, 6.3.1.1).}
|
|
|
|
@item
|
|
@cite{The mapping of members of the source character set (in character
|
|
constants and string literals) to members of the execution character
|
|
set (6.4.4.4, 5.1.1.2).}
|
|
|
|
@item
|
|
@cite{The value of an integer character constant containing more than one
|
|
character or containing a character or escape sequence that does not map
|
|
to a single-byte execution character (6.4.4.4).}
|
|
|
|
@item
|
|
@cite{The value of a wide character constant containing more than one
|
|
multibyte character, or containing a multibyte character or escape
|
|
sequence not represented in the extended execution character set (6.4.4.4).}
|
|
|
|
@item
|
|
@cite{The current locale used to convert a wide character constant consisting
|
|
of a single multibyte character that maps to a member of the extended
|
|
execution character set into a corresponding wide character code (6.4.4.4).}
|
|
|
|
@item
|
|
@cite{The current locale used to convert a wide string literal into
|
|
corresponding wide character codes (6.4.5).}
|
|
|
|
@item
|
|
@cite{The value of a string literal containing a multibyte character or escape
|
|
sequence not represented in the execution character set (6.4.5).}
|
|
@end itemize
|
|
|
|
@node Integers implementation
|
|
@section Integers
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{Any extended integer types that exist in the implementation (6.2.5).}
|
|
|
|
@item
|
|
@cite{Whether signed integer types are represented using sign and magnitude,
|
|
two's complement, or one's complement, and whether the extraordinary value
|
|
is a trap representation or an ordinary value (6.2.6.2).}
|
|
|
|
GCC supports only two's complement integer types, and all bit patterns
|
|
are ordinary values.
|
|
|
|
@item
|
|
@cite{The rank of any extended integer type relative to another extended
|
|
integer type with the same precision (6.3.1.1).}
|
|
|
|
@item
|
|
@cite{The result of, or the signal raised by, converting an integer to a
|
|
signed integer type when the value cannot be represented in an object of
|
|
that type (6.3.1.3).}
|
|
|
|
@item
|
|
@cite{The results of some bitwise operations on signed integers (6.5).}
|
|
@end itemize
|
|
|
|
@node Floating point implementation
|
|
@section Floating point
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{The accuracy of the floating-point operations and of the library
|
|
functions in @code{<math.h>} and @code{<complex.h>} that return floating-point
|
|
results (5.2.4.2.2).}
|
|
|
|
@item
|
|
@cite{The rounding behaviors characterized by non-standard values
|
|
of @code{FLT_ROUNDS} @gol
|
|
(5.2.4.2.2).}
|
|
|
|
@item
|
|
@cite{The evaluation methods characterized by non-standard negative
|
|
values of @code{FLT_EVAL_METHOD} (5.2.4.2.2).}
|
|
|
|
@item
|
|
@cite{The direction of rounding when an integer is converted to a
|
|
floating-point number that cannot exactly represent the original
|
|
value (6.3.1.4).}
|
|
|
|
@item
|
|
@cite{The direction of rounding when a floating-point number is
|
|
converted to a narrower floating-point number (6.3.1.5).}
|
|
|
|
@item
|
|
@cite{How the nearest representable value or the larger or smaller
|
|
representable value immediately adjacent to the nearest representable
|
|
value is chosen for certain floating constants (6.4.4.2).}
|
|
|
|
@item
|
|
@cite{Whether and how floating expressions are contracted when not
|
|
disallowed by the @code{FP_CONTRACT} pragma (6.5).}
|
|
|
|
@item
|
|
@cite{The default state for the @code{FENV_ACCESS} pragma (7.6.1).}
|
|
|
|
@item
|
|
@cite{Additional floating-point exceptions, rounding modes, environments,
|
|
and classifications, and their macro names (7.6, 7.12).}
|
|
|
|
@item
|
|
@cite{The default state for the @code{FP_CONTRACT} pragma (7.12.2).}
|
|
|
|
@item
|
|
@cite{Whether the ``inexact'' floating-point exception can be raised
|
|
when the rounded result actually does equal the mathematical result
|
|
in an IEC 60559 conformant implementation (F.9).}
|
|
|
|
@item
|
|
@cite{Whether the ``underflow'' (and ``inexact'') floating-point
|
|
exception can be raised when a result is tiny but not inexact in an
|
|
IEC 60559 conformant implementation (F.9).}
|
|
|
|
@end itemize
|
|
|
|
@node Arrays and pointers implementation
|
|
@section Arrays and pointers
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{The result of converting a pointer to an integer or
|
|
vice versa (6.3.2.3).}
|
|
|
|
A cast from pointer to integer discards most-significant bits if the
|
|
pointer representation is larger than the integer type,
|
|
sign-extends@footnote{Future versions of GCC may zero-extend, or use
|
|
a target-defined @code{ptr_extend} pattern. Do not rely on sign extension.}
|
|
if the pointer representation is smaller than the integer type, otherwise
|
|
the bits are unchanged.
|
|
@c ??? We've always claimed that pointers were unsigned entities.
|
|
@c Shouldn't we therefore be doing zero-extension? If so, the bug
|
|
@c is in convert_to_integer, where we call type_for_size and request
|
|
@c a signed integral type. On the other hand, it might be most useful
|
|
@c for the target if we extend according to POINTERS_EXTEND_UNSIGNED.
|
|
|
|
A cast from integer to pointer discards most-significant bits if the
|
|
pointer representation is smaller than the integer type, extends according
|
|
to the signedness of the integer type if the pointer representation
|
|
is larger than the integer type, otherwise the bits are unchanged.
|
|
|
|
When casting from pointer to integer and back again, the resulting
|
|
pointer must reference the same object as the original pointer, otherwise
|
|
the behavior is undefined. That is, one may not use integer arithmetic to
|
|
avoid the undefined behavior of pointer arithmetic as proscribed in 6.5.6/8.
|
|
|
|
@item
|
|
@cite{The size of the result of subtracting two pointers to elements
|
|
of the same array (6.5.6).}
|
|
|
|
@end itemize
|
|
|
|
@node Hints implementation
|
|
@section Hints
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{The extent to which suggestions made by using the @code{register}
|
|
storage-class specifier are effective (6.7.1).}
|
|
|
|
The @code{register} specifier affects code generation only in these ways:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
When used as part of the register variable extension, see
|
|
@ref{Explicit Reg Vars}.
|
|
|
|
@item
|
|
When @option{-O0} is in use, the compiler allocates distinct stack
|
|
memory for all variables that do not have the @code{register}
|
|
storage-class specifier; if @code{register} is specified, the variable
|
|
may have a shorter lifespan than the code would indicate and may never
|
|
be placed in memory.
|
|
|
|
@item
|
|
On some rare x86 targets, @code{setjmp} doesn't save the registers in
|
|
all circumstances. In those cases, GCC doesn't allocate any variables
|
|
in registers unless they are marked @code{register}.
|
|
|
|
@end itemize
|
|
|
|
@item
|
|
@cite{The extent to which suggestions made by using the inline function
|
|
specifier are effective (6.7.4).}
|
|
|
|
GCC will not inline any functions if the @option{-fno-inline} option is
|
|
used or if @option{-O0} is used. Otherwise, GCC may still be unable to
|
|
inline a function for many reasons; the @option{-Winline} option may be
|
|
used to determine if a function has not been inlined and why not.
|
|
|
|
@end itemize
|
|
|
|
@node Structures unions enumerations and bit-fields implementation
|
|
@section Structures, unions, enumerations, and bit-fields
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{Whether a ``plain'' int bit-field is treated as a @code{signed int}
|
|
bit-field or as an @code{unsigned int} bit-field (6.7.2, 6.7.2.1).}
|
|
|
|
@item
|
|
@cite{Allowable bit-field types other than @code{_Bool}, @code{signed int},
|
|
and @code{unsigned int} (6.7.2.1).}
|
|
|
|
@item
|
|
@cite{Whether a bit-field can straddle a storage-unit boundary (6.7.2.1).}
|
|
|
|
@item
|
|
@cite{The order of allocation of bit-fields within a unit (6.7.2.1).}
|
|
|
|
@item
|
|
@cite{The alignment of non-bit-field members of structures (6.7.2.1).}
|
|
|
|
@item
|
|
@cite{The integer type compatible with each enumerated type (6.7.2.2).}
|
|
|
|
@end itemize
|
|
|
|
@node Qualifiers implementation
|
|
@section Qualifiers
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{What constitutes an access to an object that has volatile-qualified
|
|
type (6.7.3).}
|
|
|
|
@end itemize
|
|
|
|
@node Preprocessing directives implementation
|
|
@section Preprocessing directives
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{How sequences in both forms of header names are mapped to headers
|
|
or external source file names (6.4.7).}
|
|
|
|
@item
|
|
@cite{Whether the value of a character constant in a constant expression
|
|
that controls conditional inclusion matches the value of the same character
|
|
constant in the execution character set (6.10.1).}
|
|
|
|
@item
|
|
@cite{Whether the value of a single-character character constant in a
|
|
constant expression that controls conditional inclusion may have a
|
|
negative value (6.10.1).}
|
|
|
|
@item
|
|
@cite{The places that are searched for an included @samp{<>} delimited
|
|
header, and how the places are specified or the header is
|
|
identified (6.10.2).}
|
|
|
|
@item
|
|
@cite{How the named source file is searched for in an included @samp{""}
|
|
delimited header (6.10.2).}
|
|
|
|
@item
|
|
@cite{The method by which preprocessing tokens (possibly resulting from
|
|
macro expansion) in a @code{#include} directive are combined into a header
|
|
name (6.10.2).}
|
|
|
|
@item
|
|
@cite{The nesting limit for @code{#include} processing (6.10.2).}
|
|
|
|
GCC imposes a limit of 200 nested @code{#include}s.
|
|
|
|
@item
|
|
@cite{Whether the @samp{#} operator inserts a @samp{\} character before
|
|
the @samp{\} character that begins a universal character name in a
|
|
character constant or string literal (6.10.3.2).}
|
|
|
|
@item
|
|
@cite{The behavior on each recognized non-@code{STDC #pragma}
|
|
directive (6.10.6).}
|
|
|
|
@item
|
|
@cite{The definitions for @code{__DATE__} and @code{__TIME__} when
|
|
respectively, the date and time of translation are not available (6.10.8).}
|
|
|
|
If the date and time are not available, @code{__DATE__} expands to
|
|
@code{@w{"??? ?? ????"}} and @code{__TIME__} expands to
|
|
@code{"??:??:??"}.
|
|
|
|
@end itemize
|
|
|
|
@node Library functions implementation
|
|
@section Library functions
|
|
|
|
The behavior of these points are dependent on the implementation
|
|
of the C library, and are not defined by GCC itself.
|
|
|
|
@node Architecture implementation
|
|
@section Architecture
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{The values or expressions assigned to the macros specified in the
|
|
headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>}
|
|
(5.2.4.2, 7.18.2, 7.18.3).}
|
|
|
|
@item
|
|
@cite{The number, order, and encoding of bytes in any object
|
|
(when not explicitly specified in this International Standard) (6.2.6.1).}
|
|
|
|
@item
|
|
@cite{The value of the result of the sizeof operator (6.5.3.4).}
|
|
|
|
@end itemize
|
|
|
|
@node Locale-specific behavior implementation
|
|
@section Locale-specific behavior
|
|
|
|
The behavior of these points are dependent on the implementation
|
|
of the C library, and are not defined by GCC itself.
|
|
|
|
@node C Extensions
|
|
@chapter Extensions to the C Language Family
|
|
@cindex extensions, C language
|
|
@cindex C language extensions
|
|
|
|
@opindex pedantic
|
|
GNU C provides several language features not found in ISO standard C@.
|
|
(The @option{-pedantic} option directs GCC to print a warning message if
|
|
any of these features is used.) To test for the availability of these
|
|
features in conditional compilation, check for a predefined macro
|
|
@code{__GNUC__}, which is always defined under GCC@.
|
|
|
|
These extensions are available in C and Objective-C@. Most of them are
|
|
also available in C++. @xref{C++ Extensions,,Extensions to the
|
|
C++ Language}, for extensions that apply @emph{only} to C++.
|
|
|
|
Some features that are in ISO C99 but not C89 or C++ are also, as
|
|
extensions, accepted by GCC in C89 mode and in C++.
|
|
|
|
@menu
|
|
* Statement Exprs:: Putting statements and declarations inside expressions.
|
|
* Local Labels:: Labels local to a statement-expression.
|
|
* Labels as Values:: Getting pointers to labels, and computed gotos.
|
|
* Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
|
|
* Constructing Calls:: Dispatching a call to another function.
|
|
* Typeof:: @code{typeof}: referring to the type of an expression.
|
|
* Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
|
|
* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
|
|
* Long Long:: Double-word integers---@code{long long int}.
|
|
* Complex:: Data types for complex numbers.
|
|
* Hex Floats:: Hexadecimal floating-point constants.
|
|
* Zero Length:: Zero-length arrays.
|
|
* Variable Length:: Arrays whose length is computed at run time.
|
|
* Empty Structures:: Structures with no members.
|
|
* Variadic Macros:: Macros with a variable number of arguments.
|
|
* Escaped Newlines:: Slightly looser rules for escaped newlines.
|
|
* Subscripting:: Any array can be subscripted, even if not an lvalue.
|
|
* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
|
|
* Initializers:: Non-constant initializers.
|
|
* Compound Literals:: Compound literals give structures, unions
|
|
or arrays as values.
|
|
* Designated Inits:: Labeling elements of initializers.
|
|
* Cast to Union:: Casting to union type from any member of the union.
|
|
* Case Ranges:: `case 1 ... 9' and such.
|
|
* Mixed Declarations:: Mixing declarations and code.
|
|
* Function Attributes:: Declaring that functions have no side effects,
|
|
or that they can never return.
|
|
* Attribute Syntax:: Formal syntax for attributes.
|
|
* Function Prototypes:: Prototype declarations and old-style definitions.
|
|
* C++ Comments:: C++ comments are recognized.
|
|
* Dollar Signs:: Dollar sign is allowed in identifiers.
|
|
* Character Escapes:: @samp{\e} stands for the character @key{ESC}.
|
|
* Variable Attributes:: Specifying attributes of variables.
|
|
* Type Attributes:: Specifying attributes of types.
|
|
* Alignment:: Inquiring about the alignment of a type or variable.
|
|
* Inline:: Defining inline functions (as fast as macros).
|
|
* Extended Asm:: Assembler instructions with C expressions as operands.
|
|
(With them you can define ``built-in'' functions.)
|
|
* Constraints:: Constraints for asm operands
|
|
* Asm Labels:: Specifying the assembler name to use for a C symbol.
|
|
* Explicit Reg Vars:: Defining variables residing in specified registers.
|
|
* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
|
|
* Incomplete Enums:: @code{enum foo;}, with details to follow.
|
|
* Function Names:: Printable strings which are the name of the current
|
|
function.
|
|
* Return Address:: Getting the return or frame address of a function.
|
|
* Vector Extensions:: Using vector instructions through built-in functions.
|
|
* Other Builtins:: Other built-in functions.
|
|
* Target Builtins:: Built-in functions specific to particular targets.
|
|
* Pragmas:: Pragmas accepted by GCC.
|
|
* Unnamed Fields:: Unnamed struct/union fields within structs/unions.
|
|
* Thread-Local:: Per-thread variables.
|
|
@end menu
|
|
|
|
@node Statement Exprs
|
|
@section Statements and Declarations in Expressions
|
|
@cindex statements inside expressions
|
|
@cindex declarations inside expressions
|
|
@cindex expressions containing statements
|
|
@cindex macros, statements in expressions
|
|
|
|
@c the above section title wrapped and causes an underfull hbox.. i
|
|
@c changed it from "within" to "in". --mew 4feb93
|
|
A compound statement enclosed in parentheses may appear as an expression
|
|
in GNU C@. This allows you to use loops, switches, and local variables
|
|
within an expression.
|
|
|
|
Recall that a compound statement is a sequence of statements surrounded
|
|
by braces; in this construct, parentheses go around the braces. For
|
|
example:
|
|
|
|
@example
|
|
(@{ int y = foo (); int z;
|
|
if (y > 0) z = y;
|
|
else z = - y;
|
|
z; @})
|
|
@end example
|
|
|
|
@noindent
|
|
is a valid (though slightly more complex than necessary) expression
|
|
for the absolute value of @code{foo ()}.
|
|
|
|
The last thing in the compound statement should be an expression
|
|
followed by a semicolon; the value of this subexpression serves as the
|
|
value of the entire construct. (If you use some other kind of statement
|
|
last within the braces, the construct has type @code{void}, and thus
|
|
effectively no value.)
|
|
|
|
This feature is especially useful in making macro definitions ``safe'' (so
|
|
that they evaluate each operand exactly once). For example, the
|
|
``maximum'' function is commonly defined as a macro in standard C as
|
|
follows:
|
|
|
|
@example
|
|
#define max(a,b) ((a) > (b) ? (a) : (b))
|
|
@end example
|
|
|
|
@noindent
|
|
@cindex side effects, macro argument
|
|
But this definition computes either @var{a} or @var{b} twice, with bad
|
|
results if the operand has side effects. In GNU C, if you know the
|
|
type of the operands (here let's assume @code{int}), you can define
|
|
the macro safely as follows:
|
|
|
|
@example
|
|
#define maxint(a,b) \
|
|
(@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
|
|
@end example
|
|
|
|
Embedded statements are not allowed in constant expressions, such as
|
|
the value of an enumeration constant, the width of a bit-field, or
|
|
the initial value of a static variable.
|
|
|
|
If you don't know the type of the operand, you can still do this, but you
|
|
must use @code{typeof} (@pxref{Typeof}).
|
|
|
|
Statement expressions are not supported fully in G++, and their fate
|
|
there is unclear. (It is possible that they will become fully supported
|
|
at some point, or that they will be deprecated, or that the bugs that
|
|
are present will continue to exist indefinitely.) Presently, statement
|
|
expressions do not work well as default arguments.
|
|
|
|
In addition, there are semantic issues with statement-expressions in
|
|
C++. If you try to use statement-expressions instead of inline
|
|
functions in C++, you may be surprised at the way object destruction is
|
|
handled. For example:
|
|
|
|
@example
|
|
#define foo(a) (@{int b = (a); b + 3; @})
|
|
@end example
|
|
|
|
@noindent
|
|
does not work the same way as:
|
|
|
|
@example
|
|
inline int foo(int a) @{ int b = a; return b + 3; @}
|
|
@end example
|
|
|
|
@noindent
|
|
In particular, if the expression passed into @code{foo} involves the
|
|
creation of temporaries, the destructors for those temporaries will be
|
|
run earlier in the case of the macro than in the case of the function.
|
|
|
|
These considerations mean that it is probably a bad idea to use
|
|
statement-expressions of this form in header files that are designed to
|
|
work with C++. (Note that some versions of the GNU C Library contained
|
|
header files using statement-expression that lead to precisely this
|
|
bug.)
|
|
|
|
@node Local Labels
|
|
@section Locally Declared Labels
|
|
@cindex local labels
|
|
@cindex macros, local labels
|
|
|
|
Each statement expression is a scope in which @dfn{local labels} can be
|
|
declared. A local label is simply an identifier; you can jump to it
|
|
with an ordinary @code{goto} statement, but only from within the
|
|
statement expression it belongs to.
|
|
|
|
A local label declaration looks like this:
|
|
|
|
@example
|
|
__label__ @var{label};
|
|
@end example
|
|
|
|
@noindent
|
|
or
|
|
|
|
@example
|
|
__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
|
|
@end example
|
|
|
|
Local label declarations must come at the beginning of the statement
|
|
expression, right after the @samp{(@{}, before any ordinary
|
|
declarations.
|
|
|
|
The label declaration defines the label @emph{name}, but does not define
|
|
the label itself. You must do this in the usual way, with
|
|
@code{@var{label}:}, within the statements of the statement expression.
|
|
|
|
The local label feature is useful because statement expressions are
|
|
often used in macros. If the macro contains nested loops, a @code{goto}
|
|
can be useful for breaking out of them. However, an ordinary label
|
|
whose scope is the whole function cannot be used: if the macro can be
|
|
expanded several times in one function, the label will be multiply
|
|
defined in that function. A local label avoids this problem. For
|
|
example:
|
|
|
|
@example
|
|
#define SEARCH(array, target) \
|
|
(@{ \
|
|
__label__ found; \
|
|
typeof (target) _SEARCH_target = (target); \
|
|
typeof (*(array)) *_SEARCH_array = (array); \
|
|
int i, j; \
|
|
int value; \
|
|
for (i = 0; i < max; i++) \
|
|
for (j = 0; j < max; j++) \
|
|
if (_SEARCH_array[i][j] == _SEARCH_target) \
|
|
@{ value = i; goto found; @} \
|
|
value = -1; \
|
|
found: \
|
|
value; \
|
|
@})
|
|
@end example
|
|
|
|
@node Labels as Values
|
|
@section Labels as Values
|
|
@cindex labels as values
|
|
@cindex computed gotos
|
|
@cindex goto with computed label
|
|
@cindex address of a label
|
|
|
|
You can get the address of a label defined in the current function
|
|
(or a containing function) with the unary operator @samp{&&}. The
|
|
value has type @code{void *}. This value is a constant and can be used
|
|
wherever a constant of that type is valid. For example:
|
|
|
|
@example
|
|
void *ptr;
|
|
/* @r{@dots{}} */
|
|
ptr = &&foo;
|
|
@end example
|
|
|
|
To use these values, you need to be able to jump to one. This is done
|
|
with the computed goto statement@footnote{The analogous feature in
|
|
Fortran is called an assigned goto, but that name seems inappropriate in
|
|
C, where one can do more than simply store label addresses in label
|
|
variables.}, @code{goto *@var{exp};}. For example,
|
|
|
|
@example
|
|
goto *ptr;
|
|
@end example
|
|
|
|
@noindent
|
|
Any expression of type @code{void *} is allowed.
|
|
|
|
One way of using these constants is in initializing a static array that
|
|
will serve as a jump table:
|
|
|
|
@example
|
|
static void *array[] = @{ &&foo, &&bar, &&hack @};
|
|
@end example
|
|
|
|
Then you can select a label with indexing, like this:
|
|
|
|
@example
|
|
goto *array[i];
|
|
@end example
|
|
|
|
@noindent
|
|
Note that this does not check whether the subscript is in bounds---array
|
|
indexing in C never does that.
|
|
|
|
Such an array of label values serves a purpose much like that of the
|
|
@code{switch} statement. The @code{switch} statement is cleaner, so
|
|
use that rather than an array unless the problem does not fit a
|
|
@code{switch} statement very well.
|
|
|
|
Another use of label values is in an interpreter for threaded code.
|
|
The labels within the interpreter function can be stored in the
|
|
threaded code for super-fast dispatching.
|
|
|
|
You may not use this mechanism to jump to code in a different function.
|
|
If you do that, totally unpredictable things will happen. The best way to
|
|
avoid this is to store the label address only in automatic variables and
|
|
never pass it as an argument.
|
|
|
|
An alternate way to write the above example is
|
|
|
|
@example
|
|
static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
|
|
&&hack - &&foo @};
|
|
goto *(&&foo + array[i]);
|
|
@end example
|
|
|
|
@noindent
|
|
This is more friendly to code living in shared libraries, as it reduces
|
|
the number of dynamic relocations that are needed, and by consequence,
|
|
allows the data to be read-only.
|
|
|
|
@node Nested Functions
|
|
@section Nested Functions
|
|
@cindex nested functions
|
|
@cindex downward funargs
|
|
@cindex thunks
|
|
|
|
A @dfn{nested function} is a function defined inside another function.
|
|
(Nested functions are not supported for GNU C++.) The nested function's
|
|
name is local to the block where it is defined. For example, here we
|
|
define a nested function named @code{square}, and call it twice:
|
|
|
|
@example
|
|
@group
|
|
foo (double a, double b)
|
|
@{
|
|
double square (double z) @{ return z * z; @}
|
|
|
|
return square (a) + square (b);
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
The nested function can access all the variables of the containing
|
|
function that are visible at the point of its definition. This is
|
|
called @dfn{lexical scoping}. For example, here we show a nested
|
|
function which uses an inherited variable named @code{offset}:
|
|
|
|
@example
|
|
@group
|
|
bar (int *array, int offset, int size)
|
|
@{
|
|
int access (int *array, int index)
|
|
@{ return array[index + offset]; @}
|
|
int i;
|
|
/* @r{@dots{}} */
|
|
for (i = 0; i < size; i++)
|
|
/* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
Nested function definitions are permitted within functions in the places
|
|
where variable definitions are allowed; that is, in any block, before
|
|
the first statement in the block.
|
|
|
|
It is possible to call the nested function from outside the scope of its
|
|
name by storing its address or passing the address to another function:
|
|
|
|
@example
|
|
hack (int *array, int size)
|
|
@{
|
|
void store (int index, int value)
|
|
@{ array[index] = value; @}
|
|
|
|
intermediate (store, size);
|
|
@}
|
|
@end example
|
|
|
|
Here, the function @code{intermediate} receives the address of
|
|
@code{store} as an argument. If @code{intermediate} calls @code{store},
|
|
the arguments given to @code{store} are used to store into @code{array}.
|
|
But this technique works only so long as the containing function
|
|
(@code{hack}, in this example) does not exit.
|
|
|
|
If you try to call the nested function through its address after the
|
|
containing function has exited, all hell will break loose. If you try
|
|
to call it after a containing scope level has exited, and if it refers
|
|
to some of the variables that are no longer in scope, you may be lucky,
|
|
but it's not wise to take the risk. If, however, the nested function
|
|
does not refer to anything that has gone out of scope, you should be
|
|
safe.
|
|
|
|
GCC implements taking the address of a nested function using a technique
|
|
called @dfn{trampolines}. A paper describing them is available as
|
|
|
|
@noindent
|
|
@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}.
|
|
|
|
A nested function can jump to a label inherited from a containing
|
|
function, provided the label was explicitly declared in the containing
|
|
function (@pxref{Local Labels}). Such a jump returns instantly to the
|
|
containing function, exiting the nested function which did the
|
|
@code{goto} and any intermediate functions as well. Here is an example:
|
|
|
|
@example
|
|
@group
|
|
bar (int *array, int offset, int size)
|
|
@{
|
|
__label__ failure;
|
|
int access (int *array, int index)
|
|
@{
|
|
if (index > size)
|
|
goto failure;
|
|
return array[index + offset];
|
|
@}
|
|
int i;
|
|
/* @r{@dots{}} */
|
|
for (i = 0; i < size; i++)
|
|
/* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
|
|
/* @r{@dots{}} */
|
|
return 0;
|
|
|
|
/* @r{Control comes here from @code{access}
|
|
if it detects an error.} */
|
|
failure:
|
|
return -1;
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
A nested function always has internal linkage. Declaring one with
|
|
@code{extern} is erroneous. If you need to declare the nested function
|
|
before its definition, use @code{auto} (which is otherwise meaningless
|
|
for function declarations).
|
|
|
|
@example
|
|
bar (int *array, int offset, int size)
|
|
@{
|
|
__label__ failure;
|
|
auto int access (int *, int);
|
|
/* @r{@dots{}} */
|
|
int access (int *array, int index)
|
|
@{
|
|
if (index > size)
|
|
goto failure;
|
|
return array[index + offset];
|
|
@}
|
|
/* @r{@dots{}} */
|
|
@}
|
|
@end example
|
|
|
|
@node Constructing Calls
|
|
@section Constructing Function Calls
|
|
@cindex constructing calls
|
|
@cindex forwarding calls
|
|
|
|
Using the built-in functions described below, you can record
|
|
the arguments a function received, and call another function
|
|
with the same arguments, without knowing the number or types
|
|
of the arguments.
|
|
|
|
You can also record the return value of that function call,
|
|
and later return that value, without knowing what data type
|
|
the function tried to return (as long as your caller expects
|
|
that data type).
|
|
|
|
@deftypefn {Built-in Function} {void *} __builtin_apply_args ()
|
|
This built-in function returns a pointer to data
|
|
describing how to perform a call with the same arguments as were passed
|
|
to the current function.
|
|
|
|
The function saves the arg pointer register, structure value address,
|
|
and all registers that might be used to pass arguments to a function
|
|
into a block of memory allocated on the stack. Then it returns the
|
|
address of that block.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
|
|
This built-in function invokes @var{function}
|
|
with a copy of the parameters described by @var{arguments}
|
|
and @var{size}.
|
|
|
|
The value of @var{arguments} should be the value returned by
|
|
@code{__builtin_apply_args}. The argument @var{size} specifies the size
|
|
of the stack argument data, in bytes.
|
|
|
|
This function returns a pointer to data describing
|
|
how to return whatever value was returned by @var{function}. The data
|
|
is saved in a block of memory allocated on the stack.
|
|
|
|
It is not always simple to compute the proper value for @var{size}. The
|
|
value is used by @code{__builtin_apply} to compute the amount of data
|
|
that should be pushed on the stack and copied from the incoming argument
|
|
area.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
|
|
This built-in function returns the value described by @var{result} from
|
|
the containing function. You should specify, for @var{result}, a value
|
|
returned by @code{__builtin_apply}.
|
|
@end deftypefn
|
|
|
|
@node Typeof
|
|
@section Referring to a Type with @code{typeof}
|
|
@findex typeof
|
|
@findex sizeof
|
|
@cindex macros, types of arguments
|
|
|
|
Another way to refer to the type of an expression is with @code{typeof}.
|
|
The syntax of using of this keyword looks like @code{sizeof}, but the
|
|
construct acts semantically like a type name defined with @code{typedef}.
|
|
|
|
There are two ways of writing the argument to @code{typeof}: with an
|
|
expression or with a type. Here is an example with an expression:
|
|
|
|
@example
|
|
typeof (x[0](1))
|
|
@end example
|
|
|
|
@noindent
|
|
This assumes that @code{x} is an array of pointers to functions;
|
|
the type described is that of the values of the functions.
|
|
|
|
Here is an example with a typename as the argument:
|
|
|
|
@example
|
|
typeof (int *)
|
|
@end example
|
|
|
|
@noindent
|
|
Here the type described is that of pointers to @code{int}.
|
|
|
|
If you are writing a header file that must work when included in ISO C
|
|
programs, write @code{__typeof__} instead of @code{typeof}.
|
|
@xref{Alternate Keywords}.
|
|
|
|
A @code{typeof}-construct can be used anywhere a typedef name could be
|
|
used. For example, you can use it in a declaration, in a cast, or inside
|
|
of @code{sizeof} or @code{typeof}.
|
|
|
|
@code{typeof} is often useful in conjunction with the
|
|
statements-within-expressions feature. Here is how the two together can
|
|
be used to define a safe ``maximum'' macro that operates on any
|
|
arithmetic type and evaluates each of its arguments exactly once:
|
|
|
|
@example
|
|
#define max(a,b) \
|
|
(@{ typeof (a) _a = (a); \
|
|
typeof (b) _b = (b); \
|
|
_a > _b ? _a : _b; @})
|
|
@end example
|
|
|
|
@cindex underscores in variables in macros
|
|
@cindex @samp{_} in variables in macros
|
|
@cindex local variables in macros
|
|
@cindex variables, local, in macros
|
|
@cindex macros, local variables in
|
|
|
|
The reason for using names that start with underscores for the local
|
|
variables is to avoid conflicts with variable names that occur within the
|
|
expressions that are substituted for @code{a} and @code{b}. Eventually we
|
|
hope to design a new form of declaration syntax that allows you to declare
|
|
variables whose scopes start only after their initializers; this will be a
|
|
more reliable way to prevent such conflicts.
|
|
|
|
@noindent
|
|
Some more examples of the use of @code{typeof}:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
This declares @code{y} with the type of what @code{x} points to.
|
|
|
|
@example
|
|
typeof (*x) y;
|
|
@end example
|
|
|
|
@item
|
|
This declares @code{y} as an array of such values.
|
|
|
|
@example
|
|
typeof (*x) y[4];
|
|
@end example
|
|
|
|
@item
|
|
This declares @code{y} as an array of pointers to characters:
|
|
|
|
@example
|
|
typeof (typeof (char *)[4]) y;
|
|
@end example
|
|
|
|
@noindent
|
|
It is equivalent to the following traditional C declaration:
|
|
|
|
@example
|
|
char *y[4];
|
|
@end example
|
|
|
|
To see the meaning of the declaration using @code{typeof}, and why it
|
|
might be a useful way to write, let's rewrite it with these macros:
|
|
|
|
@example
|
|
#define pointer(T) typeof(T *)
|
|
#define array(T, N) typeof(T [N])
|
|
@end example
|
|
|
|
@noindent
|
|
Now the declaration can be rewritten this way:
|
|
|
|
@example
|
|
array (pointer (char), 4) y;
|
|
@end example
|
|
|
|
@noindent
|
|
Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
|
|
pointers to @code{char}.
|
|
@end itemize
|
|
|
|
@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported
|
|
a more limited extension which permitted one to write
|
|
|
|
@example
|
|
typedef @var{T} = @var{expr};
|
|
@end example
|
|
|
|
@noindent
|
|
with the effect of declaring @var{T} to have the type of the expression
|
|
@var{expr}. This extension does not work with GCC 3 (versions between
|
|
3.0 and 3.2 will crash; 3.2.1 and later give an error). Code which
|
|
relies on it should be rewritten to use @code{typeof}:
|
|
|
|
@example
|
|
typedef typeof(@var{expr}) @var{T};
|
|
@end example
|
|
|
|
@noindent
|
|
This will work with all versions of GCC@.
|
|
|
|
@node Lvalues
|
|
@section Generalized Lvalues
|
|
@cindex compound expressions as lvalues
|
|
@cindex expressions, compound, as lvalues
|
|
@cindex conditional expressions as lvalues
|
|
@cindex expressions, conditional, as lvalues
|
|
@cindex casts as lvalues
|
|
@cindex generalized lvalues
|
|
@cindex lvalues, generalized
|
|
@cindex extensions, @code{?:}
|
|
@cindex @code{?:} extensions
|
|
|
|
Compound expressions, conditional expressions and casts are allowed as
|
|
lvalues provided their operands are lvalues. This means that you can take
|
|
their addresses or store values into them.
|
|
|
|
Standard C++ allows compound expressions and conditional expressions as
|
|
lvalues, and permits casts to reference type, so use of this extension
|
|
is deprecated for C++ code.
|
|
|
|
For example, a compound expression can be assigned, provided the last
|
|
expression in the sequence is an lvalue. These two expressions are
|
|
equivalent:
|
|
|
|
@example
|
|
(a, b) += 5
|
|
a, (b += 5)
|
|
@end example
|
|
|
|
Similarly, the address of the compound expression can be taken. These two
|
|
expressions are equivalent:
|
|
|
|
@example
|
|
&(a, b)
|
|
a, &b
|
|
@end example
|
|
|
|
A conditional expression is a valid lvalue if its type is not void and the
|
|
true and false branches are both valid lvalues. For example, these two
|
|
expressions are equivalent:
|
|
|
|
@example
|
|
(a ? b : c) = 5
|
|
(a ? b = 5 : (c = 5))
|
|
@end example
|
|
|
|
A cast is a valid lvalue if its operand is an lvalue. A simple
|
|
assignment whose left-hand side is a cast works by converting the
|
|
right-hand side first to the specified type, then to the type of the
|
|
inner left-hand side expression. After this is stored, the value is
|
|
converted back to the specified type to become the value of the
|
|
assignment. Thus, if @code{a} has type @code{char *}, the following two
|
|
expressions are equivalent:
|
|
|
|
@example
|
|
(int)a = 5
|
|
(int)(a = (char *)(int)5)
|
|
@end example
|
|
|
|
An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
|
|
performs the arithmetic using the type resulting from the cast, and then
|
|
continues as in the previous case. Therefore, these two expressions are
|
|
equivalent:
|
|
|
|
@example
|
|
(int)a += 5
|
|
(int)(a = (char *)(int) ((int)a + 5))
|
|
@end example
|
|
|
|
You cannot take the address of an lvalue cast, because the use of its
|
|
address would not work out coherently. Suppose that @code{&(int)f} were
|
|
permitted, where @code{f} has type @code{float}. Then the following
|
|
statement would try to store an integer bit-pattern where a floating
|
|
point number belongs:
|
|
|
|
@example
|
|
*&(int)f = 1;
|
|
@end example
|
|
|
|
This is quite different from what @code{(int)f = 1} would do---that
|
|
would convert 1 to floating point and store it. Rather than cause this
|
|
inconsistency, we think it is better to prohibit use of @samp{&} on a cast.
|
|
|
|
If you really do want an @code{int *} pointer with the address of
|
|
@code{f}, you can simply write @code{(int *)&f}.
|
|
|
|
@node Conditionals
|
|
@section Conditionals with Omitted Operands
|
|
@cindex conditional expressions, extensions
|
|
@cindex omitted middle-operands
|
|
@cindex middle-operands, omitted
|
|
@cindex extensions, @code{?:}
|
|
@cindex @code{?:} extensions
|
|
|
|
The middle operand in a conditional expression may be omitted. Then
|
|
if the first operand is nonzero, its value is the value of the conditional
|
|
expression.
|
|
|
|
Therefore, the expression
|
|
|
|
@example
|
|
x ? : y
|
|
@end example
|
|
|
|
@noindent
|
|
has the value of @code{x} if that is nonzero; otherwise, the value of
|
|
@code{y}.
|
|
|
|
This example is perfectly equivalent to
|
|
|
|
@example
|
|
x ? x : y
|
|
@end example
|
|
|
|
@cindex side effect in ?:
|
|
@cindex ?: side effect
|
|
@noindent
|
|
In this simple case, the ability to omit the middle operand is not
|
|
especially useful. When it becomes useful is when the first operand does,
|
|
or may (if it is a macro argument), contain a side effect. Then repeating
|
|
the operand in the middle would perform the side effect twice. Omitting
|
|
the middle operand uses the value already computed without the undesirable
|
|
effects of recomputing it.
|
|
|
|
@node Long Long
|
|
@section Double-Word Integers
|
|
@cindex @code{long long} data types
|
|
@cindex double-word arithmetic
|
|
@cindex multiprecision arithmetic
|
|
@cindex @code{LL} integer suffix
|
|
@cindex @code{ULL} integer suffix
|
|
|
|
ISO C99 supports data types for integers that are at least 64 bits wide,
|
|
and as an extension GCC supports them in C89 mode and in C++.
|
|
Simply write @code{long long int} for a signed integer, or
|
|
@code{unsigned long long int} for an unsigned integer. To make an
|
|
integer constant of type @code{long long int}, add the suffix @samp{LL}
|
|
to the integer. To make an integer constant of type @code{unsigned long
|
|
long int}, add the suffix @samp{ULL} to the integer.
|
|
|
|
You can use these types in arithmetic like any other integer types.
|
|
Addition, subtraction, and bitwise boolean operations on these types
|
|
are open-coded on all types of machines. Multiplication is open-coded
|
|
if the machine supports fullword-to-doubleword a widening multiply
|
|
instruction. Division and shifts are open-coded only on machines that
|
|
provide special support. The operations that are not open-coded use
|
|
special library routines that come with GCC@.
|
|
|
|
There may be pitfalls when you use @code{long long} types for function
|
|
arguments, unless you declare function prototypes. If a function
|
|
expects type @code{int} for its argument, and you pass a value of type
|
|
@code{long long int}, confusion will result because the caller and the
|
|
subroutine will disagree about the number of bytes for the argument.
|
|
Likewise, if the function expects @code{long long int} and you pass
|
|
@code{int}. The best way to avoid such problems is to use prototypes.
|
|
|
|
@node Complex
|
|
@section Complex Numbers
|
|
@cindex complex numbers
|
|
@cindex @code{_Complex} keyword
|
|
@cindex @code{__complex__} keyword
|
|
|
|
ISO C99 supports complex floating data types, and as an extension GCC
|
|
supports them in C89 mode and in C++, and supports complex integer data
|
|
types which are not part of ISO C99. You can declare complex types
|
|
using the keyword @code{_Complex}. As an extension, the older GNU
|
|
keyword @code{__complex__} is also supported.
|
|
|
|
For example, @samp{_Complex double x;} declares @code{x} as a
|
|
variable whose real part and imaginary part are both of type
|
|
@code{double}. @samp{_Complex short int y;} declares @code{y} to
|
|
have real and imaginary parts of type @code{short int}; this is not
|
|
likely to be useful, but it shows that the set of complex types is
|
|
complete.
|
|
|
|
To write a constant with a complex data type, use the suffix @samp{i} or
|
|
@samp{j} (either one; they are equivalent). For example, @code{2.5fi}
|
|
has type @code{_Complex float} and @code{3i} has type
|
|
@code{_Complex int}. Such a constant always has a pure imaginary
|
|
value, but you can form any complex value you like by adding one to a
|
|
real constant. This is a GNU extension; if you have an ISO C99
|
|
conforming C library (such as GNU libc), and want to construct complex
|
|
constants of floating type, you should include @code{<complex.h>} and
|
|
use the macros @code{I} or @code{_Complex_I} instead.
|
|
|
|
@cindex @code{__real__} keyword
|
|
@cindex @code{__imag__} keyword
|
|
To extract the real part of a complex-valued expression @var{exp}, write
|
|
@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
|
|
extract the imaginary part. This is a GNU extension; for values of
|
|
floating type, you should use the ISO C99 functions @code{crealf},
|
|
@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
|
|
@code{cimagl}, declared in @code{<complex.h>} and also provided as
|
|
built-in functions by GCC@.
|
|
|
|
@cindex complex conjugation
|
|
The operator @samp{~} performs complex conjugation when used on a value
|
|
with a complex type. This is a GNU extension; for values of
|
|
floating type, you should use the ISO C99 functions @code{conjf},
|
|
@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
|
|
provided as built-in functions by GCC@.
|
|
|
|
GCC can allocate complex automatic variables in a noncontiguous
|
|
fashion; it's even possible for the real part to be in a register while
|
|
the imaginary part is on the stack (or vice-versa). Only the DWARF2
|
|
debug info format can represent this, so use of DWARF2 is recommended.
|
|
If you are using the stabs debug info format, GCC describes a noncontiguous
|
|
complex variable as if it were two separate variables of noncomplex type.
|
|
If the variable's actual name is @code{foo}, the two fictitious
|
|
variables are named @code{foo$real} and @code{foo$imag}. You can
|
|
examine and set these two fictitious variables with your debugger.
|
|
|
|
@node Hex Floats
|
|
@section Hex Floats
|
|
@cindex hex floats
|
|
|
|
ISO C99 supports floating-point numbers written not only in the usual
|
|
decimal notation, such as @code{1.55e1}, but also numbers such as
|
|
@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
|
|
supports this in C89 mode (except in some cases when strictly
|
|
conforming) and in C++. In that format the
|
|
@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
|
|
mandatory. The exponent is a decimal number that indicates the power of
|
|
2 by which the significant part will be multiplied. Thus @samp{0x1.f} is
|
|
@tex
|
|
$1 {15\over16}$,
|
|
@end tex
|
|
@ifnottex
|
|
1 15/16,
|
|
@end ifnottex
|
|
@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
|
|
is the same as @code{1.55e1}.
|
|
|
|
Unlike for floating-point numbers in the decimal notation the exponent
|
|
is always required in the hexadecimal notation. Otherwise the compiler
|
|
would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
|
|
could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
|
|
extension for floating-point constants of type @code{float}.
|
|
|
|
@node Zero Length
|
|
@section Arrays of Length Zero
|
|
@cindex arrays of length zero
|
|
@cindex zero-length arrays
|
|
@cindex length-zero arrays
|
|
@cindex flexible array members
|
|
|
|
Zero-length arrays are allowed in GNU C@. They are very useful as the
|
|
last element of a structure which is really a header for a variable-length
|
|
object:
|
|
|
|
@example
|
|
struct line @{
|
|
int length;
|
|
char contents[0];
|
|
@};
|
|
|
|
struct line *thisline = (struct line *)
|
|
malloc (sizeof (struct line) + this_length);
|
|
thisline->length = this_length;
|
|
@end example
|
|
|
|
In ISO C90, you would have to give @code{contents} a length of 1, which
|
|
means either you waste space or complicate the argument to @code{malloc}.
|
|
|
|
In ISO C99, you would use a @dfn{flexible array member}, which is
|
|
slightly different in syntax and semantics:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Flexible array members are written as @code{contents[]} without
|
|
the @code{0}.
|
|
|
|
@item
|
|
Flexible array members have incomplete type, and so the @code{sizeof}
|
|
operator may not be applied. As a quirk of the original implementation
|
|
of zero-length arrays, @code{sizeof} evaluates to zero.
|
|
|
|
@item
|
|
Flexible array members may only appear as the last member of a
|
|
@code{struct} that is otherwise non-empty.
|
|
|
|
@item
|
|
A structure containing a flexible array member, or a union containing
|
|
such a structure (possibly recursively), may not be a member of a
|
|
structure or an element of an array. (However, these uses are
|
|
permitted by GCC as extensions.)
|
|
@end itemize
|
|
|
|
GCC versions before 3.0 allowed zero-length arrays to be statically
|
|
initialized, as if they were flexible arrays. In addition to those
|
|
cases that were useful, it also allowed initializations in situations
|
|
that would corrupt later data. Non-empty initialization of zero-length
|
|
arrays is now treated like any case where there are more initializer
|
|
elements than the array holds, in that a suitable warning about "excess
|
|
elements in array" is given, and the excess elements (all of them, in
|
|
this case) are ignored.
|
|
|
|
Instead GCC allows static initialization of flexible array members.
|
|
This is equivalent to defining a new structure containing the original
|
|
structure followed by an array of sufficient size to contain the data.
|
|
I.e.@: in the following, @code{f1} is constructed as if it were declared
|
|
like @code{f2}.
|
|
|
|
@example
|
|
struct f1 @{
|
|
int x; int y[];
|
|
@} f1 = @{ 1, @{ 2, 3, 4 @} @};
|
|
|
|
struct f2 @{
|
|
struct f1 f1; int data[3];
|
|
@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
|
|
@end example
|
|
|
|
@noindent
|
|
The convenience of this extension is that @code{f1} has the desired
|
|
type, eliminating the need to consistently refer to @code{f2.f1}.
|
|
|
|
This has symmetry with normal static arrays, in that an array of
|
|
unknown size is also written with @code{[]}.
|
|
|
|
Of course, this extension only makes sense if the extra data comes at
|
|
the end of a top-level object, as otherwise we would be overwriting
|
|
data at subsequent offsets. To avoid undue complication and confusion
|
|
with initialization of deeply nested arrays, we simply disallow any
|
|
non-empty initialization except when the structure is the top-level
|
|
object. For example:
|
|
|
|
@example
|
|
struct foo @{ int x; int y[]; @};
|
|
struct bar @{ struct foo z; @};
|
|
|
|
struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
|
|
struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
|
|
struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
|
|
struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
|
|
@end example
|
|
|
|
@node Empty Structures
|
|
@section Structures With No Members
|
|
@cindex empty structures
|
|
@cindex zero-size structures
|
|
|
|
GCC permits a C structure to have no members:
|
|
|
|
@example
|
|
struct empty @{
|
|
@};
|
|
@end example
|
|
|
|
The structure will have size zero. In C++, empty structures are part
|
|
of the language, and the language standard says they have size 1.
|
|
|
|
@node Variable Length
|
|
@section Arrays of Variable Length
|
|
@cindex variable-length arrays
|
|
@cindex arrays of variable length
|
|
@cindex VLAs
|
|
|
|
Variable-length automatic arrays are allowed in ISO C99, and as an
|
|
extension GCC accepts them in C89 mode and in C++. (However, GCC's
|
|
implementation of variable-length arrays does not yet conform in detail
|
|
to the ISO C99 standard.) These arrays are
|
|
declared like any other automatic arrays, but with a length that is not
|
|
a constant expression. The storage is allocated at the point of
|
|
declaration and deallocated when the brace-level is exited. For
|
|
example:
|
|
|
|
@example
|
|
FILE *
|
|
concat_fopen (char *s1, char *s2, char *mode)
|
|
@{
|
|
char str[strlen (s1) + strlen (s2) + 1];
|
|
strcpy (str, s1);
|
|
strcat (str, s2);
|
|
return fopen (str, mode);
|
|
@}
|
|
@end example
|
|
|
|
@cindex scope of a variable length array
|
|
@cindex variable-length array scope
|
|
@cindex deallocating variable length arrays
|
|
Jumping or breaking out of the scope of the array name deallocates the
|
|
storage. Jumping into the scope is not allowed; you get an error
|
|
message for it.
|
|
|
|
@cindex @code{alloca} vs variable-length arrays
|
|
You can use the function @code{alloca} to get an effect much like
|
|
variable-length arrays. The function @code{alloca} is available in
|
|
many other C implementations (but not in all). On the other hand,
|
|
variable-length arrays are more elegant.
|
|
|
|
There are other differences between these two methods. Space allocated
|
|
with @code{alloca} exists until the containing @emph{function} returns.
|
|
The space for a variable-length array is deallocated as soon as the array
|
|
name's scope ends. (If you use both variable-length arrays and
|
|
@code{alloca} in the same function, deallocation of a variable-length array
|
|
will also deallocate anything more recently allocated with @code{alloca}.)
|
|
|
|
You can also use variable-length arrays as arguments to functions:
|
|
|
|
@example
|
|
struct entry
|
|
tester (int len, char data[len][len])
|
|
@{
|
|
/* @r{@dots{}} */
|
|
@}
|
|
@end example
|
|
|
|
The length of an array is computed once when the storage is allocated
|
|
and is remembered for the scope of the array in case you access it with
|
|
@code{sizeof}.
|
|
|
|
If you want to pass the array first and the length afterward, you can
|
|
use a forward declaration in the parameter list---another GNU extension.
|
|
|
|
@example
|
|
struct entry
|
|
tester (int len; char data[len][len], int len)
|
|
@{
|
|
/* @r{@dots{}} */
|
|
@}
|
|
@end example
|
|
|
|
@cindex parameter forward declaration
|
|
The @samp{int len} before the semicolon is a @dfn{parameter forward
|
|
declaration}, and it serves the purpose of making the name @code{len}
|
|
known when the declaration of @code{data} is parsed.
|
|
|
|
You can write any number of such parameter forward declarations in the
|
|
parameter list. They can be separated by commas or semicolons, but the
|
|
last one must end with a semicolon, which is followed by the ``real''
|
|
parameter declarations. Each forward declaration must match a ``real''
|
|
declaration in parameter name and data type. ISO C99 does not support
|
|
parameter forward declarations.
|
|
|
|
@node Variadic Macros
|
|
@section Macros with a Variable Number of Arguments.
|
|
@cindex variable number of arguments
|
|
@cindex macro with variable arguments
|
|
@cindex rest argument (in macro)
|
|
@cindex variadic macros
|
|
|
|
In the ISO C standard of 1999, a macro can be declared to accept a
|
|
variable number of arguments much as a function can. The syntax for
|
|
defining the macro is similar to that of a function. Here is an
|
|
example:
|
|
|
|
@smallexample
|
|
#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
|
|
@end smallexample
|
|
|
|
Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
|
|
such a macro, it represents the zero or more tokens until the closing
|
|
parenthesis that ends the invocation, including any commas. This set of
|
|
tokens replaces the identifier @code{__VA_ARGS__} in the macro body
|
|
wherever it appears. See the CPP manual for more information.
|
|
|
|
GCC has long supported variadic macros, and used a different syntax that
|
|
allowed you to give a name to the variable arguments just like any other
|
|
argument. Here is an example:
|
|
|
|
@example
|
|
#define debug(format, args...) fprintf (stderr, format, args)
|
|
@end example
|
|
|
|
This is in all ways equivalent to the ISO C example above, but arguably
|
|
more readable and descriptive.
|
|
|
|
GNU CPP has two further variadic macro extensions, and permits them to
|
|
be used with either of the above forms of macro definition.
|
|
|
|
In standard C, you are not allowed to leave the variable argument out
|
|
entirely; but you are allowed to pass an empty argument. For example,
|
|
this invocation is invalid in ISO C, because there is no comma after
|
|
the string:
|
|
|
|
@example
|
|
debug ("A message")
|
|
@end example
|
|
|
|
GNU CPP permits you to completely omit the variable arguments in this
|
|
way. In the above examples, the compiler would complain, though since
|
|
the expansion of the macro still has the extra comma after the format
|
|
string.
|
|
|
|
To help solve this problem, CPP behaves specially for variable arguments
|
|
used with the token paste operator, @samp{##}. If instead you write
|
|
|
|
@smallexample
|
|
#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
|
|
@end smallexample
|
|
|
|
and if the variable arguments are omitted or empty, the @samp{##}
|
|
operator causes the preprocessor to remove the comma before it. If you
|
|
do provide some variable arguments in your macro invocation, GNU CPP
|
|
does not complain about the paste operation and instead places the
|
|
variable arguments after the comma. Just like any other pasted macro
|
|
argument, these arguments are not macro expanded.
|
|
|
|
@node Escaped Newlines
|
|
@section Slightly Looser Rules for Escaped Newlines
|
|
@cindex escaped newlines
|
|
@cindex newlines (escaped)
|
|
|
|
Recently, the preprocessor has relaxed its treatment of escaped
|
|
newlines. Previously, the newline had to immediately follow a
|
|
backslash. The current implementation allows whitespace in the form of
|
|
spaces, horizontal and vertical tabs, and form feeds between the
|
|
backslash and the subsequent newline. The preprocessor issues a
|
|
warning, but treats it as a valid escaped newline and combines the two
|
|
lines to form a single logical line. This works within comments and
|
|
tokens, as well as between tokens. Comments are @emph{not} treated as
|
|
whitespace for the purposes of this relaxation, since they have not
|
|
yet been replaced with spaces.
|
|
|
|
@node Subscripting
|
|
@section Non-Lvalue Arrays May Have Subscripts
|
|
@cindex subscripting
|
|
@cindex arrays, non-lvalue
|
|
|
|
@cindex subscripting and function values
|
|
In ISO C99, arrays that are not lvalues still decay to pointers, and
|
|
may be subscripted, although they may not be modified or used after
|
|
the next sequence point and the unary @samp{&} operator may not be
|
|
applied to them. As an extension, GCC allows such arrays to be
|
|
subscripted in C89 mode, though otherwise they do not decay to
|
|
pointers outside C99 mode. For example,
|
|
this is valid in GNU C though not valid in C89:
|
|
|
|
@example
|
|
@group
|
|
struct foo @{int a[4];@};
|
|
|
|
struct foo f();
|
|
|
|
bar (int index)
|
|
@{
|
|
return f().a[index];
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
@node Pointer Arith
|
|
@section Arithmetic on @code{void}- and Function-Pointers
|
|
@cindex void pointers, arithmetic
|
|
@cindex void, size of pointer to
|
|
@cindex function pointers, arithmetic
|
|
@cindex function, size of pointer to
|
|
|
|
In GNU C, addition and subtraction operations are supported on pointers to
|
|
@code{void} and on pointers to functions. This is done by treating the
|
|
size of a @code{void} or of a function as 1.
|
|
|
|
A consequence of this is that @code{sizeof} is also allowed on @code{void}
|
|
and on function types, and returns 1.
|
|
|
|
@opindex Wpointer-arith
|
|
The option @option{-Wpointer-arith} requests a warning if these extensions
|
|
are used.
|
|
|
|
@node Initializers
|
|
@section Non-Constant Initializers
|
|
@cindex initializers, non-constant
|
|
@cindex non-constant initializers
|
|
|
|
As in standard C++ and ISO C99, the elements of an aggregate initializer for an
|
|
automatic variable are not required to be constant expressions in GNU C@.
|
|
Here is an example of an initializer with run-time varying elements:
|
|
|
|
@example
|
|
foo (float f, float g)
|
|
@{
|
|
float beat_freqs[2] = @{ f-g, f+g @};
|
|
/* @r{@dots{}} */
|
|
@}
|
|
@end example
|
|
|
|
@node Compound Literals
|
|
@section Compound Literals
|
|
@cindex constructor expressions
|
|
@cindex initializations in expressions
|
|
@cindex structures, constructor expression
|
|
@cindex expressions, constructor
|
|
@cindex compound literals
|
|
@c The GNU C name for what C99 calls compound literals was "constructor expressions".
|
|
|
|
ISO C99 supports compound literals. A compound literal looks like
|
|
a cast containing an initializer. Its value is an object of the
|
|
type specified in the cast, containing the elements specified in
|
|
the initializer; it is an lvalue. As an extension, GCC supports
|
|
compound literals in C89 mode and in C++.
|
|
|
|
Usually, the specified type is a structure. Assume that
|
|
@code{struct foo} and @code{structure} are declared as shown:
|
|
|
|
@example
|
|
struct foo @{int a; char b[2];@} structure;
|
|
@end example
|
|
|
|
@noindent
|
|
Here is an example of constructing a @code{struct foo} with a compound literal:
|
|
|
|
@example
|
|
structure = ((struct foo) @{x + y, 'a', 0@});
|
|
@end example
|
|
|
|
@noindent
|
|
This is equivalent to writing the following:
|
|
|
|
@example
|
|
@{
|
|
struct foo temp = @{x + y, 'a', 0@};
|
|
structure = temp;
|
|
@}
|
|
@end example
|
|
|
|
You can also construct an array. If all the elements of the compound literal
|
|
are (made up of) simple constant expressions, suitable for use in
|
|
initializers of objects of static storage duration, then the compound
|
|
literal can be coerced to a pointer to its first element and used in
|
|
such an initializer, as shown here:
|
|
|
|
@example
|
|
char **foo = (char *[]) @{ "x", "y", "z" @};
|
|
@end example
|
|
|
|
Compound literals for scalar types and union types are is
|
|
also allowed, but then the compound literal is equivalent
|
|
to a cast.
|
|
|
|
As a GNU extension, GCC allows initialization of objects with static storage
|
|
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.
|
|
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.
|
|
|
|
@example
|
|
static struct foo x = (struct foo) @{1, 'a', 'b'@};
|
|
static int y[] = (int []) @{1, 2, 3@};
|
|
static int z[] = (int [3]) @{1@};
|
|
@end example
|
|
|
|
@noindent
|
|
The above lines are equivalent to the following:
|
|
@example
|
|
static struct foo x = @{1, 'a', 'b'@};
|
|
static int y[] = @{1, 2, 3@};
|
|
static int z[] = @{1, 0, 0@};
|
|
@end example
|
|
|
|
@node Designated Inits
|
|
@section Designated Initializers
|
|
@cindex initializers with labeled elements
|
|
@cindex labeled elements in initializers
|
|
@cindex case labels in initializers
|
|
@cindex designated initializers
|
|
|
|
Standard C89 requires the elements of an initializer to appear in a fixed
|
|
order, the same as the order of the elements in the array or structure
|
|
being initialized.
|
|
|
|
In ISO C99 you can give the elements in any order, specifying the array
|
|
indices or structure field names they apply to, and GNU C allows this as
|
|
an extension in C89 mode as well. This extension is not
|
|
implemented in GNU C++.
|
|
|
|
To specify an array index, write
|
|
@samp{[@var{index}] =} before the element value. For example,
|
|
|
|
@example
|
|
int a[6] = @{ [4] = 29, [2] = 15 @};
|
|
@end example
|
|
|
|
@noindent
|
|
is equivalent to
|
|
|
|
@example
|
|
int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
|
|
@end example
|
|
|
|
@noindent
|
|
The index values must be constant expressions, even if the array being
|
|
initialized is automatic.
|
|
|
|
An alternative syntax for this which has been obsolete since GCC 2.5 but
|
|
GCC still accepts is to write @samp{[@var{index}]} before the element
|
|
value, with no @samp{=}.
|
|
|
|
To initialize a range of elements to the same value, write
|
|
@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
|
|
extension. For example,
|
|
|
|
@example
|
|
int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
|
|
@end example
|
|
|
|
@noindent
|
|
If the value in it has side-effects, the side-effects will happen only once,
|
|
not for each initialized field by the range initializer.
|
|
|
|
@noindent
|
|
Note that the length of the array is the highest value specified
|
|
plus one.
|
|
|
|
In a structure initializer, specify the name of a field to initialize
|
|
with @samp{.@var{fieldname} =} before the element value. For example,
|
|
given the following structure,
|
|
|
|
@example
|
|
struct point @{ int x, y; @};
|
|
@end example
|
|
|
|
@noindent
|
|
the following initialization
|
|
|
|
@example
|
|
struct point p = @{ .y = yvalue, .x = xvalue @};
|
|
@end example
|
|
|
|
@noindent
|
|
is equivalent to
|
|
|
|
@example
|
|
struct point p = @{ xvalue, yvalue @};
|
|
@end example
|
|
|
|
Another syntax which has the same meaning, obsolete since GCC 2.5, is
|
|
@samp{@var{fieldname}:}, as shown here:
|
|
|
|
@example
|
|
struct point p = @{ y: yvalue, x: xvalue @};
|
|
@end example
|
|
|
|
@cindex designators
|
|
The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
|
|
@dfn{designator}. You can also use a designator (or the obsolete colon
|
|
syntax) when initializing a union, to specify which element of the union
|
|
should be used. For example,
|
|
|
|
@example
|
|
union foo @{ int i; double d; @};
|
|
|
|
union foo f = @{ .d = 4 @};
|
|
@end example
|
|
|
|
@noindent
|
|
will convert 4 to a @code{double} to store it in the union using
|
|
the second element. By contrast, casting 4 to type @code{union foo}
|
|
would store it into the union as the integer @code{i}, since it is
|
|
an integer. (@xref{Cast to Union}.)
|
|
|
|
You can combine this technique of naming elements with ordinary C
|
|
initialization of successive elements. Each initializer element that
|
|
does not have a designator applies to the next consecutive element of the
|
|
array or structure. For example,
|
|
|
|
@example
|
|
int a[6] = @{ [1] = v1, v2, [4] = v4 @};
|
|
@end example
|
|
|
|
@noindent
|
|
is equivalent to
|
|
|
|
@example
|
|
int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
|
|
@end example
|
|
|
|
Labeling the elements of an array initializer is especially useful
|
|
when the indices are characters or belong to an @code{enum} type.
|
|
For example:
|
|
|
|
@example
|
|
int whitespace[256]
|
|
= @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
|
|
['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
|
|
@end example
|
|
|
|
@cindex designator lists
|
|
You can also write a series of @samp{.@var{fieldname}} and
|
|
@samp{[@var{index}]} designators before an @samp{=} to specify a
|
|
nested subobject to initialize; the list is taken relative to the
|
|
subobject corresponding to the closest surrounding brace pair. For
|
|
example, with the @samp{struct point} declaration above:
|
|
|
|
@smallexample
|
|
struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the same field is initialized multiple times, it will have value from
|
|
the last initialization. If any such overridden initialization has
|
|
side-effect, it is unspecified whether the side-effect happens or not.
|
|
Currently, gcc will discard them and issue a warning.
|
|
|
|
@node Case Ranges
|
|
@section Case Ranges
|
|
@cindex case ranges
|
|
@cindex ranges in case statements
|
|
|
|
You can specify a range of consecutive values in a single @code{case} label,
|
|
like this:
|
|
|
|
@example
|
|
case @var{low} ... @var{high}:
|
|
@end example
|
|
|
|
@noindent
|
|
This has the same effect as the proper number of individual @code{case}
|
|
labels, one for each integer value from @var{low} to @var{high}, inclusive.
|
|
|
|
This feature is especially useful for ranges of ASCII character codes:
|
|
|
|
@example
|
|
case 'A' ... 'Z':
|
|
@end example
|
|
|
|
@strong{Be careful:} Write spaces around the @code{...}, for otherwise
|
|
it may be parsed wrong when you use it with integer values. For example,
|
|
write this:
|
|
|
|
@example
|
|
case 1 ... 5:
|
|
@end example
|
|
|
|
@noindent
|
|
rather than this:
|
|
|
|
@example
|
|
case 1...5:
|
|
@end example
|
|
|
|
@node Cast to Union
|
|
@section Cast to a Union Type
|
|
@cindex cast to a union
|
|
@cindex union, casting to a
|
|
|
|
A cast to union type is similar to other casts, except that the type
|
|
specified is a union type. You can specify the type either with
|
|
@code{union @var{tag}} or with a typedef name. A cast to union is actually
|
|
a constructor though, not a cast, and hence does not yield an lvalue like
|
|
normal casts. (@xref{Compound Literals}.)
|
|
|
|
The types that may be cast to the union type are those of the members
|
|
of the union. Thus, given the following union and variables:
|
|
|
|
@example
|
|
union foo @{ int i; double d; @};
|
|
int x;
|
|
double y;
|
|
@end example
|
|
|
|
@noindent
|
|
both @code{x} and @code{y} can be cast to type @code{union foo}.
|
|
|
|
Using the cast as the right-hand side of an assignment to a variable of
|
|
union type is equivalent to storing in a member of the union:
|
|
|
|
@example
|
|
union foo u;
|
|
/* @r{@dots{}} */
|
|
u = (union foo) x @equiv{} u.i = x
|
|
u = (union foo) y @equiv{} u.d = y
|
|
@end example
|
|
|
|
You can also use the union cast as a function argument:
|
|
|
|
@example
|
|
void hack (union foo);
|
|
/* @r{@dots{}} */
|
|
hack ((union foo) x);
|
|
@end example
|
|
|
|
@node Mixed Declarations
|
|
@section Mixed Declarations and Code
|
|
@cindex mixed declarations and code
|
|
@cindex declarations, mixed with code
|
|
@cindex code, mixed with declarations
|
|
|
|
ISO C99 and ISO C++ allow declarations and code to be freely mixed
|
|
within compound statements. As an extension, GCC also allows this in
|
|
C89 mode. For example, you could do:
|
|
|
|
@example
|
|
int i;
|
|
/* @r{@dots{}} */
|
|
i++;
|
|
int j = i + 2;
|
|
@end example
|
|
|
|
Each identifier is visible from where it is declared until the end of
|
|
the enclosing block.
|
|
|
|
@node Function Attributes
|
|
@section Declaring Attributes of Functions
|
|
@cindex function attributes
|
|
@cindex declaring attributes of functions
|
|
@cindex functions that never return
|
|
@cindex functions that have no side effects
|
|
@cindex functions in arbitrary sections
|
|
@cindex functions that behave like malloc
|
|
@cindex @code{volatile} applied to function
|
|
@cindex @code{const} applied to function
|
|
@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
|
|
@cindex functions with non-null pointer arguments
|
|
@cindex functions that are passed arguments in registers on the 386
|
|
@cindex functions that pop the argument stack on the 386
|
|
@cindex functions that do not pop the argument stack on the 386
|
|
|
|
In GNU C, you declare certain things about functions called in your program
|
|
which help the compiler optimize function calls and check your code more
|
|
carefully.
|
|
|
|
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. The following
|
|
attributes are currently defined for functions on all targets:
|
|
@code{noreturn}, @code{noinline}, @code{always_inline},
|
|
@code{pure}, @code{const}, @code{nothrow},
|
|
@code{format}, @code{format_arg}, @code{no_instrument_function},
|
|
@code{section}, @code{constructor}, @code{destructor}, @code{used},
|
|
@code{unused}, @code{deprecated}, @code{weak}, @code{malloc},
|
|
@code{alias}, and @code{nonnull}. 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
|
|
being concerned about a possible macro of the same name. For example,
|
|
you may use @code{__noreturn__} instead of @code{noreturn}.
|
|
|
|
@xref{Attribute Syntax}, for details of the exact syntax for using
|
|
attributes.
|
|
|
|
@table @code
|
|
@cindex @code{noreturn} function attribute
|
|
@item noreturn
|
|
A few standard library functions, such as @code{abort} and @code{exit},
|
|
cannot return. GCC knows this automatically. Some programs define
|
|
their own functions that never return. You can declare them
|
|
@code{noreturn} to tell the compiler this fact. For example,
|
|
|
|
@smallexample
|
|
@group
|
|
void fatal () __attribute__ ((noreturn));
|
|
|
|
void
|
|
fatal (/* @r{@dots{}} */)
|
|
@{
|
|
/* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
|
|
exit (1);
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @code{noreturn} keyword tells the compiler to assume that
|
|
@code{fatal} cannot return. It can then optimize without regard to what
|
|
would happen if @code{fatal} ever did return. This makes slightly
|
|
better code. More importantly, it helps avoid spurious warnings of
|
|
uninitialized variables.
|
|
|
|
Do not assume that registers saved by the calling function are
|
|
restored before calling the @code{noreturn} function.
|
|
|
|
It does not make sense for a @code{noreturn} function to have a return
|
|
type other than @code{void}.
|
|
|
|
The attribute @code{noreturn} is not implemented in GCC versions
|
|
earlier than 2.5. An alternative way to declare that a function does
|
|
not return, which works in the current version and in some older
|
|
versions, is as follows:
|
|
|
|
@smallexample
|
|
typedef void voidfn ();
|
|
|
|
volatile voidfn fatal;
|
|
@end smallexample
|
|
|
|
@cindex @code{noinline} function attribute
|
|
@item noinline
|
|
This function attribute prevents a function from being considered for
|
|
inlining.
|
|
|
|
@cindex @code{always_inline} function attribute
|
|
@item always_inline
|
|
Generally, functions are not inlined unless optimization is specified.
|
|
For functions declared inline, this attribute inlines the function even
|
|
if no optimization level was specified.
|
|
|
|
@cindex @code{pure} function attribute
|
|
@item pure
|
|
Many functions have no effects except the return value and their
|
|
return value depends only on the parameters and/or global variables.
|
|
Such a function can be subject
|
|
to common subexpression elimination and loop optimization just as an
|
|
arithmetic operator would be. These functions should be declared
|
|
with the attribute @code{pure}. For example,
|
|
|
|
@smallexample
|
|
int square (int) __attribute__ ((pure));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
says that the hypothetical function @code{square} is safe to call
|
|
fewer times than the program says.
|
|
|
|
Some of common examples of pure functions are @code{strlen} or @code{memcmp}.
|
|
Interesting non-pure functions are functions with infinite loops or those
|
|
depending on volatile memory or other system resource, that may change between
|
|
two consecutive calls (such as @code{feof} in a multithreading environment).
|
|
|
|
The attribute @code{pure} is not implemented in GCC versions earlier
|
|
than 2.96.
|
|
@cindex @code{const} function attribute
|
|
@item const
|
|
Many functions do not examine any values except their arguments, and
|
|
have no effects except the return value. Basically this is just slightly
|
|
more strict class than the @code{pure} attribute above, since function is not
|
|
allowed to read global memory.
|
|
|
|
@cindex pointer arguments
|
|
Note that a function that has pointer arguments and examines the data
|
|
pointed to must @emph{not} be declared @code{const}. Likewise, a
|
|
function that calls a non-@code{const} function usually must not be
|
|
@code{const}. It does not make sense for a @code{const} function to
|
|
return @code{void}.
|
|
|
|
The attribute @code{const} is not implemented in GCC versions earlier
|
|
than 2.5. An alternative way to declare that a function has no side
|
|
effects, which works in the current version and in some older versions,
|
|
is as follows:
|
|
|
|
@smallexample
|
|
typedef int intfn ();
|
|
|
|
extern const intfn square;
|
|
@end smallexample
|
|
|
|
This approach does not work in GNU C++ from 2.6.0 on, since the language
|
|
specifies that the @samp{const} must be attached to the return value.
|
|
|
|
@cindex @code{nothrow} function attribute
|
|
@item nothrow
|
|
The @code{nothrow} attribute is used to inform the compiler that a
|
|
function cannot throw an exception. For example, most functions in
|
|
the standard C library can be guaranteed not to throw an exception
|
|
with the notable exceptions of @code{qsort} and @code{bsearch} that
|
|
take function pointer arguments. The @code{nothrow} attribute is not
|
|
implemented in GCC versions earlier than 3.2.
|
|
|
|
@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
|
|
@cindex @code{format} function attribute
|
|
@opindex Wformat
|
|
The @code{format} attribute specifies that a function takes @code{printf},
|
|
@code{scanf}, @code{strftime} or @code{strfmon} style arguments which
|
|
should be type-checked against a format string. For example, the
|
|
declaration:
|
|
|
|
@smallexample
|
|
extern int
|
|
my_printf (void *my_object, const char *my_format, ...)
|
|
__attribute__ ((format (printf, 2, 3)));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes the compiler to check the arguments in calls to @code{my_printf}
|
|
for consistency with the @code{printf} style format string argument
|
|
@code{my_format}.
|
|
|
|
The parameter @var{archetype} determines how the format string is
|
|
interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}
|
|
or @code{strfmon}. (You can also use @code{__printf__},
|
|
@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) The
|
|
parameter @var{string-index} specifies which argument is the format
|
|
string argument (starting from 1), while @var{first-to-check} is the
|
|
number of the first argument to check against the format string. For
|
|
functions where the arguments are not available to be checked (such as
|
|
@code{vprintf}), specify the third parameter as zero. In this case the
|
|
compiler only checks the format string for consistency. For
|
|
@code{strftime} formats, the third parameter is required to be zero.
|
|
|
|
In the example above, the format string (@code{my_format}) is the second
|
|
argument of the function @code{my_print}, and the arguments to check
|
|
start with the third argument, so the correct parameters for the format
|
|
attribute are 2 and 3.
|
|
|
|
@opindex ffreestanding
|
|
The @code{format} attribute allows you to identify your own functions
|
|
which take format strings as arguments, so that GCC can check the
|
|
calls to these functions for errors. The compiler always (unless
|
|
@option{-ffreestanding} is used) checks formats
|
|
for the standard library functions @code{printf}, @code{fprintf},
|
|
@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
|
|
@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
|
|
warnings are requested (using @option{-Wformat}), so there is no need to
|
|
modify the header file @file{stdio.h}. In C99 mode, the functions
|
|
@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
|
|
@code{vsscanf} are also checked. Except in strictly conforming C
|
|
standard modes, the X/Open function @code{strfmon} is also checked as
|
|
are @code{printf_unlocked} and @code{fprintf_unlocked}.
|
|
@xref{C Dialect Options,,Options Controlling C Dialect}.
|
|
|
|
@item format_arg (@var{string-index})
|
|
@cindex @code{format_arg} function attribute
|
|
@opindex Wformat-nonliteral
|
|
The @code{format_arg} attribute specifies that a function takes a format
|
|
string for a @code{printf}, @code{scanf}, @code{strftime} or
|
|
@code{strfmon} style function and modifies it (for example, to translate
|
|
it into another language), so the result can be passed to a
|
|
@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
|
|
function (with the remaining arguments to the format function the same
|
|
as they would have been for the unmodified string). For example, the
|
|
declaration:
|
|
|
|
@smallexample
|
|
extern char *
|
|
my_dgettext (char *my_domain, const char *my_format)
|
|
__attribute__ ((format_arg (2)));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes the compiler to check the arguments in calls to a @code{printf},
|
|
@code{scanf}, @code{strftime} or @code{strfmon} type function, whose
|
|
format string argument is a call to the @code{my_dgettext} function, for
|
|
consistency with the format string argument @code{my_format}. If the
|
|
@code{format_arg} attribute had not been specified, all the compiler
|
|
could tell in such calls to format functions would be that the format
|
|
string argument is not constant; this would generate a warning when
|
|
@option{-Wformat-nonliteral} is used, but the calls could not be checked
|
|
without the attribute.
|
|
|
|
The parameter @var{string-index} specifies which argument is the format
|
|
string argument (starting from 1).
|
|
|
|
The @code{format-arg} attribute allows you to identify your own
|
|
functions which modify format strings, so that GCC can check the
|
|
calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
|
|
type function whose operands are a call to one of your own function.
|
|
The compiler always treats @code{gettext}, @code{dgettext}, and
|
|
@code{dcgettext} in this manner except when strict ISO C support is
|
|
requested by @option{-ansi} or an appropriate @option{-std} option, or
|
|
@option{-ffreestanding} is used. @xref{C Dialect Options,,Options
|
|
Controlling C Dialect}.
|
|
|
|
@item nonnull (@var{arg-index}, @dots{})
|
|
@cindex @code{nonnull} function attribute
|
|
The @code{nonnull} attribute specifies that some function parameters should
|
|
be non-null pointers. For instance, the declaration:
|
|
|
|
@smallexample
|
|
extern void *
|
|
my_memcpy (void *dest, const void *src, size_t len)
|
|
__attribute__((nonnull (1, 2)));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes the compiler to check that, in calls to @code{my_memcpy},
|
|
arguments @var{dest} and @var{src} are non-null. If the compiler
|
|
determines that a null pointer is passed in an argument slot marked
|
|
as non-null, and the @option{-Wnonnull} option is enabled, a warning
|
|
is issued. The compiler may also choose to make optimizations based
|
|
on the knowledge that certain function arguments will not be null.
|
|
|
|
If no argument index list is given to the @code{nonnull} attribute,
|
|
all pointer arguments are marked as non-null. To illustrate, the
|
|
following declaration is equivalent to the previous example:
|
|
|
|
@smallexample
|
|
extern void *
|
|
my_memcpy (void *dest, const void *src, size_t len)
|
|
__attribute__((nonnull));
|
|
@end smallexample
|
|
|
|
@item no_instrument_function
|
|
@cindex @code{no_instrument_function} function attribute
|
|
@opindex finstrument-functions
|
|
If @option{-finstrument-functions} is given, profiling function calls will
|
|
be generated at entry and exit of most user-compiled functions.
|
|
Functions with this attribute will not be so instrumented.
|
|
|
|
@item section ("@var{section-name}")
|
|
@cindex @code{section} function attribute
|
|
Normally, the compiler places the code it generates in the @code{text} section.
|
|
Sometimes, however, you need additional sections, or you need certain
|
|
particular functions to appear in special sections. The @code{section}
|
|
attribute specifies that a function lives in a particular section.
|
|
For example, the declaration:
|
|
|
|
@smallexample
|
|
extern void foobar (void) __attribute__ ((section ("bar")));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
puts the function @code{foobar} in the @code{bar} section.
|
|
|
|
Some file formats do not support arbitrary sections so the @code{section}
|
|
attribute is not available on all platforms.
|
|
If you need to map the entire contents of a module to a particular
|
|
section, consider using the facilities of the linker instead.
|
|
|
|
@item constructor
|
|
@itemx destructor
|
|
@cindex @code{constructor} function attribute
|
|
@cindex @code{destructor} function attribute
|
|
The @code{constructor} attribute causes the function to be called
|
|
automatically before execution enters @code{main ()}. Similarly, the
|
|
@code{destructor} attribute causes the function to be called
|
|
automatically after @code{main ()} has completed or @code{exit ()} has
|
|
been called. Functions with these attributes are useful for
|
|
initializing data that will be used implicitly during the execution of
|
|
the program.
|
|
|
|
These attributes are not currently implemented for Objective-C@.
|
|
|
|
@cindex @code{unused} attribute.
|
|
@item unused
|
|
This attribute, attached to a function, means that the function is meant
|
|
to be possibly unused. GCC will not produce a warning for this
|
|
function. GNU C++ does not currently support this attribute as
|
|
definitions without parameters are valid in C++.
|
|
|
|
@cindex @code{used} attribute.
|
|
@item used
|
|
This attribute, attached to a function, means that code must be emitted
|
|
for the function even if it appears that the function is not referenced.
|
|
This is useful, for example, when the function is referenced only in
|
|
inline assembly.
|
|
|
|
@cindex @code{deprecated} attribute.
|
|
@item deprecated
|
|
The @code{deprecated} attribute results in a warning if the function
|
|
is used anywhere in the source file. This is useful when identifying
|
|
functions that are expected to be removed in a future version of a
|
|
program. The warning also includes the location of the declaration
|
|
of the deprecated function, to enable users to easily find further
|
|
information about why the function is deprecated, or what they should
|
|
do instead. Note that the warnings only occurs for uses:
|
|
|
|
@smallexample
|
|
int old_fn () __attribute__ ((deprecated));
|
|
int old_fn ();
|
|
int (*fn_ptr)() = old_fn;
|
|
@end smallexample
|
|
|
|
results in a warning on line 3 but not line 2.
|
|
|
|
The @code{deprecated} attribute can also be used for variables and
|
|
types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
|
|
|
|
@item weak
|
|
@cindex @code{weak} attribute
|
|
The @code{weak} attribute causes the declaration to be emitted as a weak
|
|
symbol rather than a global. This is primarily useful in defining
|
|
library functions which can be overridden in user code, though it can
|
|
also be used with non-function declarations. Weak symbols are supported
|
|
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 ("@var{target}")
|
|
@cindex @code{alias} attribute
|
|
The @code{alias} attribute causes the declaration to be emitted as an
|
|
alias for another symbol, which must be specified. For instance,
|
|
|
|
@smallexample
|
|
void __f () @{ /* @r{Do something.} */; @}
|
|
void f () __attribute__ ((weak, alias ("__f")));
|
|
@end smallexample
|
|
|
|
declares @samp{f} to be a weak alias for @samp{__f}. In C++, the
|
|
mangled name for the target must be used.
|
|
|
|
Not all target machines support this attribute.
|
|
|
|
@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.
|
|
|
|
@smallexample
|
|
void __attribute__ ((visibility ("protected")))
|
|
f () @{ /* @r{Do something.} */; @}
|
|
int i __attribute__ ((visibility ("hidden")));
|
|
@end smallexample
|
|
|
|
See the ELF gABI for complete details, but the short story is:
|
|
|
|
@table @dfn
|
|
@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.
|
|
|
|
@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.
|
|
|
|
@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.
|
|
|
|
@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 then 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.
|
|
@end table
|
|
|
|
Not all ELF targets support this attribute.
|
|
|
|
@item tls_model ("@var{tls_model}")
|
|
@cindex @code{tls_model} attribute
|
|
The @code{tls_model} attribute sets thread-local storage model
|
|
(@pxref{Thread-Local}) of a particular @code{__thread} variable,
|
|
overriding @code{-ftls-model=} command line switch on a per-variable
|
|
basis.
|
|
The @var{tls_model} argument should be one of @code{global-dynamic},
|
|
@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
|
|
|
|
@item regparm (@var{number})
|
|
@cindex @code{regparm} attribute
|
|
@cindex functions that are passed arguments in registers on the 386
|
|
On the Intel 386, the @code{regparm} attribute causes the compiler to
|
|
pass up to @var{number} integer arguments in registers EAX,
|
|
EDX, and ECX instead of on the stack. Functions that take a
|
|
variable number of arguments will continue to be passed all of their
|
|
arguments on the stack.
|
|
|
|
Beware that on some ELF systems this attribute is unsuitable for
|
|
global functions in shared libraries with lazy binding (which is the
|
|
default). Lazy binding will send the first call via resolving code in
|
|
the loader, which might assume EAX, EDX and ECX can be clobbered, as
|
|
per the standard calling conventions. Solaris 8 is affected by this.
|
|
GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be
|
|
safe since the loaders there save all registers. (Lazy binding can be
|
|
disabled with the linker or the loader if desired, to avoid the
|
|
problem.)
|
|
|
|
@item stdcall
|
|
@cindex functions that pop the argument stack on the 386
|
|
On the Intel 386, the @code{stdcall} attribute causes the compiler to
|
|
assume that the called function will pop off the stack space used to
|
|
pass arguments, unless it takes a variable number of arguments.
|
|
|
|
The PowerPC compiler for Windows NT currently ignores the @code{stdcall}
|
|
attribute.
|
|
|
|
@item cdecl
|
|
@cindex functions that do pop the argument stack on the 386
|
|
@opindex mrtd
|
|
On the Intel 386, the @code{cdecl} attribute causes the compiler to
|
|
assume that the calling function will pop off the stack space used to
|
|
pass arguments. This is
|
|
useful to override the effects of the @option{-mrtd} switch.
|
|
|
|
The PowerPC compiler for Windows NT currently ignores the @code{cdecl}
|
|
attribute.
|
|
|
|
@item longcall/shortcall
|
|
@cindex functions called via pointer on the RS/6000 and PowerPC
|
|
On the 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 the @code{#pragma longcall}
|
|
setting.
|
|
|
|
@xref{RS/6000 and PowerPC Options}, for more information on when long
|
|
calls are and are not necessary.
|
|
|
|
@item long_call/short_call
|
|
@cindex indirect calls on ARM
|
|
This attribute allows to specify how to call a particular function 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
|
|
the offset to the function from the call site into the @samp{BL}
|
|
instruction directly.
|
|
|
|
@item dllimport
|
|
@cindex functions which are imported from a dll on PowerPC Windows NT
|
|
On the PowerPC running Windows NT, the @code{dllimport} attribute causes
|
|
the compiler to call the function via a global pointer to the function
|
|
pointer that is set up by the Windows NT dll library. The pointer name
|
|
is formed by combining @code{__imp_} and the function name.
|
|
|
|
@item dllexport
|
|
@cindex functions which are exported from a dll on PowerPC Windows NT
|
|
On the PowerPC running Windows NT, the @code{dllexport} attribute causes
|
|
the compiler to provide a global pointer to the function pointer, so
|
|
that it can be called with the @code{dllimport} attribute. The pointer
|
|
name is formed by combining @code{__imp_} and the function name.
|
|
|
|
@item exception (@var{except-func} [, @var{except-arg}])
|
|
@cindex functions which specify exception handling on PowerPC Windows NT
|
|
On the PowerPC running Windows NT, the @code{exception} attribute causes
|
|
the compiler to modify the structured exception table entry it emits for
|
|
the declared function. The string or identifier @var{except-func} is
|
|
placed in the third entry of the structured exception table. It
|
|
represents a function, which is called by the exception handling
|
|
mechanism if an exception occurs. If it was specified, the string or
|
|
identifier @var{except-arg} is placed in the fourth entry of the
|
|
structured exception table.
|
|
|
|
@item function_vector
|
|
@cindex calling functions through the function vector on the H8/300 processors
|
|
Use this attribute on the H8/300 and H8/300H to indicate that the specified
|
|
function should be called through the function vector. Calling a
|
|
function through the function vector will reduce code size, however;
|
|
the function vector has a limited size (maximum 128 entries on the H8/300
|
|
and 64 entries on the H8/300H) and shares space with the interrupt vector.
|
|
|
|
You must use GAS and GLD from GNU binutils version 2.7 or later for
|
|
this attribute to work correctly.
|
|
|
|
@item interrupt
|
|
@cindex interrupt handler functions
|
|
Use this attribute on the ARM, AVR, M32R/D 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 is present.
|
|
|
|
Note, interrupt handlers for the H8/300, H8/300H and SH processors can
|
|
be specified via the @code{interrupt_handler} attribute.
|
|
|
|
Note, on the AVR interrupts will be enabled inside the function.
|
|
|
|
Note, for the ARM you can specify the kind of interrupt to be handled by
|
|
adding an optional parameter to the interrupt attribute like this:
|
|
|
|
@smallexample
|
|
void f () __attribute__ ((interrupt ("IRQ")));
|
|
@end smallexample
|
|
|
|
Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@.
|
|
|
|
@item interrupt_handler
|
|
@cindex interrupt handler functions on the H8/300 and SH processors
|
|
Use this attribute on the H8/300, H8/300H and SH 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 is present.
|
|
|
|
@item sp_switch
|
|
Use this attribute on the SH to indicate an @code{interrupt_handler}
|
|
function should switch to an alternate stack. It expects a string
|
|
argument that names a global variable holding the address of the
|
|
alternate stack.
|
|
|
|
@smallexample
|
|
void *alt_stack;
|
|
void f () __attribute__ ((interrupt_handler,
|
|
sp_switch ("alt_stack")));
|
|
@end smallexample
|
|
|
|
@item trap_exit
|
|
Use this attribute on the SH for an @code{interrupt_handle} to return using
|
|
@code{trapa} instead of @code{rte}. This attribute expects an integer
|
|
argument specifying the trap number to be used.
|
|
|
|
@item eightbit_data
|
|
@cindex eight bit data on the H8/300 and H8/300H
|
|
Use this attribute on the H8/300 and H8/300H to indicate that the specified
|
|
variable should be placed into the eight bit data section.
|
|
The compiler will generate more efficient code for certain operations
|
|
on data in the eight bit data area. Note the eight bit data area is limited to
|
|
256 bytes of data.
|
|
|
|
You must use GAS and GLD from GNU binutils version 2.7 or later for
|
|
this attribute to work correctly.
|
|
|
|
@item tiny_data
|
|
@cindex tiny data section on the H8/300H
|
|
Use this attribute on the H8/300H to indicate that the specified
|
|
variable should be placed into the tiny data section.
|
|
The compiler will generate more efficient code for loads and stores
|
|
on data in the tiny data section. Note the tiny data area is limited to
|
|
slightly under 32kbytes of data.
|
|
|
|
@item signal
|
|
@cindex signal handler functions on the AVR processors
|
|
Use this attribute on the AVR to indicate that the specified
|
|
function is an signal handler. The compiler will generate function
|
|
entry and exit sequences suitable for use in an signal handler when this
|
|
attribute is present. Interrupts will be disabled inside function.
|
|
|
|
@item naked
|
|
@cindex function without a prologue/epilogue code
|
|
Use this attribute on the ARM, AVR and IP2K ports to indicate that the
|
|
specified function do not need prologue/epilogue sequences generated by
|
|
the compiler. It is up to the programmer to provide these sequences.
|
|
|
|
@item model (@var{model-name})
|
|
@cindex function addressability on the M32R/D
|
|
Use this attribute on the M32R/D to set the addressability of an object,
|
|
and the code generated for a function.
|
|
The identifier @var{model-name} is one of @code{small}, @code{medium},
|
|
or @code{large}, representing each of the code models.
|
|
|
|
Small model objects live in the lower 16MB of memory (so that their
|
|
addresses can be loaded with the @code{ld24} instruction), and are
|
|
callable with the @code{bl} instruction.
|
|
|
|
Medium model objects may live anywhere in the 32-bit address space (the
|
|
compiler will generate @code{seth/add3} instructions to load their addresses),
|
|
and are callable with the @code{bl} instruction.
|
|
|
|
Large model objects may live anywhere in the 32-bit address space (the
|
|
compiler will generate @code{seth/add3} instructions to load their addresses),
|
|
and may not be reachable with the @code{bl} instruction (the compiler will
|
|
generate the much slower @code{seth/add3/jl} instruction sequence).
|
|
|
|
@item far
|
|
@cindex functions which handle memory bank switching
|
|
On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to
|
|
use a calling convention that takes care of switching memory banks when
|
|
entering and leaving a function. This calling convention is also the
|
|
default when using the @option{-mlong-calls} option.
|
|
|
|
On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions
|
|
to call and return from a function.
|
|
|
|
On 68HC11 the compiler will generate a sequence of instructions
|
|
to invoke a board-specific routine to switch the memory bank and call the
|
|
real function. The board-specific routine simulates a @code{call}.
|
|
At the end of a function, it will jump to a board-specific routine
|
|
instead of using @code{rts}. The board-specific return routine simulates
|
|
the @code{rtc}.
|
|
|
|
@item near
|
|
@cindex functions which do not handle memory bank switching on 68HC11/68HC12
|
|
On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to
|
|
use the normal calling convention based on @code{jsr} and @code{rts}.
|
|
This attribute can be used to cancel the effect of the @option{-mlong-calls}
|
|
option.
|
|
|
|
@end table
|
|
|
|
You can specify multiple attributes in a declaration by separating them
|
|
by commas within the double parentheses or by immediately following an
|
|
attribute declaration with another attribute declaration.
|
|
|
|
@cindex @code{#pragma}, reason for not using
|
|
@cindex pragma, reason for not using
|
|
Some people object to the @code{__attribute__} feature, suggesting that
|
|
ISO C's @code{#pragma} should be used instead. At the time
|
|
@code{__attribute__} was designed, there were two reasons for not doing
|
|
this.
|
|
|
|
@enumerate
|
|
@item
|
|
It is impossible to generate @code{#pragma} commands from a macro.
|
|
|
|
@item
|
|
There is no telling what the same @code{#pragma} might mean in another
|
|
compiler.
|
|
@end enumerate
|
|
|
|
These two reasons applied to almost any application that might have been
|
|
proposed for @code{#pragma}. It was basically a mistake to use
|
|
@code{#pragma} for @emph{anything}.
|
|
|
|
The ISO C99 standard includes @code{_Pragma}, which now allows pragmas
|
|
to be generated from macros. In addition, a @code{#pragma GCC}
|
|
namespace is now in use for GCC-specific pragmas. However, it has been
|
|
found convenient to use @code{__attribute__} to achieve a natural
|
|
attachment of attributes to their corresponding declarations, whereas
|
|
@code{#pragma GCC} is of use for constructs that do not naturally form
|
|
part of the grammar. @xref{Other Directives,,Miscellaneous
|
|
Preprocessing Directives, cpp, The C Preprocessor}.
|
|
|
|
@node Attribute Syntax
|
|
@section Attribute Syntax
|
|
@cindex attribute syntax
|
|
|
|
This section describes the syntax with which @code{__attribute__} may be
|
|
used, and the constructs to which attribute specifiers bind, for the C
|
|
language. Some details may vary for C++ and Objective-C@. Because of
|
|
infelicities in the grammar for attributes, some forms described here
|
|
may not be successfully parsed in all cases.
|
|
|
|
There are some problems with the semantics of attributes in C++. For
|
|
example, there are no manglings for attributes, although they may affect
|
|
code generation, so problems may arise when attributed types are used in
|
|
conjunction with templates or overloading. Similarly, @code{typeid}
|
|
does not distinguish between types with different attributes. Support
|
|
for attributes in C++ may be restricted in future to attributes on
|
|
declarations only, but not on nested declarators.
|
|
|
|
@xref{Function Attributes}, for details of the semantics of attributes
|
|
applying to functions. @xref{Variable Attributes}, for details of the
|
|
semantics of attributes applying to variables. @xref{Type Attributes},
|
|
for details of the semantics of attributes applying to structure, union
|
|
and enumerated types.
|
|
|
|
An @dfn{attribute specifier} is of the form
|
|
@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
|
|
is a possibly empty comma-separated sequence of @dfn{attributes}, where
|
|
each attribute is one of the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Empty. Empty attributes are ignored.
|
|
|
|
@item
|
|
A word (which may be an identifier such as @code{unused}, or a reserved
|
|
word such as @code{const}).
|
|
|
|
@item
|
|
A word, followed by, in parentheses, parameters for the attribute.
|
|
These parameters take one of the following forms:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
An identifier. For example, @code{mode} attributes use this form.
|
|
|
|
@item
|
|
An identifier followed by a comma and a non-empty comma-separated list
|
|
of expressions. For example, @code{format} attributes use this form.
|
|
|
|
@item
|
|
A possibly empty comma-separated list of expressions. For example,
|
|
@code{format_arg} attributes use this form with the list being a single
|
|
integer constant expression, and @code{alias} attributes use this form
|
|
with the list being a single string constant.
|
|
@end itemize
|
|
@end itemize
|
|
|
|
An @dfn{attribute specifier list} is a sequence of one or more attribute
|
|
specifiers, not separated by any other tokens.
|
|
|
|
An attribute specifier list may appear after the colon following a
|
|
label, other than a @code{case} or @code{default} label. The only
|
|
attribute it makes sense to use after a label is @code{unused}. This
|
|
feature is intended for code generated by programs which contains labels
|
|
that may be unused but which is compiled with @option{-Wall}. It would
|
|
not normally be appropriate to use in it human-written code, though it
|
|
could be useful in cases where the code that jumps to the label is
|
|
contained within an @code{#ifdef} conditional.
|
|
|
|
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.
|
|
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
|
|
defined is not complete until after the attribute specifiers.
|
|
@c Otherwise, there would be the following problems: a shift/reduce
|
|
@c conflict between attributes binding the struct/union/enum and
|
|
@c binding to the list of specifiers/qualifiers; and "aligned"
|
|
@c attributes could use sizeof for the structure, but the size could be
|
|
@c changed later by "packed" attributes.
|
|
|
|
Otherwise, an attribute specifier appears as part of a declaration,
|
|
counting declarations of unnamed parameters and type names, and relates
|
|
to that declaration (which may be nested in another declaration, for
|
|
example in the case of a parameter declaration), or to a particular declarator
|
|
within a declaration. Where an
|
|
attribute specifier is applied to a parameter declared as a function or
|
|
an array, it should apply to the function or array rather than the
|
|
pointer to which the parameter is implicitly converted, but this is not
|
|
yet correctly implemented.
|
|
|
|
Any list of specifiers and qualifiers at the start of a declaration may
|
|
contain attribute specifiers, whether or not such a list may in that
|
|
context contain storage class specifiers. (Some attributes, however,
|
|
are essentially in the nature of storage class specifiers, and only make
|
|
sense where storage class specifiers may be used; for example,
|
|
@code{section}.) There is one necessary limitation to this syntax: the
|
|
first old-style parameter declaration in a function definition cannot
|
|
begin with an attribute specifier, because such an attribute applies to
|
|
the function instead by syntax described below (which, however, is not
|
|
yet implemented in this case). In some other cases, attribute
|
|
specifiers are permitted by this grammar but not yet supported by the
|
|
compiler. All attribute specifiers in this place relate to the
|
|
declaration as a whole. In the obsolescent usage where a type of
|
|
@code{int} is implied by the absence of type specifiers, such a list of
|
|
specifiers and qualifiers may be an attribute specifier list with no
|
|
other specifiers or qualifiers.
|
|
|
|
An attribute specifier list may appear immediately before a declarator
|
|
(other than the first) in a comma-separated list of declarators in a
|
|
declaration of more than one identifier using a single list of
|
|
specifiers and qualifiers. Such attribute specifiers apply
|
|
only to the identifier before whose declarator they appear. For
|
|
example, in
|
|
|
|
@smallexample
|
|
__attribute__((noreturn)) void d0 (void),
|
|
__attribute__((format(printf, 1, 2))) d1 (const char *, ...),
|
|
d2 (void)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
the @code{noreturn} attribute applies to all the functions
|
|
declared; the @code{format} attribute only applies to @code{d1}.
|
|
|
|
An attribute specifier list may appear immediately before the comma,
|
|
@code{=} or semicolon terminating the declaration of an identifier other
|
|
than a function definition. At present, such attribute specifiers apply
|
|
to the declared object or function, but in future they may attach to the
|
|
outermost adjacent declarator. In simple cases there is no difference,
|
|
but, for example, in
|
|
|
|
@smallexample
|
|
void (****f)(void) __attribute__((noreturn));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
at present the @code{noreturn} attribute applies to @code{f}, which
|
|
causes a warning since @code{f} is not a function, but in future it may
|
|
apply to the function @code{****f}. The precise semantics of what
|
|
attributes in such cases will apply to are not yet specified. Where an
|
|
assembler name for an object or function is specified (@pxref{Asm
|
|
Labels}), at present the attribute must follow the @code{asm}
|
|
specification; in future, attributes before the @code{asm} specification
|
|
may apply to the adjacent declarator, and those after it to the declared
|
|
object or function.
|
|
|
|
An attribute specifier list may, in future, be permitted to appear after
|
|
the declarator in a function definition (before any old-style parameter
|
|
declarations or the function body).
|
|
|
|
Attribute specifiers may be mixed with type qualifiers appearing inside
|
|
the @code{[]} of a parameter array declarator, in the C99 construct by
|
|
which such qualifiers are applied to the pointer to which the array is
|
|
implicitly converted. Such attribute specifiers apply to the pointer,
|
|
not to the array, but at present this is not implemented and they are
|
|
ignored.
|
|
|
|
An attribute specifier list may appear at the start of a nested
|
|
declarator. At present, there are some limitations in this usage: the
|
|
attributes correctly apply to the declarator, but for most individual
|
|
attributes the semantics this implies are not implemented.
|
|
When attribute specifiers follow the @code{*} of a pointer
|
|
declarator, they may be mixed with any type qualifiers present.
|
|
The following describes the formal semantics of this syntax. It will make the
|
|
most sense if you are familiar with the formal specification of
|
|
declarators in the ISO C standard.
|
|
|
|
Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
|
|
D1}, where @code{T} contains declaration specifiers that specify a type
|
|
@var{Type} (such as @code{int}) and @code{D1} is a declarator that
|
|
contains an identifier @var{ident}. The type specified for @var{ident}
|
|
for derived declarators whose type does not include an attribute
|
|
specifier is as in the ISO C standard.
|
|
|
|
If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
|
|
and the declaration @code{T D} specifies the type
|
|
``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
|
|
@code{T D1} specifies the type ``@var{derived-declarator-type-list}
|
|
@var{attribute-specifier-list} @var{Type}'' for @var{ident}.
|
|
|
|
If @code{D1} has the form @code{*
|
|
@var{type-qualifier-and-attribute-specifier-list} D}, and the
|
|
declaration @code{T D} specifies the type
|
|
``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
|
|
@code{T D1} specifies the type ``@var{derived-declarator-type-list}
|
|
@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for
|
|
@var{ident}.
|
|
|
|
For example,
|
|
|
|
@smallexample
|
|
void (__attribute__((noreturn)) ****f) (void);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
specifies the type ``pointer to pointer to pointer to pointer to
|
|
non-returning function returning @code{void}''. As another example,
|
|
|
|
@smallexample
|
|
char *__attribute__((aligned(8))) *f;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
|
|
Note again that this does not work with most attributes; for example,
|
|
the usage of @samp{aligned} and @samp{noreturn} attributes given above
|
|
is not yet supported.
|
|
|
|
For compatibility with existing code written for compiler versions that
|
|
did not implement attributes on nested declarators, some laxity is
|
|
allowed in the placing of attributes. If an attribute that only applies
|
|
to types is applied to a declaration, it will be treated as applying to
|
|
the type of that declaration. If an attribute that only applies to
|
|
declarations is applied to the type of a declaration, it will be treated
|
|
as applying to that declaration; and, for compatibility with code
|
|
placing the attributes immediately before the identifier declared, such
|
|
an attribute applied to a function return type will be treated as
|
|
applying to the function type, and such an attribute applied to an array
|
|
element type will be treated as applying to the array type. If an
|
|
attribute that only applies to function types is applied to a
|
|
pointer-to-function type, it will be treated as applying to the pointer
|
|
target type; if such an attribute is applied to a function return type
|
|
that is not a pointer-to-function type, it will be treated as applying
|
|
to the function type.
|
|
|
|
@node Function Prototypes
|
|
@section Prototypes and Old-Style Function Definitions
|
|
@cindex function prototype declarations
|
|
@cindex old-style function definitions
|
|
@cindex promotion of formal parameters
|
|
|
|
GNU C extends ISO C to allow a function prototype to override a later
|
|
old-style non-prototype definition. Consider the following example:
|
|
|
|
@example
|
|
/* @r{Use prototypes unless the compiler is old-fashioned.} */
|
|
#ifdef __STDC__
|
|
#define P(x) x
|
|
#else
|
|
#define P(x) ()
|
|
#endif
|
|
|
|
/* @r{Prototype function declaration.} */
|
|
int isroot P((uid_t));
|
|
|
|
/* @r{Old-style function definition.} */
|
|
int
|
|
isroot (x) /* ??? lossage here ??? */
|
|
uid_t x;
|
|
@{
|
|
return x == 0;
|
|
@}
|
|
@end example
|
|
|
|
Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
|
|
not allow this example, because subword arguments in old-style
|
|
non-prototype definitions are promoted. Therefore in this example the
|
|
function definition's argument is really an @code{int}, which does not
|
|
match the prototype argument type of @code{short}.
|
|
|
|
This restriction of ISO C makes it hard to write code that is portable
|
|
to traditional C compilers, because the programmer does not know
|
|
whether the @code{uid_t} type is @code{short}, @code{int}, or
|
|
@code{long}. Therefore, in cases like these GNU C allows a prototype
|
|
to override a later old-style definition. More precisely, in GNU C, a
|
|
function prototype argument type overrides the argument type specified
|
|
by a later old-style definition if the former type is the same as the
|
|
latter type before promotion. Thus in GNU C the above example is
|
|
equivalent to the following:
|
|
|
|
@example
|
|
int isroot (uid_t);
|
|
|
|
int
|
|
isroot (uid_t x)
|
|
@{
|
|
return x == 0;
|
|
@}
|
|
@end example
|
|
|
|
@noindent
|
|
GNU C++ does not support old-style function definitions, so this
|
|
extension is irrelevant.
|
|
|
|
@node C++ Comments
|
|
@section C++ Style Comments
|
|
@cindex //
|
|
@cindex C++ comments
|
|
@cindex comments, C++ style
|
|
|
|
In GNU C, you may use C++ style comments, which start with @samp{//} and
|
|
continue until the end of the line. Many other C implementations allow
|
|
such comments, and they are included in the 1999 C standard. However,
|
|
C++ style comments are not recognized if you specify an @option{-std}
|
|
option specifying a version of ISO C before C99, or @option{-ansi}
|
|
(equivalent to @option{-std=c89}).
|
|
|
|
@node Dollar Signs
|
|
@section Dollar Signs in Identifier Names
|
|
@cindex $
|
|
@cindex dollar signs in identifier names
|
|
@cindex identifier names, dollar signs in
|
|
|
|
In GNU C, you may normally use dollar signs in identifier names.
|
|
This is because many traditional C implementations allow such identifiers.
|
|
However, dollar signs in identifiers are not supported on a few target
|
|
machines, typically because the target assembler does not allow them.
|
|
|
|
@node Character Escapes
|
|
@section The Character @key{ESC} in Constants
|
|
|
|
You can use the sequence @samp{\e} in a string or character constant to
|
|
stand for the ASCII character @key{ESC}.
|
|
|
|
@node Alignment
|
|
@section Inquiring on Alignment of Types or Variables
|
|
@cindex alignment
|
|
@cindex type alignment
|
|
@cindex variable alignment
|
|
|
|
The keyword @code{__alignof__} allows you to inquire about how an object
|
|
is aligned, or the minimum alignment usually required by a type. Its
|
|
syntax is just like @code{sizeof}.
|
|
|
|
For example, if the target machine requires a @code{double} value to be
|
|
aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
|
|
This is true on many RISC machines. On more traditional machine
|
|
designs, @code{__alignof__ (double)} is 4 or even 2.
|
|
|
|
Some machines never actually require alignment; they allow reference to any
|
|
data type even at an odd addresses. For these machines, @code{__alignof__}
|
|
reports the @emph{recommended} alignment of a type.
|
|
|
|
If the operand of @code{__alignof__} is an lvalue rather than a type,
|
|
its value is the required alignment for its type, taking into account
|
|
any minimum alignment specified with GCC's @code{__attribute__}
|
|
extension (@pxref{Variable Attributes}). For example, after this
|
|
declaration:
|
|
|
|
@example
|
|
struct foo @{ int x; char y; @} foo1;
|
|
@end example
|
|
|
|
@noindent
|
|
the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
|
|
alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
|
|
|
|
It is an error to ask for the alignment of an incomplete type.
|
|
|
|
@node Variable Attributes
|
|
@section Specifying Attributes of Variables
|
|
@cindex attribute of variables
|
|
@cindex variable attributes
|
|
|
|
The keyword @code{__attribute__} allows you to specify special
|
|
attributes of variables or structure fields. This keyword is followed
|
|
by an attribute specification inside double parentheses. Ten
|
|
attributes are currently defined for variables: @code{aligned},
|
|
@code{mode}, @code{nocommon}, @code{packed}, @code{section},
|
|
@code{transparent_union}, @code{unused}, @code{deprecated},
|
|
@code{vector_size}, and @code{weak}. Some other attributes are defined
|
|
for variables on particular target systems. Other attributes are
|
|
available for functions (@pxref{Function Attributes}) and for types
|
|
(@pxref{Type Attributes}). Other front ends might define more
|
|
attributes (@pxref{C++ Extensions,,Extensions to the C++ Language}).
|
|
|
|
You may also specify attributes with @samp{__} preceding and following
|
|
each keyword. This allows you to use them in header files without
|
|
being concerned about a possible macro of the same name. For example,
|
|
you may use @code{__aligned__} instead of @code{aligned}.
|
|
|
|
@xref{Attribute Syntax}, for details of the exact syntax for using
|
|
attributes.
|
|
|
|
@table @code
|
|
@cindex @code{aligned} attribute
|
|
@item aligned (@var{alignment})
|
|
This attribute specifies a minimum alignment for the variable or
|
|
structure field, measured in bytes. For example, the declaration:
|
|
|
|
@smallexample
|
|
int x __attribute__ ((aligned (16))) = 0;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes the compiler to allocate the global variable @code{x} on a
|
|
16-byte boundary. On a 68040, this could be used in conjunction with
|
|
an @code{asm} expression to access the @code{move16} instruction which
|
|
requires 16-byte aligned operands.
|
|
|
|
You can also specify the alignment of structure fields. For example, to
|
|
create a double-word aligned @code{int} pair, you could write:
|
|
|
|
@smallexample
|
|
struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is an alternative to creating a union with a @code{double} member
|
|
that forces the union to be double-word aligned.
|
|
|
|
As in the preceding examples, you can explicitly specify the alignment
|
|
(in bytes) that you wish the compiler to use for a given variable or
|
|
structure field. Alternatively, you can leave out the alignment factor
|
|
and just ask the compiler to align a variable or field to the maximum
|
|
useful alignment for the target machine you are compiling for. For
|
|
example, you could write:
|
|
|
|
@smallexample
|
|
short array[3] __attribute__ ((aligned));
|
|
@end smallexample
|
|
|
|
Whenever you leave out the alignment factor in an @code{aligned} attribute
|
|
specification, the compiler automatically sets the alignment for the declared
|
|
variable or field to the largest alignment which is ever used for any data
|
|
type on the target machine you are compiling for. Doing this can often make
|
|
copy operations more efficient, because the compiler can use whatever
|
|
instructions copy the biggest chunks of memory when performing copies to
|
|
or from the variables or fields that you have aligned this way.
|
|
|
|
The @code{aligned} attribute can only increase the alignment; but you
|
|
can decrease it by specifying @code{packed} as well. See below.
|
|
|
|
Note that the effectiveness of @code{aligned} attributes may be limited
|
|
by inherent limitations in your linker. On many systems, the linker is
|
|
only able to arrange for variables to be aligned up to a certain maximum
|
|
alignment. (For some linkers, the maximum supported alignment may
|
|
be very very small.) If your linker is only able to align variables
|
|
up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
|
|
in an @code{__attribute__} will still only provide you with 8 byte
|
|
alignment. See your linker documentation for further information.
|
|
|
|
@item cleanup (@var{cleanup_function})
|
|
@cindex @code{cleanup} attribute
|
|
The @code{cleanup} attribute runs a function when the variable goes
|
|
out of scope. This attribute can only be applied to auto function
|
|
scope variables; it may not be applied to parameters or variables
|
|
with static storage duration. The function must take one parameter,
|
|
a pointer to a type compatible with the variable. The return value
|
|
of the function (if any) is ignored.
|
|
|
|
If @option{-fexceptions} is enabled, then @var{cleanup_function}
|
|
will be run during the stack unwinding that happens during the
|
|
processing of the exception. Note that the @code{cleanup} attribute
|
|
does not allow the exception to be caught, only to perform an action.
|
|
It is undefined what happens if @var{cleanup_function} does not
|
|
return normally.
|
|
|
|
@item mode (@var{mode})
|
|
@cindex @code{mode} attribute
|
|
This attribute specifies the data type for the declaration---whichever
|
|
type corresponds to the mode @var{mode}. This in effect lets you
|
|
request an integer or floating point type according to its width.
|
|
|
|
You may also specify a mode of @samp{byte} or @samp{__byte__} to
|
|
indicate the mode corresponding to a one-byte integer, @samp{word} or
|
|
@samp{__word__} for the mode of a one-word integer, and @samp{pointer}
|
|
or @samp{__pointer__} for the mode used to represent pointers.
|
|
|
|
@item nocommon
|
|
@cindex @code{nocommon} attribute
|
|
@opindex fno-common
|
|
This attribute specifies requests GCC not to place a variable
|
|
``common'' but instead to allocate space for it directly. If you
|
|
specify the @option{-fno-common} flag, GCC will do this for all
|
|
variables.
|
|
|
|
Specifying the @code{nocommon} attribute for a variable provides an
|
|
initialization of zeros. A variable may only be initialized in one
|
|
source file.
|
|
|
|
@item packed
|
|
@cindex @code{packed} attribute
|
|
The @code{packed} attribute specifies that a variable or structure field
|
|
should have the smallest possible alignment---one byte for a variable,
|
|
and one bit for a field, unless you specify a larger value with the
|
|
@code{aligned} attribute.
|
|
|
|
Here is a structure in which the field @code{x} is packed, so that it
|
|
immediately follows @code{a}:
|
|
|
|
@example
|
|
struct foo
|
|
@{
|
|
char a;
|
|
int x[2] __attribute__ ((packed));
|
|
@};
|
|
@end example
|
|
|
|
@item section ("@var{section-name}")
|
|
@cindex @code{section} variable attribute
|
|
Normally, the compiler places the objects it generates in sections like
|
|
@code{data} and @code{bss}. Sometimes, however, you need additional sections,
|
|
or you need certain particular variables to appear in special sections,
|
|
for example to map to special hardware. The @code{section}
|
|
attribute specifies that a variable (or function) lives in a particular
|
|
section. For example, this small program uses several specific section names:
|
|
|
|
@smallexample
|
|
struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
|
|
struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
|
|
char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
|
|
int init_data __attribute__ ((section ("INITDATA"))) = 0;
|
|
|
|
main()
|
|
@{
|
|
/* Initialize stack pointer */
|
|
init_sp (stack + sizeof (stack));
|
|
|
|
/* Initialize initialized data */
|
|
memcpy (&init_data, &data, &edata - &data);
|
|
|
|
/* Turn on the serial ports */
|
|
init_duart (&a);
|
|
init_duart (&b);
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Use the @code{section} attribute with an @emph{initialized} definition
|
|
of a @emph{global} variable, as shown in the example. GCC issues
|
|
a warning and otherwise ignores the @code{section} attribute in
|
|
uninitialized variable declarations.
|
|
|
|
You may only use the @code{section} attribute with a fully initialized
|
|
global definition because of the way linkers work. The linker requires
|
|
each object be defined once, with the exception that uninitialized
|
|
variables tentatively go in the @code{common} (or @code{bss}) section
|
|
and can be multiply ``defined''. You can force a variable to be
|
|
initialized with the @option{-fno-common} flag or the @code{nocommon}
|
|
attribute.
|
|
|
|
Some file formats do not support arbitrary sections so the @code{section}
|
|
attribute is not available on all platforms.
|
|
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 putting 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 @code{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,
|
|
but the argument is passed as if its type were that of the first union
|
|
member. For more details see @xref{Type Attributes}. You can also use
|
|
this attribute on a @code{typedef} for a union data type; then it
|
|
applies to all function parameters with that type.
|
|
|
|
@item unused
|
|
This attribute, attached to a variable, means that the variable is meant
|
|
to be possibly unused. GCC will not produce a warning for this
|
|
variable.
|
|
|
|
@item deprecated
|
|
The @code{deprecated} attribute results in a warning if the variable
|
|
is used anywhere in the source file. This is useful when identifying
|
|
variables that are expected to be removed in a future version of a
|
|
program. The warning also includes the location of the declaration
|
|
of the deprecated variable, to enable users to easily find further
|
|
information about why the variable is deprecated, or what they should
|
|
do instead. Note that the warnings only occurs for uses:
|
|
|
|
@smallexample
|
|
extern int old_var __attribute__ ((deprecated));
|
|
extern int old_var;
|
|
int new_fn () @{ return old_var; @}
|
|
@end smallexample
|
|
|
|
results in a warning on line 3 but not line 2.
|
|
|
|
The @code{deprecated} attribute can also be used for functions and
|
|
types (@pxref{Function Attributes}, @pxref{Type Attributes}.)
|
|
|
|
@item vector_size (@var{bytes})
|
|
This attribute specifies the vector size for the variable, measured in
|
|
bytes. For example, the declaration:
|
|
|
|
@smallexample
|
|
int foo __attribute__ ((vector_size (16)));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes the compiler to set the mode for @code{foo}, to be 16 bytes,
|
|
divided into @code{int} sized units. Assuming a 32-bit int (a vector of
|
|
4 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@.
|
|
|
|
This attribute is only applicable to integral and float scalars,
|
|
although arrays, pointers, and function return values are allowed in
|
|
conjunction with this construct.
|
|
|
|
Aggregates with this attribute are invalid, even if they are of the same
|
|
size as a corresponding scalar. For example, the declaration:
|
|
|
|
@smallexample
|
|
struct S @{ int a; @};
|
|
struct S __attribute__ ((vector_size (16))) foo;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
is invalid even if the size of the structure is the same as the size of
|
|
the @code{int}.
|
|
|
|
@item weak
|
|
The @code{weak} attribute is described in @xref{Function Attributes}.
|
|
|
|
@item model (@var{model-name})
|
|
@cindex variable addressability on the M32R/D
|
|
Use this attribute on the M32R/D to set the addressability of an object.
|
|
The identifier @var{model-name} is one of @code{small}, @code{medium},
|
|
or @code{large}, representing each of the code models.
|
|
|
|
Small model objects live in the lower 16MB of memory (so that their
|
|
addresses can be loaded with the @code{ld24} instruction).
|
|
|
|
Medium and large model objects may live anywhere in the 32-bit address space
|
|
(the compiler will generate @code{seth/add3} instructions to load their
|
|
addresses).
|
|
|
|
@end table
|
|
|
|
To specify multiple attributes, separate them by commas within the
|
|
double parentheses: for example, @samp{__attribute__ ((aligned (16),
|
|
packed))}.
|
|
|
|
@node Type Attributes
|
|
@section Specifying Attributes of Types
|
|
@cindex attribute of types
|
|
@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}).
|
|
|
|
You may also specify any one of these attributes with @samp{__}
|
|
preceding and following its keyword. This allows you to use these
|
|
attributes in header files without being concerned about a possible
|
|
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 also specify attributes between the enum, struct or union
|
|
tag and the name of the type rather than after the closing brace.
|
|
|
|
@xref{Attribute Syntax}, for details of the exact syntax for using
|
|
attributes.
|
|
|
|
@table @code
|
|
@cindex @code{aligned} attribute
|
|
@item aligned (@var{alignment})
|
|
This attribute specifies a minimum alignment (in bytes) for variables
|
|
of the specified type. For example, the declarations:
|
|
|
|
@smallexample
|
|
struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
|
|
typedef int more_aligned_int __attribute__ ((aligned (8)));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
force the compiler to insure (as far as it can) that each variable whose
|
|
type is @code{struct S} or @code{more_aligned_int} will be allocated and
|
|
aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
|
|
variables of type @code{struct S} aligned to 8-byte boundaries allows
|
|
the compiler to use the @code{ldd} and @code{std} (doubleword load and
|
|
store) instructions when copying one variable of type @code{struct S} to
|
|
another, thus improving run-time efficiency.
|
|
|
|
Note that the alignment of any given @code{struct} or @code{union} type
|
|
is required by the ISO C standard to be at least a perfect multiple of
|
|
the lowest common multiple of the alignments of all of the members of
|
|
the @code{struct} or @code{union} in question. This means that you @emph{can}
|
|
effectively adjust the alignment of a @code{struct} or @code{union}
|
|
type by attaching an @code{aligned} attribute to any one of the members
|
|
of such a type, but the notation illustrated in the example above is a
|
|
more obvious, intuitive, and readable way to request the compiler to
|
|
adjust the alignment of an entire @code{struct} or @code{union} type.
|
|
|
|
As in the preceding example, you can explicitly specify the alignment
|
|
(in bytes) that you wish the compiler to use for a given @code{struct}
|
|
or @code{union} type. Alternatively, you can leave out the alignment factor
|
|
and just ask the compiler to align a type to the maximum
|
|
useful alignment for the target machine you are compiling for. For
|
|
example, you could write:
|
|
|
|
@smallexample
|
|
struct S @{ short f[3]; @} __attribute__ ((aligned));
|
|
@end smallexample
|
|
|
|
Whenever you leave out the alignment factor in an @code{aligned}
|
|
attribute specification, the compiler automatically sets the alignment
|
|
for the type to the largest alignment which is ever used for any data
|
|
type on the target machine you are compiling for. Doing this can often
|
|
make copy operations more efficient, because the compiler can use
|
|
whatever instructions copy the biggest chunks of memory when performing
|
|
copies to or from the variables which have types that you have aligned
|
|
this way.
|
|
|
|
In the example above, if the size of each @code{short} is 2 bytes, then
|
|
the size of the entire @code{struct S} type is 6 bytes. The smallest
|
|
power of two which is greater than or equal to that is 8, so the
|
|
compiler sets the alignment for the entire @code{struct S} type to 8
|
|
bytes.
|
|
|
|
Note that although you can ask the compiler to select a time-efficient
|
|
alignment for a given type and then declare only individual stand-alone
|
|
objects of that type, the compiler's ability to select a time-efficient
|
|
alignment is primarily useful only when you plan to create arrays of
|
|
variables having the relevant (efficiently aligned) type. If you
|
|
declare or use arrays of variables of an efficiently-aligned type, then
|
|
it is likely that your program will also be doing pointer arithmetic (or
|
|
subscripting, which amounts to the same thing) on pointers to the
|
|
relevant type, and the code that the compiler generates for these
|
|
pointer arithmetic operations will often be more efficient for
|
|
efficiently-aligned types than for other types.
|
|
|
|
The @code{aligned} attribute can only increase the alignment; but you
|
|
can decrease it by specifying @code{packed} as well. See below.
|
|
|
|
Note that the effectiveness of @code{aligned} attributes may be limited
|
|
by inherent limitations in your linker. On many systems, the linker is
|
|
only able to arrange for variables to be aligned up to a certain maximum
|
|
alignment. (For some linkers, the maximum supported alignment may
|
|
be very very small.) If your linker is only able to align variables
|
|
up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
|
|
in an @code{__attribute__} will still only provide you with 8 byte
|
|
alignment. See your linker documentation for further information.
|
|
|
|
@item packed
|
|
This attribute, attached to an @code{enum}, @code{struct}, or
|
|
@code{union} type definition, specified that the minimum required memory
|
|
be used to represent the type.
|
|
|
|
@opindex fshort-enums
|
|
Specifying this attribute for @code{struct} and @code{union} types is
|
|
equivalent to specifying the @code{packed} attribute on each of the
|
|
structure or union members. Specifying the @option{-fshort-enums}
|
|
flag on the line is equivalent to specifying the @code{packed}
|
|
attribute on all @code{enum} definitions.
|
|
|
|
You may only specify this attribute after a closing curly brace on an
|
|
@code{enum} definition, not in a @code{typedef} declaration, unless that
|
|
declaration also contains the definition of the @code{enum}.
|
|
|
|
@item transparent_union
|
|
This attribute, attached to a @code{union} type definition, indicates
|
|
that any function parameter having that union type causes calls to that
|
|
function to be treated in a special way.
|
|
|
|
First, the argument corresponding to a transparent union type can be of
|
|
any type in the union; no cast is required. Also, if the union contains
|
|
a pointer type, the corresponding argument can be a null pointer
|
|
constant or a void pointer expression; and if the union contains a void
|
|
pointer type, the corresponding argument can be any pointer expression.
|
|
If the union member type is a pointer, qualifiers like @code{const} on
|
|
the referenced type must be respected, just as with normal pointer
|
|
conversions.
|
|
|
|
Second, the argument is passed to the function using the calling
|
|
conventions of first member of the transparent union, not the calling
|
|
conventions of the union itself. All members of the union must have the
|
|
same machine representation; this is necessary for this argument passing
|
|
to work properly.
|
|
|
|
Transparent unions are designed for library functions that have multiple
|
|
interfaces for compatibility reasons. For example, suppose the
|
|
@code{wait} function must accept either a value of type @code{int *} to
|
|
comply with Posix, or a value of type @code{union wait *} to comply with
|
|
the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
|
|
@code{wait} would accept both kinds of arguments, but it would also
|
|
accept any other pointer type and this would make argument type checking
|
|
less useful. Instead, @code{<sys/wait.h>} might define the interface
|
|
as follows:
|
|
|
|
@smallexample
|
|
typedef union
|
|
@{
|
|
int *__ip;
|
|
union wait *__up;
|
|
@} wait_status_ptr_t __attribute__ ((__transparent_union__));
|
|
|
|
pid_t wait (wait_status_ptr_t);
|
|
@end smallexample
|
|
|
|
This interface allows either @code{int *} or @code{union wait *}
|
|
arguments to be passed, using the @code{int *} calling convention.
|
|
The program can call @code{wait} with arguments of either type:
|
|
|
|
@example
|
|
int w1 () @{ int w; return wait (&w); @}
|
|
int w2 () @{ union wait w; return wait (&w); @}
|
|
@end example
|
|
|
|
With this interface, @code{wait}'s implementation might look like this:
|
|
|
|
@example
|
|
pid_t wait (wait_status_ptr_t p)
|
|
@{
|
|
return waitpid (-1, p.__ip, 0);
|
|
@}
|
|
@end example
|
|
|
|
@item unused
|
|
When attached to a type (including a @code{union} or a @code{struct}),
|
|
this attribute means that variables of that type are meant to appear
|
|
possibly unused. GCC will not produce a warning for any variables of
|
|
that type, even if the variable appears to do nothing. This is often
|
|
the case with lock or thread classes, which are usually defined and then
|
|
not referenced, but contain constructors and destructors that have
|
|
nontrivial bookkeeping functions.
|
|
|
|
@item deprecated
|
|
The @code{deprecated} attribute results in a warning if the type
|
|
is used anywhere in the source file. This is useful when identifying
|
|
types that are expected to be removed in a future version of a program.
|
|
If possible, the warning also includes the location of the declaration
|
|
of the deprecated type, to enable users to easily find further
|
|
information about why the type is deprecated, or what they should do
|
|
instead. Note that the warnings only occur for uses and then only
|
|
if the type is being applied to an identifier that itself is not being
|
|
declared as deprecated.
|
|
|
|
@smallexample
|
|
typedef int T1 __attribute__ ((deprecated));
|
|
T1 x;
|
|
typedef T1 T2;
|
|
T2 y;
|
|
typedef T1 T3 __attribute__ ((deprecated));
|
|
T3 z __attribute__ ((deprecated));
|
|
@end smallexample
|
|
|
|
results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
|
|
warning is issued for line 4 because T2 is not explicitly
|
|
deprecated. Line 5 has no warning because T3 is explicitly
|
|
deprecated. Similarly for line 6.
|
|
|
|
The @code{deprecated} attribute can also be used for functions and
|
|
variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
|
|
|
|
@item may_alias
|
|
Accesses to objects with types with this attribute are not subjected to
|
|
type-based alias analysis, but are instead assumed to be able to alias
|
|
any other type of objects, just like the @code{char} type. See
|
|
@option{-fstrict-aliasing} for more information on aliasing issues.
|
|
|
|
Example of use:
|
|
|
|
@smallexample
|
|
typedef short __attribute__((__may_alias__)) short_a;
|
|
|
|
int
|
|
main (void)
|
|
@{
|
|
int a = 0x12345678;
|
|
short_a *b = (short_a *) &a;
|
|
|
|
b[1] = 0;
|
|
|
|
if (a == 0x12345678)
|
|
abort();
|
|
|
|
exit(0);
|
|
@}
|
|
@end smallexample
|
|
|
|
If you replaced @code{short_a} with @code{short} in the variable
|
|
declaration, the above program would abort when compiled with
|
|
@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
|
|
above in recent GCC versions.
|
|
@end table
|
|
|
|
To specify multiple attributes, separate them by commas within the
|
|
double parentheses: for example, @samp{__attribute__ ((aligned (16),
|
|
packed))}.
|
|
|
|
@node Inline
|
|
@section An Inline Function is As Fast As a Macro
|
|
@cindex inline functions
|
|
@cindex integrating function code
|
|
@cindex open coding
|
|
@cindex macros, inline alternative
|
|
|
|
By declaring a function @code{inline}, you can direct GCC to
|
|
integrate that function's code into the code for its callers. This
|
|
makes execution faster by eliminating the function-call overhead; in
|
|
addition, if any of the actual argument values are constant, their known
|
|
values may permit simplifications at compile time so that not all of the
|
|
inline function's code needs to be included. The effect on code size is
|
|
less predictable; object code may be larger or smaller with function
|
|
inlining, depending on the particular case. Inlining of functions is an
|
|
optimization and it really ``works'' only in optimizing compilation. If
|
|
you don't use @option{-O}, no function is really inline.
|
|
|
|
Inline functions are included in the ISO C99 standard, but there are
|
|
currently substantial differences between what GCC implements and what
|
|
the ISO C99 standard requires.
|
|
|
|
To declare a function inline, use the @code{inline} keyword in its
|
|
declaration, like this:
|
|
|
|
@example
|
|
inline int
|
|
inc (int *a)
|
|
@{
|
|
(*a)++;
|
|
@}
|
|
@end example
|
|
|
|
(If you are writing a header file to be included in ISO C programs, write
|
|
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
|
|
You can also make all ``simple enough'' functions inline with the option
|
|
@option{-finline-functions}.
|
|
|
|
@opindex Winline
|
|
Note that certain usages in a function definition can make it unsuitable
|
|
for inline substitution. Among these usages are: use of varargs, use of
|
|
alloca, use of variable sized data types (@pxref{Variable Length}),
|
|
use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
|
|
and nested functions (@pxref{Nested Functions}). Using @option{-Winline}
|
|
will warn when a function marked @code{inline} could not be substituted,
|
|
and will give the reason for the failure.
|
|
|
|
Note that in C and Objective-C, unlike C++, the @code{inline} keyword
|
|
does not affect the linkage of the function.
|
|
|
|
@cindex automatic @code{inline} for C++ member fns
|
|
@cindex @code{inline} automatic for C++ member fns
|
|
@cindex member fns, automatically @code{inline}
|
|
@cindex C++ member fns, automatically @code{inline}
|
|
@opindex fno-default-inline
|
|
GCC automatically inlines member functions defined within the class
|
|
body of C++ programs even if they are not explicitly declared
|
|
@code{inline}. (You can override this with @option{-fno-default-inline};
|
|
@pxref{C++ Dialect Options,,Options Controlling C++ Dialect}.)
|
|
|
|
@cindex inline functions, omission of
|
|
@opindex fkeep-inline-functions
|
|
When a function is both inline and @code{static}, if all calls to the
|
|
function are integrated into the caller, and the function's address is
|
|
never used, then the function's own assembler code is never referenced.
|
|
In this case, GCC does not actually output assembler code for the
|
|
function, unless you specify the option @option{-fkeep-inline-functions}.
|
|
Some calls cannot be integrated for various reasons (in particular,
|
|
calls that precede the function's definition cannot be integrated, and
|
|
neither can recursive calls within the definition). If there is a
|
|
nonintegrated call, then the function is compiled to assembler code as
|
|
usual. The function must also be compiled as usual if the program
|
|
refers to its address, because that can't be inlined.
|
|
|
|
@cindex non-static inline function
|
|
When an inline function is not @code{static}, then the compiler must assume
|
|
that there may be calls from other source files; since a global symbol can
|
|
be defined only once in any program, the function must not be defined in
|
|
the other source files, so the calls therein cannot be integrated.
|
|
Therefore, a non-@code{static} inline function is always compiled on its
|
|
own in the usual fashion.
|
|
|
|
If you specify both @code{inline} and @code{extern} in the function
|
|
definition, then the definition is used only for inlining. In no case
|
|
is the function compiled on its own, not even if you refer to its
|
|
address explicitly. Such an address becomes an external reference, as
|
|
if you had only declared the function, and had not defined it.
|
|
|
|
This combination of @code{inline} and @code{extern} has almost the
|
|
effect of a macro. The way to use it is to put a function definition in
|
|
a header file with these keywords, and put another copy of the
|
|
definition (lacking @code{inline} and @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.
|
|
|
|
For future compatibility with when GCC implements ISO C99 semantics for
|
|
inline functions, it is best to use @code{static inline} only. (The
|
|
existing semantics will remain available when @option{-std=gnu89} is
|
|
specified, but eventually the default will be @option{-std=gnu99} and
|
|
that will implement the C99 semantics, though it does not do so yet.)
|
|
|
|
GCC does not inline any functions when not optimizing unless you specify
|
|
the @samp{always_inline} attribute for the function, like this:
|
|
|
|
@example
|
|
/* Prototype. */
|
|
inline void foo (const char) __attribute__((always_inline));
|
|
@end example
|
|
|
|
@node Extended Asm
|
|
@section Assembler Instructions with C Expression Operands
|
|
@cindex extended @code{asm}
|
|
@cindex @code{asm} expressions
|
|
@cindex assembler instructions
|
|
@cindex registers
|
|
|
|
In an assembler instruction using @code{asm}, you can specify the
|
|
operands of the instruction using C expressions. This means you need not
|
|
guess which registers or memory locations will contain the data you want
|
|
to use.
|
|
|
|
You must specify an assembler instruction template much like what
|
|
appears in a machine description, plus an operand constraint string for
|
|
each operand.
|
|
|
|
For example, here is how to use the 68881's @code{fsinx} instruction:
|
|
|
|
@example
|
|
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
|
|
@end example
|
|
|
|
@noindent
|
|
Here @code{angle} is the C expression for the input operand while
|
|
@code{result} is that of the output operand. Each has @samp{"f"} as its
|
|
operand constraint, saying that a floating point register is required.
|
|
The @samp{=} in @samp{=f} indicates that the operand is an output; all
|
|
output operands' constraints must use @samp{=}. The constraints use the
|
|
same language used in the machine description (@pxref{Constraints}).
|
|
|
|
Each operand is described by an operand-constraint string followed by
|
|
the C expression in parentheses. A colon separates the assembler
|
|
template from the first output operand and another separates the last
|
|
output operand from the first input, if any. Commas separate the
|
|
operands within each group. The total number of operands is currently
|
|
limited to 30; this limitation may be lifted in some future version of
|
|
GCC.
|
|
|
|
If there are no output operands but there are input operands, you must
|
|
place two consecutive colons surrounding the place where the output
|
|
operands would go.
|
|
|
|
As of GCC version 3.1, it is also possible to specify input and output
|
|
operands using symbolic names which can be referenced within the
|
|
assembler code. These names are specified inside square brackets
|
|
preceding the constraint string, and can be referenced inside the
|
|
assembler code using @code{%[@var{name}]} instead of a percentage sign
|
|
followed by the operand number. Using named operands the above example
|
|
could look like:
|
|
|
|
@example
|
|
asm ("fsinx %[angle],%[output]"
|
|
: [output] "=f" (result)
|
|
: [angle] "f" (angle));
|
|
@end example
|
|
|
|
@noindent
|
|
Note that the symbolic operand names have no relation whatsoever to
|
|
other C identifiers. You may use any name you like, even those of
|
|
existing C symbols, but must ensure that no two operands within the same
|
|
assembler construct use the same symbolic name.
|
|
|
|
Output operand expressions must be lvalues; the compiler can check this.
|
|
The input operands need not be lvalues. The compiler cannot check
|
|
whether the operands have data types that are reasonable for the
|
|
instruction being executed. It does not parse the assembler instruction
|
|
template and does not know what it means or even whether it is valid
|
|
assembler input. The extended @code{asm} feature is most often used for
|
|
machine instructions the compiler itself does not know exist. If
|
|
the output expression cannot be directly addressed (for example, it is a
|
|
bit-field), your constraint must allow a register. In that case, GCC
|
|
will use the register as the output of the @code{asm}, and then store
|
|
that register into the output.
|
|
|
|
The ordinary output operands must be write-only; GCC will assume that
|
|
the values in these operands before the instruction are dead and need
|
|
not be generated. Extended asm supports input-output or read-write
|
|
operands. Use the constraint character @samp{+} to indicate such an
|
|
operand and list it with the output operands.
|
|
|
|
When the constraints for the read-write operand (or the operand in which
|
|
only some of the bits are to be changed) allows a register, you may, as
|
|
an alternative, logically split its function into two separate operands,
|
|
one input operand and one write-only output operand. The connection
|
|
between them is expressed by constraints which say they need to be in
|
|
the same location when the instruction executes. You can use the same C
|
|
expression for both operands, or different expressions. For example,
|
|
here we write the (fictitious) @samp{combine} instruction with
|
|
@code{bar} as its read-only source operand and @code{foo} as its
|
|
read-write destination:
|
|
|
|
@example
|
|
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
|
|
@end example
|
|
|
|
@noindent
|
|
The constraint @samp{"0"} for operand 1 says that it must occupy the
|
|
same location as operand 0. A number in constraint is allowed only in
|
|
an input operand and it must refer to an output operand.
|
|
|
|
Only a number in the constraint can guarantee that one operand will be in
|
|
the same place as another. The mere fact that @code{foo} is the value
|
|
of both operands is not enough to guarantee that they will be in the
|
|
same place in the generated assembler code. The following would not
|
|
work reliably:
|
|
|
|
@example
|
|
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
|
|
@end example
|
|
|
|
Various optimizations or reloading could cause operands 0 and 1 to be in
|
|
different registers; GCC knows no reason not to do so. For example, the
|
|
compiler might find a copy of the value of @code{foo} in one register and
|
|
use it for operand 1, but generate the output operand 0 in a different
|
|
register (copying it afterward to @code{foo}'s own address). Of course,
|
|
since the register for operand 1 is not even mentioned in the assembler
|
|
code, the result will not work, but GCC can't tell that.
|
|
|
|
As of GCC version 3.1, one may write @code{[@var{name}]} instead of
|
|
the operand number for a matching constraint. For example:
|
|
|
|
@example
|
|
asm ("cmoveq %1,%2,%[result]"
|
|
: [result] "=r"(result)
|
|
: "r" (test), "r"(new), "[result]"(old));
|
|
@end example
|
|
|
|
Some instructions clobber specific hard registers. To describe this,
|
|
write a third colon after the input operands, followed by the names of
|
|
the clobbered hard registers (given as strings). Here is a realistic
|
|
example for the VAX:
|
|
|
|
@example
|
|
asm volatile ("movc3 %0,%1,%2"
|
|
: /* no outputs */
|
|
: "g" (from), "g" (to), "g" (count)
|
|
: "r0", "r1", "r2", "r3", "r4", "r5");
|
|
@end example
|
|
|
|
You may not write a clobber description in a way that overlaps with an
|
|
input or output operand. For example, you may not have an operand
|
|
describing a register class with one member if you mention that register
|
|
in the clobber list. Variables declared to live in specific registers
|
|
(@pxref{Explicit Reg Vars}), and used as asm input or output operands must
|
|
have no part mentioned in the clobber description.
|
|
There is no way for you to specify that an input
|
|
operand is modified without also specifying it as an output
|
|
operand. Note that if all the output operands you specify are for this
|
|
purpose (and hence unused), you will then also need to specify
|
|
@code{volatile} for the @code{asm} construct, as described below, to
|
|
prevent GCC from deleting the @code{asm} statement as unused.
|
|
|
|
If you refer to a particular hardware register from the assembler code,
|
|
you will probably have to list the register after the third colon to
|
|
tell the compiler the register's value is modified. In some assemblers,
|
|
the register names begin with @samp{%}; to produce one @samp{%} in the
|
|
assembler code, you must write @samp{%%} in the input.
|
|
|
|
If your assembler instruction can alter the condition code register, add
|
|
@samp{cc} to the list of clobbered registers. GCC on some machines
|
|
represents the condition codes as a specific hardware register;
|
|
@samp{cc} serves to name this register. On other machines, the
|
|
condition code is handled differently, and specifying @samp{cc} has no
|
|
effect. But it is valid no matter what the machine.
|
|
|
|
If your assembler instruction modifies memory in an unpredictable
|
|
fashion, add @samp{memory} to the list of clobbered registers. This
|
|
will cause GCC to not keep memory values cached in registers across
|
|
the assembler instruction. You will also want to add the
|
|
@code{volatile} keyword if the memory affected is not listed in the
|
|
inputs or outputs of the @code{asm}, as the @samp{memory} clobber does
|
|
not count as a side-effect of the @code{asm}.
|
|
|
|
You can put multiple assembler instructions together in a single
|
|
@code{asm} template, separated by the characters normally used in assembly
|
|
code for the system. A combination that works in most places is a newline
|
|
to break the line, plus a tab character to move to the instruction field
|
|
(written as @samp{\n\t}). Sometimes semicolons can be used, if the
|
|
assembler allows semicolons as a line-breaking character. Note that some
|
|
assembler dialects use semicolons to start a comment.
|
|
The input operands are guaranteed not to use any of the clobbered
|
|
registers, and neither will the output operands' addresses, so you can
|
|
read and write the clobbered registers as many times as you like. Here
|
|
is an example of multiple instructions in a template; it assumes the
|
|
subroutine @code{_foo} accepts arguments in registers 9 and 10:
|
|
|
|
@example
|
|
asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
|
|
: /* no outputs */
|
|
: "g" (from), "g" (to)
|
|
: "r9", "r10");
|
|
@end example
|
|
|
|
Unless an output operand has the @samp{&} constraint modifier, GCC
|
|
may allocate it in the same register as an unrelated input operand, on
|
|
the assumption the inputs are consumed before the outputs are produced.
|
|
This assumption may be false if the assembler code actually consists of
|
|
more than one instruction. In such a case, use @samp{&} for each output
|
|
operand that may not overlap an input. @xref{Modifiers}.
|
|
|
|
If you want to test the condition code produced by an assembler
|
|
instruction, you must include a branch and a label in the @code{asm}
|
|
construct, as follows:
|
|
|
|
@example
|
|
asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
|
|
: "g" (result)
|
|
: "g" (input));
|
|
@end example
|
|
|
|
@noindent
|
|
This assumes your assembler supports local labels, as the GNU assembler
|
|
and most Unix assemblers do.
|
|
|
|
Speaking of labels, jumps from one @code{asm} to another are not
|
|
supported. The compiler's optimizers do not know about these jumps, and
|
|
therefore they cannot take account of them when deciding how to
|
|
optimize.
|
|
|
|
@cindex macros containing @code{asm}
|
|
Usually the most convenient way to use these @code{asm} instructions is to
|
|
encapsulate them in macros that look like functions. For example,
|
|
|
|
@example
|
|
#define sin(x) \
|
|
(@{ double __value, __arg = (x); \
|
|
asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
|
|
__value; @})
|
|
@end example
|
|
|
|
@noindent
|
|
Here the variable @code{__arg} is used to make sure that the instruction
|
|
operates on a proper @code{double} value, and to accept only those
|
|
arguments @code{x} which can convert automatically to a @code{double}.
|
|
|
|
Another way to make sure the instruction operates on the correct data
|
|
type is to use a cast in the @code{asm}. This is different from using a
|
|
variable @code{__arg} in that it converts more different types. For
|
|
example, if the desired type were @code{int}, casting the argument to
|
|
@code{int} would accept a pointer with no complaint, while assigning the
|
|
argument to an @code{int} variable named @code{__arg} would warn about
|
|
using a pointer unless the caller explicitly casts it.
|
|
|
|
If an @code{asm} has output operands, GCC assumes for optimization
|
|
purposes the instruction has no side effects except to change the output
|
|
operands. This does not mean instructions with a side effect cannot be
|
|
used, but you must be careful, because the compiler may eliminate them
|
|
if the output operands aren't used, or move them out of loops, or
|
|
replace two with one if they constitute a common subexpression. Also,
|
|
if your instruction does have a side effect on a variable that otherwise
|
|
appears not to change, the old value of the variable may be reused later
|
|
if it happens to be found in a register.
|
|
|
|
You can prevent an @code{asm} instruction from being deleted, moved
|
|
significantly, or combined, by writing the keyword @code{volatile} after
|
|
the @code{asm}. For example:
|
|
|
|
@example
|
|
#define get_and_set_priority(new) \
|
|
(@{ int __old; \
|
|
asm volatile ("get_and_set_priority %0, %1" \
|
|
: "=g" (__old) : "g" (new)); \
|
|
__old; @})
|
|
@end example
|
|
|
|
@noindent
|
|
If you write an @code{asm} instruction with no outputs, GCC will know
|
|
the instruction has side-effects and will not delete the instruction or
|
|
move it outside of loops.
|
|
|
|
The @code{volatile} keyword indicates that the instruction has
|
|
important side-effects. GCC will not delete a volatile @code{asm} if
|
|
it is reachable. (The instruction can still be deleted if GCC can
|
|
prove that control-flow will never reach the location of the
|
|
instruction.) In addition, GCC will not reschedule instructions
|
|
across a volatile @code{asm} instruction. For example:
|
|
|
|
@example
|
|
*(volatile int *)addr = foo;
|
|
asm volatile ("eieio" : : );
|
|
@end example
|
|
|
|
@noindent
|
|
Assume @code{addr} contains the address of a memory mapped device
|
|
register. The PowerPC @code{eieio} instruction (Enforce In-order
|
|
Execution of I/O) tells the CPU to make sure that the store to that
|
|
device register happens before it issues any other I/O@.
|
|
|
|
Note that even a volatile @code{asm} instruction can be moved in ways
|
|
that appear insignificant to the compiler, such as across jump
|
|
instructions. You can't expect a sequence of volatile @code{asm}
|
|
instructions to remain perfectly consecutive. If you want consecutive
|
|
output, use a single @code{asm}. Also, GCC will perform some
|
|
optimizations across a volatile @code{asm} instruction; GCC does not
|
|
``forget everything'' when it encounters a volatile @code{asm}
|
|
instruction the way some other compilers do.
|
|
|
|
An @code{asm} instruction without any operands or clobbers (an ``old
|
|
style'' @code{asm}) will be treated identically to a volatile
|
|
@code{asm} instruction.
|
|
|
|
It is a natural idea to look for a way to give access to the condition
|
|
code left by the assembler instruction. However, when we attempted to
|
|
implement this, we found no way to make it work reliably. The problem
|
|
is that output operands might need reloading, which would result in
|
|
additional following ``store'' instructions. On most machines, these
|
|
instructions would alter the condition code before there was time to
|
|
test it. This problem doesn't arise for ordinary ``test'' and
|
|
``compare'' instructions because they don't have any output operands.
|
|
|
|
For reasons similar to those described above, it is not possible to give
|
|
an assembler instruction access to the condition code left by previous
|
|
instructions.
|
|
|
|
If you are writing a header file that should be includable in ISO C
|
|
programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
|
|
Keywords}.
|
|
|
|
@subsection i386 floating point asm operands
|
|
|
|
There are several rules on the usage of stack-like regs in
|
|
asm_operands insns. These rules apply only to the operands that are
|
|
stack-like regs:
|
|
|
|
@enumerate
|
|
@item
|
|
Given a set of input regs that die in an asm_operands, it is
|
|
necessary to know which are implicitly popped by the asm, and
|
|
which must be explicitly popped by gcc.
|
|
|
|
An input reg that is implicitly popped by the asm must be
|
|
explicitly clobbered, unless it is constrained to match an
|
|
output operand.
|
|
|
|
@item
|
|
For any input reg that is implicitly popped by an asm, it is
|
|
necessary to know how to adjust the stack to compensate for the pop.
|
|
If any non-popped input is closer to the top of the reg-stack than
|
|
the implicitly popped reg, it would not be possible to know what the
|
|
stack looked like---it's not clear how the rest of the stack ``slides
|
|
up''.
|
|
|
|
All implicitly popped input regs must be closer to the top of
|
|
the reg-stack than any input that is not implicitly popped.
|
|
|
|
It is possible that if an input dies in an insn, reload might
|
|
use the input reg for an output reload. Consider this example:
|
|
|
|
@example
|
|
asm ("foo" : "=t" (a) : "f" (b));
|
|
@end example
|
|
|
|
This asm says that input B is not popped by the asm, and that
|
|
the asm pushes a result onto the reg-stack, i.e., the stack is one
|
|
deeper after the asm than it was before. But, it is possible that
|
|
reload will think that it can use the same reg for both the input and
|
|
the output, if input B dies in this insn.
|
|
|
|
If any input operand uses the @code{f} constraint, all output reg
|
|
constraints must use the @code{&} earlyclobber.
|
|
|
|
The asm above would be written as
|
|
|
|
@example
|
|
asm ("foo" : "=&t" (a) : "f" (b));
|
|
@end example
|
|
|
|
@item
|
|
Some operands need to be in particular places on the stack. All
|
|
output operands fall in this category---there is no other way to
|
|
know which regs the outputs appear in unless the user indicates
|
|
this in the constraints.
|
|
|
|
Output operands must specifically indicate which reg an output
|
|
appears in after an asm. @code{=f} is not allowed: the operand
|
|
constraints must select a class with a single reg.
|
|
|
|
@item
|
|
Output operands may not be ``inserted'' between existing stack regs.
|
|
Since no 387 opcode uses a read/write operand, all output operands
|
|
are dead before the asm_operands, and are pushed by the asm_operands.
|
|
It makes no sense to push anywhere but the top of the reg-stack.
|
|
|
|
Output operands must start at the top of the reg-stack: output
|
|
operands may not ``skip'' a reg.
|
|
|
|
@item
|
|
Some asm statements may need extra stack space for internal
|
|
calculations. This can be guaranteed by clobbering stack registers
|
|
unrelated to the inputs and outputs.
|
|
|
|
@end enumerate
|
|
|
|
Here are a couple of reasonable asms to want to write. This asm
|
|
takes one input, which is internally popped, and produces two outputs.
|
|
|
|
@example
|
|
asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
|
|
@end example
|
|
|
|
This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode,
|
|
and replaces them with one output. The user must code the @code{st(1)}
|
|
clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs.
|
|
|
|
@example
|
|
asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
|
|
@end example
|
|
|
|
@include md.texi
|
|
|
|
@node Asm Labels
|
|
@section Controlling Names Used in Assembler Code
|
|
@cindex assembler names for identifiers
|
|
@cindex names used in assembler code
|
|
@cindex identifiers, names in assembler code
|
|
|
|
You can specify the name to be used in the assembler code for a C
|
|
function or variable by writing the @code{asm} (or @code{__asm__})
|
|
keyword after the declarator as follows:
|
|
|
|
@example
|
|
int foo asm ("myfoo") = 2;
|
|
@end example
|
|
|
|
@noindent
|
|
This specifies that the name to be used for the variable @code{foo} in
|
|
the assembler code should be @samp{myfoo} rather than the usual
|
|
@samp{_foo}.
|
|
|
|
On systems where an underscore is normally prepended to the name of a C
|
|
function or variable, this feature allows you to define names for the
|
|
linker that do not start with an underscore.
|
|
|
|
It does not make sense to use this feature with a non-static local
|
|
variable since such variables do not have assembler names. If you are
|
|
trying to put the variable in a particular register, see @ref{Explicit
|
|
Reg Vars}. GCC presently accepts such code with a warning, but will
|
|
probably be changed to issue an error, rather than a warning, in the
|
|
future.
|
|
|
|
You cannot use @code{asm} in this way in a function @emph{definition}; but
|
|
you can get the same effect by writing a declaration for the function
|
|
before its definition and putting @code{asm} there, like this:
|
|
|
|
@example
|
|
extern func () asm ("FUNC");
|
|
|
|
func (x, y)
|
|
int x, y;
|
|
/* @r{@dots{}} */
|
|
@end example
|
|
|
|
It is up to you to make sure that the assembler names you choose do not
|
|
conflict with any other assembler symbols. Also, you must not use a
|
|
register name; that would produce completely invalid assembler code. GCC
|
|
does not as yet have the ability to store static variables in registers.
|
|
Perhaps that will be added.
|
|
|
|
@node Explicit Reg Vars
|
|
@section Variables in Specified Registers
|
|
@cindex explicit register variables
|
|
@cindex variables in specified registers
|
|
@cindex specified registers
|
|
@cindex registers, global allocation
|
|
|
|
GNU C allows you to put a few global variables into specified hardware
|
|
registers. You can also specify the register in which an ordinary
|
|
register variable should be allocated.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Global register variables reserve registers throughout the program.
|
|
This may be useful in programs such as programming language
|
|
interpreters which have a couple of global variables that are accessed
|
|
very often.
|
|
|
|
@item
|
|
Local register variables in specific registers do not reserve the
|
|
registers. The compiler's data flow analysis is capable of determining
|
|
where the specified registers contain live values, and where they are
|
|
available for other uses. Stores into local register variables may be deleted
|
|
when they appear to be dead according to dataflow analysis. References
|
|
to local register variables may be deleted or moved or simplified.
|
|
|
|
These local variables are sometimes convenient for use with the extended
|
|
@code{asm} feature (@pxref{Extended Asm}), if you want to write one
|
|
output of the assembler instruction directly into a particular register.
|
|
(This will work provided the register you specify fits the constraints
|
|
specified for that operand in the @code{asm}.)
|
|
@end itemize
|
|
|
|
@menu
|
|
* Global Reg Vars::
|
|
* Local Reg Vars::
|
|
@end menu
|
|
|
|
@node Global Reg Vars
|
|
@subsection Defining Global Register Variables
|
|
@cindex global register variables
|
|
@cindex registers, global variables in
|
|
|
|
You can define a global register variable in GNU C like this:
|
|
|
|
@example
|
|
register int *foo asm ("a5");
|
|
@end example
|
|
|
|
@noindent
|
|
Here @code{a5} is the name of the register which should be used. Choose a
|
|
register which is normally saved and restored by function calls on your
|
|
machine, so that library routines will not clobber it.
|
|
|
|
Naturally the register name is cpu-dependent, so you would need to
|
|
conditionalize your program according to cpu type. The register
|
|
@code{a5} would be a good choice on a 68000 for a variable of pointer
|
|
type. On machines with register windows, be sure to choose a ``global''
|
|
register that is not affected magically by the function call mechanism.
|
|
|
|
In addition, operating systems on one type of cpu may differ in how they
|
|
name the registers; then you would need additional conditionals. For
|
|
example, some 68000 operating systems call this register @code{%a5}.
|
|
|
|
Eventually there may be a way of asking the compiler to choose a register
|
|
automatically, but first we need to figure out how it should choose and
|
|
how to enable you to guide the choice. No solution is evident.
|
|
|
|
Defining a global register variable in a certain register reserves that
|
|
register entirely for this use, at least within the current compilation.
|
|
The register will not be allocated for any other purpose in the functions
|
|
in the current compilation. The register will not be saved and restored by
|
|
these functions. Stores into this register are never deleted even if they
|
|
would appear to be dead, but references may be deleted or moved or
|
|
simplified.
|
|
|
|
It is not safe to access the global register variables from signal
|
|
handlers, or from more than one thread of control, because the system
|
|
library routines may temporarily use the register for other things (unless
|
|
you recompile them specially for the task at hand).
|
|
|
|
@cindex @code{qsort}, and global register variables
|
|
It is not safe for one function that uses a global register variable to
|
|
call another such function @code{foo} by way of a third function
|
|
@code{lose} that was compiled without knowledge of this variable (i.e.@: in a
|
|
different source file in which the variable wasn't declared). This is
|
|
because @code{lose} might save the register and put some other value there.
|
|
For example, you can't expect a global register variable to be available in
|
|
the comparison-function that you pass to @code{qsort}, since @code{qsort}
|
|
might have put something else in that register. (If you are prepared to
|
|
recompile @code{qsort} with the same global register variable, you can
|
|
solve this problem.)
|
|
|
|
If you want to recompile @code{qsort} or other source files which do not
|
|
actually use your global register variable, so that they will not use that
|
|
register for any other purpose, then it suffices to specify the compiler
|
|
option @option{-ffixed-@var{reg}}. You need not actually add a global
|
|
register declaration to their source code.
|
|
|
|
A function which can alter the value of a global register variable cannot
|
|
safely be called from a function compiled without this variable, because it
|
|
could clobber the value the caller expects to find there on return.
|
|
Therefore, the function which is the entry point into the part of the
|
|
program that uses the global register variable must explicitly save and
|
|
restore the value which belongs to its caller.
|
|
|
|
@cindex register variable after @code{longjmp}
|
|
@cindex global register after @code{longjmp}
|
|
@cindex value after @code{longjmp}
|
|
@findex longjmp
|
|
@findex setjmp
|
|
On most machines, @code{longjmp} will restore to each global register
|
|
variable the value it had at the time of the @code{setjmp}. On some
|
|
machines, however, @code{longjmp} will not change the value of global
|
|
register variables. To be portable, the function that called @code{setjmp}
|
|
should make other arrangements to save the values of the global register
|
|
variables, and to restore them in a @code{longjmp}. This way, the same
|
|
thing will happen regardless of what @code{longjmp} does.
|
|
|
|
All global register variable declarations must precede all function
|
|
definitions. If such a declaration could appear after function
|
|
definitions, the declaration would be too late to prevent the register from
|
|
being used for other purposes in the preceding functions.
|
|
|
|
Global register variables may not have initial values, because an
|
|
executable file has no means to supply initial contents for a register.
|
|
|
|
On the SPARC, there are reports that g3 @dots{} g7 are suitable
|
|
registers, but certain library functions, such as @code{getwd}, as well
|
|
as the subroutines for division and remainder, modify g3 and g4. g1 and
|
|
g2 are local temporaries.
|
|
|
|
On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
|
|
Of course, it will not do to use more than a few of those.
|
|
|
|
@node Local Reg Vars
|
|
@subsection Specifying Registers for Local Variables
|
|
@cindex local variables, specifying registers
|
|
@cindex specifying registers for local variables
|
|
@cindex registers for local variables
|
|
|
|
You can define a local register variable with a specified register
|
|
like this:
|
|
|
|
@example
|
|
register int *foo asm ("a5");
|
|
@end example
|
|
|
|
@noindent
|
|
Here @code{a5} is the name of the register which should be used. Note
|
|
that this is the same syntax used for defining global register
|
|
variables, but for a local variable it would appear within a function.
|
|
|
|
Naturally the register name is cpu-dependent, but this is not a
|
|
problem, since specific registers are most often useful with explicit
|
|
assembler instructions (@pxref{Extended Asm}). Both of these things
|
|
generally require that you conditionalize your program according to
|
|
cpu type.
|
|
|
|
In addition, operating systems on one type of cpu may differ in how they
|
|
name the registers; then you would need additional conditionals. For
|
|
example, some 68000 operating systems call this register @code{%a5}.
|
|
|
|
Defining such a register variable does not reserve the register; it
|
|
remains available for other uses in places where flow control determines
|
|
the variable's value is not live. However, these registers are made
|
|
unavailable for use in the reload pass; excessive use of this feature
|
|
leaves the compiler too few available registers to compile certain
|
|
functions.
|
|
|
|
This option does not guarantee that GCC will generate code that has
|
|
this variable in the register you specify at all times. You may not
|
|
code an explicit reference to this register in an @code{asm} statement
|
|
and assume it will always refer to this variable.
|
|
|
|
Stores into local register variables may be deleted when they appear to be dead
|
|
according to dataflow analysis. References to local register variables may
|
|
be deleted or moved or simplified.
|
|
|
|
@node Alternate Keywords
|
|
@section Alternate Keywords
|
|
@cindex alternate keywords
|
|
@cindex keywords, alternate
|
|
|
|
@option{-ansi} and the various @option{-std} options disable certain
|
|
keywords. This causes trouble when you want to use GNU C extensions, or
|
|
a general-purpose header file that should be usable by all programs,
|
|
including ISO C programs. The keywords @code{asm}, @code{typeof} and
|
|
@code{inline} are not available in programs compiled with
|
|
@option{-ansi} or @option{-std} (although @code{inline} can be used in a
|
|
program compiled with @option{-std=c99}). The ISO C99 keyword
|
|
@code{restrict} is only available when @option{-std=gnu99} (which will
|
|
eventually be the default) or @option{-std=c99} (or the equivalent
|
|
@option{-std=iso9899:1999}) is used.
|
|
|
|
The way to solve these problems is to put @samp{__} at the beginning and
|
|
end of each problematical keyword. For example, use @code{__asm__}
|
|
instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
|
|
|
|
Other C compilers won't accept these alternative keywords; if you want to
|
|
compile with another compiler, you can define the alternate keywords as
|
|
macros to replace them with the customary keywords. It looks like this:
|
|
|
|
@example
|
|
#ifndef __GNUC__
|
|
#define __asm__ asm
|
|
#endif
|
|
@end example
|
|
|
|
@findex __extension__
|
|
@opindex pedantic
|
|
@option{-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 Incomplete Enums
|
|
@section Incomplete @code{enum} Types
|
|
|
|
You can define an @code{enum} tag without specifying its possible values.
|
|
This results in an incomplete type, much like what you get if you write
|
|
@code{struct foo} without describing the elements. A later declaration
|
|
which does specify the possible values completes the type.
|
|
|
|
You can't allocate variables or storage using the type while it is
|
|
incomplete. However, you can work with pointers to that type.
|
|
|
|
This extension may not be very useful, but it makes the handling of
|
|
@code{enum} more consistent with the way @code{struct} and @code{union}
|
|
are handled.
|
|
|
|
This extension is not supported by GNU C++.
|
|
|
|
@node Function Names
|
|
@section Function Names as Strings
|
|
@cindex @code{__FUNCTION__} identifier
|
|
@cindex @code{__PRETTY_FUNCTION__} identifier
|
|
@cindex @code{__func__} identifier
|
|
|
|
GCC 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:
|
|
|
|
@smallexample
|
|
extern "C" @{
|
|
extern int printf (char *, ...);
|
|
@}
|
|
|
|
class a @{
|
|
public:
|
|
sub (int i)
|
|
@{
|
|
printf ("__FUNCTION__ = %s\n", __FUNCTION__);
|
|
printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
|
|
@}
|
|
@};
|
|
|
|
int
|
|
main (void)
|
|
@{
|
|
a ax;
|
|
ax.sub (0);
|
|
return 0;
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
gives this output:
|
|
|
|
@smallexample
|
|
__FUNCTION__ = sub
|
|
__PRETTY_FUNCTION__ = int a::sub (int)
|
|
@end smallexample
|
|
|
|
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__}.
|
|
|
|
Note that these semantics are deprecated, and that GCC 3.2 will handle
|
|
@code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} the same way as
|
|
@code{__func__}. @code{__func__} is defined by the ISO standard C99:
|
|
|
|
@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
|
|
|
|
These functions may be used to get information about the callers of a
|
|
function.
|
|
|
|
@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
|
|
This function returns the return address of the current function, or of
|
|
one of its callers. The @var{level} argument is number of frames to
|
|
scan up the call stack. A value of @code{0} yields the return address
|
|
of the current function, a value of @code{1} yields the return address
|
|
of the caller of the current function, and so forth. When inlining
|
|
the expected behavior is that the function will return the address of
|
|
the function that will be returned to. To work around this behavior use
|
|
the @code{noinline} function attribute.
|
|
|
|
The @var{level} argument must be a constant integer.
|
|
|
|
On some machines it may be impossible to determine the return address of
|
|
any function other than the current one; in such cases, or when the top
|
|
of the stack has been reached, this function will return @code{0} or a
|
|
random value. In addition, @code{__builtin_frame_address} may be used
|
|
to determine if the top of the stack has been reached.
|
|
|
|
This function should only be used with a nonzero argument for debugging
|
|
purposes.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
|
|
This function is similar to @code{__builtin_return_address}, but it
|
|
returns the address of the function frame rather than the return address
|
|
of the function. Calling @code{__builtin_frame_address} with a value of
|
|
@code{0} yields the frame address of the current function, a value of
|
|
@code{1} yields the frame address of the caller of the current function,
|
|
and so forth.
|
|
|
|
The frame is the area on the stack which holds local variables and saved
|
|
registers. The frame address is normally the address of the first word
|
|
pushed on to the stack by the function. However, the exact definition
|
|
depends upon the processor and the calling convention. If the processor
|
|
has a dedicated frame pointer register, and the function has a frame,
|
|
then @code{__builtin_frame_address} will return the value of the frame
|
|
pointer register.
|
|
|
|
On some machines it may be impossible to determine the frame address of
|
|
any function other than the current one; in such cases, or when the top
|
|
of the stack has been reached, this function will return @code{0} if
|
|
the first frame pointer is properly initialized by the startup code.
|
|
|
|
This function should only be used with a nonzero argument for debugging
|
|
purposes.
|
|
@end deftypefn
|
|
|
|
@node Vector Extensions
|
|
@section Using vector instructions through built-in functions
|
|
|
|
On some targets, the instruction set contains SIMD vector instructions that
|
|
operate on multiple values contained in one large register at the same time.
|
|
For example, on the i386 the MMX, 3Dnow! and SSE extensions can be used
|
|
this way.
|
|
|
|
The first step in using these extensions is to provide the necessary data
|
|
types. This should be done using an appropriate @code{typedef}:
|
|
|
|
@example
|
|
typedef int v4si __attribute__ ((mode(V4SI)));
|
|
@end example
|
|
|
|
The base type @code{int} is effectively ignored by the compiler, the
|
|
actual properties of the new type @code{v4si} are defined by the
|
|
@code{__attribute__}. It defines the machine mode to be used; for vector
|
|
types these have the form @code{V@var{n}@var{B}}; @var{n} should be the
|
|
number of elements in the vector, and @var{B} should be the base mode of the
|
|
individual elements. The following can be used as base modes:
|
|
|
|
@table @code
|
|
@item QI
|
|
An integer that is as wide as the smallest addressable unit, usually 8 bits.
|
|
@item HI
|
|
An integer, twice as wide as a QI mode integer, usually 16 bits.
|
|
@item SI
|
|
An integer, four times as wide as a QI mode integer, usually 32 bits.
|
|
@item DI
|
|
An integer, eight times as wide as a QI mode integer, usually 64 bits.
|
|
@item SF
|
|
A floating point value, as wide as a SI mode integer, usually 32 bits.
|
|
@item DF
|
|
A floating point value, as wide as a DI mode integer, usually 64 bits.
|
|
@end table
|
|
|
|
Specifying a combination that is not valid for the current architecture
|
|
will cause gcc to synthesize the instructions using a narrower mode.
|
|
For example, if you specify a variable of type @code{V4SI} and your
|
|
architecture does not allow for this specific SIMD type, gcc will
|
|
produce code that uses 4 @code{SIs}.
|
|
|
|
The types defined in this manner can be used with a subset of normal C
|
|
operations. Currently, gcc will allow using the following operators on
|
|
these types: @code{+, -, *, /, unary minus}@.
|
|
|
|
The operations behave like C++ @code{valarrays}. Addition is defined as
|
|
the addition of the corresponding elements of the operands. For
|
|
example, in the code below, each of the 4 elements in @var{a} will be
|
|
added to the corresponding 4 elements in @var{b} and the resulting
|
|
vector will be stored in @var{c}.
|
|
|
|
@example
|
|
typedef int v4si __attribute__ ((mode(V4SI)));
|
|
|
|
v4si a, b, c;
|
|
|
|
c = a + b;
|
|
@end example
|
|
|
|
Subtraction, multiplication, and division operate in a similar manner.
|
|
Likewise, the result of using the unary minus operator on a vector type
|
|
is a vector whose elements are the negative value of the corresponding
|
|
elements in the operand.
|
|
|
|
You can declare variables and use them in function calls and returns, as
|
|
well as in assignments and some casts. You can specify a vector type as
|
|
a return type for a function. Vector types can also be used as function
|
|
arguments. It is possible to cast from one vector type to another,
|
|
provided they are of the same size (in fact, you can also cast vectors
|
|
to and from other datatypes of the same size).
|
|
|
|
You cannot operate between vectors of different lengths or different
|
|
signedness without a cast.
|
|
|
|
A port that supports hardware vector operations, usually provides a set
|
|
of built-in functions that can be used to operate on vectors. For
|
|
example, a function to add two vectors and multiply the result by a
|
|
third could look like this:
|
|
|
|
@example
|
|
v4si f (v4si a, v4si b, v4si c)
|
|
@{
|
|
v4si tmp = __builtin_addv4si (a, b);
|
|
return __builtin_mulv4si (tmp, c);
|
|
@}
|
|
|
|
@end example
|
|
|
|
@node Other Builtins
|
|
@section Other built-in functions provided by GCC
|
|
@cindex built-in functions
|
|
@findex __builtin_isgreater
|
|
@findex __builtin_isgreaterequal
|
|
@findex __builtin_isless
|
|
@findex __builtin_islessequal
|
|
@findex __builtin_islessgreater
|
|
@findex __builtin_isunordered
|
|
@findex abort
|
|
@findex abs
|
|
@findex alloca
|
|
@findex bcmp
|
|
@findex bzero
|
|
@findex cimag
|
|
@findex cimagf
|
|
@findex cimagl
|
|
@findex conj
|
|
@findex conjf
|
|
@findex conjl
|
|
@findex cos
|
|
@findex cosf
|
|
@findex cosl
|
|
@findex creal
|
|
@findex crealf
|
|
@findex creall
|
|
@findex exit
|
|
@findex _exit
|
|
@findex _Exit
|
|
@findex exp
|
|
@findex expf
|
|
@findex expl
|
|
@findex fabs
|
|
@findex fabsf
|
|
@findex fabsl
|
|
@findex ffs
|
|
@findex fprintf
|
|
@findex fprintf_unlocked
|
|
@findex fputs
|
|
@findex fputs_unlocked
|
|
@findex imaxabs
|
|
@findex index
|
|
@findex labs
|
|
@findex llabs
|
|
@findex log
|
|
@findex logf
|
|
@findex logl
|
|
@findex memcmp
|
|
@findex memcpy
|
|
@findex memset
|
|
@findex printf
|
|
@findex printf_unlocked
|
|
@findex putchar
|
|
@findex puts
|
|
@findex rindex
|
|
@findex scanf
|
|
@findex sin
|
|
@findex sinf
|
|
@findex sinl
|
|
@findex snprintf
|
|
@findex sprintf
|
|
@findex sqrt
|
|
@findex sqrtf
|
|
@findex sqrtl
|
|
@findex sscanf
|
|
@findex strcat
|
|
@findex strchr
|
|
@findex strcmp
|
|
@findex strcpy
|
|
@findex strcspn
|
|
@findex strlen
|
|
@findex strncat
|
|
@findex strncmp
|
|
@findex strncpy
|
|
@findex strpbrk
|
|
@findex strrchr
|
|
@findex strspn
|
|
@findex strstr
|
|
@findex vprintf
|
|
@findex vscanf
|
|
@findex vsnprintf
|
|
@findex vsprintf
|
|
@findex vsscanf
|
|
|
|
GCC provides a large number of built-in functions other than the ones
|
|
mentioned above. Some of these are for internal use in the processing
|
|
of exceptions or variable-length argument lists and will not be
|
|
documented here because they may change from time to time; we do not
|
|
recommend general use of these functions.
|
|
|
|
The remaining functions are provided for optimization purposes.
|
|
|
|
@opindex fno-builtin
|
|
GCC includes built-in versions of many of the functions in the standard
|
|
C library. The versions prefixed with @code{__builtin_} will always be
|
|
treated as having the same meaning as the C library function even if you
|
|
specify the @option{-fno-builtin} option. (@pxref{C Dialect Options})
|
|
Many of these functions are only optimized in certain cases; if they are
|
|
not optimized in a particular case, a call to the library function will
|
|
be emitted.
|
|
|
|
@opindex ansi
|
|
@opindex std
|
|
The functions @code{abort}, @code{exit}, @code{_Exit} and @code{_exit}
|
|
are recognized and presumed not to return, but otherwise are not built
|
|
in. @code{_exit} is not recognized in strict ISO C mode (@option{-ansi},
|
|
@option{-std=c89} or @option{-std=c99}). @code{_Exit} is not recognized in
|
|
strict C89 mode (@option{-ansi} or @option{-std=c89}). All these functions
|
|
have corresponding versions prefixed with @code{__builtin_}, which may be
|
|
used even in strict C89 mode.
|
|
|
|
Outside strict ISO C mode, the functions @code{alloca}, @code{bcmp},
|
|
@code{bzero}, @code{index}, @code{rindex}, @code{ffs}, @code{fputs_unlocked},
|
|
@code{printf_unlocked} and @code{fprintf_unlocked} may be handled as
|
|
built-in functions. All these functions have corresponding versions
|
|
prefixed with @code{__builtin_}, which may be used even in strict C89
|
|
mode.
|
|
|
|
The ISO C99 functions @code{conj}, @code{conjf}, @code{conjl},
|
|
@code{creal}, @code{crealf}, @code{creall}, @code{cimag}, @code{cimagf},
|
|
@code{cimagl}, @code{imaxabs}, @code{llabs}, @code{snprintf},
|
|
@code{vscanf}, @code{vsnprintf} and @code{vsscanf} are handled as built-in
|
|
functions except in strict ISO C90 mode. There are also built-in
|
|
versions of the ISO C99 functions @code{cosf}, @code{cosl},
|
|
@code{expf}, @code{expl}, @code{fabsf}, @code{fabsl},
|
|
@code{logf}, @code{logl}, @code{sinf}, @code{sinl}, @code{sqrtf}, and
|
|
@code{sqrtl}, that are recognized in any mode since ISO C90 reserves
|
|
these names for the purpose to which ISO C99 puts them. All these
|
|
functions have corresponding versions prefixed with @code{__builtin_}.
|
|
|
|
The ISO C90 functions @code{abs}, @code{cos}, @code{exp}, @code{fabs},
|
|
@code{fprintf}, @code{fputs}, @code{labs}, @code{log},
|
|
@code{memcmp}, @code{memcpy},
|
|
@code{memset}, @code{printf}, @code{putchar}, @code{puts}, @code{scanf},
|
|
@code{sin}, @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf},
|
|
@code{strcat},
|
|
@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
|
|
@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
|
|
@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
|
|
@code{vprintf} and @code{vsprintf} are all
|
|
recognized as built-in functions unless @option{-fno-builtin} is
|
|
specified (or @option{-fno-builtin-@var{function}} is specified for an
|
|
individual function). All of these functions have corresponding
|
|
versions prefixed with @code{__builtin_}.
|
|
|
|
GCC provides built-in versions of the ISO C99 floating point comparison
|
|
macros that avoid raising exceptions for unordered operands. They have
|
|
the same names as the standard macros ( @code{isgreater},
|
|
@code{isgreaterequal}, @code{isless}, @code{islessequal},
|
|
@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
|
|
prefixed. We intend for a library implementor to be able to simply
|
|
@code{#define} each standard macro to its built-in equivalent.
|
|
|
|
@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
|
|
|
|
You can use the built-in function @code{__builtin_types_compatible_p} to
|
|
determine whether two types are the same.
|
|
|
|
This built-in function returns 1 if the unqualified versions of the
|
|
types @var{type1} and @var{type2} (which are types, not expressions) are
|
|
compatible, 0 otherwise. The result of this built-in function can be
|
|
used in integer constant expressions.
|
|
|
|
This built-in function ignores top level qualifiers (e.g., @code{const},
|
|
@code{volatile}). For example, @code{int} is equivalent to @code{const
|
|
int}.
|
|
|
|
The type @code{int[]} and @code{int[5]} are compatible. On the other
|
|
hand, @code{int} and @code{char *} are not compatible, even if the size
|
|
of their types, on the particular architecture are the same. Also, the
|
|
amount of pointer indirection is taken into account when determining
|
|
similarity. Consequently, @code{short *} is not similar to
|
|
@code{short **}. Furthermore, two types that are typedefed are
|
|
considered compatible if their underlying types are compatible.
|
|
|
|
An @code{enum} type is considered to be compatible with another
|
|
@code{enum} type. For example, @code{enum @{foo, bar@}} is similar to
|
|
@code{enum @{hot, dog@}}.
|
|
|
|
You would typically use this function in code whose execution varies
|
|
depending on the arguments' types. For example:
|
|
|
|
@smallexample
|
|
#define foo(x) \
|
|
(@{ \
|
|
typeof (x) tmp; \
|
|
if (__builtin_types_compatible_p (typeof (x), long double)) \
|
|
tmp = foo_long_double (tmp); \
|
|
else if (__builtin_types_compatible_p (typeof (x), double)) \
|
|
tmp = foo_double (tmp); \
|
|
else if (__builtin_types_compatible_p (typeof (x), float)) \
|
|
tmp = foo_float (tmp); \
|
|
else \
|
|
abort (); \
|
|
tmp; \
|
|
@})
|
|
@end smallexample
|
|
|
|
@emph{Note:} This construct is only available for C.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
|
|
|
|
You can use the built-in function @code{__builtin_choose_expr} to
|
|
evaluate code depending on the value of a constant expression. This
|
|
built-in function returns @var{exp1} if @var{const_exp}, which is a
|
|
constant expression that must be able to be determined at compile time,
|
|
is nonzero. Otherwise it returns 0.
|
|
|
|
This built-in function is analogous to the @samp{? :} operator in C,
|
|
except that the expression returned has its type unaltered by promotion
|
|
rules. Also, the built-in function does not evaluate the expression
|
|
that was not chosen. For example, if @var{const_exp} evaluates to true,
|
|
@var{exp2} is not evaluated even if it has side-effects.
|
|
|
|
This built-in function can return an lvalue if the chosen argument is an
|
|
lvalue.
|
|
|
|
If @var{exp1} is returned, the return type is the same as @var{exp1}'s
|
|
type. Similarly, if @var{exp2} is returned, its return type is the same
|
|
as @var{exp2}.
|
|
|
|
Example:
|
|
|
|
@smallexample
|
|
#define foo(x) \
|
|
__builtin_choose_expr ( \
|
|
__builtin_types_compatible_p (typeof (x), double), \
|
|
foo_double (x), \
|
|
__builtin_choose_expr ( \
|
|
__builtin_types_compatible_p (typeof (x), float), \
|
|
foo_float (x), \
|
|
/* @r{The void expression results in a compile-time error} \
|
|
@r{when assigning the result to something.} */ \
|
|
(void)0))
|
|
@end smallexample
|
|
|
|
@emph{Note:} This construct is only available for C. Furthermore, the
|
|
unused expression (@var{exp1} or @var{exp2} depending on the value of
|
|
@var{const_exp}) may still generate syntax errors. This may change in
|
|
future revisions.
|
|
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
|
|
You can use the built-in function @code{__builtin_constant_p} to
|
|
determine if a value is known to be constant at compile-time and hence
|
|
that GCC can perform constant-folding on expressions involving that
|
|
value. The argument of the function is the value to test. The function
|
|
returns the integer 1 if the argument is known to be a compile-time
|
|
constant and 0 if it is not known to be a compile-time constant. A
|
|
return of 0 does not indicate that the value is @emph{not} a constant,
|
|
but merely that GCC cannot prove it is a constant with the specified
|
|
value of the @option{-O} option.
|
|
|
|
You would typically use this function in an embedded application where
|
|
memory was a critical resource. If you have some complex calculation,
|
|
you may want it to be folded if it involves constants, but need to call
|
|
a function if it does not. For example:
|
|
|
|
@smallexample
|
|
#define Scale_Value(X) \
|
|
(__builtin_constant_p (X) \
|
|
? ((X) * SCALE + OFFSET) : Scale (X))
|
|
@end smallexample
|
|
|
|
You may use this built-in function in either a macro or an inline
|
|
function. However, if you use it in an inlined function and pass an
|
|
argument of the function as the argument to the built-in, GCC will
|
|
never return 1 when you call the inline function with a string constant
|
|
or compound literal (@pxref{Compound Literals}) and will not return 1
|
|
when you pass a constant numeric value to the inline function unless you
|
|
specify the @option{-O} option.
|
|
|
|
You may also use @code{__builtin_constant_p} in initializers for static
|
|
data. For instance, you can write
|
|
|
|
@smallexample
|
|
static const int table[] = @{
|
|
__builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
|
|
/* @r{@dots{}} */
|
|
@};
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is an acceptable initializer even if @var{EXPRESSION} is not a
|
|
constant expression. GCC must be more conservative about evaluating the
|
|
built-in in this case, because it has no opportunity to perform
|
|
optimization.
|
|
|
|
Previous versions of GCC did not accept this built-in in data
|
|
initializers. The earliest version where it is completely safe is
|
|
3.0.1.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
|
|
@opindex fprofile-arcs
|
|
You may use @code{__builtin_expect} to provide the compiler with
|
|
branch prediction information. In general, you should prefer to
|
|
use actual profile feedback for this (@option{-fprofile-arcs}), as
|
|
programmers are notoriously bad at predicting how their programs
|
|
actually perform. However, there are applications in which this
|
|
data is hard to collect.
|
|
|
|
The return value is the value of @var{exp}, which should be an
|
|
integral expression. The value of @var{c} must be a compile-time
|
|
constant. The semantics of the built-in are that it is expected
|
|
that @var{exp} == @var{c}. For example:
|
|
|
|
@smallexample
|
|
if (__builtin_expect (x, 0))
|
|
foo ();
|
|
@end smallexample
|
|
|
|
@noindent
|
|
would indicate that we do not expect to call @code{foo}, since
|
|
we expect @code{x} to be zero. Since you are limited to integral
|
|
expressions for @var{exp}, you should use constructions such as
|
|
|
|
@smallexample
|
|
if (__builtin_expect (ptr != NULL, 1))
|
|
error ();
|
|
@end smallexample
|
|
|
|
@noindent
|
|
when testing pointer or floating-point values.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
|
|
This function is used to minimize cache-miss latency by moving data into
|
|
a cache before it is accessed.
|
|
You can insert calls to @code{__builtin_prefetch} into code for which
|
|
you know addresses of data in memory that is likely to be accessed soon.
|
|
If the target supports them, data prefetch instructions will be generated.
|
|
If the prefetch is done early enough before the access then the data will
|
|
be in the cache by the time it is accessed.
|
|
|
|
The value of @var{addr} is the address of the memory to prefetch.
|
|
There are two optional arguments, @var{rw} and @var{locality}.
|
|
The value of @var{rw} is a compile-time constant one or zero; one
|
|
means that the prefetch is preparing for a write to the memory address
|
|
and zero, the default, means that the prefetch is preparing for a read.
|
|
The value @var{locality} must be a compile-time constant integer between
|
|
zero and three. A value of zero means that the data has no temporal
|
|
locality, so it need not be left in the cache after the access. A value
|
|
of three means that the data has a high degree of temporal locality and
|
|
should be left in all levels of cache possible. Values of one and two
|
|
mean, respectively, a low or moderate degree of temporal locality. The
|
|
default is three.
|
|
|
|
@smallexample
|
|
for (i = 0; i < n; i++)
|
|
@{
|
|
a[i] = a[i] + b[i];
|
|
__builtin_prefetch (&a[i+j], 1, 1);
|
|
__builtin_prefetch (&b[i+j], 0, 1);
|
|
/* @r{@dots{}} */
|
|
@}
|
|
@end smallexample
|
|
|
|
Data prefetch does not generate faults if @var{addr} is invalid, but
|
|
the address expression itself must be valid. For example, a prefetch
|
|
of @code{p->next} will not fault if @code{p->next} is not a valid
|
|
address, but evaluation will fault if @code{p} is not a valid address.
|
|
|
|
If the target does not support data prefetch, the address expression
|
|
is evaluated if it includes side effects but no other code is generated
|
|
and GCC does not issue a warning.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} double __builtin_huge_val (void)
|
|
Returns a positive infinity, if supported by the floating-point format,
|
|
else @code{DBL_MAX}. This function is suitable for implementing the
|
|
ISO C macro @code{HUGE_VAL}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} float __builtin_huge_valf (void)
|
|
Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
|
|
Similar to @code{__builtin_huge_val}, except the return
|
|
type is @code{long double}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} double __builtin_inf (void)
|
|
Similar to @code{__builtin_huge_val}, except a warning is generated
|
|
if the target floating-point format does not support infinities.
|
|
This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} float __builtin_inff (void)
|
|
Similar to @code{__builtin_inf}, except the return type is @code{float}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} {long double} __builtin_infl (void)
|
|
Similar to @code{__builtin_inf}, except the return
|
|
type is @code{long double}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} double __builtin_nan (const char *str)
|
|
This is an implementation of the ISO C99 function @code{nan}.
|
|
|
|
Since ISO C99 defines this function in terms of @code{strtod}, which we
|
|
do not implement, a description of the parsing is in order. The string
|
|
is parsed as by @code{strtol}; that is, the base is recognized by
|
|
leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
|
|
in the significand such that the least significant bit of the number
|
|
is at the least significant bit of the significand. The number is
|
|
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.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} float __builtin_nanf (const char *str)
|
|
Similar to @code{__builtin_nan}, except the return type is @code{float}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
|
|
Similar to @code{__builtin_nan}, except the return type is @code{long double}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} double __builtin_nans (const char *str)
|
|
Similar to @code{__builtin_nan}, except the significand is forced
|
|
to be a signaling NaN. The @code{nans} function is proposed by
|
|
@uref{http://std.dkuug.dk/JTC1/SC22/WG14/www/docs/n965.htm,,WG14 N965}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} float __builtin_nansf (const char *str)
|
|
Similar to @code{__builtin_nans}, except the return type is @code{float}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
|
|
Similar to @code{__builtin_nans}, except the return type is @code{long double}.
|
|
@end deftypefn
|
|
|
|
@node Target Builtins
|
|
@section Built-in Functions Specific to Particular Target Machines
|
|
|
|
On some target machines, GCC supports many built-in functions specific
|
|
to those machines. Generally these generate calls to specific machine
|
|
instructions, but allow the compiler to schedule those calls.
|
|
|
|
@menu
|
|
* Alpha Built-in Functions::
|
|
* X86 Built-in Functions::
|
|
* PowerPC AltiVec Built-in Functions::
|
|
@end menu
|
|
|
|
@node Alpha Built-in Functions
|
|
@subsection Alpha Built-in Functions
|
|
|
|
These built-in functions are available for the Alpha family of
|
|
processors, depending on the command-line switches used.
|
|
|
|
The following built-in functions are always available. They
|
|
all generate the machine instruction that is part of the name.
|
|
|
|
@example
|
|
long __builtin_alpha_implver (void)
|
|
long __builtin_alpha_rpcc (void)
|
|
long __builtin_alpha_amask (long)
|
|
long __builtin_alpha_cmpbge (long, long)
|
|
long __builtin_alpha_extbl (long, long)
|
|
long __builtin_alpha_extwl (long, long)
|
|
long __builtin_alpha_extll (long, long)
|
|
long __builtin_alpha_extql (long, long)
|
|
long __builtin_alpha_extwh (long, long)
|
|
long __builtin_alpha_extlh (long, long)
|
|
long __builtin_alpha_extqh (long, long)
|
|
long __builtin_alpha_insbl (long, long)
|
|
long __builtin_alpha_inswl (long, long)
|
|
long __builtin_alpha_insll (long, long)
|
|
long __builtin_alpha_insql (long, long)
|
|
long __builtin_alpha_inswh (long, long)
|
|
long __builtin_alpha_inslh (long, long)
|
|
long __builtin_alpha_insqh (long, long)
|
|
long __builtin_alpha_mskbl (long, long)
|
|
long __builtin_alpha_mskwl (long, long)
|
|
long __builtin_alpha_mskll (long, long)
|
|
long __builtin_alpha_mskql (long, long)
|
|
long __builtin_alpha_mskwh (long, long)
|
|
long __builtin_alpha_msklh (long, long)
|
|
long __builtin_alpha_mskqh (long, long)
|
|
long __builtin_alpha_umulh (long, long)
|
|
long __builtin_alpha_zap (long, long)
|
|
long __builtin_alpha_zapnot (long, long)
|
|
@end example
|
|
|
|
The following built-in functions are always with @option{-mmax}
|
|
or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
|
|
later. They all generate the machine instruction that is part
|
|
of the name.
|
|
|
|
@example
|
|
long __builtin_alpha_pklb (long)
|
|
long __builtin_alpha_pkwb (long)
|
|
long __builtin_alpha_unpkbl (long)
|
|
long __builtin_alpha_unpkbw (long)
|
|
long __builtin_alpha_minub8 (long, long)
|
|
long __builtin_alpha_minsb8 (long, long)
|
|
long __builtin_alpha_minuw4 (long, long)
|
|
long __builtin_alpha_minsw4 (long, long)
|
|
long __builtin_alpha_maxub8 (long, long)
|
|
long __builtin_alpha_maxsb8 (long, long)
|
|
long __builtin_alpha_maxuw4 (long, long)
|
|
long __builtin_alpha_maxsw4 (long, long)
|
|
long __builtin_alpha_perr (long, long)
|
|
@end example
|
|
|
|
The following built-in functions are always with @option{-mcix}
|
|
or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
|
|
later. They all generate the machine instruction that is part
|
|
of the name.
|
|
|
|
@example
|
|
long __builtin_alpha_cttz (long)
|
|
long __builtin_alpha_ctlz (long)
|
|
long __builtin_alpha_ctpop (long)
|
|
@end example
|
|
|
|
The following builtins are available on systems that use the OSF/1
|
|
PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
|
|
PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
|
|
@code{rdval} and @code{wrval}.
|
|
|
|
@example
|
|
void *__builtin_thread_pointer (void)
|
|
void __builtin_set_thread_pointer (void *)
|
|
@end example
|
|
|
|
@node X86 Built-in Functions
|
|
@subsection X86 Built-in Functions
|
|
|
|
These built-in functions are available for the i386 and x86-64 family
|
|
of computers, depending on the command-line switches used.
|
|
|
|
The following machine modes are available for use with MMX built-in functions
|
|
(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
|
|
@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
|
|
vector of eight 8-bit integers. Some of the built-in functions operate on
|
|
MMX registers as a whole 64-bit entity, these use @code{DI} as their mode.
|
|
|
|
If 3Dnow extensions are enabled, @code{V2SF} is used as a mode for a vector
|
|
of two 32-bit floating point values.
|
|
|
|
If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
|
|
floating point values. Some instructions use a vector of four 32-bit
|
|
integers, these use @code{V4SI}. Finally, some instructions operate on an
|
|
entire vector register, interpreting it as a 128-bit integer, these use mode
|
|
@code{TI}.
|
|
|
|
The following built-in functions are made available by @option{-mmmx}.
|
|
All of them generate the machine instruction that is part of the name.
|
|
|
|
@example
|
|
v8qi __builtin_ia32_paddb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_paddw (v4hi, v4hi)
|
|
v2si __builtin_ia32_paddd (v2si, v2si)
|
|
v8qi __builtin_ia32_psubb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_psubw (v4hi, v4hi)
|
|
v2si __builtin_ia32_psubd (v2si, v2si)
|
|
v8qi __builtin_ia32_paddsb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_paddsw (v4hi, v4hi)
|
|
v8qi __builtin_ia32_psubsb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_psubsw (v4hi, v4hi)
|
|
v8qi __builtin_ia32_paddusb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_paddusw (v4hi, v4hi)
|
|
v8qi __builtin_ia32_psubusb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_psubusw (v4hi, v4hi)
|
|
v4hi __builtin_ia32_pmullw (v4hi, v4hi)
|
|
v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
|
|
di __builtin_ia32_pand (di, di)
|
|
di __builtin_ia32_pandn (di,di)
|
|
di __builtin_ia32_por (di, di)
|
|
di __builtin_ia32_pxor (di, di)
|
|
v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
|
|
v2si __builtin_ia32_pcmpeqd (v2si, v2si)
|
|
v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
|
|
v2si __builtin_ia32_pcmpgtd (v2si, v2si)
|
|
v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
|
|
v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
|
|
v2si __builtin_ia32_punpckhdq (v2si, v2si)
|
|
v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
|
|
v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
|
|
v2si __builtin_ia32_punpckldq (v2si, v2si)
|
|
v8qi __builtin_ia32_packsswb (v4hi, v4hi)
|
|
v4hi __builtin_ia32_packssdw (v2si, v2si)
|
|
v8qi __builtin_ia32_packuswb (v4hi, v4hi)
|
|
@end example
|
|
|
|
The following built-in functions are made available either with
|
|
@option{-msse}, or with a combination of @option{-m3dnow} and
|
|
@option{-march=athlon}. All of them generate the machine
|
|
instruction that is part of the name.
|
|
|
|
@example
|
|
v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
|
|
v8qi __builtin_ia32_pavgb (v8qi, v8qi)
|
|
v4hi __builtin_ia32_pavgw (v4hi, v4hi)
|
|
v4hi __builtin_ia32_psadbw (v8qi, v8qi)
|
|
v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
|
|
v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
|
|
v8qi __builtin_ia32_pminub (v8qi, v8qi)
|
|
v4hi __builtin_ia32_pminsw (v4hi, v4hi)
|
|
int __builtin_ia32_pextrw (v4hi, int)
|
|
v4hi __builtin_ia32_pinsrw (v4hi, int, int)
|
|
int __builtin_ia32_pmovmskb (v8qi)
|
|
void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
|
|
void __builtin_ia32_movntq (di *, di)
|
|
void __builtin_ia32_sfence (void)
|
|
@end example
|
|
|
|
The following built-in functions are available when @option{-msse} is used.
|
|
All of them generate the machine instruction that is part of the name.
|
|
|
|
@example
|
|
int __builtin_ia32_comieq (v4sf, v4sf)
|
|
int __builtin_ia32_comineq (v4sf, v4sf)
|
|
int __builtin_ia32_comilt (v4sf, v4sf)
|
|
int __builtin_ia32_comile (v4sf, v4sf)
|
|
int __builtin_ia32_comigt (v4sf, v4sf)
|
|
int __builtin_ia32_comige (v4sf, v4sf)
|
|
int __builtin_ia32_ucomieq (v4sf, v4sf)
|
|
int __builtin_ia32_ucomineq (v4sf, v4sf)
|
|
int __builtin_ia32_ucomilt (v4sf, v4sf)
|
|
int __builtin_ia32_ucomile (v4sf, v4sf)
|
|
int __builtin_ia32_ucomigt (v4sf, v4sf)
|
|
int __builtin_ia32_ucomige (v4sf, v4sf)
|
|
v4sf __builtin_ia32_addps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_subps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_mulps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_divps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_addss (v4sf, v4sf)
|
|
v4sf __builtin_ia32_subss (v4sf, v4sf)
|
|
v4sf __builtin_ia32_mulss (v4sf, v4sf)
|
|
v4sf __builtin_ia32_divss (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpeqps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpltps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpleps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpgtps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpgeps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpunordps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpneqps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpnltps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpnleps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpngtps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpngeps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpordps (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpeqss (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpltss (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpless (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpunordss (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpneqss (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpnlts (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpnless (v4sf, v4sf)
|
|
v4si __builtin_ia32_cmpordss (v4sf, v4sf)
|
|
v4sf __builtin_ia32_maxps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_maxss (v4sf, v4sf)
|
|
v4sf __builtin_ia32_minps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_minss (v4sf, v4sf)
|
|
v4sf __builtin_ia32_andps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_andnps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_orps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_xorps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_movss (v4sf, v4sf)
|
|
v4sf __builtin_ia32_movhlps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_movlhps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
|
|
v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
|
|
v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
|
|
v2si __builtin_ia32_cvtps2pi (v4sf)
|
|
int __builtin_ia32_cvtss2si (v4sf)
|
|
v2si __builtin_ia32_cvttps2pi (v4sf)
|
|
int __builtin_ia32_cvttss2si (v4sf)
|
|
v4sf __builtin_ia32_rcpps (v4sf)
|
|
v4sf __builtin_ia32_rsqrtps (v4sf)
|
|
v4sf __builtin_ia32_sqrtps (v4sf)
|
|
v4sf __builtin_ia32_rcpss (v4sf)
|
|
v4sf __builtin_ia32_rsqrtss (v4sf)
|
|
v4sf __builtin_ia32_sqrtss (v4sf)
|
|
v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
|
|
void __builtin_ia32_movntps (float *, v4sf)
|
|
int __builtin_ia32_movmskps (v4sf)
|
|
@end example
|
|
|
|
The following built-in functions are available when @option{-msse} is used.
|
|
|
|
@table @code
|
|
@item v4sf __builtin_ia32_loadaps (float *)
|
|
Generates the @code{movaps} machine instruction as a load from memory.
|
|
@item void __builtin_ia32_storeaps (float *, v4sf)
|
|
Generates the @code{movaps} machine instruction as a store to memory.
|
|
@item v4sf __builtin_ia32_loadups (float *)
|
|
Generates the @code{movups} machine instruction as a load from memory.
|
|
@item void __builtin_ia32_storeups (float *, v4sf)
|
|
Generates the @code{movups} machine instruction as a store to memory.
|
|
@item v4sf __builtin_ia32_loadsss (float *)
|
|
Generates the @code{movss} machine instruction as a load from memory.
|
|
@item void __builtin_ia32_storess (float *, v4sf)
|
|
Generates the @code{movss} machine instruction as a store to memory.
|
|
@item v4sf __builtin_ia32_loadhps (v4sf, v2si *)
|
|
Generates the @code{movhps} machine instruction as a load from memory.
|
|
@item v4sf __builtin_ia32_loadlps (v4sf, v2si *)
|
|
Generates the @code{movlps} machine instruction as a load from memory
|
|
@item void __builtin_ia32_storehps (v4sf, v2si *)
|
|
Generates the @code{movhps} machine instruction as a store to memory.
|
|
@item void __builtin_ia32_storelps (v4sf, v2si *)
|
|
Generates the @code{movlps} machine instruction as a store to memory.
|
|
@end table
|
|
|
|
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.
|
|
|
|
@example
|
|
void __builtin_ia32_femms (void)
|
|
v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
|
|
v2si __builtin_ia32_pf2id (v2sf)
|
|
v2sf __builtin_ia32_pfacc (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfadd (v2sf, v2sf)
|
|
v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
|
|
v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
|
|
v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfmax (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfmin (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfmul (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfrcp (v2sf)
|
|
v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfrsqrt (v2sf)
|
|
v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfsub (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pi2fd (v2si)
|
|
v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
|
|
@end example
|
|
|
|
The following built-in functions are available when both @option{-m3dnow}
|
|
and @option{-march=athlon} are used. All of them generate the machine
|
|
instruction that is part of the name.
|
|
|
|
@example
|
|
v2si __builtin_ia32_pf2iw (v2sf)
|
|
v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
|
|
v2sf __builtin_ia32_pi2fw (v2si)
|
|
v2sf __builtin_ia32_pswapdsf (v2sf)
|
|
v2si __builtin_ia32_pswapdsi (v2si)
|
|
@end example
|
|
|
|
@node PowerPC AltiVec Built-in Functions
|
|
@subsection PowerPC AltiVec Built-in Functions
|
|
|
|
These built-in functions are available for the PowerPC family
|
|
of computers, depending on the command-line switches used.
|
|
|
|
The following machine modes are available for use with AltiVec built-in
|
|
functions (@pxref{Vector Extensions}): @code{V4SI} for a vector of four
|
|
32-bit integers, @code{V4SF} for a vector of four 32-bit floating point
|
|
numbers, @code{V8HI} for a vector of eight 16-bit integers, and
|
|
@code{V16QI} for a vector of sixteen 8-bit integers.
|
|
|
|
The following functions are made available by including
|
|
@code{<altivec.h>} and using @option{-maltivec} and
|
|
@option{-mabi=altivec}. The functions implement the functionality
|
|
described in Motorola's AltiVec Programming Interface Manual.
|
|
|
|
There are a few differences from Motorola's documentation and GCC's
|
|
implementation. Vector constants are done with curly braces (not
|
|
parentheses). Vector initializers require no casts if the vector
|
|
constant is of the same type as the variable it is initializing. The
|
|
@code{vector bool} type is deprecated and will be discontinued in
|
|
further revisions. Use @code{vector signed} instead. If @code{signed}
|
|
or @code{unsigned} is omitted, the vector type will default to
|
|
@code{signed}. Lastly, all overloaded functions are implemented with macros
|
|
for the C implementation. So code the following example will not work:
|
|
|
|
@smallexample
|
|
vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
|
|
@end smallexample
|
|
|
|
Since vec_add is a macro, the vector constant in the above example will
|
|
be treated as four different arguments. Wrap the entire argument in
|
|
parentheses for this to work. The C++ implementation does not use
|
|
macros.
|
|
|
|
@emph{Note:} Only the @code{<altivec.h>} interface is supported.
|
|
Internally, GCC uses built-in functions to achieve the functionality in
|
|
the aforementioned header file, but they are not supported and are
|
|
subject to change without notice.
|
|
|
|
@smallexample
|
|
vector signed char vec_abs (vector signed char, vector signed char);
|
|
vector signed short vec_abs (vector signed short, vector signed short);
|
|
vector signed int vec_abs (vector signed int, vector signed int);
|
|
vector signed float vec_abs (vector signed float, vector signed float);
|
|
|
|
vector signed char vec_abss (vector signed char, vector signed char);
|
|
vector signed short vec_abss (vector signed short, vector signed short);
|
|
|
|
vector signed char vec_add (vector signed char, vector signed char);
|
|
vector unsigned char vec_add (vector signed char, vector unsigned char);
|
|
|
|
vector unsigned char vec_add (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_add (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_add (vector signed short, vector signed short);
|
|
vector unsigned short vec_add (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_add (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_add (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_add (vector signed int, vector signed int);
|
|
vector unsigned int vec_add (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_add (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_add (vector unsigned int, vector unsigned int);
|
|
vector float vec_add (vector float, vector float);
|
|
|
|
vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
|
|
|
|
vector unsigned char vec_adds (vector signed char,
|
|
vector unsigned char);
|
|
vector unsigned char vec_adds (vector unsigned char,
|
|
vector signed char);
|
|
vector unsigned char vec_adds (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed char vec_adds (vector signed char, vector signed char);
|
|
vector unsigned short vec_adds (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_adds (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_adds (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_adds (vector signed short, vector signed short);
|
|
|
|
vector unsigned int vec_adds (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_adds (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_adds (vector signed int, vector signed int);
|
|
|
|
vector float vec_and (vector float, vector float);
|
|
vector float vec_and (vector float, vector signed int);
|
|
vector float vec_and (vector signed int, vector float);
|
|
vector signed int vec_and (vector signed int, vector signed int);
|
|
vector unsigned int vec_and (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_and (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_and (vector unsigned int, vector unsigned int);
|
|
vector signed short vec_and (vector signed short, vector signed short);
|
|
vector unsigned short vec_and (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_and (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_and (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed char vec_and (vector signed char, vector signed char);
|
|
vector unsigned char vec_and (vector signed char, vector unsigned char);
|
|
|
|
vector unsigned char vec_and (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_and (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector float vec_andc (vector float, vector float);
|
|
vector float vec_andc (vector float, vector signed int);
|
|
vector float vec_andc (vector signed int, vector float);
|
|
vector signed int vec_andc (vector signed int, vector signed int);
|
|
vector unsigned int vec_andc (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_andc (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed short vec_andc (vector signed short, vector signed short);
|
|
|
|
vector unsigned short vec_andc (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_andc (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_andc (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed char vec_andc (vector signed char, vector signed char);
|
|
vector unsigned char vec_andc (vector signed char,
|
|
vector unsigned char);
|
|
vector unsigned char vec_andc (vector unsigned char,
|
|
vector signed char);
|
|
vector unsigned char vec_andc (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector unsigned char vec_avg (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed char vec_avg (vector signed char, vector signed char);
|
|
vector unsigned short vec_avg (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_avg (vector signed short, vector signed short);
|
|
vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
|
|
vector signed int vec_avg (vector signed int, vector signed int);
|
|
|
|
vector float vec_ceil (vector float);
|
|
|
|
vector signed int vec_cmpb (vector float, vector float);
|
|
|
|
vector signed char vec_cmpeq (vector signed char, vector signed char);
|
|
vector signed char vec_cmpeq (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_cmpeq (vector signed short,
|
|
vector signed short);
|
|
vector signed short vec_cmpeq (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_cmpeq (vector signed int, vector signed int);
|
|
vector signed int vec_cmpeq (vector unsigned int, vector unsigned int);
|
|
vector signed int vec_cmpeq (vector float, vector float);
|
|
|
|
vector signed int vec_cmpge (vector float, vector float);
|
|
|
|
vector signed char vec_cmpgt (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed char vec_cmpgt (vector signed char, vector signed char);
|
|
vector signed short vec_cmpgt (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_cmpgt (vector signed short,
|
|
vector signed short);
|
|
vector signed int vec_cmpgt (vector unsigned int, vector unsigned int);
|
|
vector signed int vec_cmpgt (vector signed int, vector signed int);
|
|
vector signed int vec_cmpgt (vector float, vector float);
|
|
|
|
vector signed int vec_cmple (vector float, vector float);
|
|
|
|
vector signed char vec_cmplt (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed char vec_cmplt (vector signed char, vector signed char);
|
|
vector signed short vec_cmplt (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_cmplt (vector signed short,
|
|
vector signed short);
|
|
vector signed int vec_cmplt (vector unsigned int, vector unsigned int);
|
|
vector signed int vec_cmplt (vector signed int, vector signed int);
|
|
vector signed int vec_cmplt (vector float, vector float);
|
|
|
|
vector float vec_ctf (vector unsigned int, const char);
|
|
vector float vec_ctf (vector signed int, const char);
|
|
|
|
vector signed int vec_cts (vector float, const char);
|
|
|
|
vector unsigned int vec_ctu (vector float, const char);
|
|
|
|
void vec_dss (const char);
|
|
|
|
void vec_dssall (void);
|
|
|
|
void vec_dst (void *, int, const char);
|
|
|
|
void vec_dstst (void *, int, const char);
|
|
|
|
void vec_dststt (void *, int, const char);
|
|
|
|
void vec_dstt (void *, int, const char);
|
|
|
|
vector float vec_expte (vector float, vector float);
|
|
|
|
vector float vec_floor (vector float, vector float);
|
|
|
|
vector float vec_ld (int, vector float *);
|
|
vector float vec_ld (int, float *):
|
|
vector signed int vec_ld (int, int *);
|
|
vector signed int vec_ld (int, vector signed int *);
|
|
vector unsigned int vec_ld (int, vector unsigned int *);
|
|
vector unsigned int vec_ld (int, unsigned int *);
|
|
vector signed short vec_ld (int, short *, vector signed short *);
|
|
vector unsigned short vec_ld (int, unsigned short *,
|
|
vector unsigned short *);
|
|
vector signed char vec_ld (int, signed char *);
|
|
vector signed char vec_ld (int, vector signed char *);
|
|
vector unsigned char vec_ld (int, unsigned char *);
|
|
vector unsigned char vec_ld (int, vector unsigned char *);
|
|
|
|
vector signed char vec_lde (int, signed char *);
|
|
vector unsigned char vec_lde (int, unsigned char *);
|
|
vector signed short vec_lde (int, short *);
|
|
vector unsigned short vec_lde (int, unsigned short *);
|
|
vector float vec_lde (int, float *);
|
|
vector signed int vec_lde (int, int *);
|
|
vector unsigned int vec_lde (int, unsigned int *);
|
|
|
|
void float vec_ldl (int, float *);
|
|
void float vec_ldl (int, vector float *);
|
|
void signed int vec_ldl (int, vector signed int *);
|
|
void signed int vec_ldl (int, int *);
|
|
void unsigned int vec_ldl (int, unsigned int *);
|
|
void unsigned int vec_ldl (int, vector unsigned int *);
|
|
void signed short vec_ldl (int, vector signed short *);
|
|
void signed short vec_ldl (int, short *);
|
|
void unsigned short vec_ldl (int, vector unsigned short *);
|
|
void unsigned short vec_ldl (int, unsigned short *);
|
|
void signed char vec_ldl (int, vector signed char *);
|
|
void signed char vec_ldl (int, signed char *);
|
|
void unsigned char vec_ldl (int, vector unsigned char *);
|
|
void unsigned char vec_ldl (int, unsigned char *);
|
|
|
|
vector float vec_loge (vector float);
|
|
|
|
vector unsigned char vec_lvsl (int, void *, int *);
|
|
|
|
vector unsigned char vec_lvsr (int, void *, int *);
|
|
|
|
vector float vec_madd (vector float, vector float, vector float);
|
|
|
|
vector signed short vec_madds (vector signed short, vector signed short,
|
|
vector signed short);
|
|
|
|
vector unsigned char vec_max (vector signed char, vector unsigned char);
|
|
|
|
vector unsigned char vec_max (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_max (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed char vec_max (vector signed char, vector signed char);
|
|
vector unsigned short vec_max (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_max (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_max (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_max (vector signed short, vector signed short);
|
|
vector unsigned int vec_max (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_max (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_max (vector unsigned int, vector unsigned int);
|
|
vector signed int vec_max (vector signed int, vector signed int);
|
|
vector float vec_max (vector float, vector float);
|
|
|
|
vector signed char vec_mergeh (vector signed char, vector signed char);
|
|
vector unsigned char vec_mergeh (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_mergeh (vector signed short,
|
|
vector signed short);
|
|
vector unsigned short vec_mergeh (vector unsigned short,
|
|
vector unsigned short);
|
|
vector float vec_mergeh (vector float, vector float);
|
|
vector signed int vec_mergeh (vector signed int, vector signed int);
|
|
vector unsigned int vec_mergeh (vector unsigned int,
|
|
vector unsigned int);
|
|
|
|
vector signed char vec_mergel (vector signed char, vector signed char);
|
|
vector unsigned char vec_mergel (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_mergel (vector signed short,
|
|
vector signed short);
|
|
vector unsigned short vec_mergel (vector unsigned short,
|
|
vector unsigned short);
|
|
vector float vec_mergel (vector float, vector float);
|
|
vector signed int vec_mergel (vector signed int, vector signed int);
|
|
vector unsigned int vec_mergel (vector unsigned int,
|
|
vector unsigned int);
|
|
|
|
vector unsigned short vec_mfvscr (void);
|
|
|
|
vector unsigned char vec_min (vector signed char, vector unsigned char);
|
|
|
|
vector unsigned char vec_min (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_min (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed char vec_min (vector signed char, vector signed char);
|
|
vector unsigned short vec_min (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_min (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_min (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_min (vector signed short, vector signed short);
|
|
vector unsigned int vec_min (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_min (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_min (vector unsigned int, vector unsigned int);
|
|
vector signed int vec_min (vector signed int, vector signed int);
|
|
vector float vec_min (vector float, vector float);
|
|
|
|
vector signed short vec_mladd (vector signed short, vector signed short,
|
|
vector signed short);
|
|
vector signed short vec_mladd (vector signed short,
|
|
vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_mladd (vector unsigned short,
|
|
vector signed short,
|
|
vector signed short);
|
|
vector unsigned short vec_mladd (vector unsigned short,
|
|
vector unsigned short,
|
|
vector unsigned short);
|
|
|
|
vector signed short vec_mradds (vector signed short,
|
|
vector signed short,
|
|
vector signed short);
|
|
|
|
vector unsigned int vec_msum (vector unsigned char,
|
|
vector unsigned char,
|
|
vector unsigned int);
|
|
vector signed int vec_msum (vector signed char, vector unsigned char,
|
|
vector signed int);
|
|
vector unsigned int vec_msum (vector unsigned short,
|
|
vector unsigned short,
|
|
vector unsigned int);
|
|
vector signed int vec_msum (vector signed short, vector signed short,
|
|
vector signed int);
|
|
|
|
vector unsigned int vec_msums (vector unsigned short,
|
|
vector unsigned short,
|
|
vector unsigned int);
|
|
vector signed int vec_msums (vector signed short, vector signed short,
|
|
vector signed int);
|
|
|
|
void vec_mtvscr (vector signed int);
|
|
void vec_mtvscr (vector unsigned int);
|
|
void vec_mtvscr (vector signed short);
|
|
void vec_mtvscr (vector unsigned short);
|
|
void vec_mtvscr (vector signed char);
|
|
void vec_mtvscr (vector unsigned char);
|
|
|
|
vector unsigned short vec_mule (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_mule (vector signed char, vector signed char);
|
|
vector unsigned int vec_mule (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_mule (vector signed short, vector signed short);
|
|
|
|
vector unsigned short vec_mulo (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_mulo (vector signed char, vector signed char);
|
|
vector unsigned int vec_mulo (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_mulo (vector signed short, vector signed short);
|
|
|
|
vector float vec_nmsub (vector float, vector float, vector float);
|
|
@end smallexample
|
|
|
|
@smallexample
|
|
vector float vec_nor (vector float, vector float);
|
|
vector signed int vec_nor (vector signed int, vector signed int);
|
|
vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
|
|
vector signed short vec_nor (vector signed short, vector signed short);
|
|
vector unsigned short vec_nor (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed char vec_nor (vector signed char, vector signed char);
|
|
vector unsigned char vec_nor (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector float vec_or (vector float, vector float);
|
|
vector float vec_or (vector float, vector signed int);
|
|
vector float vec_or (vector signed int, vector float);
|
|
vector signed int vec_or (vector signed int, vector signed int);
|
|
vector unsigned int vec_or (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_or (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_or (vector unsigned int, vector unsigned int);
|
|
vector signed short vec_or (vector signed short, vector signed short);
|
|
vector unsigned short vec_or (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_or (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_or (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed char vec_or (vector signed char, vector signed char);
|
|
vector unsigned char vec_or (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_or (vector unsigned char, vector signed char);
|
|
vector unsigned char vec_or (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector signed char vec_pack (vector signed short, vector signed short);
|
|
vector unsigned char vec_pack (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_pack (vector signed int, vector signed int);
|
|
vector unsigned short vec_pack (vector unsigned int,
|
|
vector unsigned int);
|
|
|
|
vector signed short vec_packpx (vector unsigned int,
|
|
vector unsigned int);
|
|
|
|
vector unsigned char vec_packs (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed char vec_packs (vector signed short, vector signed short);
|
|
|
|
vector unsigned short vec_packs (vector unsigned int,
|
|
vector unsigned int);
|
|
vector signed short vec_packs (vector signed int, vector signed int);
|
|
|
|
vector unsigned char vec_packsu (vector unsigned short,
|
|
vector unsigned short);
|
|
vector unsigned char vec_packsu (vector signed short,
|
|
vector signed short);
|
|
vector unsigned short vec_packsu (vector unsigned int,
|
|
vector unsigned int);
|
|
vector unsigned short vec_packsu (vector signed int, vector signed int);
|
|
|
|
vector float vec_perm (vector float, vector float,
|
|
vector unsigned char);
|
|
vector signed int vec_perm (vector signed int, vector signed int,
|
|
vector unsigned char);
|
|
vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
|
|
vector unsigned char);
|
|
vector signed short vec_perm (vector signed short, vector signed short,
|
|
vector unsigned char);
|
|
vector unsigned short vec_perm (vector unsigned short,
|
|
vector unsigned short,
|
|
vector unsigned char);
|
|
vector signed char vec_perm (vector signed char, vector signed char,
|
|
vector unsigned char);
|
|
vector unsigned char vec_perm (vector unsigned char,
|
|
vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector float vec_re (vector float);
|
|
|
|
vector signed char vec_rl (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_rl (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_rl (vector signed short, vector unsigned short);
|
|
|
|
vector unsigned short vec_rl (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_rl (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
|
|
|
|
vector float vec_round (vector float);
|
|
|
|
vector float vec_rsqrte (vector float);
|
|
|
|
vector float vec_sel (vector float, vector float, vector signed int);
|
|
vector float vec_sel (vector float, vector float, vector unsigned int);
|
|
vector signed int vec_sel (vector signed int, vector signed int,
|
|
vector signed int);
|
|
vector signed int vec_sel (vector signed int, vector signed int,
|
|
vector unsigned int);
|
|
vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
|
|
vector signed int);
|
|
vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
|
|
vector unsigned int);
|
|
vector signed short vec_sel (vector signed short, vector signed short,
|
|
vector signed short);
|
|
vector signed short vec_sel (vector signed short, vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_sel (vector unsigned short,
|
|
vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_sel (vector unsigned short,
|
|
vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed char vec_sel (vector signed char, vector signed char,
|
|
vector signed char);
|
|
vector signed char vec_sel (vector signed char, vector signed char,
|
|
vector unsigned char);
|
|
vector unsigned char vec_sel (vector unsigned char,
|
|
vector unsigned char,
|
|
vector signed char);
|
|
vector unsigned char vec_sel (vector unsigned char,
|
|
vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector signed char vec_sl (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_sl (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_sl (vector signed short, vector unsigned short);
|
|
|
|
vector unsigned short vec_sl (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_sl (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
|
|
|
|
vector float vec_sld (vector float, vector float, const char);
|
|
vector signed int vec_sld (vector signed int, vector signed int,
|
|
const char);
|
|
vector unsigned int vec_sld (vector unsigned int, vector unsigned int,
|
|
const char);
|
|
vector signed short vec_sld (vector signed short, vector signed short,
|
|
const char);
|
|
vector unsigned short vec_sld (vector unsigned short,
|
|
vector unsigned short, const char);
|
|
vector signed char vec_sld (vector signed char, vector signed char,
|
|
const char);
|
|
vector unsigned char vec_sld (vector unsigned char,
|
|
vector unsigned char,
|
|
const char);
|
|
|
|
vector signed int vec_sll (vector signed int, vector unsigned int);
|
|
vector signed int vec_sll (vector signed int, vector unsigned short);
|
|
vector signed int vec_sll (vector signed int, vector unsigned char);
|
|
vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
|
|
vector unsigned int vec_sll (vector unsigned int,
|
|
vector unsigned short);
|
|
vector unsigned int vec_sll (vector unsigned int, vector unsigned char);
|
|
|
|
vector signed short vec_sll (vector signed short, vector unsigned int);
|
|
vector signed short vec_sll (vector signed short,
|
|
vector unsigned short);
|
|
vector signed short vec_sll (vector signed short, vector unsigned char);
|
|
|
|
vector unsigned short vec_sll (vector unsigned short,
|
|
vector unsigned int);
|
|
vector unsigned short vec_sll (vector unsigned short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_sll (vector unsigned short,
|
|
vector unsigned char);
|
|
vector signed char vec_sll (vector signed char, vector unsigned int);
|
|
vector signed char vec_sll (vector signed char, vector unsigned short);
|
|
vector signed char vec_sll (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_sll (vector unsigned char,
|
|
vector unsigned int);
|
|
vector unsigned char vec_sll (vector unsigned char,
|
|
vector unsigned short);
|
|
vector unsigned char vec_sll (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector float vec_slo (vector float, vector signed char);
|
|
vector float vec_slo (vector float, vector unsigned char);
|
|
vector signed int vec_slo (vector signed int, vector signed char);
|
|
vector signed int vec_slo (vector signed int, vector unsigned char);
|
|
vector unsigned int vec_slo (vector unsigned int, vector signed char);
|
|
vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
|
|
|
|
vector signed short vec_slo (vector signed short, vector signed char);
|
|
vector signed short vec_slo (vector signed short, vector unsigned char);
|
|
|
|
vector unsigned short vec_slo (vector unsigned short,
|
|
vector signed char);
|
|
vector unsigned short vec_slo (vector unsigned short,
|
|
vector unsigned char);
|
|
vector signed char vec_slo (vector signed char, vector signed char);
|
|
vector signed char vec_slo (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_slo (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_slo (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector signed char vec_splat (vector signed char, const char);
|
|
vector unsigned char vec_splat (vector unsigned char, const char);
|
|
vector signed short vec_splat (vector signed short, const char);
|
|
vector unsigned short vec_splat (vector unsigned short, const char);
|
|
vector float vec_splat (vector float, const char);
|
|
vector signed int vec_splat (vector signed int, const char);
|
|
vector unsigned int vec_splat (vector unsigned int, const char);
|
|
|
|
vector signed char vec_splat_s8 (const char);
|
|
|
|
vector signed short vec_splat_s16 (const char);
|
|
|
|
vector signed int vec_splat_s32 (const char);
|
|
|
|
vector unsigned char vec_splat_u8 (const char);
|
|
|
|
vector unsigned short vec_splat_u16 (const char);
|
|
|
|
vector unsigned int vec_splat_u32 (const char);
|
|
|
|
vector signed char vec_sr (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_sr (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_sr (vector signed short, vector unsigned short);
|
|
|
|
vector unsigned short vec_sr (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_sr (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed char vec_sra (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_sra (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_sra (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_sra (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_sra (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_srl (vector signed int, vector unsigned int);
|
|
vector signed int vec_srl (vector signed int, vector unsigned short);
|
|
vector signed int vec_srl (vector signed int, vector unsigned char);
|
|
vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
|
|
vector unsigned int vec_srl (vector unsigned int,
|
|
vector unsigned short);
|
|
vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
|
|
|
|
vector signed short vec_srl (vector signed short, vector unsigned int);
|
|
vector signed short vec_srl (vector signed short,
|
|
vector unsigned short);
|
|
vector signed short vec_srl (vector signed short, vector unsigned char);
|
|
|
|
vector unsigned short vec_srl (vector unsigned short,
|
|
vector unsigned int);
|
|
vector unsigned short vec_srl (vector unsigned short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_srl (vector unsigned short,
|
|
vector unsigned char);
|
|
vector signed char vec_srl (vector signed char, vector unsigned int);
|
|
vector signed char vec_srl (vector signed char, vector unsigned short);
|
|
vector signed char vec_srl (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_srl (vector unsigned char,
|
|
vector unsigned int);
|
|
vector unsigned char vec_srl (vector unsigned char,
|
|
vector unsigned short);
|
|
vector unsigned char vec_srl (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector float vec_sro (vector float, vector signed char);
|
|
vector float vec_sro (vector float, vector unsigned char);
|
|
vector signed int vec_sro (vector signed int, vector signed char);
|
|
vector signed int vec_sro (vector signed int, vector unsigned char);
|
|
vector unsigned int vec_sro (vector unsigned int, vector signed char);
|
|
vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
|
|
|
|
vector signed short vec_sro (vector signed short, vector signed char);
|
|
vector signed short vec_sro (vector signed short, vector unsigned char);
|
|
|
|
vector unsigned short vec_sro (vector unsigned short,
|
|
vector signed char);
|
|
vector unsigned short vec_sro (vector unsigned short,
|
|
vector unsigned char);
|
|
vector signed char vec_sro (vector signed char, vector signed char);
|
|
vector signed char vec_sro (vector signed char, vector unsigned char);
|
|
vector unsigned char vec_sro (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_sro (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
void vec_st (vector float, int, float *);
|
|
void vec_st (vector float, int, vector float *);
|
|
void vec_st (vector signed int, int, int *);
|
|
void vec_st (vector signed int, int, unsigned int *);
|
|
void vec_st (vector unsigned int, int, unsigned int *);
|
|
void vec_st (vector unsigned int, int, vector unsigned int *);
|
|
void vec_st (vector signed short, int, short *);
|
|
void vec_st (vector signed short, int, vector unsigned short *);
|
|
void vec_st (vector signed short, int, vector signed short *);
|
|
void vec_st (vector unsigned short, int, unsigned short *);
|
|
void vec_st (vector unsigned short, int, vector unsigned short *);
|
|
void vec_st (vector signed char, int, signed char *);
|
|
void vec_st (vector signed char, int, unsigned char *);
|
|
void vec_st (vector signed char, int, vector signed char *);
|
|
void vec_st (vector unsigned char, int, unsigned char *);
|
|
void vec_st (vector unsigned char, int, vector unsigned char *);
|
|
|
|
void vec_ste (vector signed char, int, unsigned char *);
|
|
void vec_ste (vector signed char, int, signed char *);
|
|
void vec_ste (vector unsigned char, int, unsigned char *);
|
|
void vec_ste (vector signed short, int, short *);
|
|
void vec_ste (vector signed short, int, unsigned short *);
|
|
void vec_ste (vector unsigned short, int, void *);
|
|
void vec_ste (vector signed int, int, unsigned int *);
|
|
void vec_ste (vector signed int, int, int *);
|
|
void vec_ste (vector unsigned int, int, unsigned int *);
|
|
void vec_ste (vector float, int, float *);
|
|
|
|
void vec_stl (vector float, int, vector float *);
|
|
void vec_stl (vector float, int, float *);
|
|
void vec_stl (vector signed int, int, vector signed int *);
|
|
void vec_stl (vector signed int, int, int *);
|
|
void vec_stl (vector signed int, int, unsigned int *);
|
|
void vec_stl (vector unsigned int, int, vector unsigned int *);
|
|
void vec_stl (vector unsigned int, int, unsigned int *);
|
|
void vec_stl (vector signed short, int, short *);
|
|
void vec_stl (vector signed short, int, unsigned short *);
|
|
void vec_stl (vector signed short, int, vector signed short *);
|
|
void vec_stl (vector unsigned short, int, unsigned short *);
|
|
void vec_stl (vector unsigned short, int, vector signed short *);
|
|
void vec_stl (vector signed char, int, signed char *);
|
|
void vec_stl (vector signed char, int, unsigned char *);
|
|
void vec_stl (vector signed char, int, vector signed char *);
|
|
void vec_stl (vector unsigned char, int, unsigned char *);
|
|
void vec_stl (vector unsigned char, int, vector unsigned char *);
|
|
|
|
vector signed char vec_sub (vector signed char, vector signed char);
|
|
vector unsigned char vec_sub (vector signed char, vector unsigned char);
|
|
|
|
vector unsigned char vec_sub (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_sub (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed short vec_sub (vector signed short, vector signed short);
|
|
vector unsigned short vec_sub (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_sub (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_sub (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_sub (vector signed int, vector signed int);
|
|
vector unsigned int vec_sub (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_sub (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
|
|
vector float vec_sub (vector float, vector float);
|
|
|
|
vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
|
|
|
|
vector unsigned char vec_subs (vector signed char,
|
|
vector unsigned char);
|
|
vector unsigned char vec_subs (vector unsigned char,
|
|
vector signed char);
|
|
vector unsigned char vec_subs (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed char vec_subs (vector signed char, vector signed char);
|
|
vector unsigned short vec_subs (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_subs (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_subs (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed short vec_subs (vector signed short, vector signed short);
|
|
|
|
vector unsigned int vec_subs (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_subs (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_subs (vector signed int, vector signed int);
|
|
|
|
vector unsigned int vec_sum4s (vector unsigned char,
|
|
vector unsigned int);
|
|
vector signed int vec_sum4s (vector signed char, vector signed int);
|
|
vector signed int vec_sum4s (vector signed short, vector signed int);
|
|
|
|
vector signed int vec_sum2s (vector signed int, vector signed int);
|
|
|
|
vector signed int vec_sums (vector signed int, vector signed int);
|
|
|
|
vector float vec_trunc (vector float);
|
|
|
|
vector signed short vec_unpackh (vector signed char);
|
|
vector unsigned int vec_unpackh (vector signed short);
|
|
vector signed int vec_unpackh (vector signed short);
|
|
|
|
vector signed short vec_unpackl (vector signed char);
|
|
vector unsigned int vec_unpackl (vector signed short);
|
|
vector signed int vec_unpackl (vector signed short);
|
|
|
|
vector float vec_xor (vector float, vector float);
|
|
vector float vec_xor (vector float, vector signed int);
|
|
vector float vec_xor (vector signed int, vector float);
|
|
vector signed int vec_xor (vector signed int, vector signed int);
|
|
vector unsigned int vec_xor (vector signed int, vector unsigned int);
|
|
vector unsigned int vec_xor (vector unsigned int, vector signed int);
|
|
vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
|
|
vector signed short vec_xor (vector signed short, vector signed short);
|
|
vector unsigned short vec_xor (vector signed short,
|
|
vector unsigned short);
|
|
vector unsigned short vec_xor (vector unsigned short,
|
|
vector signed short);
|
|
vector unsigned short vec_xor (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed char vec_xor (vector signed char, vector signed char);
|
|
vector unsigned char vec_xor (vector signed char, vector unsigned char);
|
|
|
|
vector unsigned char vec_xor (vector unsigned char, vector signed char);
|
|
|
|
vector unsigned char vec_xor (vector unsigned char,
|
|
vector unsigned char);
|
|
|
|
vector signed int vec_all_eq (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_all_eq (vector signed char, vector signed char);
|
|
vector signed int vec_all_eq (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_all_eq (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_all_eq (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_eq (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_all_eq (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_all_eq (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_eq (vector signed int, vector unsigned int);
|
|
vector signed int vec_all_eq (vector signed int, vector signed int);
|
|
vector signed int vec_all_eq (vector unsigned int, vector signed int);
|
|
vector signed int vec_all_eq (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_all_eq (vector float, vector float);
|
|
|
|
vector signed int vec_all_ge (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_all_ge (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_all_ge (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_all_ge (vector signed char, vector signed char);
|
|
vector signed int vec_all_ge (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_ge (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_all_ge (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_ge (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_all_ge (vector signed int, vector unsigned int);
|
|
vector signed int vec_all_ge (vector unsigned int, vector signed int);
|
|
vector signed int vec_all_ge (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_all_ge (vector signed int, vector signed int);
|
|
vector signed int vec_all_ge (vector float, vector float);
|
|
|
|
vector signed int vec_all_gt (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_all_gt (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_all_gt (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_all_gt (vector signed char, vector signed char);
|
|
vector signed int vec_all_gt (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_gt (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_all_gt (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_gt (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_all_gt (vector signed int, vector unsigned int);
|
|
vector signed int vec_all_gt (vector unsigned int, vector signed int);
|
|
vector signed int vec_all_gt (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_all_gt (vector signed int, vector signed int);
|
|
vector signed int vec_all_gt (vector float, vector float);
|
|
|
|
vector signed int vec_all_in (vector float, vector float);
|
|
|
|
vector signed int vec_all_le (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_all_le (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_all_le (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_all_le (vector signed char, vector signed char);
|
|
vector signed int vec_all_le (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_le (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_all_le (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_le (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_all_le (vector signed int, vector unsigned int);
|
|
vector signed int vec_all_le (vector unsigned int, vector signed int);
|
|
vector signed int vec_all_le (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_all_le (vector signed int, vector signed int);
|
|
vector signed int vec_all_le (vector float, vector float);
|
|
|
|
vector signed int vec_all_lt (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_all_lt (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_all_lt (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_all_lt (vector signed char, vector signed char);
|
|
vector signed int vec_all_lt (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_lt (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_all_lt (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_lt (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_all_lt (vector signed int, vector unsigned int);
|
|
vector signed int vec_all_lt (vector unsigned int, vector signed int);
|
|
vector signed int vec_all_lt (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_all_lt (vector signed int, vector signed int);
|
|
vector signed int vec_all_lt (vector float, vector float);
|
|
|
|
vector signed int vec_all_nan (vector float);
|
|
|
|
vector signed int vec_all_ne (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_all_ne (vector signed char, vector signed char);
|
|
vector signed int vec_all_ne (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_all_ne (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_all_ne (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_ne (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_all_ne (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_all_ne (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_all_ne (vector signed int, vector unsigned int);
|
|
vector signed int vec_all_ne (vector signed int, vector signed int);
|
|
vector signed int vec_all_ne (vector unsigned int, vector signed int);
|
|
vector signed int vec_all_ne (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_all_ne (vector float, vector float);
|
|
|
|
vector signed int vec_all_nge (vector float, vector float);
|
|
|
|
vector signed int vec_all_ngt (vector float, vector float);
|
|
|
|
vector signed int vec_all_nle (vector float, vector float);
|
|
|
|
vector signed int vec_all_nlt (vector float, vector float);
|
|
|
|
vector signed int vec_all_numeric (vector float);
|
|
|
|
vector signed int vec_any_eq (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_any_eq (vector signed char, vector signed char);
|
|
vector signed int vec_any_eq (vector unsigned char, vector signed char);
|
|
@end smallexample
|
|
|
|
@smallexample
|
|
vector signed int vec_any_eq (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_any_eq (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_eq (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_any_eq (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_any_eq (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_eq (vector signed int, vector unsigned int);
|
|
vector signed int vec_any_eq (vector signed int, vector signed int);
|
|
vector signed int vec_any_eq (vector unsigned int, vector signed int);
|
|
vector signed int vec_any_eq (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_any_eq (vector float, vector float);
|
|
|
|
vector signed int vec_any_ge (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_any_ge (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_any_ge (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_any_ge (vector signed char, vector signed char);
|
|
vector signed int vec_any_ge (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_ge (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_any_ge (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_ge (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_any_ge (vector signed int, vector unsigned int);
|
|
vector signed int vec_any_ge (vector unsigned int, vector signed int);
|
|
vector signed int vec_any_ge (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_any_ge (vector signed int, vector signed int);
|
|
vector signed int vec_any_ge (vector float, vector float);
|
|
|
|
vector signed int vec_any_gt (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_any_gt (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_any_gt (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_any_gt (vector signed char, vector signed char);
|
|
vector signed int vec_any_gt (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_gt (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_any_gt (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_gt (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_any_gt (vector signed int, vector unsigned int);
|
|
vector signed int vec_any_gt (vector unsigned int, vector signed int);
|
|
vector signed int vec_any_gt (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_any_gt (vector signed int, vector signed int);
|
|
vector signed int vec_any_gt (vector float, vector float);
|
|
|
|
vector signed int vec_any_le (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_any_le (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_any_le (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_any_le (vector signed char, vector signed char);
|
|
vector signed int vec_any_le (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_le (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_any_le (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_le (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_any_le (vector signed int, vector unsigned int);
|
|
vector signed int vec_any_le (vector unsigned int, vector signed int);
|
|
vector signed int vec_any_le (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_any_le (vector signed int, vector signed int);
|
|
vector signed int vec_any_le (vector float, vector float);
|
|
|
|
vector signed int vec_any_lt (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_any_lt (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_any_lt (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_any_lt (vector signed char, vector signed char);
|
|
vector signed int vec_any_lt (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_lt (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_any_lt (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_lt (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_any_lt (vector signed int, vector unsigned int);
|
|
vector signed int vec_any_lt (vector unsigned int, vector signed int);
|
|
vector signed int vec_any_lt (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_any_lt (vector signed int, vector signed int);
|
|
vector signed int vec_any_lt (vector float, vector float);
|
|
|
|
vector signed int vec_any_nan (vector float);
|
|
|
|
vector signed int vec_any_ne (vector signed char, vector unsigned char);
|
|
|
|
vector signed int vec_any_ne (vector signed char, vector signed char);
|
|
vector signed int vec_any_ne (vector unsigned char, vector signed char);
|
|
|
|
vector signed int vec_any_ne (vector unsigned char,
|
|
vector unsigned char);
|
|
vector signed int vec_any_ne (vector signed short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_ne (vector signed short, vector signed short);
|
|
|
|
vector signed int vec_any_ne (vector unsigned short,
|
|
vector signed short);
|
|
vector signed int vec_any_ne (vector unsigned short,
|
|
vector unsigned short);
|
|
vector signed int vec_any_ne (vector signed int, vector unsigned int);
|
|
vector signed int vec_any_ne (vector signed int, vector signed int);
|
|
vector signed int vec_any_ne (vector unsigned int, vector signed int);
|
|
vector signed int vec_any_ne (vector unsigned int, vector unsigned int);
|
|
|
|
vector signed int vec_any_ne (vector float, vector float);
|
|
|
|
vector signed int vec_any_nge (vector float, vector float);
|
|
|
|
vector signed int vec_any_ngt (vector float, vector float);
|
|
|
|
vector signed int vec_any_nle (vector float, vector float);
|
|
|
|
vector signed int vec_any_nlt (vector float, vector float);
|
|
|
|
vector signed int vec_any_numeric (vector float);
|
|
|
|
vector signed int vec_any_out (vector float, vector float);
|
|
@end smallexample
|
|
|
|
@node Pragmas
|
|
@section Pragmas Accepted by GCC
|
|
@cindex pragmas
|
|
@cindex #pragma
|
|
|
|
GCC supports several types of pragmas, primarily in order to compile
|
|
code originally written for other compilers. Note that in general
|
|
we do not recommend the use of pragmas; @xref{Function Attributes},
|
|
for further explanation.
|
|
|
|
@menu
|
|
* ARM Pragmas::
|
|
* RS/6000 and PowerPC Pragmas::
|
|
* Darwin Pragmas::
|
|
* Solaris Pragmas::
|
|
* Tru64 Pragmas::
|
|
@end menu
|
|
|
|
@node ARM Pragmas
|
|
@subsection ARM Pragmas
|
|
|
|
The ARM target defines pragmas for controlling the default addition of
|
|
@code{long_call} and @code{short_call} attributes to functions.
|
|
@xref{Function Attributes}, for information about the effects of these
|
|
attributes.
|
|
|
|
@table @code
|
|
@item long_calls
|
|
@cindex pragma, long_calls
|
|
Set all subsequent functions to have the @code{long_call} attribute.
|
|
|
|
@item no_long_calls
|
|
@cindex pragma, no_long_calls
|
|
Set all subsequent functions to have the @code{short_call} attribute.
|
|
|
|
@item long_calls_off
|
|
@cindex pragma, long_calls_off
|
|
Do not affect the @code{long_call} or @code{short_call} attributes of
|
|
subsequent functions.
|
|
@end table
|
|
|
|
@node RS/6000 and PowerPC Pragmas
|
|
@subsection RS/6000 and PowerPC Pragmas
|
|
|
|
The RS/6000 and PowerPC targets define one pragma for controlling
|
|
whether or not the @code{longcall} attribute is added to function
|
|
declarations by default. This pragma overrides the @option{-mlongcall}
|
|
option, but not the @code{longcall} and @code{shortcall} attributes.
|
|
@xref{RS/6000 and PowerPC Options}, for more information about when long
|
|
calls are and are not necessary.
|
|
|
|
@table @code
|
|
@item longcall (1)
|
|
@cindex pragma, longcall
|
|
Apply the @code{longcall} attribute to all subsequent function
|
|
declarations.
|
|
|
|
@item longcall (0)
|
|
Do not apply the @code{longcall} attribute to subsequent function
|
|
declarations.
|
|
@end table
|
|
|
|
@c Describe c4x pragmas here.
|
|
@c Describe h8300 pragmas here.
|
|
@c Describe i370 pragmas here.
|
|
@c Describe i960 pragmas here.
|
|
@c Describe sh pragmas here.
|
|
@c Describe v850 pragmas here.
|
|
|
|
@node Darwin Pragmas
|
|
@subsection Darwin Pragmas
|
|
|
|
The following pragmas are available for all architectures running the
|
|
Darwin operating system. These are useful for compatibility with other
|
|
Mac OS compilers.
|
|
|
|
@table @code
|
|
@item mark @var{tokens}@dots{}
|
|
@cindex pragma, mark
|
|
This pragma is accepted, but has no effect.
|
|
|
|
@item options align=@var{alignment}
|
|
@cindex pragma, options align
|
|
This pragma sets the alignment of fields in structures. The values of
|
|
@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
|
|
@code{power}, to emulate PowerPC alignment. Uses of this pragma nest
|
|
properly; to restore the previous setting, use @code{reset} for the
|
|
@var{alignment}.
|
|
|
|
@item segment @var{tokens}@dots{}
|
|
@cindex pragma, segment
|
|
This pragma is accepted, but has no effect.
|
|
|
|
@item unused (@var{var} [, @var{var}]@dots{})
|
|
@cindex pragma, unused
|
|
This pragma declares variables to be possibly unused. GCC will not
|
|
produce warnings for the listed variables. The effect is similar to
|
|
that of the @code{unused} attribute, except that this pragma may appear
|
|
anywhere within the variables' scopes.
|
|
@end table
|
|
|
|
@node Solaris Pragmas
|
|
@subsection Solaris Pragmas
|
|
|
|
For compatibility with the SunPRO compiler, the following pragma
|
|
is supported.
|
|
|
|
@table @code
|
|
@item redefine_extname @var{oldname} @var{newname}
|
|
@cindex pragma, redefine_extname
|
|
|
|
This pragma gives the C function @var{oldname} the assembler label
|
|
@var{newname}. The pragma must appear before the function declaration.
|
|
This pragma is equivalent to the asm labels extension (@pxref{Asm
|
|
Labels}). The preprocessor defines @code{__PRAGMA_REDEFINE_EXTNAME}
|
|
if the pragma is available.
|
|
@end table
|
|
|
|
@node Tru64 Pragmas
|
|
@subsection Tru64 Pragmas
|
|
|
|
For compatibility with the Compaq C compiler, the following pragma
|
|
is supported.
|
|
|
|
@table @code
|
|
@item extern_prefix @var{string}
|
|
@cindex pragma, extern_prefix
|
|
|
|
This pragma renames all subsequent function and variable declarations
|
|
such that @var{string} is prepended to the name. This effect may be
|
|
terminated by using another @code{extern_prefix} pragma with the
|
|
empty string.
|
|
|
|
This pragma is similar in intent to to the asm labels extension
|
|
(@pxref{Asm Labels}) in that the system programmer wants to change
|
|
the assembly-level ABI without changing the source-level API. The
|
|
preprocessor defines @code{__PRAGMA_EXTERN_PREFIX} if the pragma is
|
|
available.
|
|
@end table
|
|
|
|
@node Unnamed Fields
|
|
@section Unnamed struct/union fields within structs/unions.
|
|
@cindex struct
|
|
@cindex union
|
|
|
|
For compatibility with other compilers, GCC allows you to define
|
|
a structure or union that contains, as fields, structures and unions
|
|
without names. For example:
|
|
|
|
@example
|
|
struct @{
|
|
int a;
|
|
union @{
|
|
int b;
|
|
float c;
|
|
@};
|
|
int d;
|
|
@} foo;
|
|
@end example
|
|
|
|
In this example, the user would be able to access members of the unnamed
|
|
union with code like @samp{foo.b}. Note that only unnamed structs and
|
|
unions are allowed, you may not have, for example, an unnamed
|
|
@code{int}.
|
|
|
|
You must never create such structures that cause ambiguous field definitions.
|
|
For example, this structure:
|
|
|
|
@example
|
|
struct @{
|
|
int a;
|
|
struct @{
|
|
int a;
|
|
@};
|
|
@} foo;
|
|
@end example
|
|
|
|
It is ambiguous which @code{a} is being referred to with @samp{foo.a}.
|
|
Such constructs are not supported and must be avoided. In the future,
|
|
such constructs may be detected and treated as compilation errors.
|
|
|
|
@node Thread-Local
|
|
@section Thread-Local Storage
|
|
@cindex Thread-Local Storage
|
|
@cindex @acronym{TLS}
|
|
@cindex __thread
|
|
|
|
Thread-local storage (@acronym{TLS}) is a mechanism by which variables
|
|
are allocated such that there is one instance of the variable per extant
|
|
thread. The run-time model GCC uses to implement this originates
|
|
in the IA-64 processor-specific ABI, but has since been migrated
|
|
to other processors as well. It requires significant support from
|
|
the linker (@command{ld}), dynamic linker (@command{ld.so}), and
|
|
system libraries (@file{libc.so} and @file{libpthread.so}), so it
|
|
is not available everywhere.
|
|
|
|
At the user level, the extension is visible with a new storage
|
|
class keyword: @code{__thread}. For example:
|
|
|
|
@example
|
|
__thread int i;
|
|
extern __thread struct state s;
|
|
static __thread char *p;
|
|
@end example
|
|
|
|
The @code{__thread} specifier may be used alone, with the @code{extern}
|
|
or @code{static} specifiers, but with no other storage class specifier.
|
|
When used with @code{extern} or @code{static}, @code{__thread} must appear
|
|
immediately after the other storage class specifier.
|
|
|
|
The @code{__thread} specifier may be applied to any global, file-scoped
|
|
static, function-scoped static, or static data member of a class. It may
|
|
not be applied to block-scoped automatic or non-static data member.
|
|
|
|
When the address-of operator is applied to a thread-local variable, it is
|
|
evaluated at run-time and returns the address of the current thread's
|
|
instance of that variable. An address so obtained may be used by any
|
|
thread. When a thread terminates, any pointers to thread-local variables
|
|
in that thread become invalid.
|
|
|
|
No static initialization may refer to the address of a thread-local variable.
|
|
|
|
In C++, if an initializer is present for a thread-local variable, it must
|
|
be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
|
|
standard.
|
|
|
|
See @uref{http://people.redhat.com/drepper/tls.pdf,
|
|
ELF Handling For Thread-Local Storage} for a detailed explanation of
|
|
the four thread-local storage addressing models, and how the run-time
|
|
is expected to function.
|
|
|
|
@menu
|
|
* C99 Thread-Local Edits::
|
|
* C++98 Thread-Local Edits::
|
|
@end menu
|
|
|
|
@node C99 Thread-Local Edits
|
|
@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
|
|
|
|
The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
|
|
that document the exact semantics of the language extension.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@cite{5.1.2 Execution environments}
|
|
|
|
Add new text after paragraph 1
|
|
|
|
@quotation
|
|
Within either execution environment, a @dfn{thread} is a flow of
|
|
control within a program. It is implementation defined whether
|
|
or not there may be more than one thread associated with a program.
|
|
It is implementation defined how threads beyond the first are
|
|
created, the name and type of the function called at thread
|
|
startup, and how threads may be terminated. However, objects
|
|
with thread storage duration shall be initialized before thread
|
|
startup.
|
|
@end quotation
|
|
|
|
@item
|
|
@cite{6.2.4 Storage durations of objects}
|
|
|
|
Add new text before paragraph 3
|
|
|
|
@quotation
|
|
An object whose identifier is declared with the storage-class
|
|
specifier @w{@code{__thread}} has @dfn{thread storage duration}.
|
|
Its lifetime is the entire execution of the thread, and its
|
|
stored value is initialized only once, prior to thread startup.
|
|
@end quotation
|
|
|
|
@item
|
|
@cite{6.4.1 Keywords}
|
|
|
|
Add @code{__thread}.
|
|
|
|
@item
|
|
@cite{6.7.1 Storage-class specifiers}
|
|
|
|
Add @code{__thread} to the list of storage class specifiers in
|
|
paragraph 1.
|
|
|
|
Change paragraph 2 to
|
|
|
|
@quotation
|
|
With the exception of @code{__thread}, at most one storage-class
|
|
specifier may be given [@dots{}]. The @code{__thread} specifier may
|
|
be used alone, or immediately following @code{extern} or
|
|
@code{static}.
|
|
@end quotation
|
|
|
|
Add new text after paragraph 6
|
|
|
|
@quotation
|
|
The declaration of an identifier for a variable that has
|
|
block scope that specifies @code{__thread} shall also
|
|
specify either @code{extern} or @code{static}.
|
|
|
|
The @code{__thread} specifier shall be used only with
|
|
variables.
|
|
@end quotation
|
|
@end itemize
|
|
|
|
@node C++98 Thread-Local Edits
|
|
@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
|
|
|
|
The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
|
|
that document the exact semantics of the language extension.
|
|
|
|
@itemize @bullet
|
|
@b{[intro.execution]}
|
|
|
|
New text after paragraph 4
|
|
|
|
@quotation
|
|
A @dfn{thread} is a flow of control within the abstract machine.
|
|
It is implementation defined whether or not there may be more than
|
|
one thread.
|
|
@end quotation
|
|
|
|
New text after paragraph 7
|
|
|
|
@quotation
|
|
It is unspecified whether additional action must be taken to
|
|
ensure when and whether side effects are visible to other threads.
|
|
@end quotation
|
|
|
|
@item
|
|
@b{[lex.key]}
|
|
|
|
Add @code{__thread}.
|
|
|
|
@item
|
|
@b{[basic.start.main]}
|
|
|
|
Add after paragraph 5
|
|
|
|
@quotation
|
|
The thread that begins execution at the @code{main} function is called
|
|
the @dfn{main thread}. It is implementation defined how functions
|
|
beginning threads other than the main thread are designated or typed.
|
|
A function so designated, as well as the @code{main} function, is called
|
|
a @dfn{thread startup function}. It is implementation defined what
|
|
happens if a thread startup function returns. It is implementation
|
|
defined what happens to other threads when any thread calls @code{exit}.
|
|
@end quotation
|
|
|
|
@item
|
|
@b{[basic.start.init]}
|
|
|
|
Add after paragraph 4
|
|
|
|
@quotation
|
|
The storage for an object of thread storage duration shall be
|
|
statically initialized before the first statement of the thread startup
|
|
function. An object of thread storage duration shall not require
|
|
dynamic initialization.
|
|
@end quotation
|
|
|
|
@item
|
|
@b{[basic.start.term]}
|
|
|
|
Add after paragraph 3
|
|
|
|
@quotation
|
|
The type of an object with thread storage duration shall not have a
|
|
non-trivial destructor, nor shall it be an array type whose elements
|
|
(directly or indirectly) have non-trivial destructors.
|
|
@end quotation
|
|
|
|
@item
|
|
@b{[basic.stc]}
|
|
|
|
Add ``thread storage duration'' to the list in paragraph 1.
|
|
|
|
Change paragraph 2
|
|
|
|
@quotation
|
|
Thread, static, and automatic storage durations are associated with
|
|
objects introduced by declarations [@dots{}].
|
|
@end quotation
|
|
|
|
Add @code{__thread} to the list of specifiers in paragraph 3.
|
|
|
|
@item
|
|
@b{[basic.stc.thread]}
|
|
|
|
New section before @b{[basic.stc.static]}
|
|
|
|
@quotation
|
|
The keyword @code{__thread} applied to a non-local object gives the
|
|
object thread storage duration.
|
|
|
|
A local variable or class data member declared both @code{static}
|
|
and @code{__thread} gives the variable or member thread storage
|
|
duration.
|
|
@end quotation
|
|
|
|
@item
|
|
@b{[basic.stc.static]}
|
|
|
|
Change paragraph 1
|
|
|
|
@quotation
|
|
All objects which have neither thread storage duration, dynamic
|
|
storage duration nor are local [@dots{}].
|
|
@end quotation
|
|
|
|
@item
|
|
@b{[dcl.stc]}
|
|
|
|
Add @code{__thread} to the list in paragraph 1.
|
|
|
|
Change paragraph 1
|
|
|
|
@quotation
|
|
With the exception of @code{__thread}, at most one
|
|
@var{storage-class-specifier} shall appear in a given
|
|
@var{decl-specifier-seq}. The @code{__thread} specifier may
|
|
be used alone, or immediately following the @code{extern} or
|
|
@code{static} specifiers. [@dots{}]
|
|
@end quotation
|
|
|
|
Add after paragraph 5
|
|
|
|
@quotation
|
|
The @code{__thread} specifier can be applied only to the names of objects
|
|
and to anonymous unions.
|
|
@end quotation
|
|
|
|
@item
|
|
@b{[class.mem]}
|
|
|
|
Add after paragraph 6
|
|
|
|
@quotation
|
|
Non-@code{static} members shall not be @code{__thread}.
|
|
@end quotation
|
|
@end itemize
|
|
|
|
@node C++ Extensions
|
|
@chapter Extensions to the C++ Language
|
|
@cindex extensions, C++ language
|
|
@cindex C++ language extensions
|
|
|
|
The GNU compiler provides these extensions to the C++ language (and you
|
|
can also use most of the C language extensions in your C++ programs). If you
|
|
want to write code that checks whether these features are available, you can
|
|
test for the GNU compiler the same way as for C programs: check for a
|
|
predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
|
|
test specifically for GNU C++ (@pxref{Standard Predefined,,Standard
|
|
Predefined Macros,cpp.info,The C Preprocessor}).
|
|
|
|
@menu
|
|
* Min and Max:: C++ Minimum and maximum operators.
|
|
* Volatiles:: What constitutes an access to a volatile object.
|
|
* Restricted Pointers:: C99 restricted pointers and references.
|
|
* Vague Linkage:: Where G++ puts inlines, vtables and such.
|
|
* 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
|
|
each needed template instantiation is emitted.
|
|
* Bound member functions:: You can extract a function pointer to the
|
|
method denoted by a @samp{->*} or @samp{.*} expression.
|
|
* C++ Attributes:: Variable, function, and type attributes for C++ only.
|
|
* Java Exceptions:: Tweaking exception handling to work with Java.
|
|
* Deprecated Features:: Things might disappear from g++.
|
|
* Backwards Compatibility:: Compatibilities with earlier definitions of C++.
|
|
@end menu
|
|
|
|
@node Min and Max
|
|
@section Minimum and Maximum Operators in C++
|
|
|
|
It is very convenient to have operators which return the ``minimum'' or the
|
|
``maximum'' of two arguments. In GNU C++ (but not in GNU C),
|
|
|
|
@table @code
|
|
@item @var{a} <? @var{b}
|
|
@findex <?
|
|
@cindex minimum operator
|
|
is the @dfn{minimum}, returning the smaller of the numeric values
|
|
@var{a} and @var{b};
|
|
|
|
@item @var{a} >? @var{b}
|
|
@findex >?
|
|
@cindex maximum operator
|
|
is the @dfn{maximum}, returning the larger of the numeric values @var{a}
|
|
and @var{b}.
|
|
@end table
|
|
|
|
These operations are not primitive in ordinary C++, since you can
|
|
use a macro to return the minimum of two things in C++, as in the
|
|
following example.
|
|
|
|
@example
|
|
#define MIN(X,Y) ((X) < (Y) ? : (X) : (Y))
|
|
@end example
|
|
|
|
@noindent
|
|
You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to
|
|
the minimum value of variables @var{i} and @var{j}.
|
|
|
|
However, side effects in @code{X} or @code{Y} may cause unintended
|
|
behavior. For example, @code{MIN (i++, j++)} will fail, incrementing
|
|
the smaller counter twice. The GNU C @code{typeof} extension allows you
|
|
to write safe macros that avoid this kind of problem (@pxref{Typeof}).
|
|
However, writing @code{MIN} and @code{MAX} as macros also forces you to
|
|
use function-call notation for a fundamental arithmetic operation.
|
|
Using GNU C++ extensions, you can write @w{@samp{int min = i <? j;}}
|
|
instead.
|
|
|
|
Since @code{<?} and @code{>?} are built into the compiler, they properly
|
|
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
|
|
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 accesses 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 = @var{somevalue};
|
|
volatile int *src = @var{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 = @var{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 = @var{somevalue};
|
|
volatile T *ptr2 = @var{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 C99 feature of restricted pointers,
|
|
specified with the @code{__restrict__}, or @code{__restrict} type
|
|
qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
|
|
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)
|
|
@{
|
|
/* @r{@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__
|
|
@{
|
|
/* @r{@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 Vague Linkage
|
|
@section Vague Linkage
|
|
@cindex vague linkage
|
|
|
|
There are several constructs in C++ which require space in the object
|
|
file but are not clearly tied to a single translation unit. We say that
|
|
these constructs have ``vague linkage''. Typically such constructs are
|
|
emitted wherever they are needed, though sometimes we can be more
|
|
clever.
|
|
|
|
@table @asis
|
|
@item Inline Functions
|
|
Inline functions are typically defined in a header file which can be
|
|
included in many different compilations. Hopefully they can usually be
|
|
inlined, but sometimes an out-of-line copy is necessary, if the address
|
|
of the function is taken or if inlining fails. In general, we emit an
|
|
out-of-line copy in all translation units where one is needed. As an
|
|
exception, we only emit inline virtual functions with the vtable, since
|
|
it will always require a copy.
|
|
|
|
Local static variables and string constants used in an inline function
|
|
are also considered to have vague linkage, since they must be shared
|
|
between all inlined and out-of-line instances of the function.
|
|
|
|
@item VTables
|
|
@cindex vtable
|
|
C++ virtual functions are implemented in most compilers using a lookup
|
|
table, known as a vtable. The vtable contains pointers to the virtual
|
|
functions provided by a class, and each object of the class contains a
|
|
pointer to its vtable (or vtables, in some multiple-inheritance
|
|
situations). If the class declares any non-inline, non-pure virtual
|
|
functions, the first one is chosen as the ``key method'' for the class,
|
|
and the vtable is only emitted in the translation unit where the key
|
|
method is defined.
|
|
|
|
@emph{Note:} If the chosen key method is later defined as inline, the
|
|
vtable will still be emitted in every translation unit which defines it.
|
|
Make sure that any inline virtuals are declared inline in the class
|
|
body, even if they are not defined there.
|
|
|
|
@item type_info objects
|
|
@cindex type_info
|
|
@cindex RTTI
|
|
C++ requires information about types to be written out in order to
|
|
implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
|
|
For polymorphic classes (classes with virtual functions), the type_info
|
|
object is written out along with the vtable so that @samp{dynamic_cast}
|
|
can determine the dynamic type of a class object at runtime. For all
|
|
other types, we write out the type_info object when it is used: when
|
|
applying @samp{typeid} to an expression, throwing an object, or
|
|
referring to a type in a catch clause or exception specification.
|
|
|
|
@item Template Instantiations
|
|
Most everything in this section also applies to template instantiations,
|
|
but there are other options as well.
|
|
@xref{Template Instantiation,,Where's the Template?}.
|
|
|
|
@end table
|
|
|
|
When used with GNU ld version 2.8 or later on an ELF system such as
|
|
Linux/GNU or Solaris 2, or on Microsoft Windows, duplicate copies of
|
|
these constructs will be discarded at link time. This is known as
|
|
COMDAT support.
|
|
|
|
On targets that don't support COMDAT, but do support weak symbols, GCC
|
|
will use them. This way one copy will override all the others, but
|
|
the unused copies will still take up space in the executable.
|
|
|
|
For targets which do not support either COMDAT or weak symbols,
|
|
most entities with vague linkage will be emitted as local symbols to
|
|
avoid duplicate definition errors from the linker. This will not happen
|
|
for local statics in inlines, however, as having multiple copies will
|
|
almost certainly break things.
|
|
|
|
@xref{C++ Interface,,Declarations and Definitions in One Header}, for
|
|
another way to control placement of these constructs.
|
|
|
|
@node C++ Interface
|
|
@section Declarations and Definitions in One Header
|
|
|
|
@cindex interface and implementation headers, C++
|
|
@cindex C++ interface and implementation headers
|
|
C++ object definitions can be quite complex. In principle, your source
|
|
code will need two kinds of things for each object that you use across
|
|
more than one source file. First, you need an @dfn{interface}
|
|
specification, describing its structure with type declarations and
|
|
function prototypes. Second, you need the @dfn{implementation} itself.
|
|
It can be tedious to maintain a separate interface description in a
|
|
header file, in parallel to the actual implementation. It is also
|
|
dangerous, since separate interface and implementation definitions may
|
|
not remain parallel.
|
|
|
|
@cindex pragmas, interface and implementation
|
|
With GNU C++, you can use a single header file for both purposes.
|
|
|
|
@quotation
|
|
@emph{Warning:} The mechanism to specify this is in transition. For the
|
|
nonce, you must use one of two @code{#pragma} commands; in a future
|
|
release of GNU C++, an alternative mechanism will make these
|
|
@code{#pragma} commands unnecessary.
|
|
@end quotation
|
|
|
|
The header file contains the full definitions, but is marked with
|
|
@samp{#pragma interface} in the source code. This allows the compiler
|
|
to use the header file only as an interface specification when ordinary
|
|
source files incorporate it with @code{#include}. In the single source
|
|
file where the full implementation belongs, you can use either a naming
|
|
convention or @samp{#pragma implementation} to indicate this alternate
|
|
use of the header file.
|
|
|
|
@table @code
|
|
@item #pragma interface
|
|
@itemx #pragma interface "@var{subdir}/@var{objects}.h"
|
|
@kindex #pragma interface
|
|
Use this directive in @emph{header files} that define object classes, to save
|
|
space in most of the object files that use those classes. Normally,
|
|
local copies of certain information (backup copies of inline member
|
|
functions, debugging information, and the internal tables that implement
|
|
virtual functions) must be kept in each object file that includes class
|
|
definitions. You can use this pragma to avoid such duplication. When a
|
|
header file containing @samp{#pragma interface} is included in a
|
|
compilation, this auxiliary information will not be generated (unless
|
|
the main input source file itself uses @samp{#pragma implementation}).
|
|
Instead, the object files will contain references to be resolved at link
|
|
time.
|
|
|
|
The second form of this directive is useful for the case where you have
|
|
multiple headers with the same name in different directories. If you
|
|
use this form, you must specify the same string to @samp{#pragma
|
|
implementation}.
|
|
|
|
@item #pragma implementation
|
|
@itemx #pragma implementation "@var{objects}.h"
|
|
@kindex #pragma implementation
|
|
Use this pragma in a @emph{main input file}, when you want full output from
|
|
included header files to be generated (and made globally visible). The
|
|
included header file, in turn, should use @samp{#pragma interface}.
|
|
Backup copies of inline member functions, debugging information, and the
|
|
internal tables used to implement virtual functions are all generated in
|
|
implementation files.
|
|
|
|
@cindex implied @code{#pragma implementation}
|
|
@cindex @code{#pragma implementation}, implied
|
|
@cindex naming convention, implementation headers
|
|
If you use @samp{#pragma implementation} with no argument, it applies to
|
|
an include file with the same basename@footnote{A file's @dfn{basename}
|
|
was the name stripped of all leading path information and of trailing
|
|
suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
|
|
file. For example, in @file{allclass.cc}, giving just
|
|
@samp{#pragma implementation}
|
|
by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
|
|
|
|
In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as
|
|
an implementation file whenever you would include it from
|
|
@file{allclass.cc} even if you never specified @samp{#pragma
|
|
implementation}. This was deemed to be more trouble than it was worth,
|
|
however, and disabled.
|
|
|
|
If you use an explicit @samp{#pragma implementation}, it must appear in
|
|
your source file @emph{before} you include the affected header files.
|
|
|
|
Use the string argument if you want a single implementation file to
|
|
include code from multiple header files. (You must also use
|
|
@samp{#include} to include the header file; @samp{#pragma
|
|
implementation} only specifies how to use the file---it doesn't actually
|
|
include it.)
|
|
|
|
There is no way to split up the contents of a single header file into
|
|
multiple implementation files.
|
|
@end table
|
|
|
|
@cindex inlining and C++ pragmas
|
|
@cindex C++ pragmas, effect on inlining
|
|
@cindex pragmas in C++, effect on inlining
|
|
@samp{#pragma implementation} and @samp{#pragma interface} also have an
|
|
effect on function inlining.
|
|
|
|
If you define a class in a header file marked with @samp{#pragma
|
|
interface}, the effect on a function defined in that class is similar to
|
|
an explicit @code{extern} declaration---the compiler emits no code at
|
|
all to define an independent version of the function. Its definition
|
|
is used only for inlining with its callers.
|
|
|
|
@opindex fno-implement-inlines
|
|
Conversely, when you include the same header file in a main source file
|
|
that declares it as @samp{#pragma implementation}, the compiler emits
|
|
code for the function itself; this defines a version of the function
|
|
that can be found via pointers (or by callers compiled without
|
|
inlining). If all calls to the function can be inlined, you can avoid
|
|
emitting the function by compiling with @option{-fno-implement-inlines}.
|
|
If any calls were not inlined, you will get linker errors.
|
|
|
|
@node Template Instantiation
|
|
@section Where's the Template?
|
|
@cindex template instantiation
|
|
|
|
C++ templates are the first language feature to require more
|
|
intelligence from the environment than one usually finds on a UNIX
|
|
system. Somehow the compiler and linker have to make sure that each
|
|
template instance occurs exactly once in the executable if it is needed,
|
|
and not at all otherwise. There are two basic approaches to this
|
|
problem, which I will refer to as the Borland model and the Cfront model.
|
|
|
|
@table @asis
|
|
@item Borland model
|
|
Borland C++ solved the template instantiation problem by adding the code
|
|
equivalent of common blocks to their linker; the compiler emits template
|
|
instances in each translation unit that uses them, and the linker
|
|
collapses them together. The advantage of this model is that the linker
|
|
only has to consider the object files themselves; there is no external
|
|
complexity to worry about. This disadvantage is that compilation time
|
|
is increased because the template code is being compiled repeatedly.
|
|
Code written for this model tends to include definitions of all
|
|
templates in the header file, since they must be seen to be
|
|
instantiated.
|
|
|
|
@item Cfront model
|
|
The AT&T C++ translator, Cfront, solved the template instantiation
|
|
problem by creating the notion of a template repository, an
|
|
automatically maintained place where template instances are stored. A
|
|
more modern version of the repository works as follows: As individual
|
|
object files are built, the compiler places any template definitions and
|
|
instantiations encountered in the repository. At link time, the link
|
|
wrapper adds in the objects in the repository and compiles any needed
|
|
instances that were not previously emitted. The advantages of this
|
|
model are more optimal compilation speed and the ability to use the
|
|
system linker; to implement the Borland model a compiler vendor also
|
|
needs to replace the linker. The disadvantages are vastly increased
|
|
complexity, and thus potential for error; for some code this can be
|
|
just as transparent, but in practice it can been very difficult to build
|
|
multiple programs in one directory and one program in multiple
|
|
directories. Code written for this model tends to separate definitions
|
|
of non-inline member templates into a separate file, which should be
|
|
compiled separately.
|
|
@end table
|
|
|
|
When used with GNU ld version 2.8 or later on an ELF system such as
|
|
Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the
|
|
Borland model. On other systems, g++ implements neither automatic
|
|
model.
|
|
|
|
A future version of g++ will support a hybrid model whereby the compiler
|
|
will emit any instantiations for which the template definition is
|
|
included in the compile, and store template definitions and
|
|
instantiation context information into the object file for the rest.
|
|
The link wrapper will extract that information as necessary and invoke
|
|
the compiler to produce the remaining instantiations. The linker will
|
|
then combine duplicate instantiations.
|
|
|
|
In the mean time, you have the following options for dealing with
|
|
template instantiations:
|
|
|
|
@enumerate
|
|
@item
|
|
@opindex frepo
|
|
Compile your template-using code with @option{-frepo}. The compiler will
|
|
generate files with the extension @samp{.rpo} listing all of the
|
|
template instantiations used in the corresponding object files which
|
|
could be instantiated there; the link wrapper, @samp{collect2}, will
|
|
then update the @samp{.rpo} files to tell the compiler where to place
|
|
those instantiations and rebuild any affected object files. The
|
|
link-time overhead is negligible after the first pass, as the compiler
|
|
will continue to place the instantiations in the same files.
|
|
|
|
This is your best option for application code written for the Borland
|
|
model, as it will just work. Code written for the Cfront model will
|
|
need to be modified so that the template definitions are available at
|
|
one or more points of instantiation; usually this is as simple as adding
|
|
@code{#include <tmethods.cc>} to the end of each template header.
|
|
|
|
For library code, if you want the library to provide all of the template
|
|
instantiations it needs, just try to link all of its object files
|
|
together; the link will fail, but cause the instantiations to be
|
|
generated as a side effect. Be warned, however, that this may cause
|
|
conflicts if multiple libraries try to provide the same instantiations.
|
|
For greater control, use explicit instantiation as described in the next
|
|
option.
|
|
|
|
@item
|
|
@opindex fno-implicit-templates
|
|
Compile your code with @option{-fno-implicit-templates} to disable the
|
|
implicit generation of template instances, and explicitly instantiate
|
|
all the ones you use. This approach requires more knowledge of exactly
|
|
which instances you need than do the others, but it's less
|
|
mysterious and allows greater control. You can scatter the explicit
|
|
instantiations throughout your program, perhaps putting them in the
|
|
translation units where the instances are used or the translation units
|
|
that define the templates themselves; you can put all of the explicit
|
|
instantiations you need into one big file; or you can create small files
|
|
like
|
|
|
|
@example
|
|
#include "Foo.h"
|
|
#include "Foo.cc"
|
|
|
|
template class Foo<int>;
|
|
template ostream& operator <<
|
|
(ostream&, const Foo<int>&);
|
|
@end example
|
|
|
|
for each of the instances you need, and create a template instantiation
|
|
library from those.
|
|
|
|
If you are using Cfront-model code, you can probably get away with not
|
|
using @option{-fno-implicit-templates} when compiling files that don't
|
|
@samp{#include} the member template definitions.
|
|
|
|
If you use one big file to do the instantiations, you may want to
|
|
compile it without @option{-fno-implicit-templates} so you get all of the
|
|
instances required by your explicit instantiations (but not by any
|
|
other files) without having to specify them as well.
|
|
|
|
g++ has extended the template instantiation syntax given in the ISO
|
|
standard to allow forward declaration of explicit instantiations
|
|
(with @code{extern}), instantiation of the compiler support data for a
|
|
template class (i.e.@: the vtable) without instantiating any of its
|
|
members (with @code{inline}), and instantiation of only the static data
|
|
members of a template class, without the support data or member
|
|
functions (with (@code{static}):
|
|
|
|
@example
|
|
extern template int max (int, int);
|
|
inline template class Foo<int>;
|
|
static template class Foo<int>;
|
|
@end example
|
|
|
|
@item
|
|
Do nothing. Pretend g++ does implement automatic instantiation
|
|
management. Code written for the Borland model will work fine, but
|
|
each translation unit will contain instances of each of the templates it
|
|
uses. In a large program, this can lead to an unacceptable amount of code
|
|
duplication.
|
|
|
|
@xref{C++ Interface,,Declarations and Definitions in One Header}, for
|
|
more discussion of these pragmas.
|
|
@end enumerate
|
|
|
|
@node Bound member functions
|
|
@section Extracting the function pointer from a bound pointer to member function
|
|
@cindex pmf
|
|
@cindex pointer to member function
|
|
@cindex bound pointer to member function
|
|
|
|
In C++, pointer to member functions (PMFs) are implemented using a wide
|
|
pointer of sorts to handle all the possible call mechanisms; the PMF
|
|
needs to store information about how to adjust the @samp{this} pointer,
|
|
and if the function pointed to is virtual, where to find the vtable, and
|
|
where in the vtable to look for the member function. If you are using
|
|
PMFs in an inner loop, you should really reconsider that decision. If
|
|
that is not an option, you can extract the pointer to the function that
|
|
would be called for a given object/PMF pair and call it directly inside
|
|
the inner loop, to save a bit of time.
|
|
|
|
Note that you will still be paying the penalty for the call through a
|
|
function pointer; on most modern architectures, such a call defeats the
|
|
branch prediction features of the CPU@. This is also true of normal
|
|
virtual function calls.
|
|
|
|
The syntax for this extension is
|
|
|
|
@example
|
|
extern A a;
|
|
extern int (A::*fp)();
|
|
typedef int (*fptr)(A *);
|
|
|
|
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
|
|
|
|
@opindex Wno-pmf-conversions
|
|
You must specify @option{-Wno-pmf-conversions} to use this extension.
|
|
|
|
@node C++ Attributes
|
|
@section C++-Specific Variable, Function, and Type Attributes
|
|
|
|
Some attributes only make sense for C++ programs.
|
|
|
|
@table @code
|
|
@item init_priority (@var{priority})
|
|
@cindex init_priority attribute
|
|
|
|
|
|
In Standard C++, objects defined at namespace scope are guaranteed to be
|
|
initialized in an order in strict accordance with that of their definitions
|
|
@emph{in a given translation unit}. No guarantee is made for initializations
|
|
across translation units. However, GNU C++ allows users to control the
|
|
order of initialization of objects defined at namespace scope with the
|
|
@code{init_priority} attribute by specifying a relative @var{priority},
|
|
a constant integral expression currently bounded between 101 and 65535
|
|
inclusive. Lower numbers indicate a higher priority.
|
|
|
|
In the following example, @code{A} would normally be created before
|
|
@code{B}, but the @code{init_priority} attribute has reversed that order:
|
|
|
|
@smallexample
|
|
Some_Class A __attribute__ ((init_priority (2000)));
|
|
Some_Class B __attribute__ ((init_priority (543)));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Note that the particular values of @var{priority} do not matter; only their
|
|
relative ordering.
|
|
|
|
@item java_interface
|
|
@cindex java_interface attribute
|
|
|
|
This type attribute informs C++ that the class is a Java interface. It may
|
|
only be applied to classes declared within an @code{extern "Java"} block.
|
|
Calls to methods declared in this interface will be dispatched using GCJ's
|
|
interface table mechanism, instead of regular virtual table dispatch.
|
|
|
|
@end table
|
|
|
|
@node Java Exceptions
|
|
@section Java Exceptions
|
|
|
|
The Java language uses a slightly different exception handling model
|
|
from C++. Normally, GNU C++ will automatically detect when you are
|
|
writing C++ code that uses Java exceptions, and handle them
|
|
appropriately. However, if C++ code only needs to execute destructors
|
|
when Java exceptions are thrown through it, GCC will guess incorrectly.
|
|
Sample problematic code is:
|
|
|
|
@smallexample
|
|
struct S @{ ~S(); @};
|
|
extern void bar(); // is written in Java, and may throw exceptions
|
|
void foo()
|
|
@{
|
|
S s;
|
|
bar();
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The usual effect of an incorrect guess is a link failure, complaining of
|
|
a missing routine called @samp{__gxx_personality_v0}.
|
|
|
|
You can inform the compiler that Java exceptions are to be used in a
|
|
translation unit, irrespective of what it might think, by writing
|
|
@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This
|
|
@samp{#pragma} must appear before any functions that throw or catch
|
|
exceptions, or run destructors when exceptions are thrown through them.
|
|
|
|
You cannot mix Java and C++ exceptions in the same translation unit. It
|
|
is believed to be safe to throw a C++ exception from one file through
|
|
another file compiled for the Java exception model, or vice versa, but
|
|
there may be bugs in this area.
|
|
|
|
@node Deprecated Features
|
|
@section Deprecated Features
|
|
|
|
In the past, the GNU C++ compiler was extended to experiment with new
|
|
features, at a time when the C++ language was still evolving. Now that
|
|
the C++ standard is complete, some of those features are superseded by
|
|
superior alternatives. Using the old features might cause a warning in
|
|
some cases that the feature will be dropped in the future. In other
|
|
cases, the feature might be gone already.
|
|
|
|
While the list below is not exhaustive, it documents some of the options
|
|
that are now deprecated:
|
|
|
|
@table @code
|
|
@item -fexternal-templates
|
|
@itemx -falt-external-templates
|
|
These are two of the many ways for g++ to implement template
|
|
instantiation. @xref{Template Instantiation}. The C++ standard clearly
|
|
defines how template definitions have to be organized across
|
|
implementation units. g++ has an implicit instantiation mechanism that
|
|
should work just fine for standard-conforming code.
|
|
|
|
@item -fstrict-prototype
|
|
@itemx -fno-strict-prototype
|
|
Previously it was possible to use an empty prototype parameter list to
|
|
indicate an unspecified number of parameters (like C), rather than no
|
|
parameters, as C++ demands. This feature has been removed, except where
|
|
it is required for backwards compatibility @xref{Backwards Compatibility}.
|
|
@end table
|
|
|
|
The named return value extension has been deprecated, and is now
|
|
removed from g++.
|
|
|
|
The use of initializer lists with new expressions has been deprecated,
|
|
and is now removed from g++.
|
|
|
|
Floating and complex non-type template parameters have been deprecated,
|
|
and are now removed from g++.
|
|
|
|
The implicit typename extension has been deprecated and will be removed
|
|
from g++ at some point. In some cases g++ determines that a dependent
|
|
type such as @code{TPL<T>::X} is a type without needing a
|
|
@code{typename} keyword, contrary to the standard.
|
|
|
|
@node Backwards Compatibility
|
|
@section Backwards Compatibility
|
|
@cindex Backwards Compatibility
|
|
@cindex ARM [Annotated C++ Reference Manual]
|
|
|
|
Now that there is a definitive ISO standard C++, G++ has a specification
|
|
to adhere to. The C++ language evolved over time, and features that
|
|
used to be acceptable in previous drafts of the standard, such as the ARM
|
|
[Annotated C++ Reference Manual], are no longer accepted. In order to allow
|
|
compilation of C++ written to such drafts, G++ contains some backwards
|
|
compatibilities. @emph{All such backwards compatibility features are
|
|
liable to disappear in future versions of G++.} They should be considered
|
|
deprecated @xref{Deprecated Features}.
|
|
|
|
@table @code
|
|
@item For scope
|
|
If a variable is declared at for scope, it used to remain in scope until
|
|
the end of the scope which contained the for statement (rather than just
|
|
within the for scope). G++ retains this, but issues a warning, if such a
|
|
variable is accessed outside the for scope.
|
|
|
|
@item Implicit C language
|
|
Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
|
|
scope to set the language. On such systems, all header files are
|
|
implicitly scoped inside a C language scope. Also, an empty prototype
|
|
@code{()} will be treated as an unspecified number of arguments, rather
|
|
than no arguments, as C++ demands.
|
|
@end table
|