diff options
Diffstat (limited to 'gnu/usr.bin/gcc/gcc.info-9')
| -rw-r--r-- | gnu/usr.bin/gcc/gcc.info-9 | 1171 |
1 files changed, 0 insertions, 1171 deletions
diff --git a/gnu/usr.bin/gcc/gcc.info-9 b/gnu/usr.bin/gcc/gcc.info-9 deleted file mode 100644 index def28724d56..00000000000 --- a/gnu/usr.bin/gcc/gcc.info-9 +++ /dev/null @@ -1,1171 +0,0 @@ -This is Info file gcc.info, produced by Makeinfo-1.63 from the input -file gcc.texi. - - This file documents the use and the internals of the GNU compiler. - - Published by the Free Software Foundation 59 Temple Place - Suite 330 -Boston, MA 02111-1307 USA - - Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software -Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the sections entitled "GNU General Public License," "Funding for -Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are -included exactly as in the original, and provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that the sections entitled "GNU General Public -License," "Funding for Free Software," and "Protect Your Freedom--Fight -`Look And Feel'", and this permission notice, may be included in -translations approved by the Free Software Foundation instead of in the -original English. - - -File: gcc.info, Node: Constructors, Next: Labeled Elements, Prev: Initializers, Up: C Extensions - -Constructor Expressions -======================= - - 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 `struct -foo' and `structure' are declared as shown: - - struct foo {int a; char b[2];} structure; - -Here is an example of constructing a `struct foo' with a constructor: - - structure = ((struct foo) {x + y, 'a', 0}); - -This is equivalent to writing the following: - - { - struct foo temp = {x + y, 'a', 0}; - structure = temp; - } - - 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: - - char **foo = (char *[]) { "x", "y", "z" }; - - 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 `switch' -statement, while the latter does the same thing an ordinary C -initializer would do. Here is an example of subscripting an array -constructor: - - output = ((int[]) { 2, x, 28 }) [input]; - - Constructor expressions for scalar types and union types are is also -allowed, but then the constructor expression is equivalent to a cast. - - -File: gcc.info, Node: Labeled Elements, Next: Cast to Union, Prev: Constructors, Up: C Extensions - -Labeled Elements 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 `[INDEX]' or `[INDEX] =' before the -element value. For example, - - int a[6] = { [4] 29, [2] = 15 }; - -is equivalent to - - int a[6] = { 0, 0, 15, 0, 29, 0 }; - -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 `[FIRST -... LAST] = VALUE'. For example, - - int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 }; - -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 `FIELDNAME:' before the element value. For example, given the -following structure, - - struct point { int x, y; }; - -the following initialization - - struct point p = { y: yvalue, x: xvalue }; - -is equivalent to - - struct point p = { xvalue, yvalue }; - - Another syntax which has the same meaning is `.FIELDNAME ='., as -shown here: - - struct point p = { .y = yvalue, .x = xvalue }; - - 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, - - union foo { int i; double d; }; - - union foo f = { d: 4 }; - -will convert 4 to a `double' to store it in the union using the second -element. By contrast, casting 4 to type `union foo' would store it -into the union as the integer `i', since it is an integer. (*Note 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, - - int a[6] = { [1] = v1, v2, [4] = v4 }; - -is equivalent to - - int a[6] = { 0, v1, v2, 0, v4, 0 }; - - Labeling the elements of an array initializer is especially useful -when the indices are characters or belong to an `enum' type. For -example: - - int whitespace[256] - = { [' '] = 1, ['\t'] = 1, ['\h'] = 1, - ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 }; - - -File: gcc.info, Node: Case Ranges, Next: Function Attributes, Prev: Cast to Union, Up: C Extensions - -Case Ranges -=========== - - You can specify a range of consecutive values in a single `case' -label, like this: - - case LOW ... HIGH: - -This has the same effect as the proper number of individual `case' -labels, one for each integer value from LOW to HIGH, inclusive. - - This feature is especially useful for ranges of ASCII character -codes: - - case 'A' ... 'Z': - - *Be careful:* Write spaces around the `...', for otherwise it may be -parsed wrong when you use it with integer values. For example, write -this: - - case 1 ... 5: - -rather than this: - - case 1...5: - - -File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Labeled Elements, Up: C Extensions - -Cast to a Union Type -==================== - - 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 `union -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. (*Note 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: - - union foo { int i; double d; }; - int x; - double y; - -both `x' and `y' can be cast to type `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: - - union foo u; - ... - u = (union foo) x == u.i = x - u = (union foo) y == u.d = y - - You can also use the union cast as a function argument: - - void hack (union foo); - ... - hack ((union foo) x); - - -File: gcc.info, Node: Function Attributes, Next: Function Prototypes, Prev: Case Ranges, Up: C Extensions - -Declaring Attributes of Functions -================================= - - 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 `__attribute__' allows you to specify special attributes -when making a declaration. This keyword is followed by an attribute -specification inside double parentheses. Eight attributes, `noreturn', -`const', `format', `section', `constructor', `destructor', `unused' and -`weak' are currently defined for functions. Other attributes, including -`section' are supported for variables declarations (*note Variable -Attributes::.) and for types (*note Type Attributes::.). - - You may also specify attributes with `__' 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 `__noreturn__' instead of `noreturn'. - -`noreturn' - A few standard library functions, such as `abort' and `exit', - cannot return. GNU CC knows this automatically. Some programs - define their own functions that never return. You can declare them - `noreturn' to tell the compiler this fact. For example, - - void fatal () __attribute__ ((noreturn)); - - void - fatal (...) - { - ... /* Print error message. */ ... - exit (1); - } - - The `noreturn' keyword tells the compiler to assume that `fatal' - cannot return. It can then optimize without regard to what would - happen if `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 `noreturn' function. - - It does not make sense for a `noreturn' function to have a return - type other than `void'. - - The attribute `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: - - typedef void voidfn (); - - volatile voidfn fatal; - -`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 `const'. For - example, - - int square (int) __attribute__ ((const)); - - says that the hypothetical function `square' is safe to call fewer - times than the program says. - - The attribute `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: - - typedef int intfn (); - - extern const intfn square; - - This approach does not work in GNU C++ from 2.6.0 on, since the - language specifies that the `const' must be attached to the return - value. - - Note that a function that has pointer arguments and examines the - data pointed to must *not* be declared `const'. Likewise, a - function that calls a non-`const' function usually must not be - `const'. It does not make sense for a `const' function to return - `void'. - -`format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)' - The `format' attribute specifies that a function takes `printf' or - `scanf' style arguments which should be type-checked against a - format string. For example, the declaration: - - extern int - my_printf (void *my_object, const char *my_format, ...) - __attribute__ ((format (printf, 2, 3))); - - causes the compiler to check the arguments in calls to `my_printf' - for consistency with the `printf' style format string argument - `my_format'. - - The parameter ARCHETYPE determines how the format string is - interpreted, and should be either `printf' or `scanf'. The - parameter STRING-INDEX specifies which argument is the format - string argument (starting from 1), while 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 `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 (`my_format') is the second - argument of the function `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 `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 `printf', `fprintf', - `sprintf', `scanf', `fscanf', `sscanf', `vprintf', `vfprintf' and - `vsprintf' whenever such warnings are requested (using - `-Wformat'), so there is no need to modify the header file - `stdio.h'. - -`section ("section-name")' - Normally, the compiler places the code it generates in the `text' - section. Sometimes, however, you need additional sections, or you - need certain particular functions to appear in special sections. - The `section' attribute specifies that a function lives in a - particular section. For example, the declaration: - - extern void foobar (void) __attribute__ ((section ("bar"))); - - puts the function `foobar' in the `bar' section. - - Some file formats do not support arbitrary sections so the - `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. - -`constructor' -`destructor' - The `constructor' attribute causes the function to be called - automatically before execution enters `main ()'. Similarly, the - `destructor' attribute causes the function to be called - automatically after `main ()' has completed or `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. - -`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. - -`weak' - The `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. - -`alias ("target")' - The `alias' attribute causes the declaration to be emitted as an - alias for another symbol, which must be specified. For instance, - - void __f () { /* do something */; } - void f () __attribute__ ((weak, alias ("__f"))); - - declares `f' to be a weak alias for `__f'. In C++, the mangled - name for the target must be used. - -`regparm (NUMBER)' - On the Intel 386, the `regparm' attribute causes the compiler to - pass up to NUMBER integer arguments in registers EAX, EDX, and 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. - -`stdcall' - On the Intel 386, the `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. - -`cdecl' - On the Intel 386, the `cdecl' attribute causes the compiler to - assume that the called function will pop off the stack space used - to pass arguments, unless it takes a variable number of arguments. - This is useful to override the effects of the `-mrtd' switch. - - 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. - - Some people object to the `__attribute__' feature, suggesting that -ANSI C's `#pragma' should be used instead. There are two reasons for -not doing this. - - 1. It is impossible to generate `#pragma' commands from a macro. - - 2. There is no telling what the same `#pragma' might mean in another - compiler. - - These two reasons apply to almost any application that might be -proposed for `#pragma'. It is basically a mistake to use `#pragma' for -*anything*. - - -File: gcc.info, Node: Function Prototypes, Next: C++ Comments, Prev: Function Attributes, Up: C Extensions - -Prototypes and Old-Style Function Definitions -============================================= - - GNU C extends ANSI C to allow a function prototype to override a -later old-style non-prototype definition. Consider the following -example: - - /* Use prototypes unless the compiler is old-fashioned. */ - #if __STDC__ - #define P(x) x - #else - #define P(x) () - #endif - - /* Prototype function declaration. */ - int isroot P((uid_t)); - - /* Old-style function definition. */ - int - isroot (x) /* ??? lossage here ??? */ - uid_t x; - { - return x == 0; - } - - Suppose the type `uid_t' happens to be `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 `int', which does not match -the prototype argument type of `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 `uid_t' type is `short', `int', or `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: - - int isroot (uid_t); - - int - isroot (uid_t x) - { - return x == 0; - } - - GNU C++ does not support old-style function definitions, so this -extension is irrelevant. - - -File: gcc.info, Node: C++ Comments, Next: Dollar Signs, Prev: Function Prototypes, Up: C Extensions - -C++ Style Comments -================== - - In GNU C, you may use C++ style comments, which start with `//' 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 `-ansi' -or `-traditional', since they are incompatible with traditional -constructs like `dividend//*comment*/divisor'. - - -File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: C++ Comments, Up: C Extensions - -Dollar Signs in Identifier Names -================================ - - In GNU C, you may use dollar signs in identifier names. This is -because many traditional C implementations allow such identifiers. - - On some machines, dollar signs are allowed in identifiers if you -specify `-traditional'. On a few systems they are allowed by default, -even if you do not use `-traditional'. But they are never allowed if -you specify `-ansi'. - - There are certain ANSI C programs (obscure, to be sure) that would -compile incorrectly if dollar signs were permitted in identifiers. For -example: - - #define foo(a) #a - #define lose(b) foo (b) - #define test$ - lose (test) - - -File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions - -The Character ESC in Constants -============================== - - You can use the sequence `\e' in a string or character constant to -stand for the ASCII character ESC. - - -File: gcc.info, Node: Alignment, Next: Inline, Prev: Type Attributes, Up: C Extensions - -Inquiring on Alignment of Types or Variables -============================================ - - The keyword `__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 `sizeof'. - - For example, if the target machine requires a `double' value to be -aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This -is true on many RISC machines. On more traditional machine designs, -`__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, -`__alignof__' reports the *recommended* alignment of a type. - - When the operand of `__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: - - struct foo { int x; char y; } foo1; - -the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as -`__alignof__ (int)', even though the data type of `foo1.y' does not -itself demand any alignment. - - A related feature which lets you specify the alignment of an object -is `__attribute__ ((aligned (ALIGNMENT)))'; see the following section. - - -File: gcc.info, Node: Variable Attributes, Next: Type Attributes, Prev: Character Escapes, Up: C Extensions - -Specifying Attributes of Variables -================================== - - The keyword `__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: `aligned', `mode', `nocommon', -`packed', `section', `transparent_union', `unused', and `weak'. Other -attributes are available for functions (*note Function Attributes::.) -and for types (*note Type Attributes::.). - - You may also specify attributes with `__' 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 `__aligned__' instead of `aligned'. - -`aligned (ALIGNMENT)' - This attribute specifies a minimum alignment for the variable or - structure field, measured in bytes. For example, the declaration: - - int x __attribute__ ((aligned (16))) = 0; - - causes the compiler to allocate the global variable `x' on a - 16-byte boundary. On a 68040, this could be used in conjunction - with an `asm' expression to access the `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 `int' pair, you could - write: - - struct foo { int x[2] __attribute__ ((aligned (8))); }; - - This is an alternative to creating a union with a `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: - - short array[3] __attribute__ ((aligned)); - - Whenever you leave out the alignment factor in an `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 `aligned' attribute can only increase the alignment; but you - can decrease it by specifying `packed' as well. See below. - - Note that the effectiveness of `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 `aligned(16)' in an `__attribute__' will still - only provide you with 8 byte alignment. See your linker - documentation for further information. - -`mode (MODE)' - This attribute specifies the data type for the - declaration--whichever type corresponds to the mode MODE. This in - effect lets you request an integer or floating point type - according to its width. - - You may also specify a mode of `byte' or `__byte__' to indicate - the mode corresponding to a one-byte integer, `word' or `__word__' - for the mode of a one-word integer, and `pointer' or `__pointer__' - for the mode used to represent pointers. - -`nocommon' - This attribute specifies requests GNU CC not to place a variable - "common" but instead to allocate space for it directly. If you - specify the `-fno-common' flag, GNU CC will do this for all - variables. - - Specifying the `nocommon' attribute for a variable provides an - initialization of zeros. A variable may only be initialized in one - source file. - -`packed' - The `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 `aligned' attribute. - - Here is a structure in which the field `x' is packed, so that it - immediately follows `a': - - struct foo - { - char a; - int x[2] __attribute__ ((packed)); - }; - -`section ("section-name")' - Normally, the compiler places the objects it generates in sections - like `data' and `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 - `section' attribute specifies that a variable (or function) lives - in a particular section. For example, this small program uses - several specific section names: - - struct duart a __attribute__ ((section ("DUART_A"))) = { 0 }; - struct duart b __attribute__ ((section ("DUART_B"))) = { 0 }; - char stack[10000] __attribute__ ((section ("STACK"))) = { 0 }; - int init_data_copy __attribute__ ((section ("INITDATACOPY"))) = 0; - - main() - { - /* Initialize stack pointer */ - init_sp (stack + sizeof (stack)); - - /* Initialize initialized data */ - memcpy (&init_data_copy, &data, &edata - &data); - - /* Turn on the serial ports */ - init_duart (&a); - init_duart (&b); - } - - Use the `section' attribute with an *initialized* definition of a - *global* variable, as shown in the example. GNU CC issues a - warning and otherwise ignores the `section' attribute in - uninitialized variable declarations. - - You may only use the `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 `common' (or `bss') - section and can be multiply "defined". You can force a variable - to be initialized with the `-fno-common' flag or the `nocommon' - attribute. - - Some file formats do not support arbitrary sections so the - `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. - -`transparent_union' - This attribute, attached to a function argument variable which is a - union, means to pass the argument in the same way that the first - union member would be passed. You can also use this attribute on a - `typedef' for a union data type; then it applies to all function - arguments with that type. - -`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. - -`weak' - The `weak' attribute is described in *Note Function Attributes::. - - To specify multiple attributes, separate them by commas within the -double parentheses: for example, `__attribute__ ((aligned (16), -packed))'. - - -File: gcc.info, Node: Type Attributes, Next: Alignment, Prev: Variable Attributes, Up: C Extensions - -Specifying Attributes of Types -============================== - - The keyword `__attribute__' allows you to specify special attributes -of `struct' and `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: `aligned', `packed', -and `transparent_union'. Other attributes are defined for functions -(*note Function Attributes::.) and for variables (*note Variable -Attributes::.). - - You may also specify any one of these attributes with `__' 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 `__aligned__' instead of `aligned'. - - You may specify the `aligned' and `transparent_union' attributes -either in a `typedef' declaration or just past the closing curly brace -of a complete enum, struct or union type *definition* and the `packed' -attribute only past the closing brace of a definition. - -`aligned (ALIGNMENT)' - This attribute specifies a minimum alignment (in bytes) for - variables of the specified type. For example, the declarations: - - struct S { short f[3]; } __attribute__ ((aligned (8)); - typedef int more_aligned_int __attribute__ ((aligned (8)); - - force the compiler to insure (as fas as it can) that each variable - whose type is `struct S' or `more_aligned_int' will be allocated - and aligned *at least* on a 8-byte boundary. On a Sparc, having - all variables of type `struct S' aligned to 8-byte boundaries - allows the compiler to use the `ldd' and `std' (doubleword load and - store) instructions when copying one variable of type `struct S' to - another, thus improving run-time efficiency. - - Note that the alignment of any given `struct' or `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 `struct' or `union' in question. This means that - you *can* effectively adjust the alignment of a `struct' or `union' - type by attaching an `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 `struct' or `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 - `struct' or `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: - - struct S { short f[3]; } __attribute__ ((aligned)); - - Whenever you leave out the alignment factor in an `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 `short' is 2 bytes, then - the size of the entire `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 `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 `aligned' attribute can only increase the alignment; but you - can decrease it by specifying `packed' as well. See below. - - Note that the effectiveness of `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 `aligned(16)' in an `__attribute__' will still - only provide you with 8 byte alignment. See your linker - documentation for further information. - -`packed' - This attribute, attached to an `enum', `struct', or `union' type - definition, specified that the minimum required memory be used to - represent the type. - - Specifying this attribute for `struct' and `union' types is - equivalent to specifying the `packed' attribute on each of the - structure or union members. Specifying the `-fshort-enums' flag - on the line is equivalent to specifying the `packed' attribute on - all `enum' definitions. - - You may only specify this attribute after a closing curly brace on - an `enum' definition, not in a `typedef' declaration. - -`transparent_union' - This attribute, attached to a `union' type definition, indicates - that any variable having that union type should, if passed to a - function, be passed in the same way that the first union member - would be passed. For example: - - union foo - { - char a; - int x[2]; - } __attribute__ ((transparent_union)); - - To specify multiple attributes, separate them by commas within the -double parentheses: for example, `__attribute__ ((aligned (16), -packed))'. - - -File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions - -An Inline Function is As Fast As a Macro -======================================== - - By declaring a function `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 `-O', no function is really inline. - - To declare a function inline, use the `inline' keyword in its -declaration, like this: - - inline int - inc (int *a) - { - (*a)++; - } - - (If you are writing a header file to be included in ANSI C programs, -write `__inline__' instead of `inline'. *Note Alternate Keywords::.) - - You can also make all "simple enough" functions inline with the -option `-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 `inline' keyword -does not affect the linkage of the function. - - GNU CC automatically inlines member functions defined within the -class body of C++ programs even if they are not explicitly declared -`inline'. (You can override this with `-fno-default-inline'; *note -Options Controlling C++ Dialect: C++ Dialect Options..) - - When a function is both inline and `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 `-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. - - When an inline function is not `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-`static' inline function is always -compiled on its own in the usual fashion. - - If you specify both `inline' and `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 `inline' and `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 `inline' and `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. - - -File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: C Extensions - -Assembler Instructions with C Expression Operands -================================================= - - In an assembler instruction using `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 `fsinx' instruction: - - asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); - -Here `angle' is the C expression for the input operand while `result' -is that of the output operand. Each has `"f"' as its operand -constraint, saying that a floating point register is required. The `=' -in `=f' indicates that the operand is an output; all output operands' -constraints must use `='. The constraints use the same language used -in the machine description (*note 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 `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 `asm', and then store -that register into the output. - - The output operands must be write-only; GNU CC will assume that the -values in these operands before the instruction are dead and need not be -generated. Extended asm does not support input-output or read-write -operands. For this reason, the constraint character `+', which -indicates such an operand, may not be used. - - When the assembler instruction has a read-write operand, or an -operand in which only some of the bits are to be changed, you must -logically split its function into two separate operands, one input -operand and one write-only output operand. The connection between them -is expressed by constraints which say they need to be in the same -location when the instruction executes. You can use the same C -expression for both operands, or different expressions. For example, -here we write the (fictitious) `combine' instruction with `bar' as its -read-only source operand and `foo' as its read-write destination: - - asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); - -The constraint `"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 `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: - - asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); - - 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 `foo' in one -register and use it for operand 1, but generate the output operand 0 in -a different register (copying it afterward to `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: - - asm volatile ("movc3 %0,%1,%2" - : /* no outputs */ - : "g" (from), "g" (to), "g" (count) - : "r0", "r1", "r2", "r3", "r4", "r5"); - - 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 `%'; to produce one `%' -in the assembler code, you must write `%%' in the input. - - If your assembler instruction can alter the condition code register, -add `cc' to the list of clobbered registers. GNU CC on some machines -represents the condition codes as a specific hardware register; `cc' -serves to name this register. On other machines, the condition code is -handled differently, and specifying `cc' has no effect. But it is -valid no matter what the machine. - - If your assembler instruction modifies memory in an unpredictable -fashion, add `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 -`asm' template, separated either with newlines (written as `\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 -`_foo' accepts arguments in registers 9 and 10: - - asm ("movl %0,r9;movl %1,r10;call _foo" - : /* no outputs */ - : "g" (from), "g" (to) - : "r9", "r10"); - - Unless an output operand has the `&' 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 `&' for each output -operand that may not overlap an input. *Note Modifiers::. - - If you want to test the condition code produced by an assembler -instruction, you must include a branch and a label in the `asm' -construct, as follows: - - asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:" - : "g" (result) - : "g" (input)); - -This assumes your assembler supports local labels, as the GNU assembler -and most Unix assemblers do. - - Speaking of labels, jumps from one `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. - - Usually the most convenient way to use these `asm' instructions is to -encapsulate them in macros that look like functions. For example, - - #define sin(x) \ - ({ double __value, __arg = (x); \ - asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ - __value; }) - -Here the variable `__arg' is used to make sure that the instruction -operates on a proper `double' value, and to accept only those arguments -`x' which can convert automatically to a `double'. - - Another way to make sure the instruction operates on the correct -data type is to use a cast in the `asm'. This is different from using a -variable `__arg' in that it converts more different types. For -example, if the desired type were `int', casting the argument to `int' -would accept a pointer with no complaint, while assigning the argument -to an `int' variable named `__arg' would warn about using a pointer -unless the caller explicitly casts it. - - If an `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 `asm' instruction from being deleted, moved -significantly, or combined, by writing the keyword `volatile' after the -`asm'. For example: - - #define set_priority(x) \ - asm volatile ("set_priority %0": /* no outputs */ : "g" (x)) - -An instruction without output operands will not be deleted or moved -significantly, regardless, unless it is unreachable. - - Note that even a volatile `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 `asm' -instructions to remain perfectly consecutive. If you want consecutive -output, use a single `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 `__asm__' instead of `asm'. *Note Alternate Keywords::. - |