![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-6 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-6 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.3 ! root 1: This is Info file gcc.info, produced by Makeinfo-1.47 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: 6: Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc. 7: 1.1.1.3 ! root 8: Permission is granted to make and distribute verbatim copies of this ! 9: manual provided the copyright notice and this permission notice are ! 10: preserved on all copies. 1.1 root 11: 12: Permission is granted to copy and distribute modified versions of 13: this manual under the conditions for verbatim copying, provided also 1.1.1.3 ! root 14: that the sections entitled "GNU General Public License" and "Boycott" ! 15: are included exactly as in the original, and provided that the entire ! 16: resulting derived work is distributed under the terms of a permission ! 17: notice identical to this one. 1.1 root 18: 19: Permission is granted to copy and distribute translations of this 20: manual into another language, under the above conditions for modified 1.1.1.3 ! root 21: versions, except that the sections entitled "GNU General Public ! 22: License" and "Boycott", and this permission notice, may be included in ! 23: translations approved by the Free Software Foundation instead of in the ! 24: original English. 1.1 root 25: 26: 1.1.1.3 ! root 27: File: gcc.info, Node: Incompatibilities, Next: Disappointments, Prev: Interoperation, Up: Trouble 1.1.1.2 root 28: 1.1.1.3 ! root 29: Incompatibilities of GNU CC ! 30: =========================== 1.1.1.2 root 31: 1.1.1.3 ! root 32: There are several noteworthy incompatibilities between GNU C and most ! 33: existing (non-ANSI) versions of C. The `-traditional' option ! 34: eliminates many of these incompatibilities, *but not all*, by telling ! 35: GNU C to behave like the other C compilers. ! 36: ! 37: * GNU CC normally makes string constants read-only. If several ! 38: identical-looking string constants are used, GNU CC stores only one ! 39: copy of the string. ! 40: ! 41: One consequence is that you cannot call `mktemp' with a string ! 42: constant argument. The function `mktemp' always alters the string ! 43: its argument points to. ! 44: ! 45: Another consequence is that `sscanf' does not work on some systems ! 46: when passed a string constant as its format control string or ! 47: input. This is because `sscanf' incorrectly tries to write into ! 48: the string constant. Likewise `fscanf' and `scanf'. ! 49: ! 50: The best solution to these problems is to change the program to use ! 51: `char'-array variables with initialization strings for these ! 52: purposes instead of string constants. But if this is not possible, ! 53: you can use the `-fwritable-strings' flag, which directs GNU CC to ! 54: handle string constants the same way most C compilers do. ! 55: `-traditional' also has this effect, among others. ! 56: ! 57: * `-2147483648' is positive. ! 58: ! 59: This is because 2147483648 cannot fit in the type `int', so ! 60: (following the ANSI C rules) its data type is `unsigned long int'. ! 61: Negating this value yields 2147483648 again. ! 62: ! 63: * GNU CC does not substitute macro arguments when they appear inside ! 64: of string constants. For example, the following macro in GNU CC ! 65: ! 66: #define foo(a) "a" ! 67: ! 68: will produce output `"a"' regardless of what the argument A is. ! 69: ! 70: The `-traditional' option directs GNU CC to handle such cases ! 71: (among others) in the old-fashioned (non-ANSI) fashion. ! 72: ! 73: * When you use `setjmp' and `longjmp', the only automatic variables ! 74: guaranteed to remain valid are those declared `volatile'. This is ! 75: a consequence of automatic register allocation. Consider this ! 76: function: ! 77: ! 78: jmp_buf j; ! 79: ! 80: foo () ! 81: { ! 82: int a, b; ! 83: ! 84: a = fun1 (); ! 85: if (setjmp (j)) ! 86: return a; ! 87: ! 88: a = fun2 (); ! 89: /* `longjmp (j)' may occur in `fun3'. */ ! 90: return a + fun3 (); ! 91: } ! 92: ! 93: Here `a' may or may not be restored to its first value when the ! 94: `longjmp' occurs. If `a' is allocated in a register, then its ! 95: first value is restored; otherwise, it keeps the last value stored ! 96: in it. ! 97: ! 98: If you use the `-W' option with the `-O' option, you will get a ! 99: warning when GNU CC thinks such a problem might be possible. ! 100: ! 101: The `-traditional' option directs GNU C to put variables in the ! 102: stack by default, rather than in registers, in functions that call ! 103: `setjmp'. This results in the behavior found in traditional C ! 104: compilers. ! 105: ! 106: * Programs that use preprocessor directives in the middle of macro ! 107: arguments do not work with GNU CC. For example, a program like ! 108: this will not work: ! 109: ! 110: foobar ( ! 111: #define luser ! 112: hack) ! 113: ! 114: ANSI C does not permit such a construct. It would make sense to ! 115: support it when `-traditional' is used, but it is too much work to ! 116: implement. ! 117: ! 118: * Declarations of external variables and functions within a block ! 119: apply only to the block containing the declaration. In other ! 120: words, they have the same scope as any other declaration in the ! 121: same place. ! 122: ! 123: In some other C compilers, a `extern' declaration affects all the ! 124: rest of the file even if it happens within a block. ! 125: ! 126: The `-traditional' option directs GNU C to treat all `extern' ! 127: declarations as global, like traditional compilers. ! 128: ! 129: * In traditional C, you can combine `long', etc., with a typedef ! 130: name, as shown here: ! 131: ! 132: typedef int foo; ! 133: typedef long foo bar; ! 134: ! 135: In ANSI C, this is not allowed: `long' and other type modifiers ! 136: require an explicit `int'. Because this criterion is expressed by ! 137: Bison grammar rules rather than C code, the `-traditional' flag ! 138: cannot alter it. ! 139: ! 140: * PCC allows typedef names to be used as function parameters. The ! 141: difficulty described immediately above applies here too. ! 142: ! 143: * PCC allows whitespace in the middle of compound assignment ! 144: operators such as `+='. GNU CC, following the ANSI standard, does ! 145: not allow this. The difficulty described immediately above ! 146: applies here too. ! 147: ! 148: * GNU CC will flag unterminated character constants inside of ! 149: preprocessor conditionals that fail. Some programs have English ! 150: comments enclosed in conditionals that are guaranteed to fail; if ! 151: these comments contain apostrophes, GNU CC will probably report an ! 152: error. For example, this code would produce an error: ! 153: ! 154: #if 0 ! 155: You can't expect this to work. ! 156: #endif ! 157: ! 158: The best solution to such a problem is to put the text into an ! 159: actual C comment delimited by `/*...*/'. However, `-traditional' ! 160: suppresses these error messages. ! 161: ! 162: * When compiling functions that return `float', PCC converts it to a ! 163: double. GNU CC actually returns a `float'. If you are concerned ! 164: with PCC compatibility, you should declare your functions to return ! 165: `double'; you might as well say what you mean. ! 166: ! 167: * When compiling functions that return structures or unions, GNU CC ! 168: output code normally uses a method different from that used on most ! 169: versions of Unix. As a result, code compiled with GNU CC cannot ! 170: call a structure-returning function compiled with PCC, and vice ! 171: versa. ! 172: ! 173: The method used by GNU CC is as follows: a structure or union ! 174: which is 1, 2, 4 or 8 bytes long is returned like a scalar. A ! 175: structure or union with any other size is stored into an address ! 176: supplied by the caller (usually in a special, fixed register, but ! 177: on some machines it is passed on the stack). The ! 178: machine-description macros `STRUCT_VALUE' and ! 179: `STRUCT_INCOMING_VALUE' tell GNU CC where to pass this address. ! 180: ! 181: By contrast, PCC on most target machines returns structures and ! 182: unions of any size by copying the data into an area of static ! 183: storage, and then returning the address of that storage as if it ! 184: were a pointer value. The caller must copy the data from that ! 185: memory area to the place where the value is wanted. GNU CC does ! 186: not use this method because it is slower and nonreentrant. ! 187: ! 188: On some newer machines, PCC uses a reentrant convention for all ! 189: structure and union returning. GNU CC on most of these machines ! 190: uses a compatible convention when returning structures and unions ! 191: in memory, but still returns small structures and unions in ! 192: registers. ! 193: ! 194: You can tell GNU CC to use a compatible convention for all ! 195: structure and union returning with the option ! 196: `-fpcc-struct-return'. 1.1.1.2 root 197: 1.1.1.3 ! root 198: ! 199: File: gcc.info, Node: Disappointments, Next: Non-bugs, Prev: Incompatibilities, Up: Trouble 1.1.1.2 root 200: 1.1.1.3 ! root 201: Disappointments and Misunderstandings ! 202: ===================================== 1.1.1.2 root 203: 1.1.1.3 ! root 204: These problems are perhaps regrettable, but we don't know any ! 205: practical way around them. 1.1.1.2 root 206: 1.1.1.3 ! root 207: * Certain local variables aren't recognized by debuggers when you ! 208: compile with optimization. 1.1.1.2 root 209: 1.1.1.3 ! root 210: This occurs because sometimes GNU CC optimizes the variable out of ! 211: existence. There is no way to tell the debugger how to compute the ! 212: value such a variable "would have had", and it is not clear that ! 213: would be desirable anyway. So GNU CC simply does not mention the ! 214: eliminated variable when it writes debugging information. ! 215: ! 216: You have to expect a certain amount of disagreement between the ! 217: executable and your source code, when you use optimization. ! 218: ! 219: * Users often think it is a bug when GNU CC reports an error for code ! 220: like this: ! 221: ! 222: int foo (struct mumble *); ! 223: ! 224: struct mumble { ... }; ! 225: ! 226: int foo (struct mumble *x) ! 227: { ... } ! 228: ! 229: This code really is erroneous, because the scope of `struct ! 230: mumble' the prototype is limited to the argument list containing ! 231: it. It does not refer to the `struct mumble' defined with file ! 232: scope immediately below--they are two unrelated types with similar ! 233: names in different scopes. ! 234: ! 235: But in the definition of `foo', the file-scope type is used ! 236: because that is available to be inherited. Thus, the definition ! 237: and the prototype do not match, and you get an error. ! 238: ! 239: This behavior may seem silly, but it's what the ANSI standard ! 240: specifies. It is easy enough for you to make your code work by ! 241: moving the definition of `struct mumble' above the prototype. ! 242: It's not worth being incompatible with ANSI C just to avoid an ! 243: error for the example shown above. 1.1.1.2 root 244: 245: 1.1.1.3 ! root 246: File: gcc.info, Node: Non-bugs, Prev: Disappointments, Up: Trouble 1.1 root 247: 248: Certain Changes We Don't Want to Make 249: ===================================== 250: 251: This section lists changes that people frequently request, but which 252: we do not make because we think GNU CC is better without them. 253: 254: * Checking the number and type of arguments to a function which has 255: an old-fashioned definition and no prototype. 256: 257: Such a feature would work only occasionally--only for calls that 258: appear in the same file as the called function, following the 259: definition. The only way to check all calls reliably is to add a 1.1.1.3 ! root 260: prototype for the function. But adding a prototype eliminates the ! 261: motivation for this feature. So the feature is not worthwhile. 1.1 root 262: 263: * Warning about using an expression whose type is signed as a shift 264: count. 265: 1.1.1.3 ! root 266: Shift count operands are probably signed more often than unsigned. 1.1 root 267: Warning about this would cause far more annoyance than good. 268: 269: * Warning about assigning a signed value to an unsigned variable. 270: 271: Such assignments must be very common; warning about them would 272: cause more annoyance than good. 273: 1.1.1.2 root 274: * Warning when a non-void function value is ignored. 275: 276: Coming as I do from a Lisp background, I balk at the idea that 277: there is something dangerous about discarding a value. There are 278: functions that return values which some callers may find useful; 279: it makes no sense to clutter the program with a cast to `void' 280: whenever the value isn't useful. 281: 1.1.1.3 ! root 282: * Assuming (for optimization) that the address of an external symbol ! 283: is never zero. ! 284: ! 285: This assumption is false on certain systems when `#pragma weak' is ! 286: used. ! 287: ! 288: * Making `-fshort-enums' the default. ! 289: ! 290: This would cause storage layout to be incompatible with most other ! 291: C compilers. And it doesn't seem very important, given that you ! 292: can get the same result in other ways. The case where it matters ! 293: most is when the enumeration-valued object is inside a structure, ! 294: and in that case you can specify a field width explicitly. ! 295: 1.1 root 296: * Making bitfields unsigned by default on particular machines where 297: "the ABI standard" says to do so. 298: 299: The ANSI C standard leaves it up to the implementation whether a 300: bitfield declared plain `int' is signed or not. This in effect 301: creates two alternative dialects of C. 302: 303: The GNU C compiler supports both dialects; you can specify the 304: dialect you want with the option `-fsigned-bitfields' or 1.1.1.3 ! root 305: `-funsigned-bitfields'. However, this leaves open the question of ! 306: which dialect to use by default. 1.1 root 307: 308: Currently, the preferred dialect makes plain bitfields signed, 1.1.1.3 ! root 309: because this is simplest. Since `int' is the same as `signed int' ! 310: in every other context, it is cleanest for them to be the same in ! 311: bitfields as well. 1.1 root 312: 313: Some computer manufacturers have published Application Binary 314: Interface standards which specify that plain bitfields should be 315: unsigned. It is a mistake, however, to say anything about this 316: issue in an ABI. This is because the handling of plain bitfields 1.1.1.3 ! root 317: distinguishes two dialects of C. Both dialects are meaningful on 1.1 root 318: every type of machine. Whether a particular object file was 319: compiled using signed bitfields or unsigned is of no concern to 1.1.1.2 root 320: other object files, even if they access the same bitfields in the 321: same data structures. 1.1 root 322: 323: A given program is written in one or the other of these two 1.1.1.3 ! root 324: dialects. The program stands a chance to work on most any machine ! 325: if it is compiled with the proper dialect. It is unlikely to work ! 326: at all if compiled with the wrong dialect. 1.1 root 327: 328: Many users appreciate the GNU C compiler because it provides an 329: environment that is uniform across machines. These users would be 1.1.1.3 ! root 330: inconvenienced if the compiler treated plain bitfields differently ! 331: on certain machines. 1.1 root 332: 333: Occasionally users write programs intended only for a particular 334: machine type. On these occasions, the users would benefit if the 335: GNU C compiler were to support by default the same dialect as the 1.1.1.3 ! root 336: other compilers on that machine. But such applications are rare. ! 337: And users writing a program to run on more than one type of 1.1 root 338: machine cannot possibly benefit from this kind of compatibility. 339: 340: This is why GNU CC does and will treat plain bitfields in the same 341: fashion on all types of machines (by default). 342: 1.1.1.2 root 343: There are some arguments for making bitfields unsigned by default 344: on all machines. If, for example, this becomes a universal de 345: facto standard, it would make sense for GNU CC to go along with 346: it. This is something to be considered in the future. 347: 1.1 root 348: (Of course, users strongly concerned about portability should 1.1.1.3 ! root 349: indicate explicitly in each bitfield whether it is signed or not. ! 350: In this way, they write programs which have the same meaning in 1.1.1.2 root 351: both C dialects.) 1.1 root 352: 353: * Undefining `__STDC__' when `-ansi' is not used. 354: 355: Currently, GNU CC defines `__STDC__' as long as you don't use 356: `-traditional'. This provides good results in practice. 357: 358: Programmers normally use conditionals on `__STDC__' to ask whether 359: it is safe to use certain features of ANSI C, such as function 1.1.1.3 ! root 360: prototypes or ANSI token concatenation. Since plain `gcc' supports ! 361: all the features of ANSI C, the correct answer to these questions ! 362: is "yes". 1.1 root 363: 364: Some users try to use `__STDC__' to check for the availability of 365: certain library facilities. This is actually incorrect usage in 366: an ANSI C program, because the ANSI C standard says that a 367: conforming freestanding implementation should define `__STDC__' 368: even though it does not have the library facilities. `gcc -ansi 369: -pedantic' is a conforming freestanding implementation, and it is 370: therefore required to define `__STDC__', even though it does not 371: come with an ANSI C library. 372: 373: Sometimes people say that defining `__STDC__' in a compiler that 374: does not completely conform to the ANSI C standard somehow 375: violates the standard. This is illogical. The standard is a 1.1.1.2 root 376: standard for compilers that claim to support ANSI C, such as `gcc 1.1.1.3 ! root 377: -ansi'--not for other compilers such as plain `gcc'. Whatever the ! 378: ANSI C standard says is relevant to the design of plain `gcc' 1.1 root 379: without `-ansi' only for pragmatic reasons, not as a requirement. 380: 381: * Undefining `__STDC__' in C++. 382: 383: Programs written to compile with C++-to-C translators get the 384: value of `__STDC__' that goes with the C compiler that is 385: subsequently used. These programs must test `__STDC__' to 386: determine what kind of C preprocessor that compiler uses: whether 387: they should concatenate tokens in the ANSI C fashion or in the 388: traditional fashion. 389: 1.1.1.3 ! root 390: These programs work properly with GNU C++ if `__STDC__' is defined. ! 391: They would not work otherwise. 1.1 root 392: 393: In addition, many header files are written to provide prototypes 394: in ANSI C but not in traditional C. Many of these header files 1.1.1.3 ! root 395: can work without change in C++ provided `__STDC__' is defined. If ! 396: `__STDC__' is not defined, they will all fail, and will all need ! 397: to be changed to test explicitly for C++ as well. ! 398: ! 399: * Deleting "empty" loops. ! 400: ! 401: GNU CC does not delete "empty" loops because the most likely reason ! 402: you would put one in a program is to have a delay. Deleting them ! 403: will not make real programs run any faster, so it would be ! 404: pointless. ! 405: ! 406: It would be different if optimization of a nonempty loop could ! 407: produce an empty one. But this generally can't happen. ! 408: ! 409: ! 410: File: gcc.info, Node: Bugs, Next: Service, Prev: Trouble, Up: Top ! 411: ! 412: Reporting Bugs ! 413: ************** ! 414: ! 415: Your bug reports play an essential role in making GNU CC reliable. ! 416: ! 417: When you encounter a problem, the first thing to do is to see if it ! 418: is already known. *Note Trouble::. If it isn't known, then you should ! 419: report the problem. ! 420: ! 421: Reporting a bug may help you by bringing a solution to your problem, ! 422: or it may not. (If it does not, look in the service directory; see ! 423: *Note Service::.) In any case, the principal function of a bug report ! 424: is to help the entire community by making the next version of GNU CC ! 425: work better. Bug reports are your contribution to the maintenance of ! 426: GNU CC. ! 427: ! 428: In order for a bug report to serve its purpose, you must include the ! 429: information that makes for fixing the bug. ! 430: ! 431: * Menu: ! 432: ! 433: * Criteria: Bug Criteria. Have you really found a bug? ! 434: * Where: Bug Lists. Where to send your bug report. ! 435: * Reporting: Bug Reporting. How to report a bug effectively. ! 436: * Patches: Sending Patches. How to send a patch for GNU CC. ! 437: * Known: Trouble. Known problems. ! 438: * Help: Service. Where to ask for help. ! 439: ! 440: ! 441: File: gcc.info, Node: Bug Criteria, Next: Bug Lists, Up: Bugs ! 442: ! 443: Have You Found a Bug? ! 444: ===================== ! 445: ! 446: If you are not sure whether you have found a bug, here are some ! 447: guidelines: ! 448: ! 449: * If the compiler gets a fatal signal, for any input whatever, that ! 450: is a compiler bug. Reliable compilers never crash. ! 451: ! 452: * If the compiler produces invalid assembly code, for any input ! 453: whatever (except an `asm' statement), that is a compiler bug, ! 454: unless the compiler reports errors (not just warnings) which would ! 455: ordinarily prevent the assembler from being run. ! 456: ! 457: * If the compiler produces valid assembly code that does not ! 458: correctly execute the input source code, that is a compiler bug. ! 459: ! 460: However, you must double-check to make sure, because you may have ! 461: run into an incompatibility between GNU C and traditional C (*note ! 462: Incompatibilities::.). These incompatibilities might be considered ! 463: bugs, but they are inescapable consequences of valuable features. ! 464: ! 465: Or you may have a program whose behavior is undefined, which ! 466: happened by chance to give the desired results with another C or ! 467: C++ compiler. ! 468: ! 469: For example, in many nonoptimizing compilers, you can write `x;' ! 470: at the end of a function instead of `return x;', with the same ! 471: results. But the value of the function is undefined if `return' ! 472: is omitted; it is not a bug when GNU CC produces different results. ! 473: ! 474: Problems often result from expressions with two increment ! 475: operators, as in `f (*p++, *p++)'. Your previous compiler might ! 476: have interpreted that expression the way you intended; GNU CC might ! 477: interpret it another way. Neither compiler is wrong. The bug is ! 478: in your code. ! 479: ! 480: After you have localized the error to a single source line, it ! 481: should be easy to check for these things. If your program is ! 482: correct and well defined, you have found a compiler bug. ! 483: ! 484: * If the compiler produces an error message for valid input, that is ! 485: a compiler bug. ! 486: ! 487: * If the compiler does not produce an error message for invalid ! 488: input, that is a compiler bug. However, you should note that your ! 489: idea of "invalid input" might be my idea of "an extension" or ! 490: "support for traditional practice". ! 491: ! 492: * If you are an experienced user of C or C++ compilers, your ! 493: suggestions for improvement of GNU CC or GNU C++ are welcome in ! 494: any case. ! 495: ! 496: ! 497: File: gcc.info, Node: Bug Lists, Next: Bug Reporting, Prev: Bug Criteria, Up: Bugs ! 498: ! 499: Where to Report Bugs ! 500: ==================== ! 501: ! 502: Send bug reports for GNU C to one of these addresses: ! 503: ! 504: [email protected] ! 505: {ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-gcc ! 506: ! 507: Send bug reports for GNU C++ to one of these addresses: ! 508: ! 509: [email protected] ! 510: {ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-g++ ! 511: ! 512: *Do not send bug reports to `help-gcc', or to the newsgroup ! 513: `gnu.gcc.help'.* Most users of GNU CC do not want to receive bug ! 514: reports. Those that do, have asked to be on `bug-gcc' and/or `bug-g++'. ! 515: ! 516: The mailing lists `bug-gcc' and `bug-g++' both have newsgroups which ! 517: serve as repeaters: `gnu.gcc.bug' and `gnu.g++.bug'. Each mailing list ! 518: and its newsgroup carry exactly the same messages. ! 519: ! 520: Often people think of posting bug reports to the newsgroup instead of ! 521: mailing them. This appears to work, but it has one problem which can be ! 522: crucial: a newsgroup posting does not contain a mail path back to the ! 523: sender. Thus, if maintaners need more information, they may be unable ! 524: to reach you. For this reason, you should always send bug reports by ! 525: mail to the proper mailing list. ! 526: ! 527: As a last resort, send bug reports on paper to: ! 528: ! 529: GNU Compiler Bugs ! 530: Free Software Foundation ! 531: 675 Mass Ave ! 532: Cambridge, MA 02139 ! 533: ! 534: ! 535: File: gcc.info, Node: Bug Reporting, Next: Sending Patches, Prev: Bug Lists, Up: Bugs ! 536: ! 537: How to Report Bugs ! 538: ================== ! 539: ! 540: The fundamental principle of reporting bugs usefully is this: ! 541: *report all the facts*. If you are not sure whether to state a fact or ! 542: leave it out, state it! ! 543: ! 544: Often people omit facts because they think they know what causes the ! 545: problem and they conclude that some details don't matter. Thus, you ! 546: might assume that the name of the variable you use in an example does ! 547: not matter. Well, probably it doesn't, but one cannot be sure. Perhaps ! 548: the bug is a stray memory reference which happens to fetch from the ! 549: location where that name is stored in memory; perhaps, if the name were ! 550: different, the contents of that location would fool the compiler into ! 551: doing the right thing despite the bug. Play it safe and give a ! 552: specific, complete example. That is the easiest thing for you to do, ! 553: and the most helpful. ! 554: ! 555: Keep in mind that the purpose of a bug report is to enable someone to ! 556: fix the bug if it is not known. It isn't very important what happens if ! 557: the bug is already known. Therefore, always write your bug reports on ! 558: the assumption that the bug is not known. ! 559: ! 560: Sometimes people give a few sketchy facts and ask, "Does this ring a ! 561: bell?" This cannot help us fix a bug, so it is basically useless. We ! 562: respond by asking for enough details to enable us to investigate. You ! 563: might as well expedite matters by sending them to begin with. ! 564: ! 565: Try to make your bug report self-contained. If we have to ask you ! 566: for more information, it is best if you include all the previous ! 567: information in your response, as well as the information that was ! 568: missing. ! 569: ! 570: To enable someone to investigate the bug, you should include all ! 571: these things: ! 572: ! 573: * The version of GNU CC. You can get this by running it with the ! 574: `-v' option. ! 575: ! 576: Without this, we won't know whether there is any point in looking ! 577: for the bug in the current version of GNU CC. ! 578: ! 579: * A complete input file that will reproduce the bug. If the bug is ! 580: in the C preprocessor, send a source file and any header files ! 581: that it requires. If the bug is in the compiler proper (`cc1'), ! 582: run your source file through the C preprocessor by doing `gcc -E ! 583: SOURCEFILE > OUTFILE', then include the contents of OUTFILE in the ! 584: bug report. (When you do this, use the same `-I', `-D' or `-U' ! 585: options that you used in actual compilation.) ! 586: ! 587: A single statement is not enough of an example. In order to ! 588: compile it, it must be embedded in a function definition; and the ! 589: bug might depend on the details of how this is done. ! 590: ! 591: Without a real example one can compile, all anyone can do about ! 592: your bug report is wish you luck. It would be futile to try to ! 593: guess how to provoke the bug. For example, bugs in register ! 594: allocation and reloading frequently depend on every little detail ! 595: of the function they happen in. ! 596: ! 597: * The command arguments you gave GNU CC or GNU C++ to compile that ! 598: example and observe the bug. For example, did you use `-O'? To ! 599: guarantee you won't omit something important, list all the options. ! 600: ! 601: If we were to try to guess the arguments, we would probably guess ! 602: wrong and then we would not encounter the bug. ! 603: ! 604: * The type of machine you are using, and the operating system name ! 605: and version number. ! 606: ! 607: * The operands you gave to the `configure' command when you installed ! 608: the compiler. ! 609: ! 610: * A complete list of any modifications you have made to the compiler ! 611: source. (We don't promise to investigate the bug unless it ! 612: happens in an unmodified compiler. But if you've made ! 613: modifications and don't tell us, then you are sending us on a wild ! 614: goose chase.) ! 615: ! 616: Be precise about these changes--show a context diff for them. ! 617: ! 618: Adding files of your own (such as a machine description for a ! 619: machine we don't support) is a modification of the compiler source. ! 620: ! 621: * Details of any other deviations from the standard procedure for ! 622: installing GNU CC. ! 623: ! 624: * A description of what behavior you observe that you believe is ! 625: incorrect. For example, "The compiler gets a fatal signal," or, ! 626: "The assembler instruction at line 208 in the output is incorrect." ! 627: ! 628: Of course, if the bug is that the compiler gets a fatal signal, ! 629: then one can't miss it. But if the bug is incorrect output, the ! 630: maintainer might not notice unless it is glaringly wrong. None of ! 631: us has time to study all the assembler code from a 50-line C ! 632: program just on the chance that one instruction might be wrong. ! 633: We need `you' to do this part! ! 634: ! 635: Even if the problem you experience is a fatal signal, you should ! 636: still say so explicitly. Suppose something strange is going on, ! 637: such as, your copy of the compiler is out of synch, or you have ! 638: encountered a bug in the C library on your system. (This has ! 639: happened!) Your copy might crash and the copy here would not. If ! 640: you said to expect a crash, then when the compiler here fails to ! 641: crash, we would know that the bug was not happening. If you don't ! 642: say to expect a crash, then we would not know whether the bug was ! 643: happening. We would not be able to draw any conclusion from our ! 644: observations. ! 645: ! 646: Often the observed symptom is incorrect output when your program ! 647: is run. Sad to say, this is not enough information unless the ! 648: program is short and simple. None of us has time to study a large ! 649: program to figure out how it would work if compiled correctly, ! 650: much less which line of it was compiled wrong. So you will have ! 651: to do that. Tell us which source line it is, and what incorrect ! 652: result happens when that line is executed. A person who ! 653: understands the program can find this as easily as finding a bug ! 654: in the program itself. ! 655: ! 656: * If you send examples of assembler code output from GNU CC or GNU ! 657: C++, please use `-g' when you make them. The debugging information ! 658: includes source line numbers which are essential for correlating ! 659: the output with the input. ! 660: ! 661: * If you wish to suggest changes to the GNU CC source, send them as ! 662: context diffs. If you even discuss something in the GNU CC source, ! 663: refer to it by context, not by line number. ! 664: ! 665: The line numbers in the development sources don't match those in ! 666: your sources. Your line numbers would convey no useful ! 667: information to the maintainers. ! 668: ! 669: * Additional information from a debugger might enable someone to ! 670: find a problem on a machine which he does not have available. ! 671: However, you need to think when you collect this information if ! 672: you want it to have any chance of being useful. ! 673: ! 674: For example, many people send just a backtrace, but that is never ! 675: useful by itself. A simple backtrace with arguments conveys little ! 676: about GNU CC because the compiler is largely data-driven; the same ! 677: functions are called over and over for different RTL insns, doing ! 678: different things depending on the details of the insn. ! 679: ! 680: Most of the arguments listed in the backtrace are useless because ! 681: they are pointers to RTL list structure. The numeric values of the ! 682: pointers, which the debugger prints in the backtrace, have no ! 683: significance whatever; all that matters is the contents of the ! 684: objects they point to (and most of the contents are other such ! 685: pointers). ! 686: ! 687: In addition, most compiler passes consist of one or more loops that ! 688: scan the RTL insn sequence. The most vital piece of information ! 689: about such a loop--which insn it has reached--is usually in a ! 690: local variable, not in an argument. ! 691: ! 692: What you need to provide in addition to a backtrace are the values ! 693: of the local variables for several stack frames up. When a local ! 694: variable or an argument is an RTX, first print its value and then ! 695: use the GDB command `pr' to print the RTL expression that it points ! 696: to. (If GDB doesn't run on your machine, use your debugger to call ! 697: the function `debug_rtx' with the RTX as an argument.) In ! 698: general, whenever a variable is a pointer, its value is no use ! 699: without the data it points to. ! 700: ! 701: In addition, include a debugging dump from just before the pass in ! 702: which the crash happens. Most bugs involve a series of insns, not ! 703: just one. ! 704: ! 705: Here are some things that are not necessary: ! 706: ! 707: * A description of the envelope of the bug. ! 708: ! 709: Often people who encounter a bug spend a lot of time investigating ! 710: which changes to the input file will make the bug go away and which ! 711: changes will not affect it. ! 712: ! 713: This is often time consuming and not very useful, because the way ! 714: we will find the bug is by running a single example under the ! 715: debugger with breakpoints, not by pure deduction from a series of ! 716: examples. You might as well save your time for something else. ! 717: ! 718: Of course, if you can find a simpler example to report *instead* of ! 719: the original one, that is a convenience. Errors in the output ! 720: will be easier to spot, running under the debugger will take less ! 721: time, etc. Most GNU CC bugs involve just one function, so the most ! 722: straightforward way to simplify an example is to delete all the ! 723: function definitions except the one where the bug occurs. Those ! 724: earlier in the file may be replaced by external declarations if ! 725: the crucial function depends on them. (Exception: inline ! 726: functions may affect compilation of functions defined later in the ! 727: file.) ! 728: ! 729: However, simplification is not vital; if you don't want to do this, ! 730: report the bug anyway and send the entire test case you used. ! 731: ! 732: * A patch for the bug. ! 733: ! 734: A patch for the bug is useful if it is a good one. But don't omit ! 735: the necessary information, such as the test case, on the ! 736: assumption that a patch is all we need. We might see problems ! 737: with your patch and decide to fix the problem another way, or we ! 738: might not understand it at all. ! 739: ! 740: Sometimes with a program as complicated as GNU CC it is very hard ! 741: to construct an example that will make the program follow a ! 742: certain path through the code. If you don't send the example, we ! 743: won't be able to construct one, so we won't be able to verify that ! 744: the bug is fixed. ! 745: ! 746: And if we can't understand what bug you are trying to fix, or why ! 747: your patch should be an improvement, we won't install it. A test ! 748: case will help us to understand. ! 749: ! 750: *Note Sending Patches::, for guidelines on how to make it easy for ! 751: us to understand and install your patches. ! 752: ! 753: * A guess about what the bug is or what it depends on. ! 754: ! 755: Such guesses are usually wrong. Even I can't guess right about ! 756: such things without first using the debugger to find the facts. 1.1 root 757: 758: 1.1.1.3 ! root 759: File: gcc.info, Node: Sending Patches, Prev: Bug Reporting, Up: Bugs ! 760: ! 761: Sending Patches for GNU CC ! 762: ========================== ! 763: ! 764: If you would like to write bug fixes or improvements for the GNU C ! 765: compiler, that is very helpful. When you send your changes, please ! 766: follow these guidelines to avoid causing extra work for us in studying ! 767: the patches. ! 768: ! 769: If you don't follow these guidelines, your information might still be ! 770: useful, but using it will take extra work. Maintaining GNU C is a lot ! 771: of work in the best of circumstances, and we can't keep up unless you do ! 772: your best to help. ! 773: ! 774: * Send an explanation with your changes of what problem they fix or ! 775: what improvement they bring about. For a bug fix, just include a ! 776: copy of the bug report, and explain why the change fixes the bug. ! 777: ! 778: (Referring to a bug report is not as good as including it, because ! 779: then we will have to look it up, and we have probably already ! 780: deleted it if we've already fixed the bug.) ! 781: ! 782: * Always include a proper bug report for the problem you think you ! 783: have fixed. We need to convince ourselves that the change is ! 784: right before installing it. Even if it is right, we might have ! 785: trouble judging it if we don't have a way to reproduce the problem. ! 786: ! 787: * Include all the comments that are appropriate to help people ! 788: reading the source in the future understand why this change was ! 789: needed. ! 790: ! 791: * Don't mix together changes made for different reasons. Send them ! 792: *individually*. ! 793: ! 794: If you make two changes for separate reasons, then we might not ! 795: want to install them both. We might want to install just one. If ! 796: you send them all jumbled together in a single set of diffs, we ! 797: have to do extra work to disentangle them--to figure out which ! 798: parts of the change serve which purpose. If we don't have time ! 799: for this, we might have to ignore your changes entirely. ! 800: ! 801: If you send each change as soon as you have written it, with its ! 802: own explanation, then the two changes never get tangled up, and we ! 803: can consider each one properly without any extra work to ! 804: disentangle them. ! 805: ! 806: Ideally, each change you send should be impossible to subdivide ! 807: into parts that we might want to consider separately, because each ! 808: of its parts gets its motivation from the other parts. ! 809: ! 810: * Send each change as soon as that change is finished. Sometimes ! 811: people think they are helping us by accumulating many changes to ! 812: send them all together. As explained above, this is absolutely ! 813: the worst thing you could do. ! 814: ! 815: Since you should send each change separately, you might as well ! 816: send it right away. That gives us the option of installing it ! 817: immediately if it is important. ! 818: ! 819: * Use `diff -c' to make your diffs. Diffs without context are hard ! 820: for us to install reliably. More than that, they make it hard for ! 821: us to study the diffs to decide whether we want to install them. ! 822: Unidiff format is better than contextless diffs, but not as easy ! 823: to read as `-c' format. ! 824: ! 825: If you have GNU diff, use `diff -cp', which shows the name of the ! 826: function that each change occurs in. ! 827: ! 828: * Write the change log entries for your changes. We get lots of ! 829: changes, and we don't have time to do all the change log writing ! 830: ourselves. ! 831: ! 832: Read the `ChangeLog' file to see what sorts of information to put ! 833: in, and to learn the style that we use. The purpose of the change ! 834: log is to show people where to find what was changed. So you need ! 835: to be specific about what functions you changed; in large ! 836: functions, it's often helpful to indicate where within the ! 837: function the change was. ! 838: ! 839: On the other hand, once you have shown people where to find the ! 840: change, you need not explain its purpose. Thus, if you add a new ! 841: function, all you need to say about it is that it is new. If you ! 842: feel that the purpose needs explaining, it probably does--but the ! 843: explanation will be much more useful if you put it in comments in ! 844: the code. ! 845: ! 846: If you would like your name to appear in the header line for who ! 847: made the change, send us the header line. ! 848: ! 849: * When you write the fix, keep in mind that I can't install a change ! 850: that would break other systems. ! 851: ! 852: People often suggest fixing a problem by changing ! 853: machine-independent files such as `toplev.c' to do something ! 854: special that a particular system needs. Sometimes it is totally ! 855: obvious that such changes would break GNU CC for almost all users. ! 856: We can't possibly make a change like that. At best it might tell ! 857: us how to write another patch that would solve the problem ! 858: acceptably. ! 859: ! 860: Sometimes people send fixes that *might* be an improvement in ! 861: general--but it is hard to be sure of this. It's hard to install ! 862: such changes because we have to study them very carefully. Of ! 863: course, a good explanation of the reasoning by which you concluded ! 864: the change was correct can help convince us. ! 865: ! 866: The safest changes are changes to the configuration files for a ! 867: particular machine. These are safe because they can't create new ! 868: bugs on other machines. ! 869: ! 870: Please help us keep up with the workload by designing the patch in ! 871: a form that is good to install. ! 872: ! 873: ! 874: File: gcc.info, Node: Service, Next: VMS, Prev: Bugs, Up: Top ! 875: ! 876: How To Get Help with GNU CC ! 877: *************************** ! 878: ! 879: If you need help installing, using or changing GNU CC, there are two ! 880: ways to find it: ! 881: ! 882: * Send a message to a suitable network mailing list. First try ! 883: `[email protected]', and if that brings no response, try ! 884: `[email protected]'. ! 885: ! 886: * Look in the service directory for someone who might help you for a ! 887: fee. The service directory is found in the file named `SERVICE' in ! 888: the GNU CC distribution. ! 889: ! 890: ! 891: File: gcc.info, Node: VMS, Next: Portability, Prev: Service, Up: Top 1.1 root 892: 893: Using GNU CC on VMS 894: ******************* 895: 896: * Menu: 897: 898: * Include Files and VMS:: Where the preprocessor looks for the include files. 899: * Global Declarations:: How to do globaldef, globalref and globalvalue with 900: GNU CC. 901: * VMS Misc:: Misc information. 902: 903: 1.1.1.3 ! root 904: File: gcc.info, Node: Include Files and VMS, Next: Global Declarations, Up: VMS 1.1 root 905: 906: Include Files and VMS 907: ===================== 908: 909: Due to the differences between the filesystems of Unix and VMS, GNU 910: CC attempts to translate file names in `#include' into names that VMS 911: will understand. The basic strategy is to prepend a prefix to the 912: specification of the include file, convert the whole filename to a VMS 913: filename, and then try to open the file. GNU CC tries various prefixes 914: one by one until one of them succeeds: 915: 916: 1. The first prefix is the `GNU_CC_INCLUDE:' logical name: this is 1.1.1.3 ! root 917: where GNU C header files are traditionally stored. If you wish to ! 918: store header files in non-standard locations, then you can assign ! 919: the logical `GNU_CC_INCLUDE' to be a search list, where each ! 920: element of the list is suitable for use with a rooted logical. 1.1 root 921: 922: 2. The next prefix tried is `SYS$SYSROOT:[SYSLIB.]'. This is where 923: VAX-C header files are traditionally stored. 924: 925: 3. If the include file specification by itself is a valid VMS 926: filename, the preprocessor then uses this name with no prefix in 927: an attempt to open the include file. 928: 929: 4. If the file specification is not a valid VMS filename (i.e. does 930: not contain a device or a directory specifier, and contains a `/' 931: character), the preprocessor tries to convert it from Unix syntax 932: to VMS syntax. 933: 1.1.1.3 ! root 934: Conversion works like this: the first directory name becomes a 1.1 root 935: device, and the rest of the directories are converted into 936: VMS-format directory names. For example, `X11/foobar.h' is 937: translated to `X11:[000000]foobar.h' or `X11:foobar.h', whichever 938: one can be opened. This strategy allows you to assign a logical 939: name to point to the actual location of the header files. 940: 941: 5. If none of these strategies succeeds, the `#include' fails. 942: 943: Include directives of the form: 944: 945: #include foobar 946: 947: are a common source of incompatibility between VAX-C and GNU CC. VAX-C 1.1.1.3 ! root 948: treats this much like a standard `#include <foobar.h>' directive. That ! 949: is incompatible with the ANSI C behavior implemented by GNU CC: to ! 950: expand the name `foobar' as a macro. Macro expansion should eventually ! 951: yield one of the two standard formats for `#include': 1.1 root 952: 953: #include "FILE" 954: #include <FILE> 955: 956: If you have this problem, the best solution is to modify the source 1.1.1.3 ! root 957: to convert the `#include' directives to one of the two standard forms. ! 958: That will work with either compiler. If you want a quick and dirty fix, ! 959: define the file names as macros with the proper expansion, like this: 1.1 root 960: 961: #define stdio <stdio.h> 962: 963: This will work, as long as the name doesn't conflict with anything else 964: in the program. 965: 966: Another source of incompatibility is that VAX-C assumes that: 967: 968: #include "foobar" 969: 970: is actually asking for the file `foobar.h'. GNU CC does not make this 971: assumption, and instead takes what you ask for literally; it tries to 972: read the file `foobar'. The best way to avoid this problem is to 973: always specify the desired file extension in your include directives. 974: 975: GNU CC for VMS is distributed with a set of include files that is 976: sufficient to compile most general purpose programs. Even though the 977: GNU CC distribution does not contain header files to define constants 978: and structures for some VMS system-specific functions, there is no 1.1.1.3 ! root 979: reason why you cannot use GNU CC with any of these functions. You first ! 980: may have to generate or create header files, either by using the public ! 981: domain utility `UNSDL' (which can be found on a DECUS tape), or by ! 982: extracting the relevant modules from one of the system macro libraries, ! 983: and using an editor to construct a C header file. 1.1 root 984: 985: 986: File: gcc.info, Node: Global Declarations, Next: VMS Misc, Prev: Include Files and VMS, Up: VMS 987: 988: Global Declarations and VMS 989: =========================== 990: 991: GNU CC does not provide the `globalref', `globaldef' and 992: `globalvalue' keywords of VAX-C. You can get the same effect with an 993: obscure feature of GAS, the GNU assembler. (This requires GAS version 994: 1.39 or later.) The following macros allow you to use this feature in 995: a fairly natural way: 996: 997: #ifdef __GNUC__ 1.1.1.2 root 998: #define GLOBALREF(TYPE,NAME) \ 999: TYPE NAME \ 1000: asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) 1001: #define GLOBALDEF(TYPE,NAME,VALUE) \ 1002: TYPE NAME \ 1003: asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ 1004: = VALUE 1005: #define GLOBALVALUEREF(TYPE,NAME) \ 1006: const TYPE NAME[1] \ 1007: asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) 1008: #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ 1009: const TYPE NAME[1] \ 1010: asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ 1011: = {VALUE} 1.1 root 1012: #else 1.1.1.2 root 1013: #define GLOBALREF(TYPE,NAME) \ 1014: globalref TYPE NAME 1015: #define GLOBALDEF(TYPE,NAME,VALUE) \ 1016: globaldef TYPE NAME = VALUE 1017: #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ 1018: globalvalue TYPE NAME = VALUE 1019: #define GLOBALVALUEREF(TYPE,NAME) \ 1020: globalvalue TYPE NAME 1.1 root 1021: #endif 1022: 1023: (The `_$$PsectAttributes_GLOBALSYMBOL' prefix at the start of the name 1024: is removed by the assembler, after it has modified the attributes of 1025: the symbol). These macros are provided in the VMS binaries 1026: distribution in a header file `GNU_HACKS.H'. An example of the usage 1027: is: 1028: 1.1.1.2 root 1029: GLOBALREF (int, ijk); 1030: GLOBALDEF (int, jkl, 0); 1.1 root 1031: 1032: The macros `GLOBALREF' and `GLOBALDEF' cannot be used 1033: straightforwardly for arrays, since there is no way to insert the array 1034: dimension into the declaration at the right place. However, you can 1.1.1.3 ! root 1035: declare an array with these macros if you first define a typedef for the ! 1036: array type, like this: 1.1 root 1037: 1038: typedef int intvector[10]; 1.1.1.2 root 1039: GLOBALREF (intvector, foo); 1.1 root 1040: 1041: Array and structure initializers will also break the macros; you can 1042: define the initializer to be a macro of its own, or you can expand the 1043: `GLOBALDEF' macro by hand. You may find a case where you wish to use 1.1.1.3 ! root 1044: the `GLOBALDEF' macro with a large array, but you are not interested in ! 1045: explicitly initializing each element of the array. In such cases you ! 1046: can use an initializer like: `{0,}', which will initialize the entire ! 1047: array to `0'. ! 1048: ! 1049: A shortcoming of this implementation is that a variable declared with ! 1050: `GLOBALVALUEREF' or `GLOBALVALUEDEF' is always an array. For example, ! 1051: the declaration: 1.1 root 1052: 1.1.1.2 root 1053: GLOBALVALUEREF(int, ijk); 1.1 root 1054: 1.1.1.3 ! root 1055: declares the variable `ijk' as an array of type `int [1]'. This is done ! 1056: because a globalvalue is actually a constant; its "value" is what the ! 1057: linker would normally consider an address. That is not how an integer ! 1058: value works in C, but it is how an array works. So treating the symbol ! 1059: as an array name gives consistent results--with the exception that the ! 1060: value seems to have the wrong type. *Don't try to access an element of ! 1061: the array.* It doesn't have any elements. The array "address" may not ! 1062: be the address of actual storage. 1.1 root 1063: 1064: The fact that the symbol is an array may lead to warnings where the 1065: variable is used. Insert type casts to avoid the warnings. Here is an 1066: example; it takes advantage of the ANSI C feature allowing macros that 1067: expand to use the same name as the macro itself. 1068: 1.1.1.2 root 1069: GLOBALVALUEREF (int, ss$_normal); 1070: GLOBALVALUEDEF (int, xyzzy,123); 1.1 root 1071: #ifdef __GNUC__ 1072: #define ss$_normal ((int) ss$_normal) 1073: #define xyzzy ((int) xyzzy) 1074: #endif 1075: 1076: Don't use `globaldef' or `globalref' with a variable whose type is 1077: an enumeration type; this is not implemented. Instead, make the 1078: variable an integer, and use a `globalvaluedef' for each of the 1079: enumeration values. An example of this would be: 1080: 1081: #ifdef __GNUC__ 1.1.1.2 root 1082: GLOBALDEF (int, color, 0); 1083: GLOBALVALUEDEF (int, RED, 0); 1084: GLOBALVALUEDEF (int, BLUE, 1); 1085: GLOBALVALUEDEF (int, GREEN, 3); 1.1 root 1086: #else 1087: enum globaldef color {RED, BLUE, GREEN = 3}; 1088: #endif 1089: 1090:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.