| @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. |
| |
| Not all target machines support this attribute. |
| |
| @item regparm (@var{number}) |
| @cindex functions that are passed arguments in registers on the 386 |
| On the Intel 386, the @code{regparm} attribute causes the compiler to |
| pass up to @var{number} integer arguments in registers @var{EAX}, |
| @var{EDX}, and @var{ECX} instead of on the stack. Functions that take a |
| variable number of arguments will continue to be passed all of their |
| arguments on the stack. |
| |
| @item stdcall |
| @cindex functions that pop the argument stack on the 386 |
| On the Intel 386, the @code{stdcall} attribute causes the compiler to |
| assume that the called function will pop off the stack space used to |
| pass arguments, unless it takes a variable number of arguments. |
| |
| The PowerPC compiler for Windows NT currently ignores the @code{stdcall} |
| attribute. |
| |
| @item cdecl |
| @cindex functions that do pop the argument stack on the 386 |
| On the Intel 386, the @code{cdecl} attribute causes the compiler to |
| assume that the calling function will pop off the stack space used to |
| pass arguments. This is |
| useful to override the effects of the @samp{-mrtd} switch. |
| |
| The PowerPC compiler for Windows NT currently ignores the @code{cdecl} |
| attribute. |
| |
| @item longcall |
| @cindex functions called via pointer on the RS/6000 and PowerPC |
| On the RS/6000 and PowerPC, the @code{longcall} attribute causes the |
| compiler to always call the function via a pointer, so that functions |
| which reside further than 64 megabytes (67,108,864 bytes) from the |
| current location can be called. |
| |
| @item dllimport |
| @cindex functions which are imported from a dll on PowerPC Windows NT |
| On the PowerPC running Windows NT, the @code{dllimport} attribute causes |
| the compiler to call the function via a global pointer to the function |
| pointer that is set up by the Windows NT dll library. The pointer name |
| is formed by combining @code{__imp_} and the function name. |
| |
| @item dllexport |
| @cindex functions which are exported from a dll on PowerPC Windows NT |
| On the PowerPC running Windows NT, the @code{dllexport} attribute causes |
| the compiler to provide a global pointer to the function pointer, so |
| that it can be called with the @code{dllimport} attribute. The pointer |
| name is formed by combining @code{__imp_} and the function name. |
| |
| @item exception (@var{except-func} [, @var{except-arg}]) |
| @cindex functions which specify exception handling on PowerPC Windows NT |
| On the PowerPC running Windows NT, the @code{exception} attribute causes |
| the compiler to modify the structured exception table entry it emits for |
| the declared function. The string or identifier @var{except-func} is |
| placed in the third entry of the structured exception table. It |
| represents a function, which is called by the exception handling |
| mechanism if an exception occurs. If it was specified, the string or |
| identifier @var{except-arg} is placed in the fourth entry of the |
| structured exception table. |
| |
| @item function_vector |
| @cindex calling functions through the function vector on the H8/300 processors |
| Use this option on the H8/300 and H8/300H to indicate that the specified |
| function should be called through the function vector. Calling a |
| function through the function vector will reduce code size, however; |
| the function vector has a limited size (maximum 128 entries on the H8/300 |
| and 64 entries on the H8/300H) and shares space with the interrupt vector. |
| |
| You must use GAS and GLD from GNU binutils version 2.7 or later for |
| this option to work correctly. |
| |
| @item interrupt_handler |
| @cindex interrupt handler functions on the H8/300 processors |
| Use this option on the H8/300 and H8/300H to indicate that the specified |
| function is an interrupt handler. The compiler will generate function |
| entry and exit sequences suitable for use in an interrupt handler when this |
| attribute is present. |
| |
| @item eightbit_data |
| @cindex eight bit data on the H8/300 and H8/300H |
| Use this option on the H8/300 and H8/300H to indicate that the specified |
| variable should be placed into the eight bit data section. |
| The compiler will generate more efficient code for certain operations |
| on data in the eight bit data area. Note the eight bit data area is limited to |
| 256 bytes of data. |
| |
| You must use GAS and GLD from GNU binutils version 2.7 or later for |
| this option to work correctly. |
| |
| @item tiny_data |
| @cindex tiny data section on the H8/300H |
| Use this option on the H8/300H to indicate that the specified |
| variable should be placed into the tiny data section. |
| The compiler will generate more efficient code for loads and stores |
| on data in the tiny data section. Note the tiny data area is limited to |
| slightly under 32kbytes of data. |
| |
| @item interrupt |
| @cindex interrupt handlers on the M32R/D |
| Use this option on the M32R/D to indicate that the specified |
| function is an interrupt handler. The compiler will generate function |
| entry and exit sequences suitable for use in an interrupt handler when this |
| attribute is present. |
| |
| @item model (@var{model-name}) |
| @cindex function addressability on the M32R/D |
| Use this attribute on the M32R/D to set the addressability of an object, |
| and the code generated for a function. |
| The identifier @var{model-name} is one of @code{small}, @code{medium}, |
| or @code{large}, representing each of the code models. |
| |
| Small model objects live in the lower 16MB of memory (so that their |
| addresses can be loaded with the @code{ld24} instruction), and are |
| callable with the @code{bl} instruction. |
| |
| Medium model objects may live anywhere in the 32 bit address space (the |
| compiler will generate @code{seth/add3} instructions to load their addresses), |
| and are callable with the @code{bl} instruction. |
| |
| Large model objects may live anywhere in the 32 bit address space (the |
| compiler will generate @code{seth/add3} instructions to load their addresses), |
| and may not be reachable with the @code{bl} instruction (the compiler will |
| generate the much slower @code{seth/add3/jl} instruction sequence). |
| |
| @end table |
| |
| You can specify multiple attributes in a declaration by separating them |
| by commas within the double parentheses or by immediately following an |
| attribute declaration with another attribute declaration. |
| |
| @cindex @code{#pragma}, reason for not using |
| @cindex pragma, reason for not using |
| Some people object to the @code{__attribute__} feature, suggesting that ANSI C's |
| @code{#pragma} should be used instead. There are two reasons for not |
| doing this. |
| |
| @enumerate |
| @item |
| It is impossible to generate @code{#pragma} commands from a macro. |
| |
| @item |
| There is no telling what the same @code{#pragma} might mean in another |
| compiler. |
| @end enumerate |
| |
| These two reasons apply to almost any application that might be proposed |
| for @code{#pragma}. It is basically a mistake to use @code{#pragma} for |
| @emph{anything}. |
| |
| @node Function Prototypes |
| @section Prototypes and Old-Style Function Definitions |
| @cindex function prototype declarations |
| @cindex old-style function definitions |
| @cindex promotion of formal parameters |
| |
| GNU C extends ANSI C to allow a function prototype to override a later |
| old-style non-prototype definition. Consider the following example: |
| |
| @example |
| /* @r{Use prototypes unless the compiler is old-fashioned.} */ |
| #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 normally use dollar signs in identifier names. |
| This is because many traditional C implementations allow such identifiers. |
| However, dollar signs in identifiers are not supported on a few target |
| machines, typically because the target assembler does not allow them. |
| |
| @node Character Escapes |
| @section The Character @key{ESC} in Constants |
| |
| You can use the sequence @samp{\e} in a string or character constant to |
| stand for the ASCII character @key{ESC}. |
| |
| @node Alignment |
| @section Inquiring on Alignment of Types or Variables |
| @cindex alignment |
| @cindex type alignment |
| @cindex variable alignment |
| |
| The keyword @code{__alignof__} allows you to inquire about how an object |
| is aligned, or the minimum alignment usually required by a type. Its |
| syntax is just like @code{sizeof}. |
| |
| For example, if the target machine requires a @code{double} value to be |
| aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. |
| This is true on many RISC machines. On more traditional machine |
| designs, @code{__alignof__ (double)} is 4 or even 2. |
| |
| Some machines never actually require alignment; they allow reference to any |
| data type even at an odd addresses. For these machines, @code{__alignof__} |
| reports the @emph{recommended} alignment of a type. |
| |
| When the operand of @code{__alignof__} is an lvalue rather than a type, the |
| value is the largest alignment that the lvalue is known to have. It may |
| have this alignment as a result of its data type, or because it is part of |
| a structure and inherits alignment from that structure. For example, after |
| this declaration: |
| |
| @example |
| struct foo @{ int x; char y; @} foo1; |
| @end example |
| |
| @noindent |
| the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as |
| @code{__alignof__ (int)}, even though the data type of @code{foo1.y} |
| does not itself demand any alignment.@refill |
| |
| A related feature which lets you specify the alignment of an object is |
| @code{__attribute__ ((aligned (@var{alignment})))}; see the following |
| section. |
| |
| @node Variable Attributes |
| @section Specifying Attributes of Variables |
| @cindex attribute of variables |
| @cindex variable attributes |
| |
| The keyword @code{__attribute__} allows you to specify special |
| attributes of variables or structure fields. This keyword is followed |
| by an attribute specification inside double parentheses. Eight |
| attributes are currently defined for variables: @code{aligned}, |
| @code{mode}, @code{nocommon}, @code{packed}, @code{section}, |
| @code{transparent_union}, @code{unused}, and @code{weak}. Other |
| attributes are available for functions (@pxref{Function Attributes}) and |
| for types (@pxref{Type Attributes}). |
| |
| You may also specify attributes with @samp{__} preceding and following |
| each keyword. This allows you to use them in header files without |
| being concerned about a possible macro of the same name. For example, |
| you may use @code{__aligned__} instead of @code{aligned}. |
| |
| @table @code |
| @cindex @code{aligned} attribute |
| @item aligned (@var{alignment}) |
| This attribute specifies a minimum alignment for the variable or |
| structure field, measured in bytes. For example, the declaration: |
| |
| @smallexample |
| int x __attribute__ ((aligned (16))) = 0; |
| @end smallexample |
| |
| @noindent |
| causes the compiler to allocate the global variable @code{x} on a |
| 16-byte boundary. On a 68040, this could be used in conjunction with |
| an @code{asm} expression to access the @code{move16} instruction which |
| requires 16-byte aligned operands. |
| |
| You can also specify the alignment of structure fields. For example, to |
| create a double-word aligned @code{int} pair, you could write: |
| |
| @smallexample |
| struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; |
| @end smallexample |
| |
| @noindent |
| This is an alternative to creating a union with a @code{double} member |
| that forces the union to be double-word aligned. |
| |
| It is not possible to specify the alignment of functions; the alignment |
| of functions is determined by the machine's requirements and cannot be |
| changed. You cannot specify alignment for a typedef name because such a |
| name is just an alias, not a distinct type. |
| |
| As in the preceding examples, you can explicitly specify the alignment |
| (in bytes) that you wish the compiler to use for a given variable or |
| structure field. Alternatively, you can leave out the alignment factor |
| and just ask the compiler to align a variable or field to the maximum |
| useful alignment for the target machine you are compiling for. For |
| example, you could write: |
| |
| @smallexample |
| short array[3] __attribute__ ((aligned)); |
| @end smallexample |
| |
| Whenever you leave out the alignment factor in an @code{aligned} attribute |
| specification, the compiler automatically sets the alignment for the declared |
| variable or field to the largest alignment which is ever used for any data |
| type on the target machine you are compiling for. Doing this can often make |
| copy operations more efficient, because the compiler can use whatever |
| instructions copy the biggest chunks of memory when performing copies to |
| or from the variables or fields that you have aligned this way. |
| |
| The @code{aligned} attribute can only increase the alignment; but you |
| can decrease it by specifying @code{packed} as well. See below. |
| |
| Note that the effectiveness of @code{aligned} attributes may be limited |
| by inherent limitations in your linker. On many systems, the linker is |
| only able to arrange for variables to be aligned up to a certain maximum |
| alignment. (For some linkers, the maximum supported alignment may |
| be very very small.) If your linker is only able to align variables |
| up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} |
| in an @code{__attribute__} will still only provide you with 8 byte |
| alignment. See your linker documentation for further information. |
| |
| @item mode (@var{mode}) |
| @cindex @code{mode} attribute |
| This attribute specifies the data type for the declaration---whichever |
| type corresponds to the mode @var{mode}. This in effect lets you |
| request an integer or floating point type according to its width. |
| |
| You may also specify a mode of @samp{byte} or @samp{__byte__} to |
| indicate the mode corresponding to a one-byte integer, @samp{word} or |
| @samp{__word__} for the mode of a one-word integer, and @samp{pointer} |
| or @samp{__pointer__} for the mode used to represent pointers. |
| |
| @item nocommon |
| @cindex @code{nocommon} attribute |
| This attribute specifies requests GNU CC not to place a variable |
| ``common'' but instead to allocate space for it directly. If you |
| specify the @samp{-fno-common} flag, GNU CC will do this for all |
| variables. |
| |
| Specifying the @code{nocommon} attribute for a variable provides an |
| initialization of zeros. A variable may only be initialized in one |
| source file. |
| |
| @item packed |
| @cindex @code{packed} attribute |
| The @code{packed} attribute specifies that a variable or structure field |
| should have the smallest possible alignment---one byte for a variable, |
| and one bit for a field, unless you specify a larger value with the |
| @code{aligned} attribute. |
| |
| Here is a structure in which the field @code{x} is packed, so that it |
| immediately follows @code{a}: |
| |
| @example |
| struct foo |
| @{ |
| char a; |
| int x[2] __attribute__ ((packed)); |
| @}; |
| @end example |
| |
| @item section ("section-name") |
| @cindex @code{section} variable attribute |
| Normally, the compiler places the objects it generates in sections like |
| @code{data} and @code{bss}. Sometimes, however, you need additional sections, |
| or you need certain particular variables to appear in special sections, |
| for example to map to special hardware. The @code{section} |
| attribute specifies that a variable (or function) lives in a particular |
| section. For example, this small program uses several specific section names: |
| |
| @smallexample |
| struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; |
| struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; |
| char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; |
| int init_data __attribute__ ((section ("INITDATA"))) = 0; |
| |
| main() |
| @{ |
| /* Initialize stack pointer */ |
| init_sp (stack + sizeof (stack)); |
| |
| /* Initialize initialized data */ |
| memcpy (&init_data, &data, &edata - &data); |
| |
| /* Turn on the serial ports */ |
| init_duart (&a); |
| init_duart (&b); |
| @} |
| @end smallexample |
| |
| @noindent |
| Use the @code{section} attribute with an @emph{initialized} definition |
| of a @emph{global} variable, as shown in the example. GNU CC issues |
| a warning and otherwise ignores the @code{section} attribute in |
| uninitialized variable declarations. |
| |
| You may only use the @code{section} attribute with a fully initialized |
| global definition because of the way linkers work. The linker requires |
| each object be defined once, with the exception that uninitialized |
| variables tentatively go in the @code{common} (or @code{bss}) section |
| and can be multiply "defined". You can force a variable to be |
| initialized with the @samp{-fno-common} flag or the @code{nocommon} |
| attribute. |
| |
| Some file formats do not support arbitrary sections so the @code{section} |
| attribute is not available on all platforms. |
| If you need to map the entire contents of a module to a particular |
| section, consider using the facilities of the linker instead. |
| |
| @item transparent_union |
| This attribute, attached to a function parameter which is a union, means |
| that the corresponding argument may have the type of any union member, |
| but the argument is passed as if its type were that of the first union |
| member. For more details see @xref{Type Attributes}. You can also use |
| this attribute on a @code{typedef} for a union data type; then it |
| applies to all function parameters with that type. |
| |
| @item unused |
| This attribute, attached to a variable, means that the variable is meant |
| to be possibly unused. GNU CC will not produce a warning for this |
| variable. |
| |
| @item weak |
| The @code{weak} attribute is described in @xref{Function Attributes}. |
| |
| @item model (@var{model-name}) |
| @cindex variable addressability on the M32R/D |
| Use this attribute on the M32R/D to set the addressability of an object. |
| The identifier @var{model-name} is one of @code{small}, @code{medium}, |
| or @code{large}, representing each of the code models. |
| |
| Small model objects live in the lower 16MB of memory (so that their |
| addresses can be loaded with the @code{ld24} instruction). |
| |
| Medium and large model objects may live anywhere in the 32 bit address space |
| (the compiler will generate @code{seth/add3} instructions to load their |
| addresses). |
| |
| @end table |
| |
| To specify multiple attributes, separate them by commas within the |
| double parentheses: for example, @samp{__attribute__ ((aligned (16), |
| packed))}. |
| |
| @node Type Attributes |
| @section Specifying Attributes of Types |
| @cindex attribute of types |
| @cindex type attributes |
| |
| The keyword @code{__attribute__} allows you to specify special |
| attributes of @code{struct} and @code{union} types when you define such |
| types. This keyword is followed by an attribute specification inside |
| double parentheses. Three attributes are currently defined for types: |
| @code{aligned}, @code{packed}, and @code{transparent_union}. Other |
| attributes are defined for functions (@pxref{Function Attributes}) and |
| for variables (@pxref{Variable Attributes}). |
| |
| You may also specify any one of these attributes with @samp{__} |
| preceding and following its keyword. This allows you to use these |
| attributes in header files without being concerned about a possible |
| macro of the same name. For example, you may use @code{__aligned__} |
| instead of @code{aligned}. |
| |
| You may specify the @code{aligned} and @code{transparent_union} |
| attributes either in a @code{typedef} declaration or just past the |
| closing curly brace of a complete enum, struct or union type |
| @emph{definition} and the @code{packed} attribute only past the closing |
| brace of a definition. |
| |
| @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, unless that |
| declaration also contains the definition of the @code{enum}. |
| |
| @item transparent_union |
| This attribute, attached to a @code{union} type definition, indicates |
| that any function parameter having that union type causes calls to that |
| function to be treated in a special way. |
| |
| First, the argument corresponding to a transparent union type can be of |
| any type in the union; no cast is required. Also, if the union contains |
| a pointer type, the corresponding argument can be a null pointer |
| constant or a void pointer expression; and if the union contains a void |
| pointer type, the corresponding argument can be any pointer expression. |
| If the union member type is a pointer, qualifiers like @code{const} on |
| the referenced type must be respected, just as with normal pointer |
| conversions. |
| |
| Second, the argument is passed to the function using the calling |
| conventions of first member of the transparent union, not the calling |
| conventions of the union itself. All members of the union must have the |
| same machine representation; this is necessary for this argument passing |
| to work properly. |
| |
| Transparent unions are designed for library functions that have multiple |
| interfaces for compatibility reasons. For example, suppose the |
| @code{wait} function must accept either a value of type @code{int *} to |
| comply with Posix, or a value of type @code{union wait *} to comply with |
| the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, |
| @code{wait} would accept both kinds of arguments, but it would also |
| accept any other pointer type and this would make argument type checking |
| less useful. Instead, @code{<sys/wait.h>} might define the interface |
| as follows: |
| |
| @smallexample |
| typedef union |
| @{ |
| int *__ip; |
| union wait *__up; |
| @} wait_status_ptr_t __attribute__ ((__transparent_union__)); |
| |
| pid_t wait (wait_status_ptr_t); |
| @end smallexample |
| |
| This interface allows either @code{int *} or @code{union wait *} |
| arguments to be passed, using the @code{int *} calling convention. |
| The program can call @code{wait} with arguments of either type: |
| |
| @example |
| int w1 () @{ int w; return wait (&w); @} |
| int w2 () @{ union wait w; return wait (&w); @} |
| @end example |
| |
| With this interface, @code{wait}'s implementation might look like this: |
| |
| @example |
| pid_t wait (wait_status_ptr_t p) |
| @{ |
| return waitpid (-1, p.__ip, 0); |
| @} |
| @end example |
| @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 minimum operator |
| is the @dfn{minimum}, returning the smaller of the numeric values |
| @var{a} and @var{b}; |
| |
| @item @var{a} >? @var{b} |
| @findex >? |
| @cindex maximum operator |
| is the @dfn{maximum}, returning the larger of the numeric values @var{a} |
| and @var{b}. |
| @end table |
| |
| These operations are not primitive in ordinary C++, since you can |
| use a macro to return the minimum of two things in C++, as in the |
| following example. |
| |
| @example |
| #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) |
| @end example |
| |
| @noindent |
| You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to |
| the minimum value of variables @var{i} and @var{j}. |
| |
| However, side effects in @code{X} or @code{Y} may cause unintended |
| behavior. For example, @code{MIN (i++, j++)} will fail, incrementing |
| the smaller counter twice. A GNU C extension allows you to write safe |
| macros that avoid this kind of problem (@pxref{Naming Types,,Naming an |
| Expression's Type}). However, writing @code{MIN} and @code{MAX} as |
| macros also forces you to use function-call notation for a |
| fundamental arithmetic operation. Using GNU C++ extensions, you can |
| write @w{@samp{int min = i <? j;}} instead. |
| |
| Since @code{<?} and @code{>?} are built into the compiler, they properly |
| handle expressions with side-effects; @w{@samp{int min = i++ <? j++;}} |
| works correctly. |
| |
| @node Destructors and Goto |
| @section @code{goto} and Destructors in GNU C++ |
| |
| @cindex @code{goto} in C++ |
| @cindex destructors vs @code{goto} |
| In C++ programs, you can safely use the @code{goto} statement. When you |
| use it to exit a block which contains aggregates requiring destructors, |
| the destructors will run before the @code{goto} transfers control. |
| |
| @cindex constructors vs @code{goto} |
| The compiler still forbids using @code{goto} to @emph{enter} a scope |
| that requires constructors. |
| |
| @node C++ Interface |
| @section Declarations and Definitions in One Header |
| |
| @cindex interface and implementation headers, C++ |
| @cindex C++ interface and implementation headers |
| C++ object definitions can be quite complex. In principle, your source |
| code will need two kinds of things for each object that you use across |
| more than one source file. First, you need an @dfn{interface} |
| specification, describing its structure with type declarations and |
| function prototypes. Second, you need the @dfn{implementation} itself. |
| It can be tedious to maintain a separate interface description in a |
| header file, in parallel to the actual implementation. It is also |
| dangerous, since separate interface and implementation definitions may |
| not remain parallel. |
| |
| @cindex pragmas, interface and implementation |
| With GNU C++, you can use a single header file for both purposes. |
| |
| @quotation |
| @emph{Warning:} The mechanism to specify this is in transition. For the |
| nonce, you must use one of two @code{#pragma} commands; in a future |
| release of GNU C++, an alternative mechanism will make these |
| @code{#pragma} commands unnecessary. |
| @end quotation |
| |
| The header file contains the full definitions, but is marked with |
| @samp{#pragma interface} in the source code. This allows the compiler |
| to use the header file only as an interface specification when ordinary |
| source files incorporate it with @code{#include}. In the single source |
| file where the full implementation belongs, you can use either a naming |
| convention or @samp{#pragma implementation} to indicate this alternate |
| use of the header file. |
| |
| @table @code |
| @item #pragma interface |
| @itemx #pragma interface "@var{subdir}/@var{objects}.h" |
| @kindex #pragma interface |
| Use this directive in @emph{header files} that define object classes, to save |
| space in most of the object files that use those classes. Normally, |
| local copies of certain information (backup copies of inline member |
| functions, debugging information, and the internal tables that implement |
| virtual functions) must be kept in each object file that includes class |
| definitions. You can use this pragma to avoid such duplication. When a |
| header file containing @samp{#pragma interface} is included in a |
| compilation, this auxiliary information will not be generated (unless |
| the main input source file itself uses @samp{#pragma implementation}). |
| Instead, the object files will contain references to be resolved at link |
| time. |
| |
| The second form of this directive is useful for the case where you have |
| multiple headers with the same name in different directories. If you |
| use this form, you must specify the same string to @samp{#pragma |
| implementation}. |
| |
| @item #pragma implementation |
| @itemx #pragma implementation "@var{objects}.h" |
| @kindex #pragma implementation |
| Use this pragma in a @emph{main input file}, when you want full output from |
| included header files to be generated (and made globally visible). The |
| included header file, in turn, should use @samp{#pragma interface}. |
| Backup copies of inline member functions, debugging information, and the |
| internal tables used to implement virtual functions are all generated in |
| implementation files. |
| |
| @cindex implied @code{#pragma implementation} |
| @cindex @code{#pragma implementation}, implied |
| @cindex naming convention, implementation headers |
| If you use @samp{#pragma implementation} with no argument, it applies to |
| an include file with the same basename@footnote{A file's @dfn{basename} |
| was the name stripped of all leading path information and of trailing |
| suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source |
| file. For example, in @file{allclass.cc}, giving just |
| @samp{#pragma implementation} |
| by itself is equivalent to @samp{#pragma implementation "allclass.h"}. |
| |
| In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as |
| an implementation file whenever you would include it from |
| @file{allclass.cc} even if you never specified @samp{#pragma |
| implementation}. This was deemed to be more trouble than it was worth, |
| however, and disabled. |
| |
| If you use an explicit @samp{#pragma implementation}, it must appear in |
| your source file @emph{before} you include the affected header files. |
| |
| Use the string argument if you want a single implementation file to |
| include code from multiple header files. (You must also use |
| @samp{#include} to include the header file; @samp{#pragma |
| implementation} only specifies how to use the file---it doesn't actually |
| include it.) |
| |
| There is no way to split up the contents of a single header file into |
| multiple implementation files. |
| @end table |
| |
| @cindex inlining and C++ pragmas |
| @cindex C++ pragmas, effect on inlining |
| @cindex pragmas in C++, effect on inlining |
| @samp{#pragma implementation} and @samp{#pragma interface} also have an |
| effect on function inlining. |
| |
| If you define a class in a header file marked with @samp{#pragma |
| interface}, the effect on a function defined in that class is similar to |
| an explicit @code{extern} declaration---the compiler emits no code at |
| all to define an independent version of the function. Its definition |
| is used only for inlining with its callers. |
| |
| Conversely, when you include the same header file in a main source file |
| that declares it as @samp{#pragma implementation}, the compiler emits |
| code for the function itself; this defines a version of the function |
| that can be found via pointers (or by callers compiled without |
| inlining). If all calls to the function can be inlined, you can avoid |
| emitting the function by compiling with @samp{-fno-implement-inlines}. |
| If any calls were not inlined, you will get linker errors. |
| |
| @node Template Instantiation |
| @section Where's the Template? |
| |
| @cindex template instantiation |
| |
| C++ templates are the first language feature to require more |
| intelligence from the environment than one usually finds on a UNIX |
| system. Somehow the compiler and linker have to make sure that each |
| template instance occurs exactly once in the executable if it is needed, |
| and not at all otherwise. There are two basic approaches to this |
| problem, which I will refer to as the Borland model and the Cfront model. |
| |
| @table @asis |
| @item Borland model |
| Borland C++ solved the template instantiation problem by adding the code |
| equivalent of common blocks to their linker; the compiler emits template |
| instances in each translation unit that uses them, and the linker |
| collapses them together. The advantage of this model is that the linker |
| only has to consider the object files themselves; there is no external |
| complexity to worry about. This disadvantage is that compilation time |
| is increased because the template code is being compiled repeatedly. |
| Code written for this model tends to include definitions of all |
| templates in the header file, since they must be seen to be |
| instantiated. |
| |
| @item Cfront model |
| The AT&T C++ translator, Cfront, solved the template instantiation |
| problem by creating the notion of a template repository, an |
| automatically maintained place where template instances are stored. A |
| more modern version of the repository works as follows: As individual |
| object files are built, the compiler places any template definitions and |
| instantiations encountered in the repository. At link time, the link |
| wrapper adds in the objects in the repository and compiles any needed |
| instances that were not previously emitted. The advantages of this |
| model are more optimal compilation speed and the ability to use the |
| system linker; to implement the Borland model a compiler vendor also |
| needs to replace the linker. The disadvantages are vastly increased |
| complexity, and thus potential for error; for some code this can be |
| just as transparent, but in practice it can been very difficult to build |
| multiple programs in one directory and one program in multiple |
| directories. Code written for this model tends to separate definitions |
| of non-inline member templates into a separate file, which should be |
| compiled separately. |
| @end table |
| |
| When used with GNU ld version 2.8 or later on an ELF system such as |
| Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the |
| Borland model. On other systems, g++ implements neither automatic |
| model. |
| |
| A future version of g++ will support a hybrid model whereby the compiler |
| will emit any instantiations for which the template definition is |
| included in the compile, and store template definitions and |
| instantiation context information into the object file for the rest. |
| The link wrapper will extract that information as necessary and invoke |
| the compiler to produce the remaining instantiations. The linker will |
| then combine duplicate instantiations. |
| |
| In the mean time, you have the following options for dealing with |
| template instantiations: |
| |
| @enumerate |
| @item |
| Compile your code with @samp{-fno-implicit-templates} to disable the |
| implicit generation of template instances, and explicitly instantiate |
| all the ones you use. This approach requires more knowledge of exactly |
| which instances you need than do the others, but it's less |
| mysterious and allows greater control. You can scatter the explicit |
| instantiations throughout your program, perhaps putting them in the |
| translation units where the instances are used or the translation units |
| that define the templates themselves; you can put all of the explicit |
| instantiations you need into one big file; or you can create small files |
| like |
| |
| @example |
| #include "Foo.h" |
| #include "Foo.cc" |
| |
| template class Foo<int>; |
| template ostream& operator << |
| (ostream&, const Foo<int>&); |
| @end example |
| |
| for each of the instances you need, and create a template instantiation |
| library from those. |
| |
| If you are using Cfront-model code, you can probably get away with not |
| using @samp{-fno-implicit-templates} when compiling files that don't |
| @samp{#include} the member template definitions. |
| |
| If you use one big file to do the instantiations, you may want to |
| compile it without @samp{-fno-implicit-templates} so you get all of the |
| instances required by your explicit instantiations (but not by any |
| other files) without having to specify them as well. |
| |
| g++ has extended the template instantiation syntax outlined in the |
| Working Paper to allow forward declaration of explicit instantiations, |
| 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<int>::f (); |
| inline template class Foo<int>; |
| @end example |
| |
| @item |
| Do nothing. Pretend g++ does implement automatic instantiation |
| management. Code written for the Borland model will work fine, but |
| each translation unit will contain instances of each of the templates it |
| uses. In a large program, this can lead to an unacceptable amount of code |
| duplication. |
| |
| @item |
| Add @samp{#pragma interface} to all files containing template |
| definitions. For each of these files, add @samp{#pragma implementation |
| "@var{filename}"} to the top of some @samp{.C} file which |
| @samp{#include}s it. Then compile everything with |
| @samp{-fexternal-templates}. The templates will then only be expanded |
| in the translation unit which implements them (i.e. has a @samp{#pragma |
| implementation} line for the file where they live); all other files will |
| use external references. If you're lucky, everything should work |
| properly. If you get undefined symbol errors, you need to make sure |
| that each template instance which is used in the program is used in the |
| file which implements that template. If you don't have any use for a |
| particular instance in that file, you can just instantiate it |
| explicitly, using the syntax from the latest C++ working paper: |
| |
| @example |
| template class A<int>; |
| template ostream& operator << (ostream&, const A<int>&); |
| @end example |
| |
| This strategy will work with code written for either model. If you are |
| using code written for the Cfront model, the file containing a class |
| template and the file containing its member templates should be |
| implemented in the same translation unit. |
| |
| A slight variation on this approach is to instead use the flag |
| @samp{-falt-external-templates}; this flag causes template |
| instances to be emitted in the translation unit that implements the |
| header where they are first instantiated, rather than the one which |
| implements the file where the templates are defined. This header must |
| be the same in all translation units, or things are likely to break. |
| |
| @xref{C++ Interface,,Declarations and Definitions in One Header}, for |
| more discussion of these pragmas. |
| @end enumerate |
| |
| @node 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 |