diff options
Diffstat (limited to 'contrib/gcc/doc/extend.texi')
| -rw-r--r-- | contrib/gcc/doc/extend.texi | 1055 |
1 files changed, 872 insertions, 183 deletions
diff --git a/contrib/gcc/doc/extend.texi b/contrib/gcc/doc/extend.texi index 281e4ac..484a646 100644 --- a/contrib/gcc/doc/extend.texi +++ b/contrib/gcc/doc/extend.texi @@ -1,4 +1,5 @@ -@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001,2002 Free Software Foundation, Inc. +@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. @@ -35,6 +36,8 @@ along with the section number from the ISO/IEC 9899:1999 standard. @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 @@ -58,6 +61,11 @@ 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 @@ -123,6 +131,9 @@ sequence not represented in the execution character set (6.4.5).} 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).} @@ -238,10 +249,36 @@ of the same array (6.5.6).} @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 @@ -315,6 +352,8 @@ 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 @@ -328,6 +367,10 @@ directive (6.10.6).} @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 @@ -393,9 +436,9 @@ extensions, accepted by GCC in C89 mode and in C++. * 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. -* Multi-line Strings:: String literals with embedded 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. @@ -431,6 +474,7 @@ extensions, accepted by GCC in C89 mode and in C++. * 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 @@ -442,7 +486,6 @@ extensions, accepted by GCC in C89 mode and in C++. @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. @@ -549,7 +592,7 @@ __label__ @var{label}; or @example -__label__ @var{label1}, @var{label2}, @dots{}; +__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; @end example Local label declarations must come at the beginning of the statement @@ -600,7 +643,7 @@ wherever a constant of that type is valid. For example: @example void *ptr; -@dots{} +/* @r{@dots{}} */ ptr = &&foo; @end example @@ -695,9 +738,9 @@ bar (int *array, int offset, int size) int access (int *array, int index) @{ return array[index + offset]; @} int i; - @dots{} + /* @r{@dots{}} */ for (i = 0; i < size; i++) - @dots{} access (array, i) @dots{} + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ @} @end group @end example @@ -757,10 +800,10 @@ bar (int *array, int offset, int size) return array[index + offset]; @} int i; - @dots{} + /* @r{@dots{}} */ for (i = 0; i < size; i++) - @dots{} access (array, i) @dots{} - @dots{} + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ + /* @r{@dots{}} */ return 0; /* @r{Control comes here from @code{access} @@ -781,14 +824,14 @@ bar (int *array, int offset, int size) @{ __label__ failure; auto int access (int *, int); - @dots{} + /* @r{@dots{}} */ int access (int *array, int index) @{ if (index > size) goto failure; return array[index + offset]; @} - @dots{} + /* @r{@dots{}} */ @} @end example @@ -843,19 +886,6 @@ the containing function. You should specify, for @var{result}, a value returned by @code{__builtin_apply}. @end deftypefn -@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. - @node Typeof @section Referring to a Type with @code{typeof} @findex typeof @@ -906,6 +936,19 @@ arithmetic type and evaluates each of its arguments exactly once: _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}: @@ -989,6 +1032,7 @@ This will work with all versions of GCC@. @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. @@ -1181,17 +1225,14 @@ 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). None of the -supported debugging info formats has a way to represent noncontiguous -allocation like this, so GCC describes a noncontiguous complex -variable as if it were two separate variables of noncomplex type. +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. -A future version of GDB will know how to recognize such pairs and treat -them as a single variable with a complex type. - @node Hex Floats @section Hex Floats @cindex hex floats @@ -1241,7 +1282,7 @@ struct line *thisline = (struct line *) thisline->length = this_length; @end example -In ISO C89, you would have to give @code{contents} a length of 1, which +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 @@ -1260,6 +1301,12 @@ 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 @@ -1311,6 +1358,21 @@ 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 @@ -1363,7 +1425,7 @@ You can also use variable-length arrays as arguments to functions: struct entry tester (int len, char data[len][len]) @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -1378,7 +1440,7 @@ use a forward declaration in the parameter list---another GNU extension. struct entry tester (int len; char data[len][len], int len) @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -1463,29 +1525,16 @@ argument, these arguments are not macro expanded. @cindex escaped newlines @cindex newlines (escaped) -Recently, the non-traditional preprocessor has relaxed its treatment of -escaped newlines. Previously, the newline had to immediately follow a +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, including multi-line strings, 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 Multi-line Strings -@section String Literals with Embedded Newlines -@cindex multi-line string literals - -As an extension, GNU CPP permits string literals to cross multiple lines -without escaping the embedded newlines. Each embedded newline is -replaced with a single @samp{\n} character in the resulting string -literal, regardless of what form the newline took originally. - -CPP currently allows such strings in directives as well (other than the -@samp{#include} family). This is deprecated and will eventually be -removed. +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 @@ -1545,7 +1594,7 @@ Here is an example of an initializer with run-time varying elements: foo (float f, float g) @{ float beat_freqs[2] = @{ f-g, f+g @}; - @dots{} + /* @r{@dots{}} */ @} @end example @@ -1834,7 +1883,7 @@ union type is equivalent to storing in a member of the union: @example union foo u; -@dots{} +/* @r{@dots{}} */ u = (union foo) x @equiv{} u.i = x u = (union foo) y @equiv{} u.d = y @end example @@ -1843,7 +1892,7 @@ You can also use the union cast as a function argument: @example void hack (union foo); -@dots{} +/* @r{@dots{}} */ hack ((union foo) x); @end example @@ -1859,7 +1908,7 @@ C89 mode. For example, you could do: @example int i; -@dots{} +/* @r{@dots{}} */ i++; int j = i + 2; @end example @@ -1878,6 +1927,7 @@ the enclosing block. @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 @@ -1891,14 +1941,14 @@ 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{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}, and -@code{alias}. Several other attributes are defined for functions on -particular target systems. Other attributes, including @code{section} -are supported for variables declarations (@pxref{Variable Attributes}) -and for types (@pxref{Type Attributes}). +@code{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 @@ -1921,9 +1971,9 @@ their own functions that never return. You can declare them void fatal () __attribute__ ((noreturn)); void -fatal (@dots{}) +fatal (/* @r{@dots{}} */) @{ - @dots{} /* @r{Print error message.} */ @dots{} + /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ exit (1); @} @end group @@ -2015,6 +2065,14 @@ extern const intfn square; 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 @@ -2110,6 +2168,35 @@ 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 @@ -2208,7 +2295,7 @@ 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 () @{ /* do something */; @} +void __f () @{ /* @r{Do something.} */; @} void f () __attribute__ ((weak, alias ("__f"))); @end smallexample @@ -2217,7 +2304,60 @@ 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, @@ -2225,6 +2365,16 @@ 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 @@ -2245,12 +2395,17 @@ useful to override the effects of the @option{-mrtd} switch. The PowerPC compiler for Windows NT currently ignores the @code{cdecl} attribute. -@item longcall +@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 the function via a pointer, so that functions -which reside further than 64 megabytes (67,108,864 bytes) from the -current location can be called. +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 @@ -2372,9 +2527,9 @@ attribute is present. Interrupts will be disabled inside function. @item naked @cindex function without a prologue/epilogue code -Use this attribute on the ARM or AVR 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. +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 @@ -2396,6 +2551,30 @@ 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 @@ -2729,11 +2908,10 @@ extension is irrelevant. 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 likely to be in a future C standard. -However, C++ style comments are not recognized if you specify -@w{@option{-ansi}}, a @option{-std} option specifying a version of ISO C -before C99, or @w{@option{-traditional}}, since they are incompatible -with traditional constructs like @code{dividend//*comment*/divisor}. +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 @@ -2870,6 +3048,22 @@ 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 @@ -3078,10 +3272,11 @@ packed))}. 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. Five attributes are currently defined for types: +double parentheses. Six attributes are currently defined for types: @code{aligned}, @code{packed}, @code{transparent_union}, @code{unused}, -and @code{deprecated}. Other attributes are defined for functions -(@pxref{Function Attributes}) and for variables (@pxref{Variable Attributes}). +@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 @@ -3115,7 +3310,7 @@ typedef int more_aligned_int __attribute__ ((aligned (8))); @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 +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 @@ -3292,6 +3487,36 @@ 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 @@ -3550,7 +3775,10 @@ asm volatile ("movc3 %0,%1,%2" 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. There is no way for you to specify that an input +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 @@ -3854,7 +4082,7 @@ extern func () asm ("FUNC"); func (x, y) int x, y; -@dots{} +/* @r{@dots{}} */ @end example It is up to you to make sure that the assembler names you choose do not @@ -3990,7 +4218,7 @@ 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 +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. @@ -4047,25 +4275,20 @@ be deleted or moved or simplified. @cindex alternate keywords @cindex keywords, alternate -The option @option{-traditional} disables certain keywords; @option{-ansi} and the various @option{-std} options disable certain -others. This causes trouble when you want to use GNU C extensions, or -ISO C features, in a general-purpose header file that should be usable -by all programs, including ISO C programs and traditional ones. The -keywords @code{asm}, @code{typeof} and @code{inline} cannot be used -since they won't work in a program compiled with @option{-ansi} -(although @code{inline} can be used in a program compiled with -@option{-std=c99}), while the keywords @code{const}, @code{volatile}, -@code{signed}, @code{typeof} and @code{inline} won't work in a program -compiled with @option{-traditional}. The ISO C99 keyword +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}, @code{__const__} instead of @code{const}, and -@code{__inline__} instead of @code{inline}. +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 @@ -4197,7 +4420,10 @@ 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. +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. @@ -4273,28 +4499,49 @@ A floating point value, as wide as a SI mode integer, usually 32 bits. A floating point value, as wide as a DI mode integer, usually 64 bits. @end table -Not all base types or combinations are always valid; which modes can be used -is determined by the target machine. For example, if targetting the i386 MMX -extensions, only @code{V8QI}, @code{V4HI} and @code{V2SI} are allowed modes. +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 -There are no @code{V1xx} vector modes - they would be identical to the -corresponding base mode. +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. -There is no distinction between signed and unsigned vector modes. This -distinction is made by the operations that perform on the vectors, not -by the data type. +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). -The types defined in this manner are somewhat special, they cannot be -used with most normal C operations (i.e., a vector addition can @emph{not} -be represented by a normal addition of two vector type variables). You -can declare only variables and use them in function calls and returns, as -well as in assignments and some casts. 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 vector operations 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: +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) @@ -4334,6 +4581,9 @@ v4si f (v4si a, v4si b, v4si c) @findex exit @findex _exit @findex _Exit +@findex exp +@findex expf +@findex expl @findex fabs @findex fabsf @findex fabsl @@ -4346,18 +4596,27 @@ v4si f (v4si a, v4si b, v4si c) @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 @@ -4371,6 +4630,11 @@ v4si f (v4si a, v4si b, v4si c) @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 @@ -4395,7 +4659,9 @@ 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}). +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}, @@ -4406,20 +4672,26 @@ mode. The ISO C99 functions @code{conj}, @code{conjf}, @code{conjl}, @code{creal}, @code{crealf}, @code{creall}, @code{cimag}, @code{cimagf}, -@code{cimagl}, @code{llabs} and @code{imaxabs} are handled as built-in -functions except in strict ISO C89 mode. There are also built-in +@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{fabsf}, @code{fabsl}, @code{sinf}, @code{sinl}, @code{sqrtf}, and -@code{sqrtl}, that are recognized in any mode since ISO C89 reserves +@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 C89 functions @code{abs}, @code{cos}, @code{fabs}, -@code{fprintf}, @code{fputs}, @code{labs}, @code{memcmp}, @code{memcpy}, -@code{memset}, @code{printf}, @code{sin}, @code{sqrt}, @code{strcat}, +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}, and @code{strstr} are all +@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 @@ -4506,13 +4778,15 @@ 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.} */ \ +#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 @@ -4559,7 +4833,7 @@ data. For instance, you can write @smallexample static const int table[] = @{ __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, - /* ... */ + /* @r{@dots{}} */ @}; @end smallexample @@ -4635,7 +4909,7 @@ 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 @@ -4649,6 +4923,74 @@ 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 @@ -4657,10 +4999,93 @@ 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 @@ -4784,14 +5209,10 @@ 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_cmpgtss (v4sf, v4sf) -v4si __builtin_ia32_cmpgess (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_cmpngtss (v4sf, v4sf) -v4si __builtin_ia32_cmpngess (v4sf, v4sf) v4si __builtin_ia32_cmpordss (v4sf, v4sf) v4sf __builtin_ia32_maxps (v4sf, v4sf) v4sf __builtin_ia32_maxss (v4sf, v4sf) @@ -4904,6 +5325,25 @@ The following functions are made available by including @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 @@ -5249,7 +5689,9 @@ vector unsigned int vec_mulo (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); @@ -5815,7 +6257,9 @@ 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, @@ -5970,6 +6414,7 @@ for further explanation. @menu * ARM Pragmas:: +* RS/6000 and PowerPC Pragmas:: * Darwin Pragmas:: * Solaris Pragmas:: * Tru64 Pragmas:: @@ -5998,6 +6443,27 @@ 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. @@ -6010,7 +6476,7 @@ subsequent functions. The following pragmas are available for all architectures running the Darwin operating system. These are useful for compatibility with other -MacOS compilers. +Mac OS compilers. @table @code @item mark @var{tokens}@dots{} @@ -6066,13 +6532,14 @@ is supported. 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 +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{__EXTERN_PREFIX} if the pragma is available. +preprocessor defines @code{__PRAGMA_EXTERN_PREFIX} if the pragma is +available. @end table @node Unnamed Fields @@ -6116,6 +6583,265 @@ 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 @@ -6290,7 +7016,7 @@ context. @example void fn (int *__restrict__ rptr, int &__restrict__ rref) @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -6304,7 +7030,7 @@ unaliased by using @code{__restrict__} as a member function qualifier. @example void T::fn () __restrict__ @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -6515,7 +7241,6 @@ 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 @@ -6634,8 +7359,8 @@ 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 outlined in the -Working Paper to allow forward declaration of explicit instantiations +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 @@ -6655,48 +7380,12 @@ 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. -@item -@opindex fexternal-templates -Add @samp{#pragma interface} to all files containing template -definitions. For each of these files, add @samp{#pragma implementation -"@var{filename}"} to the top of some @samp{.C} file which -@samp{#include}s it. Then compile everything with -@option{-fexternal-templates}. The templates will then only be expanded -in the translation unit which implements them (i.e.@: has a @samp{#pragma -implementation} line for the file where they live); all other files will -use external references. If you're lucky, everything should work -properly. If you get undefined symbol errors, you need to make sure -that each template instance which is used in the program is used in the -file which implements that template. If you don't have any use for a -particular instance in that file, you can just instantiate it -explicitly, using the syntax from the latest C++ working paper: - -@example -template class A<int>; -template ostream& operator << (ostream&, const A<int>&); -@end example - -This strategy will work with code written for either model. If you are -using code written for the Cfront model, the file containing a class -template and the file containing its member templates should be -implemented in the same translation unit. - -@item -@opindex falt-external-templates -A slight variation on this approach is to use the flag -@option{-falt-external-templates} instead. This flag causes template -instances to be emitted in the translation unit that implements the -header where they are first instantiated, rather than the one which -implements the file where the templates are defined. This header must -be the same in all translation units, or things are likely to break. - @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 @@ -6853,7 +7542,7 @@ 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 dependant +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. |
