diff options
Diffstat (limited to 'gcc/extend.texi')
| -rw-r--r-- | gcc/extend.texi | 3445 |
1 files changed, 0 insertions, 3445 deletions
diff --git a/gcc/extend.texi b/gcc/extend.texi deleted file mode 100644 index 6942629bfcd..00000000000 --- a/gcc/extend.texi +++ /dev/null @@ -1,3445 +0,0 @@ -@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; template instances -are emitted in each translation unit that uses them, and they are -collapsed together at run time. The advantage of this model is that the -linker only has to consider the object files themselves; there is no -external complexity to worry about. This disadvantage is that -compilation time is increased because the template code is being -compiled repeatedly. Code written for this model tends to include -definitions of all member templates in the header file, since they must -be seen to be compiled. - -@item Cfront model -The AT&T C++ translator, Cfront, solved the template instantiation -problem by creating the notion of a template repository, an -automatically maintained place where template instances are stored. As -individual object files are built, notes are placed in the repository to -record where templates and potential type arguments were seen so that -the subsequent instantiation step knows where to find them. At link -time, any needed instances are generated and linked in. The advantages -of this model are more optimal compilation speed and the ability to use -the system linker; to implement the Borland model a compiler vendor also -needs to replace the linker. The disadvantages are vastly increased -complexity, and thus potential for error; theoretically, this should be -just as transparent, but in practice it has been very difficult to build -multiple programs in one directory and one program in multiple -directories using Cfront. Code written for this model tends to separate -definitions of non-inline member templates into a separate file, which -is magically found by the link preprocessor when a template needs to be -instantiated. -@end table - -Currently, g++ implements neither automatic model. In the mean time, -you have three options for dealing with template instantiations: - -@enumerate -@item -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 |