summaryrefslogtreecommitdiffstats
path: root/contrib/gcc/extend.texi
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/gcc/extend.texi')
-rw-r--r--contrib/gcc/extend.texi3197
1 files changed, 3197 insertions, 0 deletions
diff --git a/contrib/gcc/extend.texi b/contrib/gcc/extend.texi
new file mode 100644
index 0000000..e85799c
--- /dev/null
+++ b/contrib/gcc/extend.texi
@@ -0,0 +1,3197 @@
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994 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.
+* 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.
+@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.
+* 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.
+@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 from @samp{maya.idiap.ch} in directory @file{pub/tmb},
+file @file{usenix88-lexic.ps.Z}.
+
+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{long 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 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} or @code{scanf} 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. Eight attributes,
+@code{noreturn}, @code{const}, @code{format}, @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}
+or @code{scanf} 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} or @code{scanf}. 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{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 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.
+
+@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.
+
+@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.
+
+@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 called function will pop off the stack space used to
+pass arguments, unless it takes a variable number of arguments. This is
+useful to override the effects of the @samp{-mrtd} switch.
+@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.} */
+#if __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 use dollar signs in identifier names. This is because
+many traditional C implementations allow such identifiers.
+
+On some machines, dollar signs are allowed in identifiers if you specify
+@w{@samp{-traditional}}. On a few systems they are allowed by default,
+even if you do not use @w{@samp{-traditional}}. But they are never
+allowed if you specify @w{@samp{-ansi}}.
+
+There are certain ANSI C programs (obscure, to be sure) that would
+compile incorrectly if dollar signs were permitted in identifiers. For
+example:
+
+@example
+#define foo(a) #a
+#define lose(b) foo (b)
+#define test$
+lose (test)
+@end example
+
+@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_copy __attribute__ ((section ("INITDATACOPY"))) = 0;
+
+main()
+@{
+ /* Initialize stack pointer */
+ init_sp (stack + sizeof (stack));
+
+ /* Initialize initialized data */
+ memcpy (&init_data_copy, &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 argument variable which is a
+union, means to pass the argument in the same way that the first union
+member would be passed. You can also use this attribute on a
+@code{typedef} for a union data type; then it applies to all function
+arguments 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}.
+@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.
+
+@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 fas 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.
+
+@item transparent_union
+This attribute, attached to a @code{union} type definition, indicates
+that any variable having that union type should, if passed to a
+function, be passed in the same way that the first union member would be
+passed. For example:
+
+@example
+union foo
+@{
+ char a;
+ int x[2];
+@} __attribute__ ((transparent_union));
+@end example
+@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.
+
+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 now specify the
+operands of the instruction using C expressions. This means no more
+guessing 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 output operands and separate
+inputs. 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, and there are input operands, then there
+must be 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 whether it is valid assembler input. The
+extended @code{asm} feature is most often used for machine instructions
+that 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 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 does not support input-output or read-write
+operands. For this reason, the constraint character @samp{+}, which
+indicates such an operand, may not be used.
+
+When the assembler instruction has a read-write operand, or an operand
+in which only some of the bits are to be changed, you must 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:
+
+@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
+
+If you refer to a particular hardware register from the assembler code,
+then you will probably have to list the register after the third colon
+to tell the compiler that the register's value is modified. In many
+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 all 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 that 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 that 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 that the instruction has no side effects except to change the
+output operands. This does not mean that 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 set_priority(x) \
+asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
+@end example
+
+@noindent
+An instruction without output operands will not be deleted or moved
+significantly, regardless, unless it is unreachable.
+
+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}.
+
+@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.
+
+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}.
+
+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 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. I would not be surprised if
+excessive use of this feature leaves the compiler too few available
+registers to compile certain functions.
+
+@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
+
+@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 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.
+* 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 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. (In
+ANSI C++, @code{goto} is restricted to targets within the current
+block.)
+
+@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}, @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; template instances
+are emitted in each translation unit that uses them, and they are
+collapsed together at run time. 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 member templates in the header file, since they must
+be seen to be compiled.
+
+@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. As
+individual object files are built, notes are placed in the repository to
+record where templates and potential type arguments were seen so that
+the subsequent instantiation step knows where to find them. At link
+time, any needed instances are generated and linked in. 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; theoretically, this should be
+just as transparent, but in practice it has been very difficult to build
+multiple programs in one directory and one program in multiple
+directories using Cfront. Code written for this model tends to separate
+definitions of non-inline member templates into a separate file, which
+is magically found by the link preprocessor when a template needs to be
+instantiated.
+@end table
+
+Currently, g++ implements neither automatic model. In the mean time,
+you have three options for dealing with template instantiations:
+
+@enumerate
+@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 -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 use the flag
+-falt-external-templates instead; this flag causes template instances to
+be emitted in the translation unit that implements the header where they
+are first instantiated, rather than the one which implements the file
+where the templates are defined. This header must be the same in all
+translation units, or things are likely to break.
+
+@xref{C++ Interface,,Declarations and Definitions in One Header}, for
+more discussion of these pragmas.
+
+@item
+Explicitly instantiate all the template instances you use, and compile
+with -fno-implicit-templates. This is probably your best bet; it may
+require more knowledge of exactly which templates you are using, but
+it's less mysterious than the previous approach, and it doesn't require
+any @samp{#pragma}s or other g++-specific code. You can scatter the
+instantiations throughout your program, you can create one big file to
+do all the instantiations, or you can create tiny files like
+
+@example
+#include "Foo.h"
+#include "Foo.cc"
+
+template class Foo<int>;
+@end example
+
+for each instance you need, and create a template instantiation library
+from those. I'm partial to the last, but your mileage may vary. If you
+are using Cfront-model code, you can probably get away with not using
+-fno-implicit-templates when compiling files that don't @samp{#include}
+the member template definitions.
+@end enumerate
+
+@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
OpenPOWER on IntegriCloud