![[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.