![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 1.x] / gcc|
Return to gcc.info-4 CVS log | Up to [GCC 1.x] / gcc |
1.1.1.7 root 1: This is Info file gcc.info, produced by Makeinfo-1.47 from the input
1.1 root 2: file gcc.texinfo.
3:
1.1.1.6 root 4: This file documents the use and the internals of the GNU compiler.
1.1 root 5:
1.1.1.6 root 6: Copyright (C) 1988, 1989, 1990 Free Software Foundation, Inc.
1.1 root 7:
1.1.1.7 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:
1.1.1.6 root 12: Permission is granted to copy and distribute modified versions of
1.1 root 13: this manual under the conditions for verbatim copying, provided also
1.1.1.4 root 14: that the sections entitled "GNU General Public License" and "Protect
15: Your Freedom--Fight `Look And Feel'" are included exactly as in the
16: original, and provided that the entire resulting derived work is
17: distributed under the terms of a permission notice identical to this
18: one.
1.1 root 19:
1.1.1.6 root 20: Permission is granted to copy and distribute translations of this
1.1 root 21: manual into another language, under the above conditions for modified
1.1.1.4 root 22: versions, except that the sections entitled "GNU General Public
23: License" and "Protect Your Freedom--Fight `Look And Feel'" and this
1.1.1.7 root 24: permission notice may be included in translations approved by the Free
25: Software Foundation instead of in the original English.
26:
27:
1.1.1.8 ! root 28: File: gcc.info, Node: Extensions, Next: Bugs, Prev: Incompatibilities, Up: Top
! 29:
! 30: GNU Extensions to the C Language
! 31: ********************************
! 32:
! 33: GNU C provides several language features not found in ANSI standard
! 34: C. (The `-pedantic' option directs GNU CC to print a warning message if
! 35: any of these features is used.) To test for the availability of these
! 36: features in conditional compilation, check for a predefined macro
! 37: `__GNUC__', which is always defined under GNU CC.
! 38:
! 39: * Menu:
! 40:
! 41: * Statement Exprs:: Putting statements and declarations inside expressions.
! 42: * Naming Types:: Giving a name to the type of some expression.
! 43: * Typeof:: `typeof': referring to the type of an expression.
! 44: * Lvalues:: Using `?:', `,' and casts in lvalues.
! 45: * Conditionals:: Omitting the middle operand of a `?:' expression.
! 46: * Zero-Length:: Zero-length arrays.
! 47: * Variable-Length:: Arrays whose length is computed at run time.
! 48: * Subscripting:: Any array can be subscripted, even if not an lvalue.
! 49: * Pointer Arith:: Arithmetic on `void'-pointers and function pointers.
! 50: * Initializers:: Non-constant initializers.
! 51: * Constructors:: Constructor expressions give structures, unions
! 52: or arrays as values.
! 53: * Function Attributes:: Declaring that functions have no side effects,
! 54: or that they can never return.
! 55: * Dollar Signs:: Dollar sign is allowed in identifiers.
! 56: * Alignment:: Inquiring about the alignment of a type or variable.
! 57: * Inline:: Defining inline functions (as fast as macros).
! 58: * Extended Asm:: Assembler instructions with C expressions as operands.
! 59: (With them you can define "built-in" functions.)
! 60: * Asm Labels:: Specifying the assembler name to use for a C symbol.
! 61: * Explicit Reg Vars:: Defining variables residing in specified registers.
! 62: * Alternate Keywords:: `__const__', `__asm__', etc., for header files.
! 63:
! 64:
1.1.1.7 root 65: File: gcc.info, Node: Statement Exprs, Next: Naming Types, Prev: Extensions, Up: Extensions
66:
67: Statements and Declarations inside of Expressions
68: =================================================
69:
70: A compound statement in parentheses may appear inside an expression
71: in GNU C. This allows you to declare variables within an expression.
72: For example:
73:
74: ({ int y = foo (); int z;
75: if (y > 0) z = y;
76: else z = - y;
77: z; })
78:
79: is a valid (though slightly more complex than necessary) expression for
80: the absolute value of `foo ()'.
81:
82: This feature is especially useful in making macro definitions "safe"
83: (so that they evaluate each operand exactly once). For example, the
84: "maximum" function is commonly defined as a macro in standard C as
85: follows:
86:
87: #define max(a,b) ((a) > (b) ? (a) : (b))
88:
89: But this definition computes either A or B twice, with bad results if
90: the operand has side effects. In GNU C, if you know the type of the
91: operands (here let's assume `int'), you can define the macro safely as
92: follows:
93:
94: #define maxint(a,b) \
95: ({int _a = (a), _b = (b); _a > _b ? _a : _b; })
96:
97: Embedded statements are not allowed in constant expressions, such as
98: the value of an enumeration constant, the width of a bit field, or the
99: initial value of a static variable.
100:
101: If you don't know the type of the operand, you can still do this,
102: but you must use `typeof' (*note Typeof::.) or type naming (*note
103: Naming Types::.).
1.1.1.4 root 104:
1.1.1.6 root 105:
106: File: gcc.info, Node: Naming Types, Next: Typeof, Prev: Statement Exprs, Up: Extensions
107:
108: Naming an Expression's Type
109: ===========================
110:
111: You can give a name to the type of an expression using a `typedef'
1.1.1.7 root 112: declaration with an initializer. Here is how to define NAME as a type
113: name for the type of EXP:
1.1.1.6 root 114:
115: typedef NAME = EXP;
116:
1.1.1.7 root 117: This is useful in conjunction with the statements-within-expressions
118: feature. Here is how the two together can be used to define a safe
119: "maximum" macro that operates on any arithmetic type:
1.1.1.6 root 120:
121: #define max(a,b) \
122: ({typedef _ta = (a), _tb = (b); \
123: _ta _a = (a); _tb _b = (b); \
124: _a > _b ? _a : _b; })
125:
1.1.1.7 root 126: The reason for using names that start with underscores for the local
127: variables is to avoid conflicts with variable names that occur within
128: the expressions that are substituted for `a' and `b'. Eventually we
129: hope to design a new form of declaration syntax that allows you to
130: declare variables whose scopes start only after their initializers;
131: this will be a more reliable way to prevent such conflicts.
1.1.1.6 root 132:
133:
134: File: gcc.info, Node: Typeof, Next: Lvalues, Prev: Naming Types, Up: Extensions
135:
136: Referring to a Type with `typeof'
137: =================================
138:
139: Another way to refer to the type of an expression is with `typeof'.
140: The syntax of using of this keyword looks like `sizeof', but the
141: construct acts semantically like a type name defined with `typedef'.
142:
143: There are two ways of writing the argument to `typeof': with an
144: expression or with a type. Here is an example with an expression:
145:
146: typeof (x[0](1))
147:
148: This assumes that `x' is an array of functions; the type described is
149: that of the values of the functions.
150:
151: Here is an example with a typename as the argument:
152:
153: typeof (int *)
154:
155: Here the type described is that of pointers to `int'.
156:
157: If you are writing a header file that must work when included in
1.1.1.7 root 158: ANSI C programs, write `__typeof__' instead of `typeof'. *Note
1.1.1.6 root 159: Alternate Keywords::.
160:
161: A `typeof'-construct can be used anywhere a typedef name could be
162: used. For example, you can use it in a declaration, in a cast, or
163: inside of `sizeof' or `typeof'.
164:
165: * This declares `y' with the type of what `x' points to.
166:
167: typeof (*x) y;
168:
169: * This declares `y' as an array of such values.
170:
171: typeof (*x) y[4];
172:
173: * This declares `y' as an array of pointers to characters:
174:
175: typeof (typeof (char *)[4]) y;
176:
177: It is equivalent to the following traditional C declaration:
178:
179: char *y[4];
180:
181: To see the meaning of the declaration using `typeof', and why it
1.1.1.7 root 182: might be a useful way to write, let's rewrite it with these macros:
1.1.1.6 root 183:
184: #define pointer(T) typeof(T *)
185: #define array(T, N) typeof(T [N])
186:
187: Now the declaration can be rewritten this way:
188:
189: array (pointer (char), 4) y;
190:
191: Thus, `array (pointer (char), 4)' is the type of arrays of 4
192: pointers to `char'.
193:
194:
195: File: gcc.info, Node: Lvalues, Next: Conditionals, Prev: Typeof, Up: Extensions
196:
197: Generalized Lvalues
198: ===================
199:
1.1.1.7 root 200: Compound expressions, conditional expressions and casts are allowed
201: as lvalues provided their operands are lvalues. This means that you
202: can take their addresses or store values into them.
203:
204: For example, a compound expression can be assigned, provided the last
205: expression in the sequence is an lvalue. These two expressions are
206: equivalent:
1.1.1.6 root 207:
208: (a, b) += 5
209: a, (b += 5)
210:
211: Similarly, the address of the compound expression can be taken.
212: These two expressions are equivalent:
213:
214: &(a, b)
215: a, &b
216:
217: A conditional expression is a valid lvalue if its type is not void
218: and the true and false branches are both valid lvalues. For example,
219: these two expressions are equivalent:
220:
221: (a ? b : c) = 5
222: (a ? b = 5 : (c = 5))
223:
1.1.1.7 root 224: A cast is a valid lvalue if its operand is an lvalue. A simple
225: assignment whose left-hand side is a cast works by converting the
226: right-hand side first to the specified type, then to the type of the
227: inner left-hand side expression. After this is stored, the value is
228: converted back to the specified type to become the value of the
229: assignment. Thus, if `a' has type `char *', the following two
230: expressions are equivalent:
1.1.1.6 root 231:
232: (int)a = 5
1.1.1.7 root 233: (int)(a = (char *)(int)5)
1.1.1.6 root 234:
235: An assignment-with-arithmetic operation such as `+=' applied to a
236: cast performs the arithmetic using the type resulting from the cast,
237: and then continues as in the previous case. Therefore, these two
238: expressions are equivalent:
239:
240: (int)a += 5
1.1.1.7 root 241: (int)(a = (char *)(int) ((int)a + 5))
242:
243: You cannot take the address of an lvalue cast, because the use of its
244: address would not work out coherently. Suppose that `&(int)f' were
245: permitted, where `f' has type `float'. Then the following statement
246: would try to store an integer bit-pattern where a floating point number
247: belongs:
248:
249: *&(int)f = 1;
250:
251: This is quite different from what `(int)f = 1' would do--that would
252: convert 1 to floating point and store it. Rather than cause this
253: inconsistancy, we think it is better to prohibit use of `&' on a cast.
254:
255: If you really do want an `int *' pointer with the address of `f',
256: you can simply write `(int *)&f'.
1.1.1.6 root 257:
258:
259: File: gcc.info, Node: Conditionals, Next: Zero-Length, Prev: Lvalues, Up: Extensions
260:
261: Conditional Expressions with Omitted Middle-Operands
262: ====================================================
263:
1.1.1.7 root 264: The middle operand in a conditional expression may be omitted. Then
265: if the first operand is nonzero, its value is the value of the
1.1.1.6 root 266: conditional expression.
267:
268: Therefore, the expression
269:
270: x ? : y
271:
272: has the value of `x' if that is nonzero; otherwise, the value of `y'.
273:
274: This example is perfectly equivalent to
275:
276: x ? x : y
277:
278: In this simple case, the ability to omit the middle operand is not
279: especially useful. When it becomes useful is when the first operand
1.1.1.7 root 280: does, or may (if it is a macro argument), contain a side effect. Then
281: repeating the operand in the middle would perform the side effect
282: twice. Omitting the middle operand uses the value already computed
283: without the undesirable effects of recomputing it.
1.1.1.4 root 284:
285:
1.1.1.5 root 286: File: gcc.info, Node: Zero-Length, Next: Variable-Length, Prev: Conditionals, Up: Extensions
287:
288: Arrays of Length Zero
289: =====================
290:
1.1.1.6 root 291: Zero-length arrays are allowed in GNU C. They are very useful as
292: the last element of a structure which is really a header for a
1.1.1.5 root 293: variable-length object:
294:
295: struct line {
296: int length;
297: char contents[0];
298: };
299:
300: {
1.1.1.7 root 301: struct line *thisline
1.1.1.5 root 302: = (struct line *) malloc (sizeof (struct line) + this_length);
303: thisline->length = this_length;
304: }
305:
1.1.1.7 root 306: In standard C, you would have to give `contents' a length of 1, which
307: means either you waste space or complicate the argument to `malloc'.
1.1.1.5 root 308:
309:
1.1.1.4 root 310: File: gcc.info, Node: Variable-Length, Next: Subscripting, Prev: Zero-Length, Up: Extensions
311:
312: Arrays of Variable Length
313: =========================
314:
1.1.1.7 root 315: Variable-length automatic arrays are allowed in GNU C. These arrays
316: are declared like any other automatic arrays, but with a length that is
317: not a constant expression. The storage is allocated at that time and
318: deallocated when the brace-level is exited. For example:
1.1.1.4 root 319:
320: FILE *concat_fopen (char *s1, char *s2, char *mode)
321: {
322: char str[strlen (s1) + strlen (s2) + 1];
323: strcpy (str, s1);
324: strcat (str, s2);
325: return fopen (str, mode);
326: }
327:
1.1.1.6 root 328: You can also use variable-length arrays as arguments to functions:
1.1.1.4 root 329:
330: struct entry
331: tester (int len, char data[len])
332: {
333: ...
334: }
335:
1.1.1.7 root 336: The length of an array is computed on entry to the brace-level where
337: the array is declared and is remembered for the scope of the array in
338: case you access it with `sizeof'.
1.1.1.4 root 339:
1.1.1.6 root 340: Jumping or breaking out of the scope of the array name will also
1.1.1.4 root 341: deallocate the storage. Jumping into the scope is not allowed; you
342: will get an error message for it.
343:
1.1.1.6 root 344: You can use the function `alloca' to get an effect much like
1.1.1.4 root 345: variable-length arrays. The function `alloca' is available in many
346: other C implementations (but not in all). On the other hand,
347: variable-length arrays are more elegant.
348:
1.1.1.6 root 349: There are other differences between these two methods. Space
1.1.1.4 root 350: allocated with `alloca' exists until the containing *function* returns.
351: The space for a variable-length array is deallocated as soon as the
352: array name's scope ends. (If you use both variable-length arrays and
1.1.1.7 root 353: `alloca' in the same function, deallocation of a variable-length array
354: will also deallocate anything more recently allocated with `alloca'.)
1.1.1.4 root 355:
356:
357: File: gcc.info, Node: Subscripting, Next: Pointer Arith, Prev: Variable-Length, Up: Extensions
358:
359: Non-Lvalue Arrays May Have Subscripts
360: =====================================
361:
1.1.1.7 root 362: Subscripting is allowed on arrays that are not lvalues, even though
363: the unary `&' operator is not. For example, this is valid in GNU C
364: though not valid in other C dialects:
1.1.1.4 root 365:
366: struct foo {int a[4];};
367:
368: struct foo f();
369:
370: bar (int index)
371: {
372: return f().a[index];
373: }
374:
375:
376: File: gcc.info, Node: Pointer Arith, Next: Initializers, Prev: Subscripting, Up: Extensions
377:
378: Arithmetic on `void'-Pointers and Function Pointers
379: ===================================================
380:
1.1.1.6 root 381: In GNU C, addition and subtraction operations are supported on
1.1.1.4 root 382: pointers to `void' and on pointers to functions. This is done by
383: treating the size of a `void' or of a function as 1.
384:
1.1.1.7 root 385: A consequence of this is that `sizeof' is also allowed on `void' and
386: on function types, and returns 1.
1.1.1.4 root 387:
1.1.1.7 root 388: The option `-Wpointer-arith' requests a warning if these extensions
389: are used.
1.1.1.4 root 390:
391:
392: File: gcc.info, Node: Initializers, Next: Constructors, Prev: Pointer Arith, Up: Extensions
393:
394: Non-Constant Initializers
395: =========================
396:
1.1.1.6 root 397: The elements of an aggregate initializer for an automatic variable
1.1.1.4 root 398: are not required to be constant expressions in GNU C. Here is an
399: example of an initializer with run-time varying elements:
400:
401: foo (float f, float g)
402: {
403: float beat_freqs[2] = { f-g, f+g };
404: ...
405: }
406:
407:
408: File: gcc.info, Node: Constructors, Next: Function Attributes, Prev: Initializers, Up: Extensions
409:
410: Constructor Expressions
411: =======================
412:
1.1.1.7 root 413: GNU C supports constructor expressions. A constructor looks like a
414: cast containing an initializer. Its value is an object of the type
1.1.1.4 root 415: specified in the cast, containing the elements specified in the
416: initializer. The type must be a structure, union or array type.
417:
1.1.1.6 root 418: Assume that `struct foo' and `structure' are declared as shown:
1.1.1.4 root 419:
420: struct foo {int a; char b[2];} structure;
421:
422: Here is an example of constructing a `struct foo' with a constructor:
423:
424: structure = ((struct foo) {x + y, 'a', 0});
425:
426: This is equivalent to writing the following:
427:
428: {
429: struct foo temp = {x + y, 'a', 0};
430: structure = temp;
431: }
432:
1.1.1.6 root 433: You can also construct an array. If all the elements of the
1.1.1.7 root 434: constructor are (made up of) simple constant expressions, suitable for
435: use in initializers, then the constructor is an lvalue and can be
1.1.1.4 root 436: coerced to a pointer to its first element, as shown here:
437:
438: char **foo = (char *[]) { "x", "y", "z" };
439:
1.1.1.6 root 440: Array constructors whose elements are not simple constants are not
1.1.1.7 root 441: very useful, because the constructor is not an lvalue. There are only
442: two valid ways to use it: to subscript it, or initialize an array
443: variable with it. The former is probably slower than a `switch'
444: statement, while the latter does the same thing an ordinary C
445: initializer would do.
1.1.1.4 root 446:
447: output = ((int[]) { 2, x, 28 }) [input];
1.1.1.3 root 448:
1.1.1.2 root 449:
1.1.1.3 root 450: File: gcc.info, Node: Function Attributes, Next: Dollar Signs, Prev: Constructors, Up: Extensions
451:
452: Declaring Attributes of Functions
453: =================================
454:
1.1.1.7 root 455: In GNU C, you declare certain things about functions called in your
456: program which help the compiler optimize function calls.
1.1.1.3 root 457:
1.1.1.7 root 458: A few functions, such as `abort' and `exit', cannot return. These
1.1.1.3 root 459: functions should be declared `volatile'. For example,
460:
461: extern volatile void abort ();
462:
1.1.1.7 root 463: tells the compiler that it can assume that `abort' will not return.
1.1.1.3 root 464: This makes slightly better code, but more importantly it helps avoid
465: spurious warnings of uninitialized variables.
1.1.1.2 root 466:
1.1.1.7 root 467: Many functions do not examine any values except their arguments, and
468: have no effects except the return value. Such a function can be subject
469: to common subexpression elimination and loop optimization just as an
470: arithmetic operator would be. These functions should be declared
471: `const'. For example,
1.1.1.2 root 472:
1.1.1.7 root 473: extern const int square ();
1.1.1.2 root 474:
1.1.1.3 root 475: says that the hypothetical function `square' is safe to call fewer
476: times than the program says.
477:
1.1.1.7 root 478: Note that a function that has pointer arguments and examines the data
479: pointed to must *not* be declared `const'. Likewise, a function that
480: calls a non-`const' function usually must not be `const'.
481:
482: Some people object to this feature, claiming that ANSI C's `#pragma'
483: should be used instead. There are two reasons I did not do this.
1.1.1.3 root 484:
485: 1. It is impossible to generate `#pragma' commands from a macro.
486:
1.1.1.7 root 487: 2. The `#pragma' command is just as likely as these keywords to mean
488: something else in another compiler.
1.1.1.3 root 489:
1.1.1.6 root 490: These two reasons apply to *any* application whatever: as far as I
1.1.1.3 root 491: can see, `#pragma' is never useful.
1.1.1.2 root 492:
493:
1.1.1.3 root 494: File: gcc.info, Node: Dollar Signs, Next: Alignment, Prev: Function Attributes, Up: Extensions
1.1.1.2 root 495:
1.1.1.3 root 496: Dollar Signs in Identifier Names
497: ================================
498:
1.1.1.6 root 499: In GNU C, you may use dollar signs in identifier names. This is
1.1.1.3 root 500: because many traditional C implementations allow such identifiers.
1.1.1.2 root 501:
1.1.1.7 root 502: Dollar signs are allowed if you specify `-traditional'; they are not
503: allowed if you specify `-ansi'. Whether they are allowed by default
504: depends on the target machine; usually, they are not.
1.1.1.2 root 505:
506:
1.1.1.3 root 507: File: gcc.info, Node: Alignment, Next: Inline, Prev: Dollar Signs, Up: Extensions
1.1.1.2 root 508:
1.1.1.3 root 509: Inquiring about the Alignment of a Type or Variable
510: ===================================================
1.1.1.2 root 511:
1.1.1.7 root 512: The keyword `__alignof__' allows you to inquire about how an object
513: is aligned, or the minimum alignment usually required by a type. Its
514: syntax is just like `sizeof'.
1.1.1.3 root 515:
1.1.1.6 root 516: For example, if the target machine requires a `double' value to be
1.1.1.7 root 517: aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This
518: is true on many RISC machines. On more traditional machine designs,
519: `__alignof__ (double)' is 4 or even 2.
520:
521: Some machines never actually require alignment; they allow reference
522: to any data type even at an odd addresses. For these machines,
523: `__alignof__' reports the *recommended* alignment of a type.
1.1.1.3 root 524:
1.1.1.6 root 525: When the operand of `__alignof__' is an lvalue rather than a type,
1.1.1.3 root 526: the value is the largest alignment that the lvalue is known to have.
1.1.1.7 root 527: It may have this alignment as a result of its data type, or because it
528: is part of a structure and inherits alignment from that structure. For
529: example, after this declaration:
1.1.1.3 root 530:
531: struct foo { int x; char y; } foo1;
532:
533: the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as
534: `__alignof__ (int)', even though the data type of `foo1.y' does not
535: itself demand any alignment.
1.1.1.2 root 536:
537:
1.1.1.3 root 538: File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: Extensions
539:
540: An Inline Function is As Fast As a Macro
541: ========================================
542:
1.1.1.7 root 543: By declaring a function `inline', you can direct GNU CC to integrate
544: that function's code into the code for its callers. This makes
545: execution faster by eliminating the function-call overhead; in
1.1.1.3 root 546: addition, if any of the actual argument values are constant, their
1.1.1.7 root 547: known values may permit simplifications at compile time so that not all
548: of the inline function's code needs to be included.
1.1.1.2 root 549:
1.1.1.6 root 550: To declare a function inline, use the `inline' keyword in its
1.1.1.3 root 551: declaration, like this:
1.1.1.2 root 552:
1.1.1.3 root 553: inline int
554: inc (int *a)
555: {
556: (*a)++;
557: }
558:
1.1.1.7 root 559: (If you are writing a header file to be included in ANSI C programs,
560: write `__inline__' instead of `inline'. *Note Alternate Keywords::.)
1.1.1.3 root 561:
1.1.1.6 root 562: You can also make all "simple enough" functions inline with the
1.1.1.3 root 563: option `-finline-functions'. Note that certain usages in a function
564: definition can make it unsuitable for inline substitution.
565:
1.1.1.6 root 566: When a function is both inline and `static', if all calls to the
1.1.1.7 root 567: function are integrated into the caller, and the function's address is
568: never used, then the function's own assembler code is never referenced.
569: In this case, GNU CC does not actually output assembler code for the
570: function, unless you specify the option `-fkeep-inline-functions'. Some
571: calls cannot be integrated for various reasons (in particular, calls
572: that precede the function's definition cannot be integrated, and
573: neither can recursive calls within the definition). If there is a
574: nonintegrated call, then the function is compiled to assembler code as
575: usual. The function must also be compiled as usual if the program
576: refers to its address, because that can't be inlined.
1.1.1.3 root 577:
1.1.1.6 root 578: When an inline function is not `static', then the compiler must
1.1.1.7 root 579: assume that there may be calls from other source files; since a global
580: symbol can be defined only once in any program, the function must not
581: be defined in the other source files, so the calls therein cannot be
582: integrated. Therefore, a non-`static' inline function is always
583: compiled on its own in the usual fashion.
1.1.1.3 root 584:
1.1.1.6 root 585: If you specify both `inline' and `extern' in the function
1.1.1.7 root 586: definition, then the definition is used only for inlining. In no case
587: is the function compiled on its own, not even if you refer to its
588: address explicitly. Such an address becomes an external reference, as
589: if you had only declared the function, and had not defined it.
590:
591: This combination of `inline' and `extern' has almost the effect of a
592: macro. The way to use it is to put a function definition in a header
593: file with these keywords, and put another copy of the definition
594: (lacking `inline' and `extern') in a library file. The definition in
595: the header file will cause most calls to the function to be inlined.
596: If any uses of the function remain, they will refer to the single copy
597: in the library.
1.1.1.2 root 598:
599:
1.1.1.3 root 600: File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: Extensions
601:
602: Assembler Instructions with C Expression Operands
603: =================================================
604:
1.1.1.6 root 605: In an assembler instruction using `asm', you can now specify the
1.1.1.3 root 606: operands of the instruction using C expressions. This means no more
1.1.1.7 root 607: guessing which registers or memory locations will contain the data you
608: want to use.
1.1.1.3 root 609:
1.1.1.6 root 610: You must specify an assembler instruction template much like what
1.1.1.7 root 611: appears in a machine description, plus an operand constraint string for
612: each operand.
1.1.1.3 root 613:
1.1.1.6 root 614: For example, here is how to use the 68881's `fsinx' instruction:
1.1.1.3 root 615:
616: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
617:
618: Here `angle' is the C expression for the input operand while `result'
619: is that of the output operand. Each has `"f"' as its operand
1.1.1.7 root 620: constraint, saying that a floating-point register is required. The `='
621: in `=f' indicates that the operand is an output; all output operands'
622: constraints must use `='. The constraints use the same language used
623: in the machine description (*note Constraints::.).
1.1.1.3 root 624:
1.1.1.6 root 625: Each operand is described by an operand-constraint string followed
626: by the C expression in parentheses. A colon separates the assembler
1.1.1.7 root 627: template from the first output operand, and another separates the last
628: output operand from the first input, if any. Commas separate output
629: operands and separate inputs. The total number of operands is limited
630: to the maximum number of operands in any instruction pattern in the
631: machine description.
632:
633: If there are no output operands, and there are input operands, then
634: there must be two consecutive colons surrounding the place where the
635: output operands would go.
1.1.1.3 root 636:
1.1.1.6 root 637: Output operand expressions must be lvalues; the compiler can check
1.1.1.7 root 638: this. The input operands need not be lvalues. The compiler cannot
639: check whether the operands have data types that are reasonable for the
640: instruction being executed. It does not parse the assembler
641: instruction template and does not know what it means, or whether it is
642: valid assembler input. The extended `asm' feature is most often used
643: for machine instructions that the compiler itself does not know exist.
644:
645: The output operands must be write-only; GNU CC will assume that the
646: values in these operands before the instruction are dead and need not be
647: generated. Extended asm does not support input-output or read-write
648: operands. For this reason, the constraint character `+', which
649: indicates such an operand, may not be used.
1.1.1.3 root 650:
1.1.1.6 root 651: When the assembler instruction has a read-write operand, or an
1.1.1.3 root 652: operand in which only some of the bits are to be changed, you must
653: logically split its function into two separate operands, one input
1.1.1.7 root 654: operand and one write-only output operand. The connection between them
655: is expressed by constraints which say they need to be in the same
656: location when the instruction executes. You can use the same C
1.1.1.3 root 657: expression for both operands, or different expressions. For example,
1.1.1.7 root 658: here we write the (fictitious) `combine' instruction with `bar' as its
659: read-only source operand and `foo' as its read-write destination:
1.1.1.3 root 660:
661: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
662:
663: The constraint `"0"' for operand 1 says that it must occupy the same
664: location as operand 0. A digit in constraint is allowed only in an
665: input operand, and it must refer to an output operand.
666:
1.1.1.6 root 667: Only a digit in the constraint can guarantee that one operand will
1.1.1.7 root 668: be in the same place as another. The mere fact that `foo' is the value
669: of both operands is not enough to guarantee that they will be in the
670: same place in the generated assembler code. The following would not
671: work:
1.1.1.3 root 672:
673: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
674:
1.1.1.6 root 675: Various optimizations or reloading could cause operands 0 and 1 to
676: be in different registers; GNU CC knows no reason not to do so. For
1.1.1.3 root 677: example, the compiler might find a copy of the value of `foo' in one
1.1.1.7 root 678: register and use it for operand 1, but generate the output operand 0 in
679: a different register (copying it afterward to `foo''s own address). Of
680: course, since the register for operand 1 is not even mentioned in the
681: assembler code, the result will not work, but GNU CC can't tell that.
682:
683: Unless an output operand has the `&' constraint modifier, GNU CC may
684: allocate it in the same register as an unrelated input operand, on the
685: assumption that the inputs are consumed before the outputs are produced.
686: This assumption may be false if the assembler code actually consists of
687: more than one instruction. In such a case, use `&' for each output
688: operand that may not overlap an input. *Note Modifiers::.
1.1.1.3 root 689:
1.1.1.6 root 690: Some instructions clobber specific hard registers. To describe
691: this, write a third colon after the input operands, followed by the
692: names of the clobbered hard registers (given as strings). Here is a
1.1.1.3 root 693: realistic example for the vax:
694:
695: asm volatile ("movc3 %0,%1,%2"
696: : /* no outputs */
697: : "g" (from), "g" (to), "g" (count)
698: : "r0", "r1", "r2", "r3", "r4", "r5");
699:
1.1.1.6 root 700: You can put multiple assembler instructions together in a single
1.1.1.7 root 701: `asm' template, separated either with newlines (written as `\n') or with
702: semicolons if the assembler allows such semicolons. The GNU assembler
703: allows semicolons and all Unix assemblers seem to do so. The input
704: operands are guaranteed not to use any of the clobbered registers, and
705: neither will the output operands' addresses, so you can read and write
706: the clobbered registers as many times as you like. Here is an example
707: of multiple instructions in a template; it assumes that the subroutine
708: `_foo' accepts arguments in registers 9 and 10:
1.1.1.3 root 709:
710: asm ("movl %0,r9;movl %1,r10;call _foo"
711: : /* no outputs */
712: : "g" (from), "g" (to)
713: : "r9", "r10");
714:
1.1.1.6 root 715: If you want to test the condition code produced by an assembler
1.1.1.3 root 716: instruction, you must include a branch and a label in the `asm'
717: construct, as follows:
718:
719: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
720: : "g" (result)
721: : "g" (input));
722:
1.1.1.7 root 723: This assumes your assembler supports local labels, as the GNU assembler
724: and most Unix assemblers do.
1.1.1.3 root 725:
1.1.1.7 root 726: Usually the most convenient way to use these `asm' instructions is to
727: encapsulate them in macros that look like functions. For example,
1.1.1.3 root 728:
729: #define sin(x) \
730: ({ double __value, __arg = (x); \
731: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
732: __value; })
733:
734: Here the variable `__arg' is used to make sure that the instruction
1.1.1.7 root 735: operates on a proper `double' value, and to accept only those arguments
736: `x' which can convert automatically to a `double'.
1.1.1.3 root 737:
1.1.1.6 root 738: Another way to make sure the instruction operates on the correct
1.1.1.7 root 739: data type is to use a cast in the `asm'. This is different from using a
740: variable `__arg' in that it converts more different types. For
741: example, if the desired type were `int', casting the argument to `int'
742: would accept a pointer with no complaint, while assigning the argument
743: to an `int' variable named `__arg' would warn about using a pointer
744: unless the caller explicitly casts it.
1.1.1.2 root 745:
1.1.1.6 root 746: If an `asm' has output operands, GNU CC assumes for optimization
1.1.1.7 root 747: purposes that the instruction has no side effects except to change the
748: output operands. This does not mean that instructions with a side
749: effect cannot be used, but you must be careful, because the compiler
750: may eliminate them if the output operands aren't used, or move them out
751: of loops, or replace two with one if they constitute a common
752: subexpression. Also, if your instruction does have a side effect on a
753: variable that otherwise appears not to change, the old value of the
754: variable may be reused later if it happens to be found in a register.
1.1.1.2 root 755:
1.1.1.6 root 756: You can prevent an `asm' instruction from being deleted, moved or
1.1.1.3 root 757: combined by writing the keyword `volatile' after the `asm'. For
758: example:
1.1.1.2 root 759:
1.1.1.3 root 760: #define set_priority(x) \
761: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
762:
1.1.1.7 root 763: (However, an instruction without output operands will not be deleted or
764: moved, regardless, unless it is unreachable.)
1.1.1.3 root 765:
1.1.1.6 root 766: It is a natural idea to look for a way to give access to the
1.1.1.3 root 767: condition code left by the assembler instruction. However, when we
1.1.1.7 root 768: attempted to implement this, we found no way to make it work reliably.
769: The problem is that output operands might need reloading, which would
770: result in additional following "store" instructions. On most machines,
771: these instructions would alter the condition code before there was time
772: to test it. This problem doesn't arise for ordinary "test" and
773: "compare" instructions because they don't have any output operands.
774:
775: If you are writing a header file that should be includable in ANSI C
776: programs, write `__asm__' instead of `asm'. *Note Alternate Keywords::.
1.1.1.2 root 777:
778:
1.1.1.3 root 779: File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: Extensions
780:
781: Controlling Names Used in Assembler Code
782: ========================================
783:
1.1.1.6 root 784: You can specify the name to be used in the assembler code for a C
1.1.1.7 root 785: function or variable by writing the `asm' (or `__asm__') keyword after
786: the declarator as follows:
1.1.1.3 root 787:
788: int foo asm ("myfoo") = 2;
789:
790: This specifies that the name to be used for the variable `foo' in the
791: assembler code should be `myfoo' rather than the usual `_foo'.
1.1.1.2 root 792:
1.1.1.7 root 793: On systems where an underscore is normally prepended to the name of
794: a C function or variable, this feature allows you to define names for
795: the linker that do not start with an underscore.
1.1.1.2 root 796:
1.1.1.7 root 797: You cannot use `asm' in this way in a function *definition*; but you
798: can get the same effect by writing a declaration for the function
1.1.1.3 root 799: before its definition and putting `asm' there, like this:
1.1.1.2 root 800:
1.1.1.3 root 801: extern func () asm ("FUNC");
802:
803: func (x, y)
804: int x, y;
805: ...
806:
1.1.1.7 root 807: It is up to you to make sure that the assembler names you choose do
808: not conflict with any other assembler symbols. Also, you must not use a
809: register name; that would produce completely invalid assembler code.
810: GNU CC does not as yet have the ability to store static variables in
811: registers. Perhaps that will be added.
1.1.1.2 root 812:
813:
1.1.1.3 root 814: File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: Extensions
815:
816: Variables in Specified Registers
817: ================================
818:
1.1.1.6 root 819: GNU C allows you to put a few global variables into specified
1.1.1.3 root 820: hardware registers. You can also specify the register in which an
821: ordinary register variable should be allocated.
822:
1.1.1.7 root 823: * Global register variables reserve registers throughout the program.
824: This may be useful in programs such as programming language
825: interpreters which have a couple of global variables that are
826: accessed very often.
827:
828: * Local register variables in specific registers do not reserve the
829: registers. The compiler's data flow analysis is capable of
830: determining where the specified registers contain live values, and
831: where they are available for other uses. These local variables are
832: sometimes convenient for use with the extended `asm' feature
833: (*note Extended Asm::.).
1.1.1.2 root 834:
1.1.1.3 root 835: * Menu:
836:
837: * Global Reg Vars::
838: * Local Reg Vars::
1.1.1.2 root 839:
1.1 root 840:
1.1.1.3 root 841: File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Prev: Explicit Reg Vars, Up: Explicit Reg Vars
1.1 root 842:
1.1.1.3 root 843: Defining Global Register Variables
844: ----------------------------------
845:
1.1.1.6 root 846: You can define a global register variable in GNU C like this:
1.1 root 847:
1.1.1.3 root 848: register int *foo asm ("a5");
1.1 root 849:
1.1.1.3 root 850: Here `a5' is the name of the register which should be used. Choose a
1.1.1.7 root 851: register which is normally saved and restored by function calls on your
852: machine, so that library routines will not clobber it.
1.1.1.3 root 853:
1.1.1.6 root 854: Naturally the register name is cpu-dependent, so you would need to
1.1.1.3 root 855: conditionalize your program according to cpu type. The register `a5'
856: would be a good choice on a 68000 for a variable of pointer type. On
1.1.1.4 root 857: machines with register windows, be sure to choose a "global" register
858: that is not affected magically by the function call mechanism.
1.1.1.3 root 859:
1.1.1.7 root 860: In addition, operating systems on one type of cpu may differ in how
861: they name the registers; then you would need additional conditionals.
862: For example, some 68000 operating systems call this register `%a5'.
1.1.1.3 root 863:
1.1.1.6 root 864: Eventually there may be a way of asking the compiler to choose a
1.1.1.3 root 865: register automatically, but first we need to figure out how it should
866: choose and how to enable you to guide the choice. No solution is
867: evident.
868:
1.1.1.6 root 869: Defining a global register variable in a certain register reserves
1.1.1.3 root 870: that register entirely for this use, at least within the current
1.1.1.7 root 871: compilation. The register will not be allocated for any other purpose
872: in the functions in the current compilation. The register will not be
873: saved and restored by these functions. Stores into this register are
874: never deleted even if they would appear to be dead, but references may
875: be deleted or moved or simplified.
1.1.1.3 root 876:
1.1.1.6 root 877: It is not safe to access the global register variables from signal
1.1.1.3 root 878: handlers, or from more than one thread of control, because the system
879: library routines may temporarily use the register for other things
880: (unless you recompile them specially for the task at hand).
881:
1.1.1.7 root 882: It is not safe for one function that uses a global register variable
883: to call another such function `foo' by way of a third function `lose'
884: that was compiled without knowledge of this variable (i.e. in a
885: different source file in which the variable wasn't declared). This is
886: because `lose' might save the register and put some other value there.
887: For example, you can't expect a global register variable to be
888: available in the comparison-function that you pass to `qsort', since
889: `qsort' might have put something else in that register. (If you are
890: prepared to recompile `qsort' with the same global register variable,
891: you can solve this problem.)
892:
893: If you want to recompile `qsort' or other source files which do not
894: actually use your global register variable, so that they will not use
895: that register for any other purpose, then it suffices to specify the
896: compiler option `-ffixed-REG'. You need not actually add a global
897: register declaration to their source code.
1.1.1.3 root 898:
1.1.1.6 root 899: A function which can alter the value of a global register variable
1.1.1.7 root 900: cannot safely be called from a function compiled without this variable,
901: because it could clobber the value the caller expects to find there on
902: return. Therefore, the function which is the entry point into the part
903: of the program that uses the global register variable must explicitly
904: save and restore the value which belongs to its caller.
1.1.1.3 root 905:
1.1.1.6 root 906: On most machines, `longjmp' will restore to each global register
1.1.1.3 root 907: variable the value it had at the time of the `setjmp'. On some
908: machines, however, `longjmp' will not change the value of global
1.1.1.7 root 909: register variables. To be portable, the function that called `setjmp'
910: should make other arrangements to save the values of the global register
911: variables, and to restore them in a `longjmp'. This way, the same
912: thing will happen regardless of what `longjmp' does.
913:
914: All global register variable declarations must precede all function
915: definitions. If such a declaration could appear after function
916: definitions, the declaration would be too late to prevent the register
917: from being used for other purposes in the preceding functions.
1.1.1.3 root 918:
1.1.1.6 root 919: Global register variables may not have initial values, because an
1.1.1.3 root 920: executable file has no means to supply initial contents for a register.
1.1 root 921:
922:
1.1.1.3 root 923: File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars
924:
925: Specifying Registers for Local Variables
926: ----------------------------------------
927:
1.1.1.6 root 928: You can define a local register variable with a specified register
1.1.1.3 root 929: like this:
930:
931: register int *foo asm ("a5");
1.1 root 932:
1.1.1.7 root 933: Here `a5' is the name of the register which should be used. Note that
934: this is the same syntax used for defining global register variables,
935: but for a local variable it would appear within a function.
1.1 root 936:
1.1.1.6 root 937: Naturally the register name is cpu-dependent, but this is not a
1.1.1.3 root 938: problem, since specific registers are most often useful with explicit
939: assembler instructions (*note Extended Asm::.). Both of these things
1.1.1.7 root 940: generally require that you conditionalize your program according to cpu
941: type.
1.1.1.3 root 942:
1.1.1.7 root 943: In addition, operating systems on one type of cpu may differ in how
944: they name the registers; then you would need additional conditionals.
945: For example, some 68000 operating systems call this register `%a5'.
1.1.1.3 root 946:
1.1.1.6 root 947: Eventually there may be a way of asking the compiler to choose a
1.1.1.3 root 948: register automatically, but first we need to figure out how it should
949: choose and how to enable you to guide the choice. No solution is
950: evident.
951:
1.1.1.7 root 952: Defining such a register variable does not reserve the register; it
953: remains available for other uses in places where flow control determines
954: the variable's value is not live. However, these registers are made
955: unavailable for use in the reload pass. I would not be surprised if
956: excessive use of this feature leaves the compiler too few available
957: registers to compile certain functions.
1.1 root 958:
959:
1.1.1.3 root 960: File: gcc.info, Node: Alternate Keywords, Prev: Explicit Reg Vars, Up: Extensions
961:
962: Alternate Keywords
963: ==================
964:
1.1.1.6 root 965: The option `-traditional' disables certain keywords; `-ansi'
1.1.1.7 root 966: disables certain others. This causes trouble when you want to use GNU C
967: extensions, or ANSI C features, in a general-purpose header file that
968: should be usable by all programs, including ANSI C programs and
969: traditional ones. The keywords `asm', `typeof' and `inline' cannot be
970: used since they won't work in a program compiled with `-ansi', while
971: the keywords `const', `volatile', `signed', `typeof' and `inline' won't
972: work in a program compiled with `-traditional'.
973:
974: The way to solve these problems is to put `__' at the beginning and
975: end of each problematical keyword. For example, use `__asm__' instead
976: of `asm', `__const__' instead of `const', and `__inline__' instead of
977: `inline'.
1.1 root 978:
1.1.1.6 root 979: Other C compilers won't accept these alternative keywords; if you
1.1.1.3 root 980: want to compile with another compiler, you can define the alternate
981: keywords as macros to replace them with the customary keywords. It
982: looks like this:
1.1 root 983:
1.1.1.3 root 984: #ifndef __GNUC__
985: #define __asm__ asm
986: #endif
1.1 root 987:
988:
1.1.1.3 root 989: File: gcc.info, Node: Bugs, Next: Portability, Prev: Extensions, Up: Top
1.1 root 990:
1.1.1.3 root 991: Reporting Bugs
992: **************
1.1 root 993:
1.1.1.6 root 994: Your bug reports play an essential role in making GNU CC reliable.
1.1 root 995:
1.1.1.7 root 996: When you encounter a problem, the first thing to do is to see if it
997: is already known. *Note Trouble::. Also look in *Note
998: Incompatibilities::. If it isn't known, then you should report the
1.1.1.5 root 999: problem.
1000:
1.1.1.7 root 1001: Reporting a bug may help you by bringing a solution to your problem,
1002: or it may not. (If it does not, look in the service directory; see
1003: *Note Service::.) In any case, the principal function of a bug report
1004: is to help the entire community by making the next version of GNU CC
1005: work better. Bug reports are your contribution to the maintenance of
1006: GNU CC.
1.1 root 1007:
1.1.1.7 root 1008: In order for a bug report to serve its purpose, you must include the
1009: information that makes for fixing the bug.
1.1 root 1010:
1.1.1.3 root 1011: * Menu:
1012:
1013: * Criteria: Bug Criteria. Have you really found a bug?
1014: * Reporting: Bug Reporting. How to report a bug effectively.
1015:
1.1 root 1016:
1.1.1.3 root 1017: File: gcc.info, Node: Bug Criteria, Next: Bug Reporting, Prev: Bugs, Up: Bugs
1018:
1019: Have You Found a Bug?
1020: =====================
1021:
1.1.1.6 root 1022: If you are not sure whether you have found a bug, here are some
1.1.1.3 root 1023: guidelines:
1024:
1.1.1.7 root 1025: * If the compiler gets a fatal signal, for any input whatever, that
1026: is a compiler bug. Reliable compilers never crash.
1.1 root 1027:
1.1.1.3 root 1028: * If the compiler produces invalid assembly code, for any input
1029: whatever (except an `asm' statement), that is a compiler bug,
1.1.1.7 root 1030: unless the compiler reports errors (not just warnings) which would
1031: ordinarily prevent the assembler from being run.
1.1 root 1032:
1.1.1.3 root 1033: * If the compiler produces valid assembly code that does not
1034: correctly execute the input source code, that is a compiler bug.
1035:
1.1.1.7 root 1036: However, you must double-check to make sure, because you may have
1037: run into an incompatibility between GNU C and traditional C (*note
1038: Incompatibilities::.). These incompatibilities might be considered
1039: bugs, but they are inescapable consequences of valuable features.
1.1.1.3 root 1040:
1041: Or you may have a program whose behavior is undefined, which
1042: happened by chance to give the desired results with another C
1043: compiler.
1044:
1045: For example, in many nonoptimizing compilers, you can write `x;'
1046: at the end of a function instead of `return x;', with the same
1047: results. But the value of the function is undefined if `return'
1.1.1.7 root 1048: is omitted; it is not a bug when GNU CC produces different results.
1.1.1.3 root 1049:
1050: Problems often result from expressions with two increment
1051: operators, as in `f (*p++, *p++)'. Your previous compiler might
1.1.1.7 root 1052: have interpreted that expression the way you intended; GNU CC might
1053: interpret it another way. Neither compiler is wrong. The bug is
1054: in your code.
1.1.1.3 root 1055:
1056: After you have localized the error to a single source line, it
1057: should be easy to check for these things. If your program is
1058: correct and well defined, you have found a compiler bug.
1059:
1.1.1.7 root 1060: * If the compiler produces an error message for valid input, that is
1061: a compiler bug.
1.1.1.3 root 1062:
1.1.1.7 root 1063: Note that the following is not valid input, and the error message
1064: for it is not a bug:
1.1.1.3 root 1065:
1066: int foo (char);
1067:
1068: int
1069: foo (x)
1070: char x;
1071: { ... }
1072:
1.1.1.7 root 1073: The prototype says to pass a `char', while the definition says to
1074: pass an `int' and treat the value as a `char'. This is what the
1075: ANSI standard says, and it makes sense.
1.1.1.3 root 1076:
1077: * If the compiler does not produce an error message for invalid
1.1.1.7 root 1078: input, that is a compiler bug. However, you should note that your
1079: idea of "invalid input" might be my idea of "an extension" or
1080: "support for traditional practice".
1.1.1.3 root 1081:
1082: * If you are an experienced user of C compilers, your suggestions
1083: for improvement of GNU CC are welcome in any case.
1.1 root 1084:
1.1.1.6 root 1085:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.