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