![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-5 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to gcc.info-5 CVS log | Up to [GCC 2.x] / gcc |
1.1 ! root 1: This is Info file gcc.info, produced by Makeinfo-1.43 from the input ! 2: file gcc.texi. ! 3: ! 4: This file documents the use and the internals of the GNU compiler. ! 5: ! 6: Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc. ! 7: ! 8: Permission is granted to make and distribute verbatim copies of ! 9: this manual provided the copyright notice and this permission notice ! 10: are preserved on all copies. ! 11: ! 12: Permission is granted to copy and distribute modified versions of ! 13: this manual under the conditions for verbatim copying, provided also ! 14: that the section entitled "GNU General Public License" is included ! 15: exactly as in the original, and provided that the entire resulting ! 16: derived work is distributed under the terms of a permission notice ! 17: identical to this one. ! 18: ! 19: Permission is granted to copy and distribute translations of this ! 20: manual into another language, under the above conditions for modified ! 21: versions, except that the section entitled "GNU General Public ! 22: License" and this permission notice may be included in translations ! 23: approved by the Free Software Foundation instead of in the original ! 24: English. ! 25: ! 26: ! 27: File: gcc.info, Node: Function Attributes, Next: Dollar Signs, Prev: Case Ranges, Up: Extensions ! 28: ! 29: Declaring Attributes of Functions ! 30: ================================= ! 31: ! 32: In GNU C, you declare certain things about functions called in your ! 33: program which help the compiler optimize function calls. ! 34: ! 35: A few standard library functions, such as `abort' and `exit', ! 36: cannot return. GNU CC knows this automatically. Some programs define ! 37: their own functions that never return. You can declare them ! 38: `volatile' to tell the compiler this fact. For example, ! 39: ! 40: extern void volatile fatal (); ! 41: ! 42: void ! 43: fatal (...) ! 44: { ! 45: ... /* Print error message. */ ... ! 46: exit (1); ! 47: } ! 48: ! 49: The `volatile' keyword tells the compiler to assume that `fatal' ! 50: cannot return. This makes slightly better code, but more importantly ! 51: it helps avoid spurious warnings of uninitialized variables. ! 52: ! 53: It does not make sense for a `volatile' function to have a return ! 54: type other than `void'. ! 55: ! 56: Many functions do not examine any values except their arguments, and ! 57: have no effects except the return value. Such a function can be ! 58: subject to common subexpression elimination and loop optimization just ! 59: as an arithmetic operator would be. These functions should be declared ! 60: `const'. For example, ! 61: ! 62: extern int const square (); ! 63: ! 64: says that the hypothetical function `square' is safe to call fewer ! 65: times than the program says. ! 66: ! 67: Note that a function that has pointer arguments and examines the ! 68: data pointed to must *not* be declared `const'. Likewise, a function ! 69: that calls a non-`const' function usually must not be `const'. It ! 70: does not make sense for a `const' function to return `void'. ! 71: ! 72: We recommend placing the keyword `const' after the function's ! 73: return type. It makes no difference in the example above, but when the ! 74: return type is a pointer, it is the only way to make the function ! 75: itself const. For example, ! 76: ! 77: const char *mincp (int); ! 78: ! 79: says that `mincp' returns `const char *'--a pointer to a const object. ! 80: To declare `mincp' const, you must write this: ! 81: ! 82: char * const mincp (int); ! 83: ! 84: Some people object to this feature, suggesting that ANSI C's ! 85: `#pragma' should be used instead. There are two reasons for not doing ! 86: this. ! 87: ! 88: 1. It is impossible to generate `#pragma' commands from a macro. ! 89: ! 90: 2. The `#pragma' command is just as likely as these keywords to mean ! 91: something else in another compiler. ! 92: ! 93: These two reasons apply to almost any application that might be ! 94: proposed for `#pragma'. It is basically a mistake to use `#pragma' for ! 95: *anything*. ! 96: ! 97: ! 98: File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: Function Attributes, Up: Extensions ! 99: ! 100: Dollar Signs in Identifier Names ! 101: ================================ ! 102: ! 103: In GNU C, you may use dollar signs in identifier names. This is ! 104: because many traditional C implementations allow such identifiers. ! 105: ! 106: Dollar signs are allowed on certain machines if you specify ! 107: `-traditional'. On a few systems they are allowed by default, even if ! 108: `-traditional' is not used. But they are never allowed if you specify ! 109: `-ansi'. ! 110: ! 111: There are certain ANSI C programs (obscure, to be sure) that would ! 112: compile incorrectly if dollar signs were permitted in identifiers. For ! 113: example: ! 114: ! 115: #define foo(a) #a ! 116: #define lose(b) foo (b) ! 117: #define test$ ! 118: lose (test) ! 119: ! 120: ! 121: File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: Extensions ! 122: ! 123: The Character ESC in Constants ! 124: ============================== ! 125: ! 126: You can use the sequence `\e' in a string or character constant to ! 127: stand for the ASCII character ESC. ! 128: ! 129: ! 130: File: gcc.info, Node: Alignment, Next: Inline, Prev: Variable Attributes, Up: Extensions ! 131: ! 132: Inquiring on Alignment of Types or Variables ! 133: ============================================ ! 134: ! 135: The keyword `__alignof__' allows you to inquire about how an object ! 136: is aligned, or the minimum alignment usually required by a type. Its ! 137: syntax is just like `sizeof'. ! 138: ! 139: For example, if the target machine requires a `double' value to be ! 140: aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This ! 141: is true on many RISC machines. On more traditional machine designs, ! 142: `__alignof__ (double)' is 4 or even 2. ! 143: ! 144: Some machines never actually require alignment; they allow ! 145: reference to any data type even at an odd addresses. For these ! 146: machines, `__alignof__' reports the *recommended* alignment of a type. ! 147: ! 148: When the operand of `__alignof__' is an lvalue rather than a type, ! 149: the value is the largest alignment that the lvalue is known to have. ! 150: It may have this alignment as a result of its data type, or because it ! 151: is part of a structure and inherits alignment from that structure. For ! 152: example, after this declaration: ! 153: ! 154: struct foo { int x; char y; } foo1; ! 155: ! 156: the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as ! 157: `__alignof__ (int)', even though the data type of `foo1.y' does not ! 158: itself demand any alignment. ! 159: ! 160: ! 161: File: gcc.info, Node: Variable Attributes, Next: Alignment, Prev: Character Escapes, Up: Extensions ! 162: ! 163: Specifying Attributes of Variables ! 164: ================================== ! 165: ! 166: The keyword `__attribute__' allows you to specify special ! 167: attributes of variables or structure fields. The only attributes ! 168: currently defined are the `aligned' and `format' attributes. ! 169: ! 170: The `aligned' attribute specifies the alignment of the variable or ! 171: structure field. For example, the declaration: ! 172: ! 173: int x __attribute__ ((aligned (16))) = 0; ! 174: ! 175: causes the compiler to allocate the global variable `x' on a 16-byte ! 176: boundary. On a 68000, this could be used in conjunction with an `asm' ! 177: expression to access the `move16' instruction which requires 16-byte ! 178: aligned operands. ! 179: ! 180: You can also specify the alignment of structure fields. For ! 181: example, to create a double-word aligned `int' pair, you could write: ! 182: ! 183: struct foo { int x[2] __attribute__ ((aligned (8))); }; ! 184: ! 185: This is an alternative to creating a union with a `double' member that ! 186: forces the union to be double-word aligned. ! 187: ! 188: It is not possible to specify the alignment of functions; the ! 189: alignment of functions is determined by the machine's requirements and ! 190: cannot be changed. ! 191: ! 192: The `format' attribute specifies that a function takes `printf' or ! 193: `scanf' style arguments which should be type-checked against a format ! 194: string. For example, the declaration: ! 195: ! 196: extern int ! 197: my_printf (void *my_object, const char *my_format, ...) ! 198: __attribute__ ((format (printf, 2, 3))); ! 199: ! 200: causes the compiler to check the arguments in calls to `my_printf' for ! 201: consistency with the `printf' style format string argument `my_format'. ! 202: ! 203: The first parameter of the `format' attribute determines how the ! 204: format string is interpreted, and should be either `printf' or ! 205: `scanf'. The second parameter specifies the number of the format ! 206: string argument (starting from 1). The third parameter specifies the ! 207: number of the first argument which should be checked against the ! 208: format string. For functions where the arguments are not available to ! 209: be checked (such as `vprintf'), specify the third parameter as zero. ! 210: In this case the compiler only checks the format string for ! 211: consistency. ! 212: ! 213: In the example above, the format string (`my_format') is the second ! 214: argument to `my_print' and the arguments to check start with the third ! 215: argument, so the correct parameters for the format attribute are 2 and ! 216: 3. ! 217: ! 218: The `format' attribute allows you to identify your own functions ! 219: which take format strings as arguments, so that GNU CC can check the ! 220: calls to these functions for errors. The compiler always checks ! 221: formats for the ANSI library functions `printf', `fprintf', `sprintf', ! 222: `scanf', `fscanf', `sscanf', `vprintf', `vfprintf' and `vsprintf' ! 223: whenever such warnings are requested (using `-Wformat'), so there is no ! 224: need to modify the header file `stdio.h'. ! 225: ! 226: ! 227: File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: Extensions ! 228: ! 229: An Inline Function is As Fast As a Macro ! 230: ======================================== ! 231: ! 232: By declaring a function `inline', you can direct GNU CC to integrate ! 233: that function's code into the code for its callers. This makes ! 234: execution faster by eliminating the function-call overhead; in ! 235: addition, if any of the actual argument values are constant, their ! 236: known values may permit simplifications at compile time so that not ! 237: all of the inline function's code needs to be included. ! 238: ! 239: To declare a function inline, use the `inline' keyword in its ! 240: declaration, like this: ! 241: ! 242: inline int ! 243: inc (int *a) ! 244: { ! 245: (*a)++; ! 246: } ! 247: ! 248: (If you are writing a header file to be included in ANSI C ! 249: programs, write `__inline__' instead of `inline'. *Note Alternate ! 250: Keywords::.) ! 251: ! 252: You can also make all "simple enough" functions inline with the ! 253: option `-finline-functions'. Note that certain usages in a function ! 254: definition can make it unsuitable for inline substitution. ! 255: ! 256: When a function is both inline and `static', if all calls to the ! 257: function are integrated into the caller, and the function's address is ! 258: never used, then the function's own assembler code is never referenced. ! 259: In this case, GNU CC does not actually output assembler code for the ! 260: function, unless you specify the option `-fkeep-inline-functions'. ! 261: Some calls cannot be integrated for various reasons (in particular, ! 262: calls that precede the function's definition cannot be integrated, and ! 263: neither can recursive calls within the definition). If there is a ! 264: nonintegrated call, then the function is compiled to assembler code as ! 265: usual. The function must also be compiled as usual if the program ! 266: refers to its address, because that can't be inlined. ! 267: ! 268: When an inline function is not `static', then the compiler must ! 269: assume that there may be calls from other source files; since a global ! 270: symbol can be defined only once in any program, the function must not ! 271: be defined in the other source files, so the calls therein cannot be ! 272: integrated. Therefore, a non-`static' inline function is always ! 273: compiled on its own in the usual fashion. ! 274: ! 275: If you specify both `inline' and `extern' in the function ! 276: definition, then the definition is used only for inlining. In no case ! 277: is the function compiled on its own, not even if you refer to its ! 278: address explicitly. Such an address becomes an external reference, as ! 279: if you had only declared the function, and had not defined it. ! 280: ! 281: This combination of `inline' and `extern' has almost the effect of ! 282: a macro. The way to use it is to put a function definition in a ! 283: header file with these keywords, and put another copy of the ! 284: definition (lacking `inline' and `extern') in a library file. The ! 285: definition in the header file will cause most calls to the function to ! 286: be inlined. If any uses of the function remain, they will refer to ! 287: the single copy in the library. ! 288: ! 289: ! 290: File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: Extensions ! 291: ! 292: Assembler Instructions with C Expression Operands ! 293: ================================================= ! 294: ! 295: In an assembler instruction using `asm', you can now specify the ! 296: operands of the instruction using C expressions. This means no more ! 297: guessing which registers or memory locations will contain the data you ! 298: want to use. ! 299: ! 300: You must specify an assembler instruction template much like what ! 301: appears in a machine description, plus an operand constraint string ! 302: for each operand. ! 303: ! 304: For example, here is how to use the 68881's `fsinx' instruction: ! 305: ! 306: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); ! 307: ! 308: Here `angle' is the C expression for the input operand while `result' ! 309: is that of the output operand. Each has `"f"' as its operand ! 310: constraint, saying that a floating point register is required. The ! 311: `=' in `=f' indicates that the operand is an output; all output ! 312: operands' constraints must use `='. The constraints use the same ! 313: language used in the machine description (*note Constraints::.). ! 314: ! 315: Each operand is described by an operand-constraint string followed by ! 316: the C expression in parentheses. A colon separates the assembler ! 317: template from the first output operand, and another separates the last ! 318: output operand from the first input, if any. Commas separate output ! 319: operands and separate inputs. The total number of operands is limited ! 320: to ten or to the maximum number of operands in any instruction pattern ! 321: in the machine description, whichever is greater. ! 322: ! 323: If there are no output operands, and there are input operands, then ! 324: there must be two consecutive colons surrounding the place where the ! 325: output operands would go. ! 326: ! 327: Output operand expressions must be lvalues; the compiler can check ! 328: this. The input operands need not be lvalues. The compiler cannot ! 329: check whether the operands have data types that are reasonable for the ! 330: instruction being executed. It does not parse the assembler ! 331: instruction template and does not know what it means, or whether it is ! 332: valid assembler input. The extended `asm' feature is most often used ! 333: for machine instructions that the compiler itself does not know exist. ! 334: ! 335: The output operands must be write-only; GNU CC will assume that the ! 336: values in these operands before the instruction are dead and need not ! 337: be generated. Extended asm does not support input-output or read-write ! 338: operands. For this reason, the constraint character `+', which ! 339: indicates such an operand, may not be used. ! 340: ! 341: When the assembler instruction has a read-write operand, or an ! 342: operand in which only some of the bits are to be changed, you must ! 343: logically split its function into two separate operands, one input ! 344: operand and one write-only output operand. The connection between ! 345: them is expressed by constraints which say they need to be in the same ! 346: location when the instruction executes. You can use the same C ! 347: expression for both operands, or different expressions. For example, ! 348: here we write the (fictitious) `combine' instruction with `bar' as its ! 349: read-only source operand and `foo' as its read-write destination: ! 350: ! 351: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); ! 352: ! 353: The constraint `"0"' for operand 1 says that it must occupy the same ! 354: location as operand 0. A digit in constraint is allowed only in an ! 355: input operand, and it must refer to an output operand. ! 356: ! 357: Only a digit in the constraint can guarantee that one operand will ! 358: be in the same place as another. The mere fact that `foo' is the ! 359: value of both operands is not enough to guarantee that they will be in ! 360: the same place in the generated assembler code. The following would ! 361: not work: ! 362: ! 363: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); ! 364: ! 365: Various optimizations or reloading could cause operands 0 and 1 to ! 366: be in different registers; GNU CC knows no reason not to do so. For ! 367: example, the compiler might find a copy of the value of `foo' in one ! 368: register and use it for operand 1, but generate the output operand 0 ! 369: in a different register (copying it afterward to `foo''s own address). ! 370: Of course, since the register for operand 1 is not even mentioned in ! 371: the assembler code, the result will not work, but GNU CC can't tell ! 372: that. ! 373: ! 374: Some instructions clobber specific hard registers. To describe ! 375: this, write a third colon after the input operands, followed by the ! 376: names of the clobbered hard registers (given as strings). Here is a ! 377: realistic example for the Vax: ! 378: ! 379: asm volatile ("movc3 %0,%1,%2" ! 380: : /* no outputs */ ! 381: : "g" (from), "g" (to), "g" (count) ! 382: : "r0", "r1", "r2", "r3", "r4", "r5"); ! 383: ! 384: If you refer to a particular hardware register from the assembler ! 385: code, then you will probably have to list the register after the third ! 386: colon to tell the compiler that the register's value is modified. In ! 387: many assemblers, the register names begin with `%'; to produce one `%' ! 388: in the assembler code, you must write `%%' in the input. ! 389: ! 390: You can put multiple assembler instructions together in a single ! 391: `asm' template, separated either with newlines (written as `\n') or ! 392: with semicolons if the assembler allows such semicolons. The GNU ! 393: assembler allows semicolons and all Unix assemblers seem to do so. ! 394: The input operands are guaranteed not to use any of the clobbered ! 395: registers, and neither will the output operands' addresses, so you can ! 396: read and write the clobbered registers as many times as you like. ! 397: Here is an example of multiple instructions in a template; it assumes ! 398: that the subroutine `_foo' accepts arguments in registers 9 and 10: ! 399: ! 400: asm ("movl %0,r9;movl %1,r10;call _foo" ! 401: : /* no outputs */ ! 402: : "g" (from), "g" (to) ! 403: : "r9", "r10"); ! 404: ! 405: Unless an output operand has the `&' constraint modifier, GNU CC may ! 406: allocate it in the same register as an unrelated input operand, on the ! 407: assumption that the inputs are consumed before the outputs are ! 408: produced. This assumption may be false if the assembler code actually ! 409: consists of more than one instruction. In such a case, use `&' for ! 410: each output operand that may not overlap an input. *Note Modifiers::. ! 411: ! 412: If you want to test the condition code produced by an assembler ! 413: instruction, you must include a branch and a label in the `asm' ! 414: construct, as follows: ! 415: ! 416: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:" ! 417: : "g" (result) ! 418: : "g" (input)); ! 419: ! 420: This assumes your assembler supports local labels, as the GNU assembler ! 421: and most Unix assemblers do. ! 422: ! 423: Usually the most convenient way to use these `asm' instructions is ! 424: to encapsulate them in macros that look like functions. For example, ! 425: ! 426: #define sin(x) \ ! 427: ({ double __value, __arg = (x); \ ! 428: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ ! 429: __value; }) ! 430: ! 431: Here the variable `__arg' is used to make sure that the instruction ! 432: operates on a proper `double' value, and to accept only those ! 433: arguments `x' which can convert automatically to a `double'. ! 434: ! 435: Another way to make sure the instruction operates on the correct ! 436: data type is to use a cast in the `asm'. This is different from using ! 437: a variable `__arg' in that it converts more different types. For ! 438: example, if the desired type were `int', casting the argument to `int' ! 439: would accept a pointer with no complaint, while assigning the argument ! 440: to an `int' variable named `__arg' would warn about using a pointer ! 441: unless the caller explicitly casts it. ! 442: ! 443: If an `asm' has output operands, GNU CC assumes for optimization ! 444: purposes that the instruction has no side effects except to change the ! 445: output operands. This does not mean that instructions with a side ! 446: effect cannot be used, but you must be careful, because the compiler ! 447: may eliminate them if the output operands aren't used, or move them ! 448: out of loops, or replace two with one if they constitute a common ! 449: subexpression. Also, if your instruction does have a side effect on a ! 450: variable that otherwise appears not to change, the old value of the ! 451: variable may be reused later if it happens to be found in a register. ! 452: ! 453: You can prevent an `asm' instruction from being deleted, moved ! 454: significantly, or combined, by writing the keyword `volatile' after ! 455: the `asm'. For example: ! 456: ! 457: #define set_priority(x) \ ! 458: asm volatile ("set_priority %0": /* no outputs */ : "g" (x)) ! 459: ! 460: An instruction without output operands will not be deleted or moved ! 461: significantly, regardless, unless it is unreachable. ! 462: ! 463: Note that even a volatile `asm' instruction can be moved in ways ! 464: that appear insignificant to the compiler, such as across jump ! 465: instructions. You can't expect a sequence of volatile `asm' ! 466: instructions to remain perfectly consecutive. If you want consecutive ! 467: output, use a single `asm'. ! 468: ! 469: It is a natural idea to look for a way to give access to the ! 470: condition code left by the assembler instruction. However, when we ! 471: attempted to implement this, we found no way to make it work reliably. ! 472: The problem is that output operands might need reloading, which would ! 473: result in additional following "store" instructions. On most ! 474: machines, these instructions would alter the condition code before ! 475: there was time to test it. This problem doesn't arise for ordinary ! 476: "test" and "compare" instructions because they don't have any output ! 477: operands. ! 478: ! 479: If you are writing a header file that should be includable in ANSI C ! 480: programs, write `__asm__' instead of `asm'. *Note Alternate ! 481: Keywords::. ! 482: ! 483: ! 484: File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: Extensions ! 485: ! 486: Controlling Names Used in Assembler Code ! 487: ======================================== ! 488: ! 489: You can specify the name to be used in the assembler code for a C ! 490: function or variable by writing the `asm' (or `__asm__') keyword after ! 491: the declarator as follows: ! 492: ! 493: int foo asm ("myfoo") = 2; ! 494: ! 495: This specifies that the name to be used for the variable `foo' in the ! 496: assembler code should be `myfoo' rather than the usual `_foo'. ! 497: ! 498: On systems where an underscore is normally prepended to the name of ! 499: a C function or variable, this feature allows you to define names for ! 500: the linker that do not start with an underscore. ! 501: ! 502: You cannot use `asm' in this way in a function *definition*; but ! 503: you can get the same effect by writing a declaration for the function ! 504: before its definition and putting `asm' there, like this: ! 505: ! 506: extern func () asm ("FUNC"); ! 507: ! 508: func (x, y) ! 509: int x, y; ! 510: ... ! 511: ! 512: It is up to you to make sure that the assembler names you choose do ! 513: not conflict with any other assembler symbols. Also, you must not use ! 514: a register name; that would produce completely invalid assembler code. ! 515: GNU CC does not as yet have the ability to store static variables in ! 516: registers. Perhaps that will be added. ! 517: ! 518: ! 519: File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: Extensions ! 520: ! 521: Variables in Specified Registers ! 522: ================================ ! 523: ! 524: GNU C allows you to put a few global variables into specified ! 525: hardware registers. You can also specify the register in which an ! 526: ordinary register variable should be allocated. ! 527: ! 528: * Global register variables reserve registers throughout the ! 529: program. This may be useful in programs such as programming ! 530: language interpreters which have a couple of global variables ! 531: that are accessed very often. ! 532: ! 533: * Local register variables in specific registers do not reserve the ! 534: registers. The compiler's data flow analysis is capable of ! 535: determining where the specified registers contain live values, ! 536: and where they are available for other uses. ! 537: ! 538: These local variables are sometimes convenient for use with the ! 539: extended `asm' feature (*note Extended Asm::.), if you want to ! 540: write one output of the assembler instruction directly into a ! 541: particular register. (This will work provided the register you ! 542: specify fits the constraints specified for that operand in the ! 543: `asm'.) ! 544: ! 545: * Menu: ! 546: ! 547: * Global Reg Vars:: ! 548: * Local Reg Vars:: ! 549: ! 550: ! 551: File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars ! 552: ! 553: Defining Global Register Variables ! 554: ---------------------------------- ! 555: ! 556: You can define a global register variable in GNU C like this: ! 557: ! 558: register int *foo asm ("a5"); ! 559: ! 560: Here `a5' is the name of the register which should be used. Choose a ! 561: register which is normally saved and restored by function calls on your ! 562: machine, so that library routines will not clobber it. ! 563: ! 564: Naturally the register name is cpu-dependent, so you would need to ! 565: conditionalize your program according to cpu type. The register `a5' ! 566: would be a good choice on a 68000 for a variable of pointer type. On ! 567: machines with register windows, be sure to choose a "global" register ! 568: that is not affected magically by the function call mechanism. ! 569: ! 570: In addition, operating systems on one type of cpu may differ in how ! 571: they name the registers; then you would need additional conditionals. ! 572: For example, some 68000 operating systems call this register `%a5'. ! 573: ! 574: Eventually there may be a way of asking the compiler to choose a ! 575: register automatically, but first we need to figure out how it should ! 576: choose and how to enable you to guide the choice. No solution is ! 577: evident. ! 578: ! 579: Defining a global register variable in a certain register reserves ! 580: that register entirely for this use, at least within the current ! 581: compilation. The register will not be allocated for any other purpose ! 582: in the functions in the current compilation. The register will not be ! 583: saved and restored by these functions. Stores into this register are ! 584: never deleted even if they would appear to be dead, but references may ! 585: be deleted or moved or simplified. ! 586: ! 587: It is not safe to access the global register variables from signal ! 588: handlers, or from more than one thread of control, because the system ! 589: library routines may temporarily use the register for other things ! 590: (unless you recompile them specially for the task at hand). ! 591: ! 592: It is not safe for one function that uses a global register ! 593: variable to call another such function `foo' by way of a third function ! 594: `lose' that was compiled without knowledge of this variable (i.e. in a ! 595: different source file in which the variable wasn't declared). This is ! 596: because `lose' might save the register and put some other value there. ! 597: For example, you can't expect a global register variable to be ! 598: available in the comparison-function that you pass to `qsort', since ! 599: `qsort' might have put something else in that register. (If you are ! 600: prepared to recompile `qsort' with the same global register variable, ! 601: you can solve this problem.) ! 602: ! 603: If you want to recompile `qsort' or other source files which do not ! 604: actually use your global register variable, so that they will not use ! 605: that register for any other purpose, then it suffices to specify the ! 606: compiler option `-ffixed-REG'. You need not actually add a global ! 607: register declaration to their source code. ! 608: ! 609: A function which can alter the value of a global register variable ! 610: cannot safely be called from a function compiled without this ! 611: variable, because it could clobber the value the caller expects to ! 612: find there on return. Therefore, the function which is the entry ! 613: point into the part of the program that uses the global register ! 614: variable must explicitly save and restore the value which belongs to ! 615: its caller. ! 616: ! 617: On most machines, `longjmp' will restore to each global register ! 618: variable the value it had at the time of the `setjmp'. On some ! 619: machines, however, `longjmp' will not change the value of global ! 620: register variables. To be portable, the function that called `setjmp' ! 621: should make other arrangements to save the values of the global ! 622: register variables, and to restore them in a `longjmp'. This way, the ! 623: same thing will happen regardless of what `longjmp' does. ! 624: ! 625: All global register variable declarations must precede all function ! 626: definitions. If such a declaration could appear after function ! 627: definitions, the declaration would be too late to prevent the register ! 628: from being used for other purposes in the preceding functions. ! 629: ! 630: Global register variables may not have initial values, because an ! 631: executable file has no means to supply initial contents for a register. ! 632: ! 633: On the Sparc, there are reports that g3 ... g7 are suitable ! 634: registers, but certain library functions, such as `getwd', as well as ! 635: the subroutines for division and remainder, modify g3 and g4. g1 and ! 636: g2 are local temporaries. ! 637: ! 638: On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. ! 639: Of course, it will not do to use more than a few of those. ! 640: ! 641: ! 642: File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars ! 643: ! 644: Specifying Registers for Local Variables ! 645: ---------------------------------------- ! 646: ! 647: You can define a local register variable with a specified register ! 648: like this: ! 649: ! 650: register int *foo asm ("a5"); ! 651: ! 652: Here `a5' is the name of the register which should be used. Note that ! 653: this is the same syntax used for defining global register variables, ! 654: but for a local variable it would appear within a function. ! 655: ! 656: Naturally the register name is cpu-dependent, but this is not a ! 657: problem, since specific registers are most often useful with explicit ! 658: assembler instructions (*note Extended Asm::.). Both of these things ! 659: generally require that you conditionalize your program according to ! 660: cpu type. ! 661: ! 662: In addition, operating systems on one type of cpu may differ in how ! 663: they name the registers; then you would need additional conditionals. ! 664: For example, some 68000 operating systems call this register `%a5'. ! 665: ! 666: Eventually there may be a way of asking the compiler to choose a ! 667: register automatically, but first we need to figure out how it should ! 668: choose and how to enable you to guide the choice. No solution is ! 669: evident. ! 670: ! 671: Defining such a register variable does not reserve the register; it ! 672: remains available for other uses in places where flow control ! 673: determines the variable's value is not live. However, these registers ! 674: are made unavailable for use in the reload pass. I would not be ! 675: surprised if excessive use of this feature leaves the compiler too few ! 676: available registers to compile certain functions. ! 677: ! 678: ! 679: File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: Extensions ! 680: ! 681: Alternate Keywords ! 682: ================== ! 683: ! 684: The option `-traditional' disables certain keywords; `-ansi' ! 685: disables certain others. This causes trouble when you want to use GNU ! 686: C extensions, or ANSI C features, in a general-purpose header file that ! 687: should be usable by all programs, including ANSI C programs and ! 688: traditional ones. The keywords `asm', `typeof' and `inline' cannot be ! 689: used since they won't work in a program compiled with `-ansi', while ! 690: the keywords `const', `volatile', `signed', `typeof' and `inline' ! 691: won't work in a program compiled with `-traditional'. ! 692: ! 693: The way to solve these problems is to put `__' at the beginning and ! 694: end of each problematical keyword. For example, use `__asm__' instead ! 695: of `asm', `__const__' instead of `const', and `__inline__' instead of ! 696: `inline'. ! 697: ! 698: Other C compilers won't accept these alternative keywords; if you ! 699: want to compile with another compiler, you can define the alternate ! 700: keywords as macros to replace them with the customary keywords. It ! 701: looks like this: ! 702: ! 703: #ifndef __GNUC__ ! 704: #define __asm__ asm ! 705: #endif ! 706: ! 707: `-pedantic' causes warnings for many GNU C extensions. You can ! 708: prevent such warnings within one expression by writing `__extension__' ! 709: before the expression. `__extension__' has no effect aside from this. ! 710: ! 711: ! 712: File: gcc.info, Node: Incomplete Enums, Prev: Alternate Keywords, Up: Extensions ! 713: ! 714: Incomplete `enum' Types ! 715: ======================= ! 716: ! 717: You can define an `enum' tag without specifying its possible values. ! 718: This results in an incomplete type, much like what you get if you write ! 719: `struct foo' without describing the elements. A later declaration ! 720: which does specify the possible values completes the type. ! 721: ! 722: You can't allocate variables or storage using the type while it is ! 723: incomplete. However, you can work with pointers to that type. ! 724: ! 725: This extension may not be very useful, but it makes the handling of ! 726: `enum' more consistent with the way `struct' and `union' are handled. ! 727: ! 728: ! 729: File: gcc.info, Node: Bugs, Next: VMS, Prev: Extensions, Up: Top ! 730: ! 731: Reporting Bugs ! 732: ************** ! 733: ! 734: Your bug reports play an essential role in making GNU CC reliable. ! 735: ! 736: When you encounter a problem, the first thing to do is to see if it ! 737: is already known. *Note Trouble::. Also look in *Note ! 738: Incompatibilities::. If it isn't known, then you should report the ! 739: problem. ! 740: ! 741: Reporting a bug may help you by bringing a solution to your ! 742: problem, or it may not. (If it does not, look in the service ! 743: directory; see *Note Service::.) In any case, the principal function ! 744: of a bug report is to help the entire community by making the next ! 745: version of GNU CC work better. Bug reports are your contribution to ! 746: the maintenance of GNU CC. ! 747: ! 748: In order for a bug report to serve its purpose, you must include the ! 749: information that makes for fixing the bug. ! 750: ! 751: * Menu: ! 752: ! 753: * Criteria: Bug Criteria. Have you really found a bug? ! 754: * Reporting: Bug Reporting. How to report a bug effectively. ! 755: * Non-bugs:: Some things we think are not problems. ! 756: * Known: Trouble. Known problems. ! 757: * Help: Service. Where to ask for help. ! 758: ! 759: ! 760: File: gcc.info, Node: Bug Criteria, Next: Bug Reporting, Prev: Bugs, Up: Bugs ! 761: ! 762: Have You Found a Bug? ! 763: ===================== ! 764: ! 765: If you are not sure whether you have found a bug, here are some ! 766: guidelines: ! 767: ! 768: * If the compiler gets a fatal signal, for any input whatever, that ! 769: is a compiler bug. Reliable compilers never crash. ! 770: ! 771: * If the compiler produces invalid assembly code, for any input ! 772: whatever (except an `asm' statement), that is a compiler bug, ! 773: unless the compiler reports errors (not just warnings) which ! 774: would ordinarily prevent the assembler from being run. ! 775: ! 776: * If the compiler produces valid assembly code that does not ! 777: correctly execute the input source code, that is a compiler bug. ! 778: ! 779: However, you must double-check to make sure, because you may have ! 780: run into an incompatibility between GNU C and traditional C ! 781: (*note Incompatibilities::.). These incompatibilities might be ! 782: considered bugs, but they are inescapable consequences of ! 783: valuable features. ! 784: ! 785: Or you may have a program whose behavior is undefined, which ! 786: happened by chance to give the desired results with another C ! 787: compiler. ! 788: ! 789: For example, in many nonoptimizing compilers, you can write `x;' ! 790: at the end of a function instead of `return x;', with the same ! 791: results. But the value of the function is undefined if `return' ! 792: is omitted; it is not a bug when GNU CC produces different ! 793: results. ! 794: ! 795: Problems often result from expressions with two increment ! 796: operators, as in `f (*p++, *p++)'. Your previous compiler might ! 797: have interpreted that expression the way you intended; GNU CC ! 798: might interpret it another way. Neither compiler is wrong. The ! 799: bug is in your code. ! 800: ! 801: After you have localized the error to a single source line, it ! 802: should be easy to check for these things. If your program is ! 803: correct and well defined, you have found a compiler bug. ! 804: ! 805: * If the compiler produces an error message for valid input, that ! 806: is a compiler bug. ! 807: ! 808: Note that the following is not valid input, and the error message ! 809: for it is not a bug: ! 810: ! 811: int foo (char); ! 812: ! 813: int ! 814: foo (x) ! 815: char x; ! 816: { ... } ! 817: ! 818: The prototype says to pass a `char', while the definition says to ! 819: pass an `int' and treat the value as a `char'. This is what the ! 820: ANSI standard says, and it makes sense. ! 821: ! 822: * If the compiler does not produce an error message for invalid ! 823: input, that is a compiler bug. However, you should note that ! 824: your idea of "invalid input" might be my idea of "an extension" ! 825: or "support for traditional practice". ! 826: ! 827: * If you are an experienced user of C compilers, your suggestions ! 828: for improvement of GNU CC are welcome in any case. ! 829: ! 830: ! 831: File: gcc.info, Node: Bug Reporting, Next: Non-bugs, Prev: Bug Criteria, Up: Bugs ! 832: ! 833: How to Report Bugs ! 834: ================== ! 835: ! 836: Send bug reports for GNU C to one of these addresses: ! 837: ! 838: [email protected] ! 839: {ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-gcc ! 840: ! 841: *Do not send bug reports to `help-gcc', or to the newsgroup ! 842: `gnu.gcc.help'.* Most users of GNU CC do not want to receive bug ! 843: reports. Those that do, have asked to be on `bug-gcc'. ! 844: ! 845: The mailing list `bug-gcc' has a newsgroup which serves as a ! 846: repeater. The mailing list and the newsgroup carry exactly the same ! 847: messages. Often people think of posting bug reports to the newsgroup ! 848: instead of mailing them. This appears to work, but it has one problem ! 849: which can be crucial: a newsgroup posting does not contain a mail path ! 850: back to the sender. Thus, if I need to ask for more information, I ! 851: may be unable to reach you. For this reason, it is better to send bug ! 852: reports to the mailing list. ! 853: ! 854: As a last resort, send bug reports on paper to: ! 855: ! 856: GNU Compiler Bugs ! 857: Free Software Foundation ! 858: 675 Mass Ave ! 859: Cambridge, MA 02139 ! 860: ! 861: The fundamental principle of reporting bugs usefully is this: ! 862: *report all the facts*. If you are not sure whether to state a fact ! 863: or leave it out, state it! ! 864: ! 865: Often people omit facts because they think they know what causes the ! 866: problem and they conclude that some details don't matter. Thus, you ! 867: might assume that the name of the variable you use in an example does ! 868: not matter. Well, probably it doesn't, but one cannot be sure. ! 869: Perhaps the bug is a stray memory reference which happens to fetch ! 870: from the location where that name is stored in memory; perhaps, if the ! 871: name were different, the contents of that location would fool the ! 872: compiler into doing the right thing despite the bug. Play it safe and ! 873: give a specific, complete example. That is the easiest thing for you ! 874: to do, and the most helpful. ! 875: ! 876: Keep in mind that the purpose of a bug report is to enable me to fix ! 877: the bug if it is not known. It isn't very important what happens if ! 878: the bug is already known. Therefore, always write your bug reports on ! 879: the assumption that the bug is not known. ! 880: ! 881: Sometimes people give a few sketchy facts and ask, "Does this ring a ! 882: bell?" Those bug reports are useless, and I urge everyone to *refuse ! 883: to respond to them* except to chide the sender to report bugs properly. ! 884: ! 885: To enable me to fix the bug, you should include all these things: ! 886: ! 887: * The version of GNU CC. You can get this by running it with the ! 888: `-v' option. ! 889: ! 890: Without this, I won't know whether there is any point in looking ! 891: for the bug in the current version of GNU CC. ! 892: ! 893: * A complete input file that will reproduce the bug. If the bug is ! 894: in the C preprocessor, send me a source file and any header files ! 895: that it requires. If the bug is in the compiler proper (`cc1'), ! 896: run your source file through the C preprocessor by doing `gcc -E ! 897: SOURCEFILE > OUTFILE', then include the contents of OUTFILE in ! 898: the bug report. (Any `-I', `-D' or `-U' options that you used in ! 899: actual compilation should also be used when doing this.) ! 900: ! 901: A single statement is not enough of an example. In order to ! 902: compile it, it must be embedded in a function definition; and the ! 903: bug might depend on the details of how this is done. ! 904: ! 905: Without a real example I can compile, all I can do about your bug ! 906: report is wish you luck. It would be futile to try to guess how ! 907: to provoke the bug. For example, bugs in register allocation and ! 908: reloading frequently depend on every little detail of the function ! 909: they happen in. ! 910: ! 911: * The command arguments you gave GNU CC to compile that example and ! 912: observe the bug. For example, did you use `-O'? To guarantee ! 913: you won't omit something important, list them all. ! 914: ! 915: If I were to try to guess the arguments, I would probably guess ! 916: wrong and then I would not encounter the bug. ! 917: ! 918: * The type of machine you are using, and the operating system name ! 919: and version number. ! 920: ! 921: * The operands you gave to the `configure' command when you ! 922: installed the compiler. ! 923: ! 924: * A description of what behavior you observe that you believe is ! 925: incorrect. For example, "It gets a fatal signal," or, "There is ! 926: an incorrect assembler instruction in the output." ! 927: ! 928: Of course, if the bug is that the compiler gets a fatal signal, ! 929: then I will certainly notice it. But if the bug is incorrect ! 930: output, I might not notice unless it is glaringly wrong. I won't ! 931: study all the assembler code from a 50-line C program just on the ! 932: off chance that it might be wrong. ! 933: ! 934: Even if the problem you experience is a fatal signal, you should ! 935: still say so explicitly. Suppose something strange is going on, ! 936: such as, your copy of the compiler is out of synch, or you have ! 937: encountered a bug in the C library on your system. (This has ! 938: happened!) Your copy might crash and mine would not. If you ! 939: told me to expect a crash, then when mine fails to crash, I would ! 940: know that the bug was not happening for me. If you had not told ! 941: me to expect a crash, then I would not be able to draw any ! 942: conclusion from my observations. ! 943: ! 944: Often the observed symptom is incorrect output when your program ! 945: is run. Sad to say, this is not enough information for me unless ! 946: the program is short and simple. If you send me a large program, ! 947: I don't have time to figure out how it would work if compiled ! 948: correctly, much less which line of it was compiled wrong. So you ! 949: will have to do that. Tell me which source line it is, and what ! 950: incorrect result happens when that line is executed. A person ! 951: who understands the program can find this as easily as a bug in ! 952: the program itself. ! 953: ! 954: * If you send me examples of output from GNU CC, please use `-g' ! 955: when you make them. The debugging information includes source ! 956: line numbers which are essential for correlating the output with ! 957: the input. ! 958: ! 959: * If you wish to suggest changes to the GNU CC source, send me ! 960: context diffs. If you even discuss something in the GNU CC ! 961: source, refer to it by context, not by line number. ! 962: ! 963: The line numbers in my development sources don't match those in ! 964: your sources. Your line numbers would convey no useful ! 965: information to me. ! 966: ! 967: * Additional information from a debugger might enable me to find a ! 968: problem on a machine which I do not have available myself. ! 969: However, you need to think when you collect this information if ! 970: you want it to have any chance of being useful. ! 971: ! 972: For example, many people send just a backtrace, but that is never ! 973: useful by itself. A simple backtrace with arguments conveys ! 974: little about GNU CC because the compiler is largely data-driven; ! 975: the same functions are called over and over for different RTL ! 976: insns, doing different things depending on the details of the ! 977: insn. ! 978: ! 979: Most of the arguments listed in the backtrace are useless because ! 980: they are pointers to RTL list structure. The numeric values of ! 981: the pointers, which the debugger prints in the backtrace, have no ! 982: significance whatever; all that matters is the contents of the ! 983: objects they point to (and most of the contents are other such ! 984: pointers). ! 985: ! 986: In addition, most compiler passes consist of one or more loops ! 987: that scan the RTL insn sequence. The most vital piece of ! 988: information about such a loop--which insn it has reached--is ! 989: usually in a local variable, not in an argument. ! 990: ! 991: What you need to provide in addition to a backtrace are the ! 992: values of the local variables for several stack frames up. When ! 993: a local variable or an argument is an RTX, first print its value ! 994: and then use the GDB command `pr' to print the RTL expression ! 995: that it points to. (If GDB doesn't run on your machine, use your ! 996: debugger to call the function `debug_rtx' with the RTX as an ! 997: argument.) In general, whenever a variable is a pointer, its ! 998: value is no use without the data it points to. ! 999: ! 1000: In addition, include a debugging dump from just before the pass ! 1001: in which the crash happens. Most bugs involve a series of insns, ! 1002: not just one. ! 1003: ! 1004: Here are some things that are not necessary: ! 1005: ! 1006: * A description of the envelope of the bug. ! 1007: ! 1008: Often people who encounter a bug spend a lot of time investigating ! 1009: which changes to the input file will make the bug go away and ! 1010: which changes will not affect it. ! 1011: ! 1012: This is often time consuming and not very useful, because the way ! 1013: I will find the bug is by running a single example under the ! 1014: debugger with breakpoints, not by pure deduction from a series of ! 1015: examples. I recommend that you save your time for something else. ! 1016: ! 1017: Of course, if you can find a simpler example to report *instead* ! 1018: of the original one, that is a convenience for me. Errors in the ! 1019: output will be easier to spot, running under the debugger will ! 1020: take less time, etc. Most GNU CC bugs involve just one function, ! 1021: so the most straightforward way to simplify an example is to ! 1022: delete all the function definitions except the one where the bug ! 1023: occurs. Those earlier in the file may be replaced by external ! 1024: declarations if the crucial function depends on them. ! 1025: (Exception: inline functions may affect compilation of functions ! 1026: defined later in the file.) ! 1027: ! 1028: However, simplification is not vital; if you don't want to do ! 1029: this, report the bug anyway and send me the entire test case you ! 1030: used. ! 1031: ! 1032: * A patch for the bug. ! 1033: ! 1034: A patch for the bug does help me if it is a good one. But don't ! 1035: omit the necessary information, such as the test case, on the ! 1036: assumption that a patch is all I need. I might see problems with ! 1037: your patch and decide to fix the problem another way, or I might ! 1038: not understand it at all. ! 1039: ! 1040: Sometimes with a program as complicated as GNU CC it is very hard ! 1041: to construct an example that will make the program follow a ! 1042: certain path through the code. If you don't send me the example, ! 1043: I won't be able to construct one, so I won't be able to verify ! 1044: that the bug is fixed. ! 1045: ! 1046: And if I can't understand what bug you are trying to fix, or why ! 1047: your patch should be an improvement, I won't install it. A test ! 1048: case will help me to understand. ! 1049: ! 1050: * A guess about what the bug is or what it depends on. ! 1051: ! 1052: Such guesses are usually wrong. Even I can't guess right about ! 1053: such things without first using the debugger to find the facts. ! 1054: ! 1055:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.