|
|
1.1.1.5 ! root 1: This is Info file gcc.info, produced by Makeinfo-1.54 from the input 1.1 root 2: file gcc.texi. 3: 4: This file documents the use and the internals of the GNU compiler. 5: 1.1.1.5 ! root 6: Published by the Free Software Foundation 675 Massachusetts Avenue ! 7: Cambridge, MA 02139 USA ! 8: ! 9: Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc. 1.1 root 10: 1.1.1.3 root 11: Permission is granted to make and distribute verbatim copies of this 12: manual provided the copyright notice and this permission notice are 13: preserved on all copies. 1.1 root 14: 15: Permission is granted to copy and distribute modified versions of 16: this manual under the conditions for verbatim copying, provided also 1.1.1.4 root 17: that the sections entitled "GNU General Public License" and "Protect 18: Your Freedom--Fight `Look And Feel'" are included exactly as in the 19: original, and provided that the entire resulting derived work is 20: distributed under the terms of a permission notice identical to this 21: one. 1.1 root 22: 23: Permission is granted to copy and distribute translations of this 24: manual into another language, under the above conditions for modified 1.1.1.3 root 25: versions, except that the sections entitled "GNU General Public 1.1.1.4 root 26: License" and "Protect Your Freedom--Fight `Look And Feel'", and this 27: permission notice, may be included in translations approved by the Free 28: Software Foundation instead of in the original English. 1.1.1.3 root 29: 30: 1.1.1.5 ! root 31: File: gcc.info, Node: Case Ranges, Next: Function Attributes, Prev: Cast to Union, Up: C Extensions 1.1.1.3 root 32: 1.1.1.5 ! root 33: Case Ranges ! 34: =========== 1.1.1.3 root 35: 1.1.1.5 ! root 36: You can specify a range of consecutive values in a single `case' ! 37: label, like this: 1.1.1.4 root 38: 1.1.1.5 ! root 39: case LOW ... HIGH: 1.1.1.2 root 40: 1.1.1.5 ! root 41: This has the same effect as the proper number of individual `case' ! 42: labels, one for each integer value from LOW to HIGH, inclusive. ! 43: ! 44: This feature is especially useful for ranges of ASCII character ! 45: codes: ! 46: ! 47: case 'A' ... 'Z': ! 48: ! 49: *Be careful:* Write spaces around the `...', for otherwise it may be ! 50: parsed wrong when you use it with integer values. For example, write ! 51: this: ! 52: ! 53: case 1 ... 5: 1.1.1.2 root 54: 1.1.1.5 ! root 55: rather than this: ! 56: ! 57: case 1...5: ! 58: ! 59: *Warning to C++ users:* When compiling C++, you must write two dots ! 60: `..' rather than three to specify a range in case statements, thus: ! 61: ! 62: case 'A' .. 'Z': ! 63: ! 64: This is an anachronism in the GNU C++ front end, and will be ! 65: rectified in a future release. 1.1.1.2 root 66: 67: 1.1.1.5 ! root 68: File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Labeled Elements, Up: C Extensions 1.1.1.2 root 69: 1.1.1.5 ! root 70: Cast to a Union Type ! 71: ==================== 1.1.1.2 root 72: 1.1.1.5 ! root 73: A cast to union type is similar to other casts, except that the type ! 74: specified is a union type. You can specify the type either with `union ! 75: TAG' or with a typedef name. A cast to union is actually a constructor ! 76: though, not a cast, and hence does not yield an lvalue like normal ! 77: casts. (*Note Constructors::.) ! 78: ! 79: The types that may be cast to the union type are those of the members ! 80: of the union. Thus, given the following union and variables: ! 81: ! 82: union foo { int i; double d; }; ! 83: int x; ! 84: double y; ! 85: ! 86: both `x' and `y' can be cast to type `union' foo. ! 87: ! 88: Using the cast as the right-hand side of an assignment to a variable ! 89: of union type is equivalent to storing in a member of the union: ! 90: ! 91: union foo u; ! 92: ... ! 93: u = (union foo) x == u.i = x ! 94: u = (union foo) y == u.d = y ! 95: ! 96: You can also use the union cast as a function argument: ! 97: ! 98: void hack (union foo); ! 99: ... ! 100: hack ((union foo) x); 1.1.1.2 root 101: 1.1.1.5 ! root 102: ! 103: File: gcc.info, Node: Function Attributes, Next: Function Prototypes, Prev: Case Ranges, Up: C Extensions 1.1.1.4 root 104: 1.1.1.5 ! root 105: Declaring Attributes of Functions ! 106: ================================= 1.1.1.4 root 107: 1.1.1.5 ! root 108: In GNU C, you declare certain things about functions called in your ! 109: program which help the compiler optimize function calls. 1.1.1.4 root 110: 1.1.1.5 ! root 111: A few standard library functions, such as `abort' and `exit', cannot ! 112: return. GNU CC knows this automatically. Some programs define their ! 113: own functions that never return. You can declare them `volatile' to ! 114: tell the compiler this fact. For example, ! 115: ! 116: extern void volatile fatal (); ! 117: ! 118: void ! 119: fatal (...) ! 120: { ! 121: ... /* Print error message. */ ... ! 122: exit (1); ! 123: } ! 124: ! 125: The `volatile' keyword tells the compiler to assume that `fatal' ! 126: cannot return. This makes slightly better code, but more importantly ! 127: it helps avoid spurious warnings of uninitialized variables. ! 128: ! 129: It does not make sense for a `volatile' function to have a return ! 130: type other than `void'. ! 131: ! 132: Many functions do not examine any values except their arguments, and ! 133: have no effects except the return value. Such a function can be subject ! 134: to common subexpression elimination and loop optimization just as an ! 135: arithmetic operator would be. These functions should be declared ! 136: `const'. For example, ! 137: ! 138: extern int const square (); ! 139: ! 140: says that the hypothetical function `square' is safe to call fewer ! 141: times than the program says. ! 142: ! 143: Note that a function that has pointer arguments and examines the data ! 144: pointed to must *not* be declared `const'. Likewise, a function that ! 145: calls a non-`const' function usually must not be `const'. It does not ! 146: make sense for a `const' function to return `void'. ! 147: ! 148: We recommend placing the keyword `const' after the function's return ! 149: type. It makes no difference in the example above, but when the return ! 150: type is a pointer, it is the only way to make the function itself ! 151: const. For example, ! 152: ! 153: const char *mincp (int); ! 154: ! 155: says that `mincp' returns `const char *'--a pointer to a const object. ! 156: To declare `mincp' const, you must write this: ! 157: ! 158: char * const mincp (int); ! 159: ! 160: Some people object to this feature, suggesting that ANSI C's ! 161: `#pragma' should be used instead. There are two reasons for not doing ! 162: this. ! 163: ! 164: 1. It is impossible to generate `#pragma' commands from a macro. ! 165: ! 166: 2. The `#pragma' command is just as likely as these keywords to mean ! 167: something else in another compiler. ! 168: ! 169: These two reasons apply to almost any application that might be ! 170: proposed for `#pragma'. It is basically a mistake to use `#pragma' for ! 171: *anything*. ! 172: ! 173: The keyword `__attribute__' allows you to specify special attributes ! 174: when making a declaration. This keyword is followed by an attribute ! 175: specification inside double parentheses. One attribute, `format', is ! 176: currently defined for functions. Others are implemented for variables ! 177: and structure fields (*note Function Attributes::.). ! 178: ! 179: `format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)' ! 180: The `format' attribute specifies that a function takes `printf' or ! 181: `scanf' style arguments which should be type-checked against a ! 182: format string. For example, the declaration: ! 183: ! 184: extern int ! 185: my_printf (void *my_object, const char *my_format, ...) ! 186: __attribute__ ((format (printf, 2, 3))); ! 187: ! 188: causes the compiler to check the arguments in calls to `my_printf' ! 189: for consistency with the `printf' style format string argument ! 190: `my_format'. ! 191: ! 192: The parameter ARCHETYPE determines how the format string is ! 193: interpreted, and should be either `printf' or `scanf'. The ! 194: parameter STRING-INDEX specifies which argument is the format ! 195: string argument (starting from 1), while FIRST-TO-CHECK is the ! 196: number of the first argument to check against the format string. ! 197: For functions where the arguments are not available to be checked ! 198: (such as `vprintf'), specify the third parameter as zero. In this ! 199: case the compiler only checks the format string for consistency. ! 200: ! 201: In the example above, the format string (`my_format') is the second ! 202: argument of the function `my_print', and the arguments to check ! 203: start with the third argument, so the correct parameters for the ! 204: format attribute are 2 and 3. ! 205: ! 206: The `format' attribute allows you to identify your own functions ! 207: which take format strings as arguments, so that GNU CC can check ! 208: the calls to these functions for errors. The compiler always ! 209: checks formats for the ANSI library functions `printf', `fprintf', ! 210: `sprintf', `scanf', `fscanf', `sscanf', `vprintf', `vfprintf' and ! 211: `vsprintf' whenever such warnings are requested (using ! 212: `-Wformat'), so there is no need to modify the header file ! 213: `stdio.h'. 1.1.1.4 root 214: 1.1.1.5 ! root 215: ! 216: File: gcc.info, Node: Function Prototypes, Next: Dollar Signs, Prev: Function Attributes, Up: C Extensions 1.1.1.4 root 217: 1.1.1.5 ! root 218: Prototypes and Old-Style Function Definitions ! 219: ============================================= 1.1.1.4 root 220: 1.1.1.5 ! root 221: GNU C extends ANSI C to allow a function prototype to override a ! 222: later old-style non-prototype definition. Consider the following ! 223: example: ! 224: ! 225: /* Use prototypes unless the compiler is old-fashioned. */ ! 226: #if __STDC__ ! 227: #define P(x) (x) ! 228: #else ! 229: #define P(x) () ! 230: #endif ! 231: ! 232: /* Prototype function declaration. */ ! 233: int isroot P((uid_t)); ! 234: ! 235: /* Old-style function definition. */ ! 236: int ! 237: isroot (x) /* ??? lossage here ??? */ ! 238: uid_t x; ! 239: { ! 240: return x == 0; ! 241: } ! 242: ! 243: Suppose the type `uid_t' happens to be `short'. ANSI C does not ! 244: allow this example, because subword arguments in old-style ! 245: non-prototype definitions are promoted. Therefore in this example the ! 246: function definition's argument is really an `int', which does not match ! 247: the prototype argument type of `short'. ! 248: ! 249: This restriction of ANSI C makes it hard to write code that is ! 250: portable to traditional C compilers, because the programmer does not ! 251: know whether the `uid_t' type is `short', `int', or `long'. Therefore, ! 252: in cases like these GNU C allows a prototype to override a later ! 253: old-style definition. More precisely, in GNU C, a function prototype ! 254: argument type overrides the argument type specified by a later ! 255: old-style definition if the former type is the same as the latter type ! 256: before promotion. Thus in GNU C the above example is equivalent to the ! 257: following: ! 258: ! 259: int isroot (uid_t); ! 260: ! 261: int ! 262: isroot (uid_t x) ! 263: { ! 264: return x == 0; ! 265: } 1.1.1.4 root 266: 1.1.1.5 ! root 267: ! 268: File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: Function Prototypes, Up: C Extensions 1.1.1.4 root 269: 1.1.1.5 ! root 270: Dollar Signs in Identifier Names ! 271: ================================ 1.1.1.4 root 272: 1.1.1.5 ! root 273: In GNU C, you may use dollar signs in identifier names. This is ! 274: because many traditional C implementations allow such identifiers. 1.1.1.4 root 275: 1.1.1.5 ! root 276: On some machines, dollar signs are allowed in identifiers if you ! 277: specify `-traditional'. On a few systems they are allowed by default, ! 278: even if you do not use `-traditional'. But they are never allowed if ! 279: you specify `-ansi'. ! 280: ! 281: There are certain ANSI C programs (obscure, to be sure) that would ! 282: compile incorrectly if dollar signs were permitted in identifiers. For ! 283: example: ! 284: ! 285: #define foo(a) #a ! 286: #define lose(b) foo (b) ! 287: #define test$ ! 288: lose (test) 1.1.1.2 root 289: 290: 1.1.1.5 ! root 291: File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions 1.1 root 292: 1.1.1.5 ! root 293: The Character ESC in Constants ! 294: ============================== ! 295: ! 296: You can use the sequence `\e' in a string or character constant to ! 297: stand for the ASCII character ESC. 1.1 root 298: 1.1.1.5 ! root 299: ! 300: File: gcc.info, Node: Alignment, Next: Inline, Prev: Variable Attributes, Up: C Extensions 1.1.1.4 root 301: 1.1.1.5 ! root 302: Inquiring on Alignment of Types or Variables ! 303: ============================================ 1.1.1.4 root 304: 1.1.1.5 ! root 305: The keyword `__alignof__' allows you to inquire about how an object ! 306: is aligned, or the minimum alignment usually required by a type. Its ! 307: syntax is just like `sizeof'. ! 308: ! 309: For example, if the target machine requires a `double' value to be ! 310: aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This ! 311: is true on many RISC machines. On more traditional machine designs, ! 312: `__alignof__ (double)' is 4 or even 2. ! 313: ! 314: Some machines never actually require alignment; they allow reference ! 315: to any data type even at an odd addresses. For these machines, ! 316: `__alignof__' reports the *recommended* alignment of a type. ! 317: ! 318: When the operand of `__alignof__' is an lvalue rather than a type, ! 319: the value is the largest alignment that the lvalue is known to have. ! 320: It may have this alignment as a result of its data type, or because it ! 321: is part of a structure and inherits alignment from that structure. For ! 322: example, after this declaration: ! 323: ! 324: struct foo { int x; char y; } foo1; ! 325: ! 326: the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as ! 327: `__alignof__ (int)', even though the data type of `foo1.y' does not ! 328: itself demand any alignment. 1.1.1.4 root 329: 1.1.1.5 ! root 330: A related feature which lets you specify the alignment of an object ! 331: is `__attribute__ ((aligned (ALIGNMENT)))'; see the following section. 1.1.1.4 root 332: 1.1.1.5 ! root 333: ! 334: File: gcc.info, Node: Variable Attributes, Next: Alignment, Prev: Character Escapes, Up: C Extensions 1.1.1.4 root 335: 1.1.1.5 ! root 336: Specifying Attributes of Variables ! 337: ================================== 1.1.1.4 root 338: 1.1.1.5 ! root 339: The keyword `__attribute__' allows you to specify special attributes ! 340: of variables or structure fields. This keyword is followed by an ! 341: attribute specification inside double parentheses. Four attributes are ! 342: currently defined: `aligned', `format', `mode' and `packed'. `format' ! 343: is used for functions, and thus not documented here; see *Note Function ! 344: Attributes::. ! 345: ! 346: `aligned (ALIGNMENT)' ! 347: This attribute specifies a minimum alignment for the variable or ! 348: structure field, measured in bytes. For example, the declaration: ! 349: ! 350: int x __attribute__ ((aligned (16))) = 0; ! 351: ! 352: causes the compiler to allocate the global variable `x' on a ! 353: 16-byte boundary. On a 68040, this could be used in conjunction ! 354: with an `asm' expression to access the `move16' instruction which ! 355: requires 16-byte aligned operands. ! 356: ! 357: You can also specify the alignment of structure fields. For ! 358: example, to create a double-word aligned `int' pair, you could ! 359: write: ! 360: ! 361: struct foo { int x[2] __attribute__ ((aligned (8))); }; ! 362: ! 363: This is an alternative to creating a union with a `double' member ! 364: that forces the union to be double-word aligned. ! 365: ! 366: It is not possible to specify the alignment of functions; the ! 367: alignment of functions is determined by the machine's requirements ! 368: and cannot be changed. You cannot specify alignment for a typedef ! 369: name because such a name is just an alias, not a distinct type. ! 370: ! 371: The `aligned' attribute can only increase the alignment; but you ! 372: can decrease it by specifying `packed' as well. See below. ! 373: ! 374: The linker of your operating system imposes a maximum alignment. ! 375: If the linker aligns each object file on a four byte boundary, ! 376: then it is beyond the compiler's power to cause anything to be ! 377: aligned to a larger boundary than that. For example, if the ! 378: linker happens to put this object file at address 136 (eight more ! 379: than a multiple of 64), then the compiler cannot guarantee an ! 380: alignment of more than 8 just by aligning variables in the object ! 381: file. ! 382: ! 383: `mode (MODE)' ! 384: This attribute specifies the data type for the ! 385: declaration--whichever type corresponds to the mode MODE. This in ! 386: effect lets you request an integer or floating point type ! 387: according to its width. ! 388: ! 389: `packed' ! 390: The `packed' attribute specifies that a variable or structure field ! 391: should have the smallest possible alignment--one byte for a ! 392: variable, and one bit for a field, unless you specify a larger ! 393: value with the `aligned' attribute. 1.1.1.4 root 394: 1.1.1.5 ! root 395: ! 396: File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions 1.1.1.4 root 397: 1.1.1.5 ! root 398: An Inline Function is As Fast As a Macro ! 399: ======================================== ! 400: ! 401: By declaring a function `inline', you can direct GNU CC to integrate ! 402: that function's code into the code for its callers. This makes ! 403: execution faster by eliminating the function-call overhead; in ! 404: addition, if any of the actual argument values are constant, their known ! 405: values may permit simplifications at compile time so that not all of the ! 406: inline function's code needs to be included. The effect on code size is ! 407: less predictable; object code may be larger or smaller with function ! 408: inlining, depending on the particular case. Inlining of functions is an ! 409: optimization and it really "works" only in optimizing compilation. If ! 410: you don't use `-O', no function is really inline. ! 411: ! 412: To declare a function inline, use the `inline' keyword in its ! 413: declaration, like this: ! 414: ! 415: inline int ! 416: inc (int *a) ! 417: { ! 418: (*a)++; ! 419: } ! 420: ! 421: (If you are writing a header file to be included in ANSI C programs, ! 422: write `__inline__' instead of `inline'. *Note Alternate Keywords::.) ! 423: ! 424: You can also make all "simple enough" functions inline with the ! 425: option `-finline-functions'. Note that certain usages in a function ! 426: definition can make it unsuitable for inline substitution. ! 427: ! 428: For C++ programs, GNU CC automatically inlines member functions even ! 429: if they are not explicitly declared `inline'. (You can override this ! 430: with `-fno-default-inline'; *note Options Controlling C++ Dialect: C++ ! 431: Dialect Options..) ! 432: ! 433: When a function is both inline and `static', if all calls to the ! 434: function are integrated into the caller, and the function's address is ! 435: never used, then the function's own assembler code is never referenced. ! 436: In this case, GNU CC does not actually output assembler code for the ! 437: function, unless you specify the option `-fkeep-inline-functions'. ! 438: Some calls cannot be integrated for various reasons (in particular, ! 439: calls that precede the function's definition cannot be integrated, and ! 440: neither can recursive calls within the definition). If there is a ! 441: nonintegrated call, then the function is compiled to assembler code as ! 442: usual. The function must also be compiled as usual if the program ! 443: refers to its address, because that can't be inlined. ! 444: ! 445: When an inline function is not `static', then the compiler must ! 446: assume that there may be calls from other source files; since a global ! 447: symbol can be defined only once in any program, the function must not ! 448: be defined in the other source files, so the calls therein cannot be ! 449: integrated. Therefore, a non-`static' inline function is always ! 450: compiled on its own in the usual fashion. ! 451: ! 452: If you specify both `inline' and `extern' in the function ! 453: definition, then the definition is used only for inlining. In no case ! 454: is the function compiled on its own, not even if you refer to its ! 455: address explicitly. Such an address becomes an external reference, as ! 456: if you had only declared the function, and had not defined it. ! 457: ! 458: This combination of `inline' and `extern' has almost the effect of a ! 459: macro. The way to use it is to put a function definition in a header ! 460: file with these keywords, and put another copy of the definition ! 461: (lacking `inline' and `extern') in a library file. The definition in ! 462: the header file will cause most calls to the function to be inlined. ! 463: If any uses of the function remain, they will refer to the single copy ! 464: in the library. ! 465: ! 466: GNU C does not inline any functions when not optimizing. It is not ! 467: clear whether it is better to inline or not, in this case, but we found ! 468: that a correct implementation when not optimizing was difficult. So we ! 469: did the easy thing, and turned it off. 1.1 root 470: 471: 1.1.1.5 ! root 472: File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: C Extensions ! 473: ! 474: Assembler Instructions with C Expression Operands ! 475: ================================================= ! 476: ! 477: In an assembler instruction using `asm', you can now specify the ! 478: operands of the instruction using C expressions. This means no more ! 479: guessing which registers or memory locations will contain the data you ! 480: want to use. ! 481: ! 482: You must specify an assembler instruction template much like what ! 483: appears in a machine description, plus an operand constraint string for ! 484: each operand. ! 485: ! 486: For example, here is how to use the 68881's `fsinx' instruction: ! 487: ! 488: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); ! 489: ! 490: Here `angle' is the C expression for the input operand while `result' ! 491: is that of the output operand. Each has `"f"' as its operand ! 492: constraint, saying that a floating point register is required. The `=' ! 493: in `=f' indicates that the operand is an output; all output operands' ! 494: constraints must use `='. The constraints use the same language used ! 495: in the machine description (*note Constraints::.). ! 496: ! 497: Each operand is described by an operand-constraint string followed ! 498: by the C expression in parentheses. A colon separates the assembler ! 499: template from the first output operand, and another separates the last ! 500: output operand from the first input, if any. Commas separate output ! 501: operands and separate inputs. The total number of operands is limited ! 502: to ten or to the maximum number of operands in any instruction pattern ! 503: in the machine description, whichever is greater. ! 504: ! 505: If there are no output operands, and there are input operands, then ! 506: there must be two consecutive colons surrounding the place where the ! 507: output operands would go. ! 508: ! 509: Output operand expressions must be lvalues; the compiler can check ! 510: this. The input operands need not be lvalues. The compiler cannot ! 511: check whether the operands have data types that are reasonable for the ! 512: instruction being executed. It does not parse the assembler ! 513: instruction template and does not know what it means, or whether it is ! 514: valid assembler input. The extended `asm' feature is most often used ! 515: for machine instructions that the compiler itself does not know exist. ! 516: ! 517: The output operands must be write-only; GNU CC will assume that the ! 518: values in these operands before the instruction are dead and need not be ! 519: generated. Extended asm does not support input-output or read-write ! 520: operands. For this reason, the constraint character `+', which ! 521: indicates such an operand, may not be used. ! 522: ! 523: When the assembler instruction has a read-write operand, or an ! 524: operand in which only some of the bits are to be changed, you must ! 525: logically split its function into two separate operands, one input ! 526: operand and one write-only output operand. The connection between them ! 527: is expressed by constraints which say they need to be in the same ! 528: location when the instruction executes. You can use the same C ! 529: expression for both operands, or different expressions. For example, ! 530: here we write the (fictitious) `combine' instruction with `bar' as its ! 531: read-only source operand and `foo' as its read-write destination: ! 532: ! 533: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); ! 534: ! 535: The constraint `"0"' for operand 1 says that it must occupy the same ! 536: location as operand 0. A digit in constraint is allowed only in an ! 537: input operand, and it must refer to an output operand. ! 538: ! 539: Only a digit in the constraint can guarantee that one operand will ! 540: be in the same place as another. The mere fact that `foo' is the value ! 541: of both operands is not enough to guarantee that they will be in the ! 542: same place in the generated assembler code. The following would not ! 543: work: ! 544: ! 545: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); ! 546: ! 547: Various optimizations or reloading could cause operands 0 and 1 to ! 548: be in different registers; GNU CC knows no reason not to do so. For ! 549: example, the compiler might find a copy of the value of `foo' in one ! 550: register and use it for operand 1, but generate the output operand 0 in ! 551: a different register (copying it afterward to `foo''s own address). Of ! 552: course, since the register for operand 1 is not even mentioned in the ! 553: assembler code, the result will not work, but GNU CC can't tell that. ! 554: ! 555: Some instructions clobber specific hard registers. To describe ! 556: this, write a third colon after the input operands, followed by the ! 557: names of the clobbered hard registers (given as strings). Here is a ! 558: realistic example for the Vax: ! 559: ! 560: asm volatile ("movc3 %0,%1,%2" ! 561: : /* no outputs */ ! 562: : "g" (from), "g" (to), "g" (count) ! 563: : "r0", "r1", "r2", "r3", "r4", "r5"); ! 564: ! 565: If you refer to a particular hardware register from the assembler ! 566: code, then you will probably have to list the register after the third ! 567: colon to tell the compiler that the register's value is modified. In ! 568: many assemblers, the register names begin with `%'; to produce one `%' ! 569: in the assembler code, you must write `%%' in the input. ! 570: ! 571: If your assembler instruction can alter the condition code register, ! 572: add `cc' to the list of clobbered registers. GNU CC on some machines ! 573: represents the condition codes as a specific hardware register; `cc' ! 574: serves to name this register. On other machines, the condition code is ! 575: handled differently, and specifying `cc' has no effect. But it is ! 576: valid no matter what the machine. ! 577: ! 578: If your assembler instruction modifies memory in an unpredictable ! 579: fashion, add `memory' to the list of clobbered registers. This will ! 580: cause GNU CC to not keep memory values cached in registers across the ! 581: assembler instruction. ! 582: ! 583: You can put multiple assembler instructions together in a single ! 584: `asm' template, separated either with newlines (written as `\n') or with ! 585: semicolons if the assembler allows such semicolons. The GNU assembler ! 586: allows semicolons and all Unix assemblers seem to do so. The input ! 587: operands are guaranteed not to use any of the clobbered registers, and ! 588: neither will the output operands' addresses, so you can read and write ! 589: the clobbered registers as many times as you like. Here is an example ! 590: of multiple instructions in a template; it assumes that the subroutine ! 591: `_foo' accepts arguments in registers 9 and 10: ! 592: ! 593: asm ("movl %0,r9;movl %1,r10;call _foo" ! 594: : /* no outputs */ ! 595: : "g" (from), "g" (to) ! 596: : "r9", "r10"); ! 597: ! 598: Unless an output operand has the `&' constraint modifier, GNU CC may ! 599: allocate it in the same register as an unrelated input operand, on the ! 600: assumption that the inputs are consumed before the outputs are produced. ! 601: This assumption may be false if the assembler code actually consists of ! 602: more than one instruction. In such a case, use `&' for each output ! 603: operand that may not overlap an input. *Note Modifiers::. ! 604: ! 605: If you want to test the condition code produced by an assembler ! 606: instruction, you must include a branch and a label in the `asm' ! 607: construct, as follows: ! 608: ! 609: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:" ! 610: : "g" (result) ! 611: : "g" (input)); ! 612: ! 613: This assumes your assembler supports local labels, as the GNU assembler ! 614: and most Unix assemblers do. ! 615: ! 616: Usually the most convenient way to use these `asm' instructions is to ! 617: encapsulate them in macros that look like functions. For example, ! 618: ! 619: #define sin(x) \ ! 620: ({ double __value, __arg = (x); \ ! 621: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ ! 622: __value; }) ! 623: ! 624: Here the variable `__arg' is used to make sure that the instruction ! 625: operates on a proper `double' value, and to accept only those arguments ! 626: `x' which can convert automatically to a `double'. ! 627: ! 628: Another way to make sure the instruction operates on the correct ! 629: data type is to use a cast in the `asm'. This is different from using a ! 630: variable `__arg' in that it converts more different types. For ! 631: example, if the desired type were `int', casting the argument to `int' ! 632: would accept a pointer with no complaint, while assigning the argument ! 633: to an `int' variable named `__arg' would warn about using a pointer ! 634: unless the caller explicitly casts it. ! 635: ! 636: If an `asm' has output operands, GNU CC assumes for optimization ! 637: purposes that the instruction has no side effects except to change the ! 638: output operands. This does not mean that instructions with a side ! 639: effect cannot be used, but you must be careful, because the compiler ! 640: may eliminate them if the output operands aren't used, or move them out ! 641: of loops, or replace two with one if they constitute a common ! 642: subexpression. Also, if your instruction does have a side effect on a ! 643: variable that otherwise appears not to change, the old value of the ! 644: variable may be reused later if it happens to be found in a register. ! 645: ! 646: You can prevent an `asm' instruction from being deleted, moved ! 647: significantly, or combined, by writing the keyword `volatile' after the ! 648: `asm'. For example: ! 649: ! 650: #define set_priority(x) \ ! 651: asm volatile ("set_priority %0": /* no outputs */ : "g" (x)) ! 652: ! 653: An instruction without output operands will not be deleted or moved ! 654: significantly, regardless, unless it is unreachable. ! 655: ! 656: Note that even a volatile `asm' instruction can be moved in ways ! 657: that appear insignificant to the compiler, such as across jump ! 658: instructions. You can't expect a sequence of volatile `asm' ! 659: instructions to remain perfectly consecutive. If you want consecutive ! 660: output, use a single `asm'. ! 661: ! 662: It is a natural idea to look for a way to give access to the ! 663: condition code left by the assembler instruction. However, when we ! 664: attempted to implement this, we found no way to make it work reliably. ! 665: The problem is that output operands might need reloading, which would ! 666: result in additional following "store" instructions. On most machines, ! 667: these instructions would alter the condition code before there was time ! 668: to test it. This problem doesn't arise for ordinary "test" and ! 669: "compare" instructions because they don't have any output operands. ! 670: ! 671: If you are writing a header file that should be includable in ANSI C ! 672: programs, write `__asm__' instead of `asm'. *Note Alternate Keywords::. ! 673: ! 674: ! 675: File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: C Extensions ! 676: ! 677: Controlling Names Used in Assembler Code ! 678: ======================================== ! 679: ! 680: You can specify the name to be used in the assembler code for a C ! 681: function or variable by writing the `asm' (or `__asm__') keyword after ! 682: the declarator as follows: ! 683: ! 684: int foo asm ("myfoo") = 2; ! 685: ! 686: This specifies that the name to be used for the variable `foo' in the ! 687: assembler code should be `myfoo' rather than the usual `_foo'. ! 688: ! 689: On systems where an underscore is normally prepended to the name of ! 690: a C function or variable, this feature allows you to define names for ! 691: the linker that do not start with an underscore. ! 692: ! 693: You cannot use `asm' in this way in a function *definition*; but you ! 694: can get the same effect by writing a declaration for the function ! 695: before its definition and putting `asm' there, like this: ! 696: ! 697: extern func () asm ("FUNC"); ! 698: ! 699: func (x, y) ! 700: int x, y; ! 701: ... ! 702: ! 703: It is up to you to make sure that the assembler names you choose do ! 704: not conflict with any other assembler symbols. Also, you must not use a ! 705: register name; that would produce completely invalid assembler code. ! 706: GNU CC does not as yet have the ability to store static variables in ! 707: registers. Perhaps that will be added. ! 708: ! 709: ! 710: File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions ! 711: ! 712: Variables in Specified Registers ! 713: ================================ ! 714: ! 715: GNU C allows you to put a few global variables into specified ! 716: hardware registers. You can also specify the register in which an ! 717: ordinary register variable should be allocated. ! 718: ! 719: * Global register variables reserve registers throughout the program. ! 720: This may be useful in programs such as programming language ! 721: interpreters which have a couple of global variables that are ! 722: accessed very often. ! 723: ! 724: * Local register variables in specific registers do not reserve the ! 725: registers. The compiler's data flow analysis is capable of ! 726: determining where the specified registers contain live values, and ! 727: where they are available for other uses. ! 728: ! 729: These local variables are sometimes convenient for use with the ! 730: extended `asm' feature (*note Extended Asm::.), if you want to ! 731: write one output of the assembler instruction directly into a ! 732: particular register. (This will work provided the register you ! 733: specify fits the constraints specified for that operand in the ! 734: `asm'.) ! 735: ! 736: * Menu: ! 737: ! 738: * Global Reg Vars:: ! 739: * Local Reg Vars:: ! 740: ! 741: ! 742: File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars ! 743: ! 744: Defining Global Register Variables ! 745: ---------------------------------- ! 746: ! 747: You can define a global register variable in GNU C like this: ! 748: ! 749: register int *foo asm ("a5"); ! 750: ! 751: Here `a5' is the name of the register which should be used. Choose a ! 752: register which is normally saved and restored by function calls on your ! 753: machine, so that library routines will not clobber it. ! 754: ! 755: Naturally the register name is cpu-dependent, so you would need to ! 756: conditionalize your program according to cpu type. The register `a5' ! 757: would be a good choice on a 68000 for a variable of pointer type. On ! 758: machines with register windows, be sure to choose a "global" register ! 759: that is not affected magically by the function call mechanism. ! 760: ! 761: In addition, operating systems on one type of cpu may differ in how ! 762: they name the registers; then you would need additional conditionals. ! 763: For example, some 68000 operating systems call this register `%a5'. ! 764: ! 765: Eventually there may be a way of asking the compiler to choose a ! 766: register automatically, but first we need to figure out how it should ! 767: choose and how to enable you to guide the choice. No solution is ! 768: evident. ! 769: ! 770: Defining a global register variable in a certain register reserves ! 771: that register entirely for this use, at least within the current ! 772: compilation. The register will not be allocated for any other purpose ! 773: in the functions in the current compilation. The register will not be ! 774: saved and restored by these functions. Stores into this register are ! 775: never deleted even if they would appear to be dead, but references may ! 776: be deleted or moved or simplified. ! 777: ! 778: It is not safe to access the global register variables from signal ! 779: handlers, or from more than one thread of control, because the system ! 780: library routines may temporarily use the register for other things ! 781: (unless you recompile them specially for the task at hand). ! 782: ! 783: It is not safe for one function that uses a global register variable ! 784: to call another such function `foo' by way of a third function `lose' ! 785: that was compiled without knowledge of this variable (i.e. in a ! 786: different source file in which the variable wasn't declared). This is ! 787: because `lose' might save the register and put some other value there. ! 788: For example, you can't expect a global register variable to be ! 789: available in the comparison-function that you pass to `qsort', since ! 790: `qsort' might have put something else in that register. (If you are ! 791: prepared to recompile `qsort' with the same global register variable, ! 792: you can solve this problem.) ! 793: ! 794: If you want to recompile `qsort' or other source files which do not ! 795: actually use your global register variable, so that they will not use ! 796: that register for any other purpose, then it suffices to specify the ! 797: compiler option `-ffixed-REG'. You need not actually add a global ! 798: register declaration to their source code. ! 799: ! 800: A function which can alter the value of a global register variable ! 801: cannot safely be called from a function compiled without this variable, ! 802: because it could clobber the value the caller expects to find there on ! 803: return. Therefore, the function which is the entry point into the part ! 804: of the program that uses the global register variable must explicitly ! 805: save and restore the value which belongs to its caller. ! 806: ! 807: On most machines, `longjmp' will restore to each global register ! 808: variable the value it had at the time of the `setjmp'. On some ! 809: machines, however, `longjmp' will not change the value of global ! 810: register variables. To be portable, the function that called `setjmp' ! 811: should make other arrangements to save the values of the global register ! 812: variables, and to restore them in a `longjmp'. This way, the same ! 813: thing will happen regardless of what `longjmp' does. ! 814: ! 815: All global register variable declarations must precede all function ! 816: definitions. If such a declaration could appear after function ! 817: definitions, the declaration would be too late to prevent the register ! 818: from being used for other purposes in the preceding functions. ! 819: ! 820: Global register variables may not have initial values, because an ! 821: executable file has no means to supply initial contents for a register. ! 822: ! 823: On the Sparc, there are reports that g3 ... g7 are suitable ! 824: registers, but certain library functions, such as `getwd', as well as ! 825: the subroutines for division and remainder, modify g3 and g4. g1 and ! 826: g2 are local temporaries. ! 827: ! 828: On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of ! 829: course, it will not do to use more than a few of those. 1.1 root 830: 1.1.1.5 ! root 831: ! 832: File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars ! 833: ! 834: Specifying Registers for Local Variables ! 835: ---------------------------------------- ! 836: ! 837: You can define a local register variable with a specified register ! 838: like this: ! 839: ! 840: register int *foo asm ("a5"); ! 841: ! 842: Here `a5' is the name of the register which should be used. Note that ! 843: this is the same syntax used for defining global register variables, ! 844: but for a local variable it would appear within a function. ! 845: ! 846: Naturally the register name is cpu-dependent, but this is not a ! 847: problem, since specific registers are most often useful with explicit ! 848: assembler instructions (*note Extended Asm::.). Both of these things ! 849: generally require that you conditionalize your program according to cpu ! 850: type. ! 851: ! 852: In addition, operating systems on one type of cpu may differ in how ! 853: they name the registers; then you would need additional conditionals. ! 854: For example, some 68000 operating systems call this register `%a5'. ! 855: ! 856: Eventually there may be a way of asking the compiler to choose a ! 857: register automatically, but first we need to figure out how it should ! 858: choose and how to enable you to guide the choice. No solution is ! 859: evident. ! 860: ! 861: Defining such a register variable does not reserve the register; it ! 862: remains available for other uses in places where flow control determines ! 863: the variable's value is not live. However, these registers are made ! 864: unavailable for use in the reload pass. I would not be surprised if ! 865: excessive use of this feature leaves the compiler too few available ! 866: registers to compile certain functions. ! 867: ! 868: ! 869: File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions ! 870: ! 871: Alternate Keywords 1.1.1.4 root 872: ================== 1.1 root 873: 1.1.1.5 ! root 874: The option `-traditional' disables certain keywords; `-ansi' ! 875: disables certain others. This causes trouble when you want to use GNU C ! 876: extensions, or ANSI C features, in a general-purpose header file that ! 877: should be usable by all programs, including ANSI C programs and ! 878: traditional ones. The keywords `asm', `typeof' and `inline' cannot be ! 879: used since they won't work in a program compiled with `-ansi', while ! 880: the keywords `const', `volatile', `signed', `typeof' and `inline' won't ! 881: work in a program compiled with `-traditional'. ! 882: ! 883: The way to solve these problems is to put `__' at the beginning and ! 884: end of each problematical keyword. For example, use `__asm__' instead ! 885: of `asm', `__const__' instead of `const', and `__inline__' instead of ! 886: `inline'. ! 887: ! 888: Other C compilers won't accept these alternative keywords; if you ! 889: want to compile with another compiler, you can define the alternate ! 890: keywords as macros to replace them with the customary keywords. It ! 891: looks like this: ! 892: ! 893: #ifndef __GNUC__ ! 894: #define __asm__ asm ! 895: #endif ! 896: ! 897: `-pedantic' causes warnings for many GNU C extensions. You can ! 898: prevent such warnings within one expression by writing `__extension__' ! 899: before the expression. `__extension__' has no effect aside from this. ! 900: ! 901: ! 902: File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions ! 903: ! 904: Incomplete `enum' Types ! 905: ======================= ! 906: ! 907: You can define an `enum' tag without specifying its possible values. ! 908: This results in an incomplete type, much like what you get if you write ! 909: `struct foo' without describing the elements. A later declaration ! 910: which does specify the possible values completes the type. ! 911: ! 912: You can't allocate variables or storage using the type while it is ! 913: incomplete. However, you can work with pointers to that type. ! 914: ! 915: This extension may not be very useful, but it makes the handling of ! 916: `enum' more consistent with the way `struct' and `union' are handled. ! 917: ! 918: ! 919: File: gcc.info, Node: Function Names, Prev: Incomplete Enums, Up: C Extensions ! 920: ! 921: Function Names as Strings ! 922: ========================= ! 923: ! 924: GNU CC predefines two string variables to be the name of the current ! 925: function. The variable `__FUNCTION__' is the name of the function as ! 926: it appears in the source. The variable `__PRETTY_FUNCTION__' is the ! 927: name of the function pretty printed in a language specific fashion. ! 928: ! 929: These names are always the same in a C function, but in a C++ ! 930: function they may be different. For example, this program: ! 931: ! 932: extern "C" { ! 933: extern int printf (char *, ...); ! 934: } ! 935: ! 936: class a { ! 937: public: ! 938: sub (int i) ! 939: { ! 940: printf ("__FUNCTION__ = %s\n", __FUNCTION__); ! 941: printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); ! 942: } ! 943: }; ! 944: ! 945: int ! 946: main (void) ! 947: { ! 948: a ax; ! 949: ax.sub (0); ! 950: return 0; ! 951: } ! 952: ! 953: gives this output: ! 954: ! 955: __FUNCTION__ = sub ! 956: __PRETTY_FUNCTION__ = int a::sub (int) ! 957: ! 958: ! 959: File: gcc.info, Node: C++ Extensions, Next: Trouble, Prev: C Extensions, Up: Top ! 960: ! 961: Extensions to the C++ Language ! 962: ****************************** ! 963: ! 964: The GNU compiler provides these extensions to the C++ language (and ! 965: you can also use most of the C language extensions in your C++ ! 966: programs). If you want to write code that checks whether these ! 967: features are available, you can test for the GNU compiler the same way ! 968: as for C programs: check for a predefined macro `__GNUC__'. You can ! 969: also use `__GNUG__' to test specifically for GNU C++ (*note Standard ! 970: Predefined Macros: (cpp.info)Standard Predefined.). ! 971: ! 972: * Menu: ! 973: ! 974: * Naming Results:: Giving a name to C++ function return values. ! 975: * Min and Max:: C++ Minimum and maximum operators. ! 976: * Destructors and Goto:: Goto is safe to use in C++ even when destructors ! 977: are needed. ! 978: * C++ Interface:: You can use a single C++ header file for both ! 979: declarations and definitions. ! 980: ! 981: ! 982: File: gcc.info, Node: Naming Results, Next: Min and Max, Up: C++ Extensions ! 983: ! 984: Named Return Values in C++ ! 985: ========================== ! 986: ! 987: GNU C++ extends the function-definition syntax to allow you to ! 988: specify a name for the result of a function outside the body of the ! 989: definition, in C++ programs: ! 990: ! 991: TYPE ! 992: FUNCTIONNAME (ARGS) return RESULTNAME; ! 993: { ! 994: ... ! 995: BODY ! 996: ... ! 997: } ! 998: ! 999: You can use this feature to avoid an extra constructor call when a ! 1000: function result has a class type. For example, consider a function ! 1001: `m', declared as `X v = m ();', whose result is of class `X': ! 1002: ! 1003: X ! 1004: m () ! 1005: { ! 1006: X b; ! 1007: b.a = 23; ! 1008: return b; ! 1009: } ! 1010: ! 1011: Although `m' appears to have no arguments, in fact it has one ! 1012: implicit argument: the address of the return value. At invocation, the ! 1013: address of enough space to hold `v' is sent in as the implicit argument. ! 1014: Then `b' is constructed and its `a' field is set to the value 23. ! 1015: Finally, a copy constructor (a constructor of the form `X(X&)') is ! 1016: applied to `b', with the (implicit) return value location as the ! 1017: target, so that `v' is now bound to the return value. ! 1018: ! 1019: But this is wasteful. The local `b' is declared just to hold ! 1020: something that will be copied right out. While a compiler that ! 1021: combined an "elision" algorithm with interprocedural data flow analysis ! 1022: could conceivably eliminate all of this, it is much more practical to ! 1023: allow you to assist the compiler in generating efficient code by ! 1024: manipulating the return value explicitly, thus avoiding the local ! 1025: variable and copy constructor altogether. ! 1026: ! 1027: Using the extended GNU C++ function-definition syntax, you can avoid ! 1028: the temporary allocation and copying by naming `r' as your return value ! 1029: as the outset, and assigning to its `a' field directly: ! 1030: ! 1031: X ! 1032: m () return r; ! 1033: { ! 1034: r.a = 23; ! 1035: } ! 1036: ! 1037: The declaration of `r' is a standard, proper declaration, whose effects ! 1038: are executed *before* any of the body of `m'. ! 1039: ! 1040: Functions of this type impose no additional restrictions; in ! 1041: particular, you can execute `return' statements, or return implicitly by ! 1042: reaching the end of the function body ("falling off the edge"). Cases ! 1043: like ! 1044: ! 1045: X ! 1046: m () return r (23); ! 1047: { ! 1048: return; ! 1049: } ! 1050: ! 1051: (or even `X m () return r (23); { }') are unambiguous, since the return ! 1052: value `r' has been initialized in either case. The following code may ! 1053: be hard to read, but also works predictably: ! 1054: ! 1055: X ! 1056: m () return r; ! 1057: { ! 1058: X b; ! 1059: return b; ! 1060: } ! 1061: ! 1062: The return value slot denoted by `r' is initialized at the outset, ! 1063: but the statement `return b;' overrides this value. The compiler deals ! 1064: with this by destroying `r' (calling the destructor if there is one, or ! 1065: doing nothing if there is not), and then reinitializing `r' with `b'. ! 1066: ! 1067: This extension is provided primarily to help people who use ! 1068: overloaded operators, where there is a great need to control not just ! 1069: the arguments, but the return values of functions. For classes where ! 1070: the copy constructor incurs a heavy performance penalty (especially in ! 1071: the common case where there is a quick default constructor), this is a ! 1072: major savings. The disadvantage of this extension is that you do not ! 1073: control when the default constructor for the return value is called: it ! 1074: is always called at the beginning. ! 1075: ! 1076: ! 1077: File: gcc.info, Node: Min and Max, Next: Destructors and Goto, Prev: Naming Results, Up: C++ Extensions ! 1078: ! 1079: Minimum and Maximum Operators in C++ ! 1080: ==================================== ! 1081: ! 1082: It is very convenient to have operators which return the "minimum" ! 1083: or the "maximum" of two arguments. In GNU C++ (but not in GNU C), ! 1084: ! 1085: `A <? B' ! 1086: is the "minimum", returning the smaller of the numeric values A ! 1087: and B; ! 1088: ! 1089: `A >? B' ! 1090: is the "maximum", returning the larger of the numeric values A and ! 1091: B. ! 1092: ! 1093: These operations are not primitive in ordinary C++, since you can ! 1094: use a macro to return the minimum of two things in C++, as in the ! 1095: following example. ! 1096: ! 1097: #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) ! 1098: ! 1099: You might then use `int min = MIN (i, j);' to set MIN to the minimum ! 1100: value of variables I and J. ! 1101: ! 1102: However, side effects in `X' or `Y' may cause unintended behavior. ! 1103: For example, `MIN (i++, j++)' will fail, incrementing the smaller ! 1104: counter twice. A GNU C extension allows you to write safe macros that ! 1105: avoid this kind of problem (*note Naming an Expression's Type: Naming ! 1106: Types.). However, writing `MIN' and `MAX' as macros also forces you to ! 1107: use function-call notation notation for a fundamental arithmetic ! 1108: operation. Using GNU C++ extensions, you can write `int min = i <? j;' ! 1109: instead. ! 1110: ! 1111: Since `<?' and `>?' are built into the compiler, they properly ! 1112: handle expressions with side-effects; `int min = i++ <? j++;' works ! 1113: correctly. ! 1114: ! 1115: ! 1116: File: gcc.info, Node: Destructors and Goto, Next: C++ Interface, Prev: Min and Max, Up: C++ Extensions ! 1117: ! 1118: `goto' and Destructors in GNU C++ ! 1119: ================================= ! 1120: ! 1121: In C++ programs, you can safely use the `goto' statement. When you ! 1122: use it to exit a block which contains aggregates requiring destructors, ! 1123: the destructors will run before the `goto' transfers control. (In ANSI ! 1124: C++, `goto' is restricted to targets within the current block.) ! 1125: ! 1126: The compiler still forbids using `goto' to *enter* a scope that ! 1127: requires constructors. 1.1 root 1128:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.