egcs projects compiler system

Exact copy of the snapshot, except for the removal of
	texinfo/
	gcc/ch/
	libchill/

1 files changed, 3782 insertions, 0 deletions

diff --git a/gnu/egcs/gcc/extend.texi b/gnu/egcs/gcc/extend.texi
new file mode 100644
index 00000000000..f969f65b189
--- /dev/null
+++ b/gnu/egcs/gcc/extend.texi
@@ -0,0 +1,3782 @@
+@c Copyright (C) 1988,89,92,93,94,96,99 Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node C Extensions
+@chapter Extensions to the C Language Family
+@cindex extensions, C language
+@cindex C language extensions
+
+GNU C provides several language features not found in ANSI standard C.
+(The @samp{-pedantic} option directs GNU CC 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 GNU CC.
+
+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++.
+
+@c The only difference between the two versions of this menu is that the
+@c version for clear INTERNALS has an extra node, "Constraints" (which
+@c appears in a separate chapter in the other version of the manual).
+@ifset INTERNALS
+@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.
+* Naming Types::        Giving a name to the type of some expression.
+* 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.
+* Macro Varargs::	Macros with variable number of arguments.
+* 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.
+* Constructors::        Constructor expressions give structures, unions
+                         or arrays as values.
+* Labeled Elements::	Labeling elements of initializers.
+* Cast to Union::       Casting to union type from any member of the union.
+* Case Ranges::		`case 1 ... 9' and such.
+* Function Attributes:: Declaring that functions have no side effects,
+                         or that they can never return.
+* 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.)
+* 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.
+* Other Builtins::      Other built-in functions.
+* Deprecated Features:: Things might disappear from g++.
+@end menu
+@end ifset
+@ifclear INTERNALS
+@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.
+* Naming Types::        Giving a name to the type of some expression.
+* 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.
+* Macro Varargs::	Macros with variable number of arguments.
+* 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.
+* Constructors::        Constructor expressions give structures, unions
+                         or arrays as values.
+* Labeled Elements::	Labeling elements of initializers.
+* Cast to Union::       Casting to union type from any member of the union.
+* Case Ranges::		`case 1 ... 9' and such.
+* Function Attributes:: Declaring that functions have no side effects,
+                         or that they can never return.
+* 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.
+* Deprecated Features:: Things might disappear from g++.
+@end menu
+@end ifclear
+
+@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}) or type naming (@pxref{Naming
+Types}).
+
+@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}, @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;
+@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 can 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.
+
+@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
+bar (int *array, int offset, int size)
+@{
+  int access (int *array, int index)
+    @{ return array[index + offset]; @}
+  int i;
+  @dots{}
+  for (i = 0; i < size; i++)
+    @dots{} access (array, i) @dots{}
+@}
+@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.
+
+GNU CC implements taking the address of a nested function using a
+technique called @dfn{trampolines}.   A paper describing them is
+available as @samp{http://master.debian.org/~karlheg/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;
+  @dots{}
+  for (i = 0; i < size; i++)
+    @dots{} access (array, i) @dots{}
+  @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);
+  @dots{}
+  int access (int *array, int index)
+    @{
+      if (index > size)
+        goto failure;
+      return array[index + offset];
+    @}
+  @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).
+
+@table @code
+@findex __builtin_apply_args
+@item __builtin_apply_args ()
+This built-in function returns a pointer of type @code{void *} 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.
+
+@findex __builtin_apply
+@item __builtin_apply (@var{function}, @var{arguments}, @var{size})
+This built-in function invokes @var{function} (type @code{void (*)()})
+with a copy of the parameters described by @var{arguments} (type
+@code{void *}) and @var{size} (type @code{int}).
+
+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 of type @code{void *} 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.
+
+@findex __builtin_return
+@item __builtin_return (@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 table
+
+@node Naming Types
+@section Naming an Expression's Type
+@cindex naming types
+
+You can give a name to the type of an expression using a @code{typedef}
+declaration with an initializer.  Here is how to define @var{name} as a
+type name for the type of @var{exp}:
+
+@example
+typedef @var{name} = @var{exp};
+@end example
+
+This is 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:
+
+@example
+#define max(a,b) \
+  (@{typedef _ta = (a), _tb = (b);  \
+    _ta _a = (a); _tb _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.
+
+@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 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 ANSI 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}.
+
+@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
+
+@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
+
+GNU C supports data types for integers that are twice as long as
+@code{int}.  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 @code{LL}
+to the integer.  To make an integer constant of type @code{unsigned long
+long int}, add the suffix @code{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 GNU CC.
+
+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
+
+GNU C supports complex data types.  You can declare both complex integer
+types and complex floating types, using the keyword @code{__complex__}.
+
+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.
+
+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.
+
+The operator @samp{~} performs complex conjugation when used on a value
+with a complex type.
+
+GNU CC 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 GNU CC 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
+GNU CC recognizes 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.  In that format the
+@code{0x} hex introducer and the @code{p} or @code{P} exponent field are
+mandatory.  The exponent is a decimal number that indicates the power of
+2 by which the significand part will be multiplied.  Thus @code{0x1.f} is
+1 15/16, @code{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 @code{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
+
+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 standard C, you would have to give @code{contents} a length of 1, which
+means either you waste space or complicate the argument to @code{malloc}.
+
+@node Variable Length
+@section Arrays of Variable Length
+@cindex variable-length arrays
+@cindex arrays of variable length
+
+Variable-length automatic arrays are allowed in GNU C.  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])
+@{
+  @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)
+@{
+  @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.
+
+@node Macro Varargs
+@section Macros with Variable Numbers of Arguments
+@cindex variable number of arguments
+@cindex macro with variable arguments
+@cindex rest argument (in macro)
+
+In GNU C, a macro can accept a variable number of arguments, much as a
+function can.  The syntax for defining the macro looks much like that
+used for a function.  Here is an example:
+
+@example
+#define eprintf(format, args...)  \
+ fprintf (stderr, format , ## args)
+@end example
+
+Here @code{args} is a @dfn{rest argument}: it takes in zero or more
+arguments, as many as the call contains.  All of them plus the commas
+between them form the value of @code{args}, which is substituted into
+the macro body where @code{args} is used.  Thus, we have this expansion:
+
+@example
+eprintf ("%s:%d: ", input_file_name, line_number)
+@expansion{}
+fprintf (stderr, "%s:%d: " , input_file_name, line_number)
+@end example
+
+@noindent
+Note that the comma after the string constant comes from the definition
+of @code{eprintf}, whereas the last comma comes from the value of
+@code{args}.
+
+The reason for using @samp{##} is to handle the case when @code{args}
+matches no arguments at all.  In this case, @code{args} has an empty
+value.  In this case, the second comma in the definition becomes an
+embarrassment: if it got through to the expansion of the macro, we would
+get something like this:
+
+@example
+fprintf (stderr, "success!\n" , )
+@end example
+
+@noindent
+which is invalid C syntax.  @samp{##} gets rid of the comma, so we get
+the following instead:
+
+@example
+fprintf (stderr, "success!\n")
+@end example
+
+This is a special feature of the GNU C preprocessor: @samp{##} before a
+rest argument that is empty discards the preceding sequence of
+non-whitespace characters from the macro definition.  (If another macro
+argument precedes, none of it is discarded.)
+
+It might be better to discard the last preprocessor token instead of the
+last preceding sequence of non-whitespace characters; in fact, we may
+someday change this feature to do so.  We advise you to write the macro
+definition so that the preceding sequence of non-whitespace characters
+is just a single token, so that the meaning will not change if we change
+the definition of this feature.
+
+@node Subscripting
+@section Non-Lvalue Arrays May Have Subscripts
+@cindex subscripting
+@cindex arrays, non-lvalue
+
+@cindex subscripting and function values
+Subscripting is allowed on arrays that are not lvalues, even though the
+unary @samp{&} operator is not.  For example, this is valid in GNU C though
+not valid in other C dialects:
+
+@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.
+
+The option @samp{-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++, 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 @};
+  @dots{}
+@}
+@end example
+
+@node Constructors
+@section Constructor Expressions
+@cindex constructor expressions
+@cindex initializations in expressions
+@cindex structures, constructor expression
+@cindex expressions, constructor
+
+GNU C supports constructor expressions.  A constructor 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.
+
+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 constructor:
+
+@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 constructor
+are (made up of) simple constant expressions, suitable for use in
+initializers, then the constructor is an lvalue and can be coerced to a
+pointer to its first element, as shown here:
+
+@example
+char **foo = (char *[]) @{ "x", "y", "z" @};
+@end example
+
+Array constructors whose elements are not simple constants are
+not very useful, because the constructor is not an lvalue.  There
+are only two valid ways to use it: to subscript it, or initialize
+an array variable with it.  The former is probably slower than a
+@code{switch} statement, while the latter does the same thing an
+ordinary C initializer would do.  Here is an example of
+subscripting an array constructor:
+
+@example
+output = ((int[]) @{ 2, x, 28 @}) [input];
+@end example
+
+Constructor expressions for scalar types and union types are is
+also allowed, but then the constructor expression is equivalent
+to a cast.
+
+@node Labeled Elements
+@section Labeled Elements in Initializers
+@cindex initializers with labeled elements
+@cindex labeled elements in initializers
+@cindex case labels in initializers
+
+Standard C 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 GNU C you can give the elements in any order, specifying the array
+indices or structure field names they apply to.  This extension is not
+implemented in GNU C++.
+
+To specify an array index, write @samp{[@var{index}]} or
+@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.
+
+To initialize a range of elements to the same value, write
+@samp{[@var{first} ... @var{last}] = @var{value}}.  For example,
+
+@example
+int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
+@end example
+
+@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 is @samp{.@var{fieldname} =}.,
+as shown here:
+
+@example
+struct point p = @{ .y = yvalue, .x = xvalue @};
+@end example
+
+You can also use an element label (with either the colon syntax or the
+period-equal 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 label 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
+
+@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{Constructors}.)
+
+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;
+@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);
+@dots{}
+hack ((union foo) x);
+@end example
+
+@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 @code{volatile} applied to function
+@cindex @code{const} applied to function
+@cindex functions with @code{printf}, @code{scanf} or @code{strftime} style 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.  Nine attributes,
+@code{noreturn}, @code{const}, @code{format},
+@code{no_instrument_function}, @code{section},
+@code{constructor}, @code{destructor}, @code{unused} and @code{weak} are
+currently defined for functions.  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}.
+
+@table @code
+@cindex @code{noreturn} function attribute
+@item noreturn
+A few standard library functions, such as @code{abort} and @code{exit},
+cannot return.  GNU CC 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
+void fatal () __attribute__ ((noreturn));
+
+void
+fatal (@dots{})
+@{
+  @dots{} /* @r{Print error message.} */ @dots{}
+  exit (1);
+@}
+@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 GNU C 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{const} function attribute
+@item const
+Many functions do not examine any values except their arguments, and
+have no effects except the return value.  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{const}.  For example,
+
+@smallexample
+int square (int) __attribute__ ((const));
+@end smallexample
+
+@noindent
+says that the hypothetical function @code{square} is safe to call
+fewer times than the program says.
+
+The attribute @code{const} is not implemented in GNU C 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 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}.
+
+@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
+@cindex @code{format} function attribute
+The @code{format} attribute specifies that a function takes @code{printf},
+@code{scanf}, or @code{strftime} 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 either @code{printf}, @code{scanf}, or
+@code{strftime}.  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.
+
+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.
+
+The @code{format} attribute allows you to identify your own functions
+which take format strings as arguments, so that GNU CC can check the
+calls to these functions for errors.  The compiler always checks formats
+for the ANSI 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 @samp{-Wformat}), so there is no need to
+modify the header file @file{stdio.h}.
+
+@item format_arg (@var{string-index})
+@cindex @code{format_arg} function attribute
+The @code{format_arg} attribute specifies that a function takes
+@code{printf} or @code{scanf} style arguments, modifies it (for example,
+to translate it into another language), and passes it to a @code{printf}
+or @code{scanf} style function.  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
+@code{my_dgettext} whose result is passed to a @code{printf},
+@code{scanf}, or @code{strftime} type function for consistency with the
+@code{printf} style format string argument @code{my_format}.
+
+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 GNU CC can check the
+calls to @code{printf}, @code{scanf}, or @code{strftime} 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.
+
+@item no_instrument_function
+@cindex @code{no_instrument_function} function attribute
+If @samp{-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 ("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.
+
+@item unused
+This attribute, attached to a function, means that the function is meant
+to be possibly unused.  GNU CC will not produce a warning for this
+function.  GNU C++ does not currently support this attribute as
+definitions without parameters are valid in C++.
+
+@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 alias ("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 () @{ /* 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 no_check_memory_usage
+@cindex @code{no_check_memory_usage} function attribute
+If @samp{-fcheck-memory-usage} is given, calls to support routines will
+be generated before most memory accesses, to permit support code to
+record usage and detect uses of uninitialized or unallocated storage.
+Since the compiler cannot handle them properly, @code{asm} statements
+are not allowed.  Declaring a function with this attribute disables the
+memory checking code for that function, permitting the use of @code{asm}
+statements without requiring separate compilation with different
+options, and allowing you to write support routines of your own if you
+wish, without getting infinite recursion if they get compiled with this
+option.
+
+@item regparm (@var{number})
+@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 @var{EAX},
+@var{EDX}, and @var{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.
+
+@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
+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 @samp{-mrtd} switch.
+
+The PowerPC compiler for Windows NT currently ignores the @code{cdecl}
+attribute.
+
+@item longcall
+@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.
+
+@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 option 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 option to work correctly.
+
+@item interrupt_handler
+@cindex interrupt handler functions on the H8/300 processors
+Use this option on the H8/300 and H8/300H 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 eightbit_data
+@cindex eight bit data on the H8/300 and H8/300H
+Use this option 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 option to work correctly.
+
+@item tiny_data
+@cindex tiny data section on the H8/300H
+Use this option 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 interrupt
+@cindex interrupt handlers on the M32R/D
+Use this option on the M32R/D 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 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).
+
+@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 ANSI C's
+@code{#pragma} should be used instead.  There are 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 apply to almost any application that might be proposed
+for @code{#pragma}.  It is basically a mistake to use @code{#pragma} for
+@emph{anything}.
+
+@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 ANSI 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}.  ANSI 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 ANSI 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
+
+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 likely to be in a future C standard.
+However, C++ style comments are not recognized if you specify
+@w{@samp{-ansi}} or @w{@samp{-traditional}}, since they are incompatible
+with traditional constructs like @code{dividend//*comment*/divisor}.
+
+@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.
+
+When the operand of @code{__alignof__} is an lvalue rather than a type, the
+value is the largest alignment that the lvalue is known to have.  It may
+have this alignment as a result of its data type, or because it is part of
+a structure and inherits alignment from that structure.  For example, after
+this declaration:
+
+@example
+struct foo @{ int x; char y; @} foo1;
+@end example
+
+@noindent
+the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as
+@code{__alignof__ (int)}, even though the data type of @code{foo1.y}
+does not itself demand any alignment.@refill
+
+A related feature which lets you specify the alignment of an object is
+@code{__attribute__ ((aligned (@var{alignment})))}; see the following
+section.
+
+@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.  Eight
+attributes are currently defined for variables: @code{aligned},
+@code{mode}, @code{nocommon}, @code{packed}, @code{section},
+@code{transparent_union}, @code{unused}, and @code{weak}.  Other
+attributes are available for functions (@pxref{Function 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{__aligned__} instead of @code{aligned}.
+
+@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.
+
+It is not possible to specify the alignment of functions; the alignment
+of functions is determined by the machine's requirements and cannot be
+changed.  You cannot specify alignment for a typedef name because such a
+name is just an alias, not a distinct type.
+
+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 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
+This attribute specifies requests GNU CC not to place a variable
+``common'' but instead to allocate space for it directly.  If you
+specify the @samp{-fno-common} flag, GNU CC 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 ("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.  GNU CC 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 @samp{-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 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.  GNU CC will not produce a warning for this
+variable.
+
+@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.  Three attributes are currently defined for types:
+@code{aligned}, @code{packed}, and @code{transparent_union}.  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.
+
+@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 ANSI 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.
+
+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 @samp{-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.  GNU CC 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.
+
+@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 GNU CC 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 @samp{-O}, no function is really inline.
+
+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 ANSI C programs, write
+@code{__inline__} instead of @code{inline}.  @xref{Alternate Keywords}.)
+You can also make all ``simple enough'' functions inline with the option
+@samp{-finline-functions}. 
+
+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 @samp{-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}
+GNU CC 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 @samp{-fno-default-inline};
+@pxref{C++ Dialect Options,,Options Controlling C++ Dialect}.)
+
+@cindex inline functions, omission of
+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, GNU CC does not actually output assembler code for the
+function, unless you specify the option @samp{-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.
+
+GNU C does not inline any functions when not optimizing.  It is not
+clear whether it is better to inline or not, in this case, but we found
+that a correct implementation when not optimizing was difficult.  So we
+did the easy thing, and turned it off.
+
+@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 limited to
+ten or to the maximum number of operands in any instruction pattern in
+the machine description, whichever is greater.
+
+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.
+
+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, GNU CC
+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; GNU CC 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 digit in constraint is allowed only in an
+input operand and it must refer to an output operand.
+
+Only a digit 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; GNU CC 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 GNU CC can't tell that.
+
+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
+
+It is an error for a clobber description to overlap an input or output
+operand (for example, an operand describing a register class with one
+member, mentioned in the clobber list).  Most notably, it is invalid to
+describe that an input operand is modified, but unused as output.  It has
+to be specified as an input and output operand anyway.  Note that if there
+are only unused output operands, you will then also need to specify
+@code{volatile} for the @code{asm} construct, as described below.
+
+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.  GNU CC 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 GNU CC to not keep memory values cached in registers across
+the assembler instruction.
+
+You can put multiple assembler instructions together in a single
+@code{asm} template, separated either with newlines (written as
+@samp{\n}) or with semicolons if the assembler allows such semicolons.
+The GNU assembler allows semicolons and most Unix assemblers seem to do
+so.  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;movl %1,r10;call _foo"
+     : /* no outputs */
+     : "g" (from), "g" (to)
+     : "r9", "r10");
+@end example
+
+Unless an output operand has the @samp{&} constraint modifier, GNU CC
+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;frob %1;beq 0f;mov #1,%0;0:"
+     : "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, GNU CC 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, GNU CC will know
+the instruction has side-effects and will not delete the instruction or
+move it outside of loops.  If the side-effects of your instruction are
+not purely external, but will affect variables in your program in ways
+other than reading the inputs and clobbering the specified registers or
+memory, you should write the @code{volatile} keyword to prevent future
+versions of GNU CC from moving the instruction around within a core
+region.
+
+An @code{asm} instruction without any operands or clobbers (and ``old
+style'' @code{asm}) will not be deleted or moved significantly,
+regardless, unless it is unreachable, the same wasy as if you had
+written a @code{volatile} keyword.
+
+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}.
+
+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.
+
+If you are writing a header file that should be includable in ANSI 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, ie, 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
+
+@ifclear INTERNALS
+@c Show the details on constraints if they do not appear elsewhere in
+@c the manual
+@include md.texi
+@end ifclear
+
+@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.
+
+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;
+@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.  GNU
+CC 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 @samp{-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 GNU CC 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
+
+The option @samp{-traditional} disables certain keywords; @samp{-ansi}
+disables certain others.  This causes trouble when you want to use GNU C
+extensions, or ANSI C features, in a general-purpose header file that
+should be usable by all programs, including ANSI 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 @samp{-ansi}, while
+the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
+and @code{inline} won't work in a program compiled with
+@samp{-traditional}.@refill
+
+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}.
+
+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__
+@samp{-pedantic} causes 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
+
+GNU CC predefines two string variables to be the name of the current function.
+The variable @code{__FUNCTION__} is the name of the function as it appears
+in the source.  The variable @code{__PRETTY_FUNCTION__} is 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
+
+These names are not macros: they are predefined string variables.
+For example, @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__}.
+
+@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.
+
+@table @code
+@findex __builtin_return_address
+@item __builtin_return_address (@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.
+
+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}.
+
+This function should only be used with a non-zero argument for debugging
+purposes.
+
+@findex __builtin_frame_address
+@item __builtin_frame_address (@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.
+
+The caveats that apply to @code{__builtin_return_address} apply to this
+function as well.
+@end table
+
+@node Other Builtins
+@section Other built-in functions provided by GNU CC
+
+GNU CC 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.
+
+GNU CC includes builtin versions of many of the functions in the
+standard C library.  These will always be treated as having the same
+meaning as the C library function even if you specify the
+@samp{-fno-builtin} (@pxref{C Dialect Options}) option.  These functions
+correspond to the C library functions @code{alloca}, @code{ffs},
+@code{abs}, @code{fabsf}, @code{fabs}, @code{fabsl}, @code{labs},
+@code{memcpy}, @code{memcmp}, @code{strcmp}, @code{strcpy},
+@code{strlen}, @code{sqrtf}, @code{sqrt}, @code{sqrtl}, @code{sinf},
+@code{sin}, @code{sinl}, @code{cosf}, @code{cos}, and @code{cosl}.
+
+@findex __builtin_constant_p
+You can use the builtin function @code{__builtin_constant_p} to
+determine if a value is known to be constant at compile-time and hence
+that GNU CC 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 GNU CC cannot prove it is a constant with the specified
+value of the @samp{-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 builtin 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 builtin, GNU CC will
+never return 1 when you call the inline function with a string constant
+or constructor expression (@pxref{Constructors}) and will not return 1
+when you pass a constant numeric value to the inline function unless you
+specify the @samp{-O} option.
+
+@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 superceded 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 -fthis-is-variable
+In early versions of C++, assignment to this could be used to implement
+application-defined memory allocation. Now, allocation functions
+(@samp{operator new}) are the standard-conforming way to achieve the
+same effect.
+
+@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.
+
+@end table
+
+@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
+* Naming Results::      Giving a name to C++ function return values.
+* Min and Max::		C++ Minimum and maximum operators.
+* Destructors and Goto:: Goto is safe to use in C++ even when destructors
+                           are needed.
+* 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++ Signatures::	You can specify abstract types to get subtype
+			 polymorphism independent from inheritance.
+                        
+@end menu
+
+@node Naming Results
+@section Named Return Values in C++
+
+@cindex @code{return}, in C++ function header
+@cindex return value, named, in C++
+@cindex named return value in C++
+@cindex C++ named return value
+GNU C++ extends the function-definition syntax to allow you to specify a
+name for the result of a function outside the body of the definition, in
+C++ programs:
+
+@example
+@group
+@var{type}
+@var{functionname} (@var{args}) return @var{resultname};
+@{
+  @dots{}
+  @var{body}
+  @dots{}
+@}
+@end group
+@end example
+
+You can use this feature to avoid an extra constructor call when
+a function result has a class type.  For example, consider a function
+@code{m}, declared as @w{@samp{X v = m ();}}, whose result is of class
+@code{X}:
+
+@example
+X
+m ()
+@{
+  X b;
+  b.a = 23;
+  return b;
+@}
+@end example
+
+@cindex implicit argument: return value
+Although @code{m} appears to have no arguments, in fact it has one implicit
+argument: the address of the return value.  At invocation, the address
+of enough space to hold @code{v} is sent in as the implicit argument.
+Then @code{b} is constructed and its @code{a} field is set to the value
+23.  Finally, a copy constructor (a constructor of the form @samp{X(X&)})
+is applied to @code{b}, with the (implicit) return value location as the
+target, so that @code{v} is now bound to the return value.
+
+But this is wasteful.  The local @code{b} is declared just to hold
+something that will be copied right out.  While a compiler that
+combined an ``elision'' algorithm with interprocedural data flow
+analysis could conceivably eliminate all of this, it is much more
+practical to allow you to assist the compiler in generating
+efficient code by manipulating the return value explicitly,
+thus avoiding the local variable and copy constructor altogether.
+
+Using the extended GNU C++ function-definition syntax, you can avoid the
+temporary allocation and copying by naming @code{r} as your return value
+at the outset, and assigning to its @code{a} field directly:
+
+@example
+X
+m () return r;
+@{
+  r.a = 23;
+@}
+@end example
+
+@noindent
+The declaration of @code{r} is a standard, proper declaration, whose effects
+are executed @strong{before} any of the body of @code{m}.
+
+Functions of this type impose no additional restrictions; in particular,
+you can execute @code{return} statements, or return implicitly by
+reaching the end of the function body (``falling off the edge'').
+Cases like
+
+@example
+X
+m () return r (23);
+@{
+  return;
+@}
+@end example
+
+@noindent
+(or even @w{@samp{X m () return r (23); @{ @}}}) are unambiguous, since
+the return value @code{r} has been initialized in either case.  The
+following code may be hard to read, but also works predictably:
+
+@example
+X
+m () return r;
+@{
+  X b;
+  return b;
+@}
+@end example
+
+The return value slot denoted by @code{r} is initialized at the outset,
+but the statement @samp{return b;} overrides this value.  The compiler
+deals with this by destroying @code{r} (calling the destructor if there
+is one, or doing nothing if there is not), and then reinitializing
+@code{r} with @code{b}.
+
+This extension is provided primarily to help people who use overloaded
+operators, where there is a great need to control not just the
+arguments, but the return values of functions.  For classes where the
+copy constructor incurs a heavy performance penalty (especially in the
+common case where there is a quick default constructor), this is a major
+savings.  The disadvantage of this extension is that you do not control
+when the default constructor for the return value is called: it is
+always called at the beginning.
+
+@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.  A GNU C extension allows you to write safe
+macros that avoid this kind of problem (@pxref{Naming Types,,Naming an
+Expression's Type}).  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 Destructors and Goto
+@section @code{goto} and Destructors in GNU C++
+
+@cindex @code{goto} in C++
+@cindex destructors vs @code{goto}
+In C++ programs, you can safely use the @code{goto} statement.  When you
+use it to exit a block which contains aggregates requiring destructors,
+the destructors will run before the @code{goto} transfers control.
+
+@cindex constructors vs @code{goto}
+The compiler still forbids using @code{goto} to @emph{enter} a scope
+that requires constructors.
+
+@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.
+
+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 @samp{-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
+Compile your template-using code with @samp{-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
+Compile your code with @samp{-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 @samp{-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 @samp{-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
+and instantiation of the compiler support data for a template class
+(i.e. the vtable) without instantiating any of its members:
+
+@example
+extern template int max (int, int);
+inline 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.
+
+@item
+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
+@samp{-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.
+
+A slight variation on this approach is to instead use the flag
+@samp{-falt-external-templates}; 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
+
+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
+
+You must specify @samp{-Wno-pmf-conversions} to use this extension.
+
+@node C++ Signatures
+@section Type Abstraction using Signatures
+
+@findex signature
+@cindex type abstraction, C++
+@cindex C++ type abstraction
+@cindex subtype polymorphism, C++
+@cindex C++ subtype polymorphism
+@cindex signatures, C++
+@cindex C++ signatures
+
+In GNU C++, you can use the keyword @code{signature} to define a
+completely abstract class interface as a datatype.  You can connect this
+abstraction with actual classes using signature pointers.  If you want
+to use signatures, run the GNU compiler with the
+@samp{-fhandle-signatures} command-line option.  (With this option, the
+compiler reserves a second keyword @code{sigof} as well, for a future
+extension.)
+
+Roughly, signatures are type abstractions or interfaces of classes.
+Some other languages have similar facilities.  C++ signatures are
+related to ML's signatures, Haskell's type classes, definition modules
+in Modula-2, interface modules in Modula-3, abstract types in Emerald,
+type modules in Trellis/Owl, categories in Scratchpad II, and types in
+POOL-I.  For a more detailed discussion of signatures, see
+@cite{Signatures: A Language Extension for Improving Type Abstraction and
+Subtype Polymorphism in C++}
+by @w{Gerald} Baumgartner and Vincent F. Russo (Tech report
+CSD--TR--95--051, Dept. of Computer Sciences, Purdue University,
+August 1995, a slightly improved version appeared in
+@emph{Software---Practice & Experience}, @b{25}(8), pp. 863--889,
+August 1995).  You can get the tech report by anonymous FTP from
+@code{ftp.cs.purdue.edu} in @file{pub/gb/Signature-design.ps.gz}.
+
+Syntactically, a signature declaration is a collection of
+member function declarations and nested type declarations.
+For example, this signature declaration defines a new abstract type
+@code{S} with member functions @samp{int foo ()} and @samp{int bar (int)}:
+
+@example
+signature S
+@{
+  int foo ();
+  int bar (int);
+@};
+@end example
+
+Since signature types do not include implementation definitions, you
+cannot write an instance of a signature directly.  Instead, you can
+define a pointer to any class that contains the required interfaces as a
+@dfn{signature pointer}.  Such a class @dfn{implements} the signature
+type.
+@c Eventually signature references should work too.
+
+To use a class as an implementation of @code{S}, you must ensure that
+the class has public member functions @samp{int foo ()} and @samp{int
+bar (int)}.  The class can have other member functions as well, public
+or not; as long as it offers what's declared in the signature, it is
+suitable as an implementation of that signature type.
+
+For example, suppose that @code{C} is a class that meets the
+requirements of signature @code{S} (@code{C} @dfn{conforms to}
+@code{S}).  Then
+
+@example
+C obj;
+S * p = &obj;
+@end example
+
+@noindent
+defines a signature pointer @code{p} and initializes it to point to an
+object of type @code{C}.
+The member function call @w{@samp{int i = p->foo ();}}
+executes @samp{obj.foo ()}.
+
+@cindex @code{signature} in C++, advantages
+Abstract virtual classes provide somewhat similar facilities in standard
+C++.  There are two main advantages to using signatures instead:
+
+@enumerate
+@item
+Subtyping becomes independent from inheritance.  A class or signature
+type @code{T} is a subtype of a signature type @code{S} independent of
+any inheritance hierarchy as long as all the member functions declared
+in @code{S} are also found in @code{T}.  So you can define a subtype
+hierarchy that is completely independent from any inheritance
+(implementation) hierarchy, instead of being forced to use types that
+mirror the class inheritance hierarchy.
+
+@item
+Signatures allow you to work with existing class hierarchies as
+implementations of a signature type.  If those class hierarchies are
+only available in compiled form, you're out of luck with abstract virtual
+classes, since an abstract virtual class cannot be retrofitted on top of
+existing class hierarchies.  So you would be required to write interface
+classes as subtypes of the abstract virtual class.
+@end enumerate
+
+@cindex default implementation, signature member function
+@cindex signature member function default implementation
+There is one more detail about signatures.  A signature declaration can
+contain member function @emph{definitions} as well as member function
+declarations.  A signature member function with a full definition is
+called a @emph{default implementation}; classes need not contain that
+particular interface in order to conform.  For example, a
+class @code{C} can conform to the signature
+
+@example
+signature T
+@{
+  int f (int);
+  int f0 () @{ return f (0); @};
+@};
+@end example
+
+@noindent
+whether or not @code{C} implements the member function @samp{int f0 ()}.
+If you define @code{C::f0}, that definition takes precedence;
+otherwise, the default implementation @code{S::f0} applies.
+
+@ignore
+There will be more support for signatures in the future.
+Add to this doc as the implementation grows.
+In particular, the following features are planned but not yet
+implemented:
+@itemize @bullet
+@item signature references,
+@item signature inheritance,
+@item the @code{sigof} construct for extracting the signature information
+      of a class,
+@item views for renaming member functions when matching a class type
+      with a signature type,
+@item specifying exceptions with signature member functions, and
+@item signature templates.
+@end itemize
+This list is roughly in the order in which we intend to implement
+them.  Watch this space for updates.
+@end ignore