From c1f7febfcb105bd5ceb464576227897245c4ef1c Mon Sep 17 00:00:00 2001 From: Richard Kenner Date: Mon, 23 Sep 1996 18:41:16 -0400 Subject: [PATCH] Initial revision From-SVN: r12786 --- gcc/extend.texi | 3414 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3414 insertions(+) create mode 100644 gcc/extend.texi diff --git a/gcc/extend.texi b/gcc/extend.texi new file mode 100644 index 00000000000..6b85b9e6419 --- /dev/null +++ b/gcc/extend.texi @@ -0,0 +1,3414 @@ +@c Copyright (C) 1988,89,92,93,94,96 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. +* Return Address:: Getting the return or frame address of a 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. +* Return Address:: Getting the return or frame address of a 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{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 format_arg (@var{string-index}) +@cindex @code{format_arg} function attribute +The @code{format_arg} attribute specifies that a function takes +@code{printf} or @code{scanf} style arguments, modifies it (for example, +to translate it into another language), and passes it to a @code{printf} +or @code{scanf} style function. For example, the declaration: + +@smallexample +extern char * +my_dgettext (char *my_domain, const char *my_format) + __attribute__ ((format_arg (2))); +@end smallexample + +@noindent +causes the compiler to check the arguments in calls to +@code{my_dgettext} whose result is passed to a @code{printf} or +@code{scanf} type function for consistency with the @code{printf} style +format string argument @code{my_format}. + +The parameter @var{string-index} specifies which argument is the format +string argument (starting from 1). + +The @code{format-arg} attribute allows you to identify your own +functions which modify format strings, so that GNU CC can check the +calls to @code{printf} and @code{scanf} function whose operands are a +call to one of your own function. The compiler always treats +@code{gettext}, @code{dgettext}, and @code{dcgettext} in this manner. + +@item section ("section-name") +@cindex @code{section} function attribute +Normally, the compiler places the code it generates in the @code{text} section. +Sometimes, however, you need additional sections, or you need certain +particular functions to appear in special sections. The @code{section} +attribute specifies that a function lives in a particular section. +For example, the declaration: + +@smallexample +extern void foobar (void) __attribute__ ((section ("bar"))); +@end smallexample + +@noindent +puts the function @code{foobar} in the @code{bar} section. + +Some file formats do not support arbitrary sections so the @code{section} +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. + +@item constructor +@itemx destructor +@cindex @code{constructor} function attribute +@cindex @code{destructor} function attribute +The @code{constructor} attribute causes the function to be called +automatically before execution enters @code{main ()}. Similarly, the +@code{destructor} attribute causes the function to be called +automatically after @code{main ()} has completed or @code{exit ()} has +been called. Functions with these attributes are useful for +initializing data that will be used implicitly during the execution of +the program. + +These attributes are not currently implemented for Objective C. + +@item unused +This attribute, attached to a function, means that the function is meant +to be possibly unused. GNU CC will not produce a warning for this +function. GNU C++ does not currently support this attribute as +definitions without parameters are valid in C++. + +@item weak +@cindex @code{weak} attribute +The @code{weak} attribute causes the declaration to be emitted as a weak +symbol rather than a global. This is primarily useful in defining +library functions which can be overridden in user code, though it can +also be used with non-function declarations. Weak symbols are supported +for ELF targets, and also for a.out targets when using the GNU assembler +and linker. + +@item alias ("target") +@cindex @code{alias} attribute +The @code{alias} attribute causes the declaration to be emitted as an +alias for another symbol, which must be specified. For instance, + +@smallexample +void __f () @{ /* do something */; @} +void f () __attribute__ ((weak, alias ("__f"))); +@end smallexample + +declares @samp{f} to be a weak alias for @samp{__f}. In C++, the +mangled name for the target must be used. + +@item regparm (@var{number}) +@cindex functions that are passed arguments in registers on the 386 +On the Intel 386, the @code{regparm} attribute causes the compiler to +pass up to @var{number} integer arguments in registers @var{EAX}, +@var{EDX}, and @var{ECX} instead of on the stack. Functions that take a +variable number of arguments will continue to be passed all of their +arguments on the stack. + +@item stdcall +@cindex functions that pop the argument stack on the 386 +On the Intel 386, the @code{stdcall} attribute causes the compiler to +assume that the called function will pop off the stack space used to +pass arguments, unless it takes a variable number of arguments. + +The PowerPC compiler for Windows NT currently ignores the @code{stdcall} +attribute. + +@item cdecl +@cindex functions that do pop the argument stack on the 386 +On the Intel 386, the @code{cdecl} attribute causes the compiler to +assume that the calling function will pop off the stack space used to +pass arguments. This is +useful to override the effects of the @samp{-mrtd} switch. + +The PowerPC compiler for Windows NT currently ignores the @code{cdecl} +attribute. + +@item longcall +@cindex functions called via pointer on the RS/6000 and PowerPC +On the RS/6000 and PowerPC, the @code{longcall} attribute causes the +compiler to always call the function via a pointer, so that functions +which reside further than 64 megabytes (67,108,864 bytes) from the +current location can be called. + +@item dllimport +@cindex functions which are imported from a dll on PowerPC Windows NT +On the PowerPC running Windows NT, the @code{dllimport} attribute causes +the compiler to call the function via a global pointer to the function +pointer that is set up by the Windows NT dll library. The pointer name +is formed by combining @code{__imp_} and the function name. + +@item dllexport +@cindex functions which are exported from a dll on PowerPC Windows NT +On the PowerPC running Windows NT, the @code{dllexport} attribute causes +the compiler to provide a global pointer to the function pointer, so +that it can be called with the @code{dllimport} attribute. The pointer +name is formed by combining @code{__imp_} and the function name. + +@item exception (@var{except-func} [, @var{except-arg}]) +@cindex functions which specify exception handling on PowerPC Windows NT +On the PowerPC running Windows NT, the @code{exception} attribute causes +the compiler to modify the structured exception table entry it emits for +the declared function. The string or identifier @var{except-func} is +placed in the third entry of the structured exception table. It +represents a function, which is called by the exception handling +mechanism if an exception occurs. If it was specified, the string or +identifier @var{except-arg} is placed in the fourth entry of the +structured exception table. + +@item function_vector +@cindex calling functions through the function vector on the H8/300 processors +Use this option on the H8/300 and H8/300H to indicate that the specified +function should be called through the function vector. Calling a +function through the function vector will reduce code size, however; +the function vector has a limited size (maximum 128 entries on the H8/300 +and 64 entries on the H8/300H) and shares space with the interrupt vector. + +You must use GAS and GLD from GNU binutils version 2.7 or later for +this option to work correctly. + +@item interrupt_handler +@cindex interrupt handler functions on the H8/300 processors +Use this option on the H8/300 and H8/300H to indicate that the specified +function is an interrupt handler. The compiler will generate function +entry and exit sequences suitable for use in an interrupt handler when this +attribute is present. + +@item eightbit_data +@cindex eight bit data on the H8/300 and H8/300H +Use this option on the H8/300 and H8/300H to indicate that the specified +variable should be placed into the eight bit data section. +The compiler will generate more efficient code for certain operations +on data in the eight bit data area. Note the eight bit data area is limited to +256 bytes of data. + +You must use GAS and GLD from GNU binutils version 2.7 or later for +this option to work correctly. + +@item tiny_data +@cindex tiny data section on the H8/300H +Use this option on the H8/300H to indicate that the specified +variable should be placed into the tiny data section. +The compiler will generate more efficient code for loads and stores +on data in the tiny data section. Note the tiny data area is limited to +slightly under 32kbytes of data. +@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 __attribute__ ((section ("INITDATA"))) = 0; + +main() +@{ + /* Initialize stack pointer */ + init_sp (stack + sizeof (stack)); + + /* Initialize initialized data */ + memcpy (&init_data, &data, &edata - &data); + + /* Turn on the serial ports */ + init_duart (&a); + init_duart (&b); +@} +@end smallexample + +@noindent +Use the @code{section} attribute with an @emph{initialized} definition +of a @emph{global} variable, as shown in the example. GNU CC issues +a warning and otherwise ignores the @code{section} attribute in +uninitialized variable declarations. + +You may only use the @code{section} attribute with a fully initialized +global definition because of the way linkers work. The linker requires +each object be defined once, with the exception that uninitialized +variables tentatively go in the @code{common} (or @code{bss}) section +and can be multiply "defined". You can force a variable to be +initialized with the @samp{-fno-common} flag or the @code{nocommon} +attribute. + +Some file formats do not support arbitrary sections so the @code{section} +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. + +@item transparent_union +This attribute, attached to a function parameter which is a union, means +that the corresponding argument may have the type of any union member, +but the argument is passed as if its type were that of the first union +member. For more details see @xref{Type Attributes}. You can also use +this attribute on a @code{typedef} for a union data type; then it +applies to all function parameters with that type. + +@item unused +This attribute, attached to a variable, means that the variable is meant +to be possibly unused. GNU CC will not produce a warning for this +variable. + +@item weak +The @code{weak} attribute is described in @xref{Function Attributes}. +@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 function parameter having that union type causes calls to that +function to be treated in a special way. + +First, the argument corresponding to a transparent union type can be of +any type in the union; no cast is required. Also, if the union contains +a pointer type, the corresponding argument can be a null pointer +constant or a void pointer expression; and if the union contains a void +pointer type, the corresponding argument can be any pointer expression. +If the union member type is a pointer, qualifiers like @code{const} on +the referenced type must be respected, just as with normal pointer +conversions. + +Second, the argument is passed to the function using the calling +conventions of first member of the transparent union, not the calling +conventions of the union itself. All members of the union must have the +same machine representation; this is necessary for this argument passing +to work properly. + +Transparent unions are designed for library functions that have multiple +interfaces for compatibility reasons. For example, suppose the +@code{wait} function must accept either a value of type @code{int *} to +comply with Posix, or a value of type @code{union wait *} to comply with +the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, +@code{wait} would accept both kinds of arguments, but it would also +accept any other pointer type and this would make argument type checking +less useful. Instead, @code{} might define the interface +as follows: + +@smallexample +typedef union + @{ + int *__ip; + union wait *__up; + @} wait_status_ptr_t __attribute__ ((__transparent_union__)); + +pid_t wait (wait_status_ptr_t); +@end smallexample + +This interface allows either @code{int *} or @code{union wait *} +arguments to be passed, using the @code{int *} calling convention. +The program can call @code{wait} with arguments of either type: + +@example +int w1 () @{ int w; return wait (&w); @} +int w2 () @{ union wait w; return wait (&w); @} +@end example + +With this interface, @code{wait}'s implementation might look like this: + +@example +pid_t wait (wait_status_ptr_t p) +@{ + return waitpid (-1, p.__ip, 0); +@} +@end example +@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 ordinary output operands must be write-only; GNU CC will assume +that the values in these operands before the instruction are dead and +need not be generated. Extended asm supports input-output or +read-write operands. Use the constraint character @samp{+} to indicate +such an operand and list it with the output operands. + +When the constraints for the read-write operand +(or the operand in which only some of the bits are to be changed) +allows a register, you may, as an alternative, logically +split its function into two separate operands, one input operand and one +write-only output operand. The connection between them is expressed by +constraints which say they need to be in the same location when the +instruction executes. You can use the same C expression for both +operands, or different expressions. For example, here we write the +(fictitious) @samp{combine} instruction with @code{bar} as its read-only +source operand and @code{foo} as its read-write destination: + +@example +asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); +@end example + +@noindent +The constraint @samp{"0"} for operand 1 says that it must occupy the same +location as operand 0. A digit in constraint is allowed only in an input +operand, and it must refer to an output operand. + +Only a digit in the constraint can guarantee that one operand will be in +the same place as another. The mere fact that @code{foo} is the value of +both operands is not enough to guarantee that they will be in the same +place in the generated assembler code. The following would not work: + +@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 Return Address +@section Getting the Return or Frame Address of a Function + +These functions may be used to get information about the callers of a +function. + +@table @code +@item __builtin_return_address (@var{level}) +This function returns the return address of the current function, or of +one of its callers. The @var{level} argument is number of frames to +scan up the call stack. A value of @code{0} yields the return address +of the current function, a value of @code{1} yields the return address +of the caller of the current function, and so forth. + +The @var{level} argument must be a constant integer. + +On some machines it may be impossible to determine the return address of +any function other than the current one; in such cases, or when the top +of the stack has been reached, this function will return @code{0}. + +This function should only be used with a non-zero argument for debugging +purposes. + +@item __builtin_frame_address (@var{level}) +This function is similar to @code{__builtin_return_address}, but it +returns the address of the function frame rather than the return address +of the function. Calling @code{__builtin_frame_address} with a value of +@code{0} yields the frame address of the current function, a value of +@code{1} yields the frame address of the caller of the current function, +and so forth. + +The frame is the area on the stack which holds local variables and saved +registers. The frame address is normally the address of the first word +pushed on to the stack by the function. However, the exact definition +depends upon the processor and the calling convention. If the processor +has a dedicated frame pointer register, and the function has a frame, +then @code{__builtin_frame_address} will return the value of the frame +pointer register. + +The caveats that apply to @code{__builtin_return_address} apply to this +function as well. +@end table + +@node 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 maximum operator +is the @dfn{maximum}, returning the larger of the numeric values @var{a} +and @var{b}. +@end table + +These operations are not primitive in ordinary C++, since you can +use a macro to return the minimum of two things in C++, as in the +following example. + +@example +#define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) +@end example + +@noindent +You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to +the minimum value of variables @var{i} and @var{j}. + +However, side effects in @code{X} or @code{Y} may cause unintended +behavior. For example, @code{MIN (i++, j++)} will fail, incrementing +the smaller counter twice. A GNU C extension allows you to write safe +macros that avoid this kind of problem (@pxref{Naming Types,,Naming an +Expression's Type}). However, writing @code{MIN} and @code{MAX} as +macros also forces you to use function-call notation for a +fundamental arithmetic operation. Using GNU C++ extensions, you can +write @w{@samp{int min = i ?} are built into the compiler, they properly +handle expressions with side-effects; @w{@samp{int min = i++ ; +template ostream& operator << + (ostream&, const Foo&); +@end example + +for each of the instances you need, and create a template instantiation +library from those. + +If you are using Cfront-model code, you can probably get away with not +using @samp{-fno-implicit-templates} when compiling files that don't +@samp{#include} the member template definitions. + +If you use one big file to do the instantiations, you may want to +compile it without @samp{-fno-implicit-templates} so you get all of the +instances required by your explicit instantiations (but not by any +other files) without having to specify them as well. + +g++ has extended the template instantiation syntax outlined in the +Working Paper to allow forward declaration of explicit instantiations, +explicit instantiation of members of template classes and instantiation +of the compiler support data for a template class (i.e. the vtable) +without instantiating any of its members: + +@example +extern template int max (int, int); +template void Foo::f (); +inline template class Foo; +@end example + +@item +Do nothing. Pretend g++ does implement automatic instantiation +management. Code written for the Borland model will work fine, but +each translation unit will contain instances of each of the templates it +uses. In a large program, this can lead to an unacceptable amount of code +duplication. + +@item +Add @samp{#pragma interface} to all files containing template +definitions. For each of these files, add @samp{#pragma implementation +"@var{filename}"} to the top of some @samp{.C} file which +@samp{#include}s it. Then compile everything with +@samp{-fexternal-templates}. The templates will then only be expanded +in the translation unit which implements them (i.e. has a @samp{#pragma +implementation} line for the file where they live); all other files will +use external references. If you're lucky, everything should work +properly. If you get undefined symbol errors, you need to make sure +that each template instance which is used in the program is used in the +file which implements that template. If you don't have any use for a +particular instance in that file, you can just instantiate it +explicitly, using the syntax from the latest C++ working paper: + +@example +template class A; +template ostream& operator << (ostream&, const A&); +@end example + +This strategy will work with code written for either model. If you are +using code written for the Cfront model, the file containing a class +template and the file containing its member templates should be +implemented in the same translation unit. + +A slight variation on this approach is to instead use the flag +@samp{-falt-external-templates}; this flag causes template +instances to be emitted in the translation unit that implements the +header where they are first instantiated, rather than the one which +implements the file where the templates are defined. This header must +be the same in all translation units, or things are likely to break. + +@xref{C++ Interface,,Declarations and Definitions in One Header}, for +more discussion of these pragmas. +@end enumerate + +@node 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 -- 2.30.2