![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-9 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to gcc.info-9 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.7 root 1: This is Info file gcc.info, produced by Makeinfo-1.55 from the input
1.1 root 2: file gcc.texi.
3:
4: This file documents the use and the internals of the GNU compiler.
5:
1.1.1.8 ! root 6: Published by the Free Software Foundation 59 Temple Place - Suite 330
! 7: Boston, MA 02111-1307 USA
1.1.1.5 root 8:
1.1.1.8 ! root 9: Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software
! 10: Foundation, Inc.
1.1 root 11:
1.1.1.3 root 12: Permission is granted to make and distribute verbatim copies of this
13: manual provided the copyright notice and this permission notice are
14: preserved on all copies.
1.1 root 15:
16: Permission is granted to copy and distribute modified versions of
17: this manual under the conditions for verbatim copying, provided also
1.1.1.7 root 18: that the sections entitled "GNU General Public License," "Funding for
19: Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
20: included exactly as in the original, and provided that the entire
21: resulting derived work is distributed under the terms of a permission
22: notice identical to this one.
1.1 root 23:
24: Permission is granted to copy and distribute translations of this
25: manual into another language, under the above conditions for modified
1.1.1.3 root 26: versions, except that the sections entitled "GNU General Public
1.1.1.7 root 27: License," "Funding for Free Software," and "Protect Your Freedom--Fight
28: `Look And Feel'", and this permission notice, may be included in
29: translations approved by the Free Software Foundation instead of in the
30: original English.
1.1.1.3 root 31:
32:
1.1.1.8 ! root 33: File: gcc.info, Node: Constructors, Next: Labeled Elements, Prev: Initializers, Up: C Extensions
1.1.1.6 root 34:
1.1.1.8 ! root 35: Constructor Expressions
! 36: =======================
1.1.1.6 root 37:
1.1.1.8 ! root 38: GNU C supports constructor expressions. A constructor looks like a
! 39: cast containing an initializer. Its value is an object of the type
! 40: specified in the cast, containing the elements specified in the
! 41: initializer.
1.1.1.6 root 42:
1.1.1.8 ! root 43: Usually, the specified type is a structure. Assume that `struct
! 44: foo' and `structure' are declared as shown:
1.1.1.6 root 45:
1.1.1.8 ! root 46: struct foo {int a; char b[2];} structure;
1.1.1.6 root 47:
1.1.1.8 ! root 48: Here is an example of constructing a `struct foo' with a constructor:
1.1.1.6 root 49:
1.1.1.8 ! root 50: structure = ((struct foo) {x + y, 'a', 0});
1.1.1.6 root 51:
1.1.1.8 ! root 52: This is equivalent to writing the following:
1.1.1.6 root 53:
54: {
1.1.1.8 ! root 55: struct foo temp = {x + y, 'a', 0};
! 56: structure = temp;
! 57: }
! 58:
! 59: You can also construct an array. If all the elements of the
! 60: constructor are (made up of) simple constant expressions, suitable for
! 61: use in initializers, then the constructor is an lvalue and can be
! 62: coerced to a pointer to its first element, as shown here:
! 63:
! 64: char **foo = (char *[]) { "x", "y", "z" };
! 65:
! 66: Array constructors whose elements are not simple constants are not
! 67: very useful, because the constructor is not an lvalue. There are only
! 68: two valid ways to use it: to subscript it, or initialize an array
! 69: variable with it. The former is probably slower than a `switch'
! 70: statement, while the latter does the same thing an ordinary C
! 71: initializer would do. Here is an example of subscripting an array
! 72: constructor:
1.1.1.3 root 73:
1.1.1.8 ! root 74: output = ((int[]) { 2, x, 28 }) [input];
1.1.1.5 root 75:
1.1.1.8 ! root 76: Constructor expressions for scalar types and union types are is also
! 77: allowed, but then the constructor expression is equivalent to a cast.
1.1.1.3 root 78:
1.1.1.7 root 79:
1.1.1.8 ! root 80: File: gcc.info, Node: Labeled Elements, Next: Cast to Union, Prev: Constructors, Up: C Extensions
1.1.1.5 root 81:
1.1.1.8 ! root 82: Labeled Elements in Initializers
1.1.1.7 root 83: ================================
1.1.1.5 root 84:
1.1.1.8 ! root 85: Standard C requires the elements of an initializer to appear in a
! 86: fixed order, the same as the order of the elements in the array or
! 87: structure being initialized.
1.1.1.5 root 88:
1.1.1.8 ! root 89: In GNU C you can give the elements in any order, specifying the array
! 90: indices or structure field names they apply to. This extension is not
! 91: implemented in GNU C++.
1.1.1.5 root 92:
1.1.1.8 ! root 93: To specify an array index, write `[INDEX]' or `[INDEX] =' before the
! 94: element value. For example,
1.1.1.7 root 95:
1.1.1.8 ! root 96: int a[6] = { [4] 29, [2] = 15 };
1.1.1.7 root 97:
1.1.1.8 ! root 98: is equivalent to
1.1.1.7 root 99:
1.1.1.8 ! root 100: int a[6] = { 0, 0, 15, 0, 29, 0 };
1.1.1.7 root 101:
1.1.1.8 ! root 102: The index values must be constant expressions, even if the array being
! 103: initialized is automatic.
1.1.1.7 root 104:
1.1.1.8 ! root 105: To initialize a range of elements to the same value, write `[FIRST
! 106: ... LAST] = VALUE'. For example,
1.1.1.7 root 107:
1.1.1.8 ! root 108: int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 };
1.1.1.7 root 109:
1.1.1.8 ! root 110: Note that the length of the array is the highest value specified plus
! 111: one.
1.1.1.7 root 112:
1.1.1.8 ! root 113: In a structure initializer, specify the name of a field to initialize
! 114: with `FIELDNAME:' before the element value. For example, given the
! 115: following structure,
1.1.1.7 root 116:
1.1.1.8 ! root 117: struct point { int x, y; };
1.1.1.7 root 118:
1.1.1.8 ! root 119: the following initialization
1.1.1.7 root 120:
1.1.1.8 ! root 121: struct point p = { y: yvalue, x: xvalue };
1.1.1.7 root 122:
1.1.1.8 ! root 123: is equivalent to
1.1.1.7 root 124:
1.1.1.8 ! root 125: struct point p = { xvalue, yvalue };
1.1.1.7 root 126:
1.1.1.8 ! root 127: Another syntax which has the same meaning is `.FIELDNAME ='., as
! 128: shown here:
1.1.1.7 root 129:
1.1.1.8 ! root 130: struct point p = { .y = yvalue, .x = xvalue };
1.1.1.7 root 131:
1.1.1.8 ! root 132: You can also use an element label (with either the colon syntax or
! 133: the period-equal syntax) when initializing a union, to specify which
! 134: element of the union should be used. For example,
1.1.1.7 root 135:
1.1.1.8 ! root 136: union foo { int i; double d; };
! 137:
! 138: union foo f = { d: 4 };
1.1.1.7 root 139:
1.1.1.8 ! root 140: will convert 4 to a `double' to store it in the union using the second
! 141: element. By contrast, casting 4 to type `union foo' would store it
! 142: into the union as the integer `i', since it is an integer. (*Note Cast
! 143: to Union::.)
1.1.1.7 root 144:
1.1.1.8 ! root 145: You can combine this technique of naming elements with ordinary C
! 146: initialization of successive elements. Each initializer element that
! 147: does not have a label applies to the next consecutive element of the
! 148: array or structure. For example,
1.1.1.7 root 149:
1.1.1.8 ! root 150: int a[6] = { [1] = v1, v2, [4] = v4 };
1.1.1.7 root 151:
1.1.1.8 ! root 152: is equivalent to
1.1.1.7 root 153:
1.1.1.8 ! root 154: int a[6] = { 0, v1, v2, 0, v4, 0 };
1.1.1.7 root 155:
1.1.1.8 ! root 156: Labeling the elements of an array initializer is especially useful
! 157: when the indices are characters or belong to an `enum' type. For
! 158: example:
1.1.1.7 root 159:
1.1.1.8 ! root 160: int whitespace[256]
! 161: = { [' '] = 1, ['\t'] = 1, ['\h'] = 1,
! 162: ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 };
1.1.1.7 root 163:
1.1.1.8 ! root 164:
! 165: File: gcc.info, Node: Case Ranges, Next: Function Attributes, Prev: Cast to Union, Up: C Extensions
1.1.1.7 root 166:
1.1.1.8 ! root 167: Case Ranges
! 168: ===========
1.1.1.7 root 169:
1.1.1.8 ! root 170: You can specify a range of consecutive values in a single `case'
! 171: label, like this:
1.1.1.7 root 172:
1.1.1.8 ! root 173: case LOW ... HIGH:
1.1.1.7 root 174:
1.1.1.8 ! root 175: This has the same effect as the proper number of individual `case'
! 176: labels, one for each integer value from LOW to HIGH, inclusive.
1.1.1.7 root 177:
1.1.1.8 ! root 178: This feature is especially useful for ranges of ASCII character
! 179: codes:
1.1.1.7 root 180:
1.1.1.8 ! root 181: case 'A' ... 'Z':
1.1.1.7 root 182:
1.1.1.8 ! root 183: *Be careful:* Write spaces around the `...', for otherwise it may be
! 184: parsed wrong when you use it with integer values. For example, write
! 185: this:
1.1.1.7 root 186:
1.1.1.8 ! root 187: case 1 ... 5:
1.1.1.7 root 188:
1.1.1.8 ! root 189: rather than this:
1.1.1.7 root 190:
1.1.1.8 ! root 191: case 1...5:
1.1.1.7 root 192:
1.1.1.8 ! root 193:
! 194: File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Labeled Elements, Up: C Extensions
1.1.1.7 root 195:
1.1.1.8 ! root 196: Cast to a Union Type
! 197: ====================
1.1.1.7 root 198:
1.1.1.8 ! root 199: A cast to union type is similar to other casts, except that the type
! 200: specified is a union type. You can specify the type either with `union
! 201: TAG' or with a typedef name. A cast to union is actually a constructor
! 202: though, not a cast, and hence does not yield an lvalue like normal
! 203: casts. (*Note Constructors::.)
1.1.1.7 root 204:
1.1.1.8 ! root 205: The types that may be cast to the union type are those of the members
! 206: of the union. Thus, given the following union and variables:
1.1.1.7 root 207:
1.1.1.8 ! root 208: union foo { int i; double d; };
! 209: int x;
! 210: double y;
1.1.1.7 root 211:
1.1.1.8 ! root 212: both `x' and `y' can be cast to type `union' foo.
1.1.1.7 root 213:
1.1.1.8 ! root 214: Using the cast as the right-hand side of an assignment to a variable
! 215: of union type is equivalent to storing in a member of the union:
1.1.1.7 root 216:
1.1.1.8 ! root 217: union foo u;
! 218: ...
! 219: u = (union foo) x == u.i = x
! 220: u = (union foo) y == u.d = y
1.1.1.7 root 221:
1.1.1.8 ! root 222: You can also use the union cast as a function argument:
1.1.1.7 root 223:
1.1.1.8 ! root 224: void hack (union foo);
! 225: ...
! 226: hack ((union foo) x);
1.1.1.7 root 227:
1.1.1.8 ! root 228:
! 229: File: gcc.info, Node: Function Attributes, Next: Function Prototypes, Prev: Case Ranges, Up: C Extensions
1.1.1.7 root 230:
1.1.1.8 ! root 231: Declaring Attributes of Functions
! 232: =================================
1.1.1.7 root 233:
1.1.1.8 ! root 234: In GNU C, you declare certain things about functions called in your
! 235: program which help the compiler optimize function calls and check your
! 236: code more carefully.
! 237:
! 238: The keyword `__attribute__' allows you to specify special attributes
! 239: when making a declaration. This keyword is followed by an attribute
! 240: specification inside double parentheses. Eight attributes, `noreturn',
! 241: `const', `format', `section', `constructor', `destructor', `unused' and
! 242: `weak' are currently defined for functions. Other attributes, including
! 243: `section' are supported for variables declarations (*note Variable
! 244: Attributes::.) and for types (*note Type Attributes::.).
! 245:
! 246: You may also specify attributes with `__' preceding and following
! 247: each keyword. This allows you to use them in header files without
! 248: being concerned about a possible macro of the same name. For example,
! 249: you may use `__noreturn__' instead of `noreturn'.
! 250:
! 251: `noreturn'
! 252: A few standard library functions, such as `abort' and `exit',
! 253: cannot return. GNU CC knows this automatically. Some programs
! 254: define their own functions that never return. You can declare them
! 255: `noreturn' to tell the compiler this fact. For example,
1.1.1.7 root 256:
1.1.1.8 ! root 257: void fatal () __attribute__ ((noreturn));
! 258:
! 259: void
! 260: fatal (...)
! 261: {
! 262: ... /* Print error message. */ ...
! 263: exit (1);
! 264: }
1.1.1.7 root 265:
1.1.1.8 ! root 266: The `noreturn' keyword tells the compiler to assume that `fatal'
! 267: cannot return. It can then optimize without regard to what would
! 268: happen if `fatal' ever did return. This makes slightly better
! 269: code. More importantly, it helps avoid spurious warnings of
! 270: uninitialized variables.
! 271:
! 272: Do not assume that registers saved by the calling function are
! 273: restored before calling the `noreturn' function.
! 274:
! 275: It does not make sense for a `noreturn' function to have a return
! 276: type other than `void'.
! 277:
! 278: The attribute `noreturn' is not implemented in GNU C versions
! 279: earlier than 2.5. An alternative way to declare that a function
! 280: does not return, which works in the current version and in some
! 281: older versions, is as follows:
1.1.1.7 root 282:
1.1.1.8 ! root 283: typedef void voidfn ();
! 284:
! 285: volatile voidfn fatal;
1.1.1.7 root 286:
1.1.1.8 ! root 287: `const'
! 288: Many functions do not examine any values except their arguments,
! 289: and have no effects except the return value. Such a function can
! 290: be subject to common subexpression elimination and loop
! 291: optimization just as an arithmetic operator would be. These
! 292: functions should be declared with the attribute `const'. For
! 293: example,
! 294:
! 295: int square (int) __attribute__ ((const));
! 296:
! 297: says that the hypothetical function `square' is safe to call fewer
! 298: times than the program says.
! 299:
! 300: The attribute `const' is not implemented in GNU C versions earlier
! 301: than 2.5. An alternative way to declare that a function has no
! 302: side effects, which works in the current version and in some older
! 303: versions, is as follows:
1.1.1.7 root 304:
1.1.1.8 ! root 305: typedef int intfn ();
! 306:
! 307: extern const intfn square;
1.1.1.7 root 308:
1.1.1.8 ! root 309: This approach does not work in GNU C++ from 2.6.0 on, since the
! 310: language specifies that the `const' must be attached to the return
! 311: value.
! 312:
! 313: Note that a function that has pointer arguments and examines the
! 314: data pointed to must *not* be declared `const'. Likewise, a
! 315: function that calls a non-`const' function usually must not be
! 316: `const'. It does not make sense for a `const' function to return
! 317: `void'.
! 318:
! 319: `format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)'
! 320: The `format' attribute specifies that a function takes `printf' or
! 321: `scanf' style arguments which should be type-checked against a
! 322: format string. For example, the declaration:
! 323:
! 324: extern int
! 325: my_printf (void *my_object, const char *my_format, ...)
! 326: __attribute__ ((format (printf, 2, 3)));
! 327:
! 328: causes the compiler to check the arguments in calls to `my_printf'
! 329: for consistency with the `printf' style format string argument
! 330: `my_format'.
! 331:
! 332: The parameter ARCHETYPE determines how the format string is
! 333: interpreted, and should be either `printf' or `scanf'. The
! 334: parameter STRING-INDEX specifies which argument is the format
! 335: string argument (starting from 1), while FIRST-TO-CHECK is the
! 336: number of the first argument to check against the format string.
! 337: For functions where the arguments are not available to be checked
! 338: (such as `vprintf'), specify the third parameter as zero. In this
! 339: case the compiler only checks the format string for consistency.
! 340:
! 341: In the example above, the format string (`my_format') is the second
! 342: argument of the function `my_print', and the arguments to check
! 343: start with the third argument, so the correct parameters for the
! 344: format attribute are 2 and 3.
! 345:
! 346: The `format' attribute allows you to identify your own functions
! 347: which take format strings as arguments, so that GNU CC can check
! 348: the calls to these functions for errors. The compiler always
! 349: checks formats for the ANSI library functions `printf', `fprintf',
! 350: `sprintf', `scanf', `fscanf', `sscanf', `vprintf', `vfprintf' and
! 351: `vsprintf' whenever such warnings are requested (using
! 352: `-Wformat'), so there is no need to modify the header file
! 353: `stdio.h'.
! 354:
! 355: `section ("section-name")'
! 356: Normally, the compiler places the code it generates in the `text'
! 357: section. Sometimes, however, you need additional sections, or you
! 358: need certain particular functions to appear in special sections.
! 359: The `section' attribute specifies that a function lives in a
! 360: particular section. For example, the declaration:
! 361:
! 362: extern void foobar (void) __attribute__ ((section ("bar")));
! 363:
! 364: puts the function `foobar' in the `bar' section.
! 365:
! 366: Some file formats do not support arbitrary sections so the
! 367: `section' attribute is not available on all platforms. If you
! 368: need to map the entire contents of a module to a particular
! 369: section, consider using the facilities of the linker instead.
! 370:
! 371: `constructor'
! 372: `destructor'
! 373: The `constructor' attribute causes the function to be called
! 374: automatically before execution enters `main ()'. Similarly, the
! 375: `destructor' attribute causes the function to be called
! 376: automatically after `main ()' has completed or `exit ()' has been
! 377: called. Functions with these attributes are useful for
! 378: initializing data that will be used implicitly during the
! 379: execution of the program.
! 380:
! 381: These attributes are not currently implemented for Objective C.
! 382:
! 383: `unused'
! 384: This attribute, attached to a function, means that the function is
! 385: meant to be possibly unused. GNU CC will not produce a warning
! 386: for this function.
! 387:
! 388: `weak'
! 389: The `weak' attribute causes the declaration to be emitted as a weak
! 390: symbol rather than a global. This is primarily useful in defining
! 391: library functions which can be overridden in user code, though it
! 392: can also be used with non-function declarations. Weak symbols are
! 393: supported for ELF targets, and also for a.out targets when using
! 394: the GNU assembler and linker.
! 395:
! 396: `alias ("target")'
! 397: The `alias' attribute causes the declaration to be emitted as an
! 398: alias for another symbol, which must be specified. For instance,
! 399:
! 400: void __f () { /* do something */; }
! 401: void f () __attribute__ ((weak, alias ("__f")));
! 402:
! 403: declares `f' to be a weak alias for `__f'. In C++, the mangled
! 404: name for the target must be used.
! 405:
! 406: `regparm (NUMBER)'
! 407: On the Intel 386, the `regparm' attribute causes the compiler to
! 408: pass up to NUMBER integer arguments in registers EAX, EDX, and ECX
! 409: instead of on the stack. Functions that take a variable number of
! 410: arguments will continue to be passed all of their arguments on the
! 411: stack.
! 412:
! 413: `stdcall'
! 414: On the Intel 386, the `stdcall' attribute causes the compiler to
! 415: assume that the called function will pop off the stack space used
! 416: to pass arguments, unless it takes a variable number of arguments.
! 417:
! 418: `cdecl'
! 419: On the Intel 386, the `cdecl' attribute causes the compiler to
! 420: assume that the called function will pop off the stack space used
! 421: to pass arguments, unless it takes a variable number of arguments.
! 422: This is useful to override the effects of the `-mrtd' switch.
! 423:
! 424: You can specify multiple attributes in a declaration by separating
! 425: them by commas within the double parentheses or by immediately
! 426: following an attribute declaration with another attribute declaration.
! 427:
! 428: Some people object to the `__attribute__' feature, suggesting that
! 429: ANSI C's `#pragma' should be used instead. There are two reasons for
! 430: not doing this.
! 431:
! 432: 1. It is impossible to generate `#pragma' commands from a macro.
! 433:
! 434: 2. There is no telling what the same `#pragma' might mean in another
! 435: compiler.
! 436:
! 437: These two reasons apply to almost any application that might be
! 438: proposed for `#pragma'. It is basically a mistake to use `#pragma' for
! 439: *anything*.
1.1.1.7 root 440:
1.1.1.8 ! root 441:
! 442: File: gcc.info, Node: Function Prototypes, Next: C++ Comments, Prev: Function Attributes, Up: C Extensions
1.1.1.7 root 443:
1.1.1.8 ! root 444: Prototypes and Old-Style Function Definitions
! 445: =============================================
1.1.1.7 root 446:
1.1.1.8 ! root 447: GNU C extends ANSI C to allow a function prototype to override a
! 448: later old-style non-prototype definition. Consider the following
! 449: example:
! 450:
! 451: /* Use prototypes unless the compiler is old-fashioned. */
! 452: #if __STDC__
! 453: #define P(x) x
! 454: #else
! 455: #define P(x) ()
! 456: #endif
! 457:
! 458: /* Prototype function declaration. */
! 459: int isroot P((uid_t));
! 460:
! 461: /* Old-style function definition. */
! 462: int
! 463: isroot (x) /* ??? lossage here ??? */
! 464: uid_t x;
! 465: {
! 466: return x == 0;
! 467: }
1.1.1.7 root 468:
1.1.1.8 ! root 469: Suppose the type `uid_t' happens to be `short'. ANSI C does not
! 470: allow this example, because subword arguments in old-style
! 471: non-prototype definitions are promoted. Therefore in this example the
! 472: function definition's argument is really an `int', which does not match
! 473: the prototype argument type of `short'.
! 474:
! 475: This restriction of ANSI C makes it hard to write code that is
! 476: portable to traditional C compilers, because the programmer does not
! 477: know whether the `uid_t' type is `short', `int', or `long'. Therefore,
! 478: in cases like these GNU C allows a prototype to override a later
! 479: old-style definition. More precisely, in GNU C, a function prototype
! 480: argument type overrides the argument type specified by a later
! 481: old-style definition if the former type is the same as the latter type
! 482: before promotion. Thus in GNU C the above example is equivalent to the
! 483: following:
! 484:
! 485: int isroot (uid_t);
! 486:
! 487: int
! 488: isroot (uid_t x)
! 489: {
! 490: return x == 0;
! 491: }
1.1.1.7 root 492:
1.1.1.8 ! root 493: GNU C++ does not support old-style function definitions, so this
! 494: extension is irrelevant.
1.1.1.7 root 495:
1.1.1.8 ! root 496:
! 497: File: gcc.info, Node: C++ Comments, Next: Dollar Signs, Prev: Function Prototypes, Up: C Extensions
1.1.1.7 root 498:
1.1.1.8 ! root 499: C++ Style Comments
! 500: ==================
1.1.1.7 root 501:
1.1.1.8 ! root 502: In GNU C, you may use C++ style comments, which start with `//' and
! 503: continue until the end of the line. Many other C implementations allow
! 504: such comments, and they are likely to be in a future C standard.
! 505: However, C++ style comments are not recognized if you specify `-ansi'
! 506: or `-traditional', since they are incompatible with traditional
! 507: constructs like `dividend//*comment*/divisor'.
1.1.1.5 root 508:
1.1.1.8 ! root 509:
! 510: File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: C++ Comments, Up: C Extensions
1.1.1.5 root 511:
1.1.1.8 ! root 512: Dollar Signs in Identifier Names
! 513: ================================
1.1.1.5 root 514:
1.1.1.8 ! root 515: In GNU C, you may use dollar signs in identifier names. This is
! 516: because many traditional C implementations allow such identifiers.
1.1.1.5 root 517:
1.1.1.8 ! root 518: On some machines, dollar signs are allowed in identifiers if you
! 519: specify `-traditional'. On a few systems they are allowed by default,
! 520: even if you do not use `-traditional'. But they are never allowed if
! 521: you specify `-ansi'.
! 522:
! 523: There are certain ANSI C programs (obscure, to be sure) that would
! 524: compile incorrectly if dollar signs were permitted in identifiers. For
! 525: example:
! 526:
! 527: #define foo(a) #a
! 528: #define lose(b) foo (b)
! 529: #define test$
! 530: lose (test)
1.1.1.5 root 531:
1.1.1.8 ! root 532:
! 533: File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions
1.1.1.5 root 534:
1.1.1.8 ! root 535: The Character ESC in Constants
! 536: ==============================
1.1.1.5 root 537:
1.1.1.8 ! root 538: You can use the sequence `\e' in a string or character constant to
! 539: stand for the ASCII character ESC.
1.1.1.3 root 540:
1.1.1.8 ! root 541:
! 542: File: gcc.info, Node: Alignment, Next: Inline, Prev: Type Attributes, Up: C Extensions
1.1.1.5 root 543:
1.1.1.8 ! root 544: Inquiring on Alignment of Types or Variables
! 545: ============================================
1.1.1.3 root 546:
1.1.1.8 ! root 547: The keyword `__alignof__' allows you to inquire about how an object
! 548: is aligned, or the minimum alignment usually required by a type. Its
! 549: syntax is just like `sizeof'.
! 550:
! 551: For example, if the target machine requires a `double' value to be
! 552: aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This
! 553: is true on many RISC machines. On more traditional machine designs,
! 554: `__alignof__ (double)' is 4 or even 2.
! 555:
! 556: Some machines never actually require alignment; they allow reference
! 557: to any data type even at an odd addresses. For these machines,
! 558: `__alignof__' reports the *recommended* alignment of a type.
! 559:
! 560: When the operand of `__alignof__' is an lvalue rather than a type,
! 561: the value is the largest alignment that the lvalue is known to have.
! 562: It may have this alignment as a result of its data type, or because it
! 563: is part of a structure and inherits alignment from that structure. For
! 564: example, after this declaration:
! 565:
! 566: struct foo { int x; char y; } foo1;
! 567:
! 568: the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as
! 569: `__alignof__ (int)', even though the data type of `foo1.y' does not
! 570: itself demand any alignment.
1.1.1.3 root 571:
1.1.1.8 ! root 572: A related feature which lets you specify the alignment of an object
! 573: is `__attribute__ ((aligned (ALIGNMENT)))'; see the following section.
1.1.1.6 root 574:
1.1.1.8 ! root 575:
! 576: File: gcc.info, Node: Variable Attributes, Next: Type Attributes, Prev: Character Escapes, Up: C Extensions
1.1.1.5 root 577:
1.1.1.8 ! root 578: Specifying Attributes of Variables
! 579: ==================================
1.1.1.5 root 580:
1.1.1.8 ! root 581: The keyword `__attribute__' allows you to specify special attributes
! 582: of variables or structure fields. This keyword is followed by an
! 583: attribute specification inside double parentheses. Eight attributes
! 584: are currently defined for variables: `aligned', `mode', `nocommon',
! 585: `packed', `section', `transparent_union', `unused', and `weak'. Other
! 586: attributes are available for functions (*note Function Attributes::.)
! 587: and for types (*note Type Attributes::.).
! 588:
! 589: You may also specify attributes with `__' preceding and following
! 590: each keyword. This allows you to use them in header files without
! 591: being concerned about a possible macro of the same name. For example,
! 592: you may use `__aligned__' instead of `aligned'.
! 593:
! 594: `aligned (ALIGNMENT)'
! 595: This attribute specifies a minimum alignment for the variable or
! 596: structure field, measured in bytes. For example, the declaration:
! 597:
! 598: int x __attribute__ ((aligned (16))) = 0;
! 599:
! 600: causes the compiler to allocate the global variable `x' on a
! 601: 16-byte boundary. On a 68040, this could be used in conjunction
! 602: with an `asm' expression to access the `move16' instruction which
! 603: requires 16-byte aligned operands.
! 604:
! 605: You can also specify the alignment of structure fields. For
! 606: example, to create a double-word aligned `int' pair, you could
! 607: write:
! 608:
! 609: struct foo { int x[2] __attribute__ ((aligned (8))); };
! 610:
! 611: This is an alternative to creating a union with a `double' member
! 612: that forces the union to be double-word aligned.
! 613:
! 614: It is not possible to specify the alignment of functions; the
! 615: alignment of functions is determined by the machine's requirements
! 616: and cannot be changed. You cannot specify alignment for a typedef
! 617: name because such a name is just an alias, not a distinct type.
! 618:
! 619: As in the preceding examples, you can explicitly specify the
! 620: alignment (in bytes) that you wish the compiler to use for a given
! 621: variable or structure field. Alternatively, you can leave out the
! 622: alignment factor and just ask the compiler to align a variable or
! 623: field to the maximum useful alignment for the target machine you
! 624: are compiling for. For example, you could write:
! 625:
! 626: short array[3] __attribute__ ((aligned));
! 627:
! 628: Whenever you leave out the alignment factor in an `aligned'
! 629: attribute specification, the compiler automatically sets the
! 630: alignment for the declared variable or field to the largest
! 631: alignment which is ever used for any data type on the target
! 632: machine you are compiling for. Doing this can often make copy
! 633: operations more efficient, because the compiler can use whatever
! 634: instructions copy the biggest chunks of memory when performing
! 635: copies to or from the variables or fields that you have aligned
! 636: this way.
! 637:
! 638: The `aligned' attribute can only increase the alignment; but you
! 639: can decrease it by specifying `packed' as well. See below.
! 640:
! 641: Note that the effectiveness of `aligned' attributes may be limited
! 642: by inherent limitations in your linker. On many systems, the
! 643: linker is only able to arrange for variables to be aligned up to a
! 644: certain maximum alignment. (For some linkers, the maximum
! 645: supported alignment may be very very small.) If your linker is
! 646: only able to align variables up to a maximum of 8 byte alignment,
! 647: then specifying `aligned(16)' in an `__attribute__' will still
! 648: only provide you with 8 byte alignment. See your linker
! 649: documentation for further information.
! 650:
! 651: `mode (MODE)'
! 652: This attribute specifies the data type for the
! 653: declaration--whichever type corresponds to the mode MODE. This in
! 654: effect lets you request an integer or floating point type
! 655: according to its width.
! 656:
! 657: You may also specify a mode of `byte' or `__byte__' to indicate
! 658: the mode corresponding to a one-byte integer, `word' or `__word__'
! 659: for the mode of a one-word integer, and `pointer' or `__pointer__'
! 660: for the mode used to represent pointers.
! 661:
! 662: `nocommon'
! 663: This attribute specifies requests GNU CC not to place a variable
! 664: "common" but instead to allocate space for it directly. If you
! 665: specify the `-fno-common' flag, GNU CC will do this for all
! 666: variables.
! 667:
! 668: Specifying the `nocommon' attribute for a variable provides an
! 669: initialization of zeros. A variable may only be initialized in one
! 670: source file.
! 671:
! 672: `packed'
! 673: The `packed' attribute specifies that a variable or structure field
! 674: should have the smallest possible alignment--one byte for a
! 675: variable, and one bit for a field, unless you specify a larger
! 676: value with the `aligned' attribute.
1.1 root 677:
1.1.1.8 ! root 678: Here is a structure in which the field `x' is packed, so that it
! 679: immediately follows `a':
1.1.1.2 root 680:
1.1.1.8 ! root 681: struct foo
! 682: {
! 683: char a;
! 684: int x[2] __attribute__ ((packed));
! 685: };
! 686:
! 687: `section ("section-name")'
! 688: Normally, the compiler places the objects it generates in sections
! 689: like `data' and `bss'. Sometimes, however, you need additional
! 690: sections, or you need certain particular variables to appear in
! 691: special sections, for example to map to special hardware. The
! 692: `section' attribute specifies that a variable (or function) lives
! 693: in a particular section. For example, this small program uses
! 694: several specific section names:
! 695:
! 696: struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
! 697: struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
! 698: char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
! 699: int init_data_copy __attribute__ ((section ("INITDATACOPY"))) = 0;
! 700:
! 701: main()
! 702: {
! 703: /* Initialize stack pointer */
! 704: init_sp (stack + sizeof (stack));
! 705:
! 706: /* Initialize initialized data */
! 707: memcpy (&init_data_copy, &data, &edata - &data);
! 708:
! 709: /* Turn on the serial ports */
! 710: init_duart (&a);
! 711: init_duart (&b);
! 712: }
1.1.1.2 root 713:
1.1.1.8 ! root 714: Use the `section' attribute with an *initialized* definition of a
! 715: *global* variable, as shown in the example. GNU CC issues a
! 716: warning and otherwise ignores the `section' attribute in
! 717: uninitialized variable declarations.
! 718:
! 719: You may only use the `section' attribute with a fully initialized
! 720: global definition because of the way linkers work. The linker
! 721: requires each object be defined once, with the exception that
! 722: uninitialized variables tentatively go in the `common' (or `bss')
! 723: section and can be multiply "defined". You can force a variable
! 724: to be initialized with the `-fno-common' flag or the `nocommon'
! 725: attribute.
! 726:
! 727: Some file formats do not support arbitrary sections so the
! 728: `section' attribute is not available on all platforms. If you
! 729: need to map the entire contents of a module to a particular
! 730: section, consider using the facilities of the linker instead.
! 731:
! 732: `transparent_union'
! 733: This attribute, attached to a function argument variable which is a
! 734: union, means to pass the argument in the same way that the first
! 735: union member would be passed. You can also use this attribute on a
! 736: `typedef' for a union data type; then it applies to all function
! 737: arguments with that type.
! 738:
! 739: `unused'
! 740: This attribute, attached to a variable, means that the variable is
! 741: meant to be possibly unused. GNU CC will not produce a warning
! 742: for this variable.
! 743:
! 744: `weak'
! 745: The `weak' attribute is described in *Note Function Attributes::.
! 746:
! 747: To specify multiple attributes, separate them by commas within the
! 748: double parentheses: for example, `__attribute__ ((aligned (16),
! 749: packed))'.
1.1.1.2 root 750:
1.1.1.7 root 751:
1.1.1.8 ! root 752: File: gcc.info, Node: Type Attributes, Next: Alignment, Prev: Variable Attributes, Up: C Extensions
1.1.1.2 root 753:
1.1.1.8 ! root 754: Specifying Attributes of Types
! 755: ==============================
1.1.1.2 root 756:
1.1.1.8 ! root 757: The keyword `__attribute__' allows you to specify special attributes
! 758: of `struct' and `union' types when you define such types. This keyword
! 759: is followed by an attribute specification inside double parentheses.
! 760: Three attributes are currently defined for types: `aligned', `packed',
! 761: and `transparent_union'. Other attributes are defined for functions
! 762: (*note Function Attributes::.) and for variables (*note Variable
! 763: Attributes::.).
! 764:
! 765: You may also specify any one of these attributes with `__' preceding
! 766: and following its keyword. This allows you to use these attributes in
! 767: header files without being concerned about a possible macro of the same
! 768: name. For example, you may use `__aligned__' instead of `aligned'.
! 769:
! 770: You may specify the `aligned' and `transparent_union' attributes
! 771: either in a `typedef' declaration or just past the closing curly brace
! 772: of a complete enum, struct or union type *definition* and the `packed'
! 773: attribute only past the closing brace of a definition.
! 774:
! 775: `aligned (ALIGNMENT)'
! 776: This attribute specifies a minimum alignment (in bytes) for
! 777: variables of the specified type. For example, the declarations:
! 778:
! 779: struct S { short f[3]; } __attribute__ ((aligned (8));
! 780: typedef int more_aligned_int __attribute__ ((aligned (8));
! 781:
! 782: force the compiler to insure (as fas as it can) that each variable
! 783: whose type is `struct S' or `more_aligned_int' will be allocated
! 784: and aligned *at least* on a 8-byte boundary. On a Sparc, having
! 785: all variables of type `struct S' aligned to 8-byte boundaries
! 786: allows the compiler to use the `ldd' and `std' (doubleword load and
! 787: store) instructions when copying one variable of type `struct S' to
! 788: another, thus improving run-time efficiency.
! 789:
! 790: Note that the alignment of any given `struct' or `union' type is
! 791: required by the ANSI C standard to be at least a perfect multiple
! 792: of the lowest common multiple of the alignments of all of the
! 793: members of the `struct' or `union' in question. This means that
! 794: you *can* effectively adjust the alignment of a `struct' or `union'
! 795: type by attaching an `aligned' attribute to any one of the members
! 796: of such a type, but the notation illustrated in the example above
! 797: is a more obvious, intuitive, and readable way to request the
! 798: compiler to adjust the alignment of an entire `struct' or `union'
! 799: type.
! 800:
! 801: As in the preceding example, you can explicitly specify the
! 802: alignment (in bytes) that you wish the compiler to use for a given
! 803: `struct' or `union' type. Alternatively, you can leave out the
! 804: alignment factor and just ask the compiler to align a type to the
! 805: maximum useful alignment for the target machine you are compiling
! 806: for. For example, you could write:
! 807:
! 808: struct S { short f[3]; } __attribute__ ((aligned));
! 809:
! 810: Whenever you leave out the alignment factor in an `aligned'
! 811: attribute specification, the compiler automatically sets the
! 812: alignment for the type to the largest alignment which is ever used
! 813: for any data type on the target machine you are compiling for.
! 814: Doing this can often make copy operations more efficient, because
! 815: the compiler can use whatever instructions copy the biggest chunks
! 816: of memory when performing copies to or from the variables which
! 817: have types that you have aligned this way.
! 818:
! 819: In the example above, if the size of each `short' is 2 bytes, then
! 820: the size of the entire `struct S' type is 6 bytes. The smallest
! 821: power of two which is greater than or equal to that is 8, so the
! 822: compiler sets the alignment for the entire `struct S' type to 8
! 823: bytes.
! 824:
! 825: Note that although you can ask the compiler to select a
! 826: time-efficient alignment for a given type and then declare only
! 827: individual stand-alone objects of that type, the compiler's
! 828: ability to select a time-efficient alignment is primarily useful
! 829: only when you plan to create arrays of variables having the
! 830: relevant (efficiently aligned) type. If you declare or use arrays
! 831: of variables of an efficiently-aligned type, then it is likely
! 832: that your program will also be doing pointer arithmetic (or
! 833: subscripting, which amounts to the same thing) on pointers to the
! 834: relevant type, and the code that the compiler generates for these
! 835: pointer arithmetic operations will often be more efficient for
! 836: efficiently-aligned types than for other types.
! 837:
! 838: The `aligned' attribute can only increase the alignment; but you
! 839: can decrease it by specifying `packed' as well. See below.
! 840:
! 841: Note that the effectiveness of `aligned' attributes may be limited
! 842: by inherent limitations in your linker. On many systems, the
! 843: linker is only able to arrange for variables to be aligned up to a
! 844: certain maximum alignment. (For some linkers, the maximum
! 845: supported alignment may be very very small.) If your linker is
! 846: only able to align variables up to a maximum of 8 byte alignment,
! 847: then specifying `aligned(16)' in an `__attribute__' will still
! 848: only provide you with 8 byte alignment. See your linker
! 849: documentation for further information.
! 850:
! 851: `packed'
! 852: This attribute, attached to an `enum', `struct', or `union' type
! 853: definition, specified that the minimum required memory be used to
! 854: represent the type.
! 855:
! 856: Specifying this attribute for `struct' and `union' types is
! 857: equivalent to specifying the `packed' attribute on each of the
! 858: structure or union members. Specifying the `-fshort-enums' flag
! 859: on the line is equivalent to specifying the `packed' attribute on
! 860: all `enum' definitions.
! 861:
! 862: You may only specify this attribute after a closing curly brace on
! 863: an `enum' definition, not in a `typedef' declaration.
! 864:
! 865: `transparent_union'
! 866: This attribute, attached to a `union' type definition, indicates
! 867: that any variable having that union type should, if passed to a
! 868: function, be passed in the same way that the first union member
! 869: would be passed. For example:
1.1.1.2 root 870:
1.1.1.8 ! root 871: union foo
! 872: {
! 873: char a;
! 874: int x[2];
! 875: } __attribute__ ((transparent_union));
! 876:
! 877: To specify multiple attributes, separate them by commas within the
! 878: double parentheses: for example, `__attribute__ ((aligned (16),
! 879: packed))'.
1.1.1.2 root 880:
1.1.1.7 root 881:
1.1.1.8 ! root 882: File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions
1.1.1.5 root 883:
1.1.1.8 ! root 884: An Inline Function is As Fast As a Macro
! 885: ========================================
1.1.1.2 root 886:
1.1.1.8 ! root 887: By declaring a function `inline', you can direct GNU CC to integrate
! 888: that function's code into the code for its callers. This makes
! 889: execution faster by eliminating the function-call overhead; in
! 890: addition, if any of the actual argument values are constant, their known
! 891: values may permit simplifications at compile time so that not all of the
! 892: inline function's code needs to be included. The effect on code size is
! 893: less predictable; object code may be larger or smaller with function
! 894: inlining, depending on the particular case. Inlining of functions is an
! 895: optimization and it really "works" only in optimizing compilation. If
! 896: you don't use `-O', no function is really inline.
1.1.1.5 root 897:
1.1.1.8 ! root 898: To declare a function inline, use the `inline' keyword in its
! 899: declaration, like this:
1.1.1.5 root 900:
1.1.1.8 ! root 901: inline int
! 902: inc (int *a)
! 903: {
! 904: (*a)++;
! 905: }
1.1.1.5 root 906:
1.1.1.8 ! root 907: (If you are writing a header file to be included in ANSI C programs,
! 908: write `__inline__' instead of `inline'. *Note Alternate Keywords::.)
1.1.1.5 root 909:
1.1.1.8 ! root 910: You can also make all "simple enough" functions inline with the
! 911: option `-finline-functions'. Note that certain usages in a function
! 912: definition can make it unsuitable for inline substitution.
! 913:
! 914: Note that in C and Objective C, unlike C++, the `inline' keyword
! 915: does not affect the linkage of the function.
! 916:
! 917: GNU CC automatically inlines member functions defined within the
! 918: class body of C++ programs even if they are not explicitly declared
! 919: `inline'. (You can override this with `-fno-default-inline'; *note
! 920: Options Controlling C++ Dialect: C++ Dialect Options..)
! 921:
! 922: When a function is both inline and `static', if all calls to the
! 923: function are integrated into the caller, and the function's address is
! 924: never used, then the function's own assembler code is never referenced.
! 925: In this case, GNU CC does not actually output assembler code for the
! 926: function, unless you specify the option `-fkeep-inline-functions'.
! 927: Some calls cannot be integrated for various reasons (in particular,
! 928: calls that precede the function's definition cannot be integrated, and
! 929: neither can recursive calls within the definition). If there is a
! 930: nonintegrated call, then the function is compiled to assembler code as
! 931: usual. The function must also be compiled as usual if the program
! 932: refers to its address, because that can't be inlined.
! 933:
! 934: When an inline function is not `static', then the compiler must
! 935: assume that there may be calls from other source files; since a global
! 936: symbol can be defined only once in any program, the function must not
! 937: be defined in the other source files, so the calls therein cannot be
! 938: integrated. Therefore, a non-`static' inline function is always
! 939: compiled on its own in the usual fashion.
! 940:
! 941: If you specify both `inline' and `extern' in the function
! 942: definition, then the definition is used only for inlining. In no case
! 943: is the function compiled on its own, not even if you refer to its
! 944: address explicitly. Such an address becomes an external reference, as
! 945: if you had only declared the function, and had not defined it.
! 946:
! 947: This combination of `inline' and `extern' has almost the effect of a
! 948: macro. The way to use it is to put a function definition in a header
! 949: file with these keywords, and put another copy of the definition
! 950: (lacking `inline' and `extern') in a library file. The definition in
! 951: the header file will cause most calls to the function to be inlined.
! 952: If any uses of the function remain, they will refer to the single copy
! 953: in the library.
! 954:
! 955: GNU C does not inline any functions when not optimizing. It is not
! 956: clear whether it is better to inline or not, in this case, but we found
! 957: that a correct implementation when not optimizing was difficult. So we
! 958: did the easy thing, and turned it off.
1.1.1.5 root 959:
1.1.1.8 ! root 960:
! 961: File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: C Extensions
! 962:
! 963: Assembler Instructions with C Expression Operands
! 964: =================================================
! 965:
! 966: In an assembler instruction using `asm', you can now specify the
! 967: operands of the instruction using C expressions. This means no more
! 968: guessing which registers or memory locations will contain the data you
! 969: want to use.
! 970:
! 971: You must specify an assembler instruction template much like what
! 972: appears in a machine description, plus an operand constraint string for
! 973: each operand.
! 974:
! 975: For example, here is how to use the 68881's `fsinx' instruction:
! 976:
! 977: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
! 978:
! 979: Here `angle' is the C expression for the input operand while `result'
! 980: is that of the output operand. Each has `"f"' as its operand
! 981: constraint, saying that a floating point register is required. The `='
! 982: in `=f' indicates that the operand is an output; all output operands'
! 983: constraints must use `='. The constraints use the same language used
! 984: in the machine description (*note Constraints::.).
! 985:
! 986: Each operand is described by an operand-constraint string followed
! 987: by the C expression in parentheses. A colon separates the assembler
! 988: template from the first output operand, and another separates the last
! 989: output operand from the first input, if any. Commas separate output
! 990: operands and separate inputs. The total number of operands is limited
! 991: to ten or to the maximum number of operands in any instruction pattern
! 992: in the machine description, whichever is greater.
! 993:
! 994: If there are no output operands, and there are input operands, then
! 995: there must be two consecutive colons surrounding the place where the
! 996: output operands would go.
! 997:
! 998: Output operand expressions must be lvalues; the compiler can check
! 999: this. The input operands need not be lvalues. The compiler cannot
! 1000: check whether the operands have data types that are reasonable for the
! 1001: instruction being executed. It does not parse the assembler
! 1002: instruction template and does not know what it means, or whether it is
! 1003: valid assembler input. The extended `asm' feature is most often used
! 1004: for machine instructions that the compiler itself does not know exist.
! 1005: If the output expression cannot be directly addressed (for example, it
! 1006: is a bit field), your constraint must allow a register. In that case,
! 1007: GNU CC will use the register as the output of the `asm', and then store
! 1008: that register into the output.
! 1009:
! 1010: The output operands must be write-only; GNU CC will assume that the
! 1011: values in these operands before the instruction are dead and need not be
! 1012: generated. Extended asm does not support input-output or read-write
! 1013: operands. For this reason, the constraint character `+', which
! 1014: indicates such an operand, may not be used.
! 1015:
! 1016: When the assembler instruction has a read-write operand, or an
! 1017: operand in which only some of the bits are to be changed, you must
! 1018: logically split its function into two separate operands, one input
! 1019: operand and one write-only output operand. The connection between them
! 1020: is expressed by constraints which say they need to be in the same
! 1021: location when the instruction executes. You can use the same C
! 1022: expression for both operands, or different expressions. For example,
! 1023: here we write the (fictitious) `combine' instruction with `bar' as its
! 1024: read-only source operand and `foo' as its read-write destination:
! 1025:
! 1026: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
! 1027:
! 1028: The constraint `"0"' for operand 1 says that it must occupy the same
! 1029: location as operand 0. A digit in constraint is allowed only in an
! 1030: input operand, and it must refer to an output operand.
! 1031:
! 1032: Only a digit in the constraint can guarantee that one operand will
! 1033: be in the same place as another. The mere fact that `foo' is the value
! 1034: of both operands is not enough to guarantee that they will be in the
! 1035: same place in the generated assembler code. The following would not
! 1036: work:
! 1037:
! 1038: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
! 1039:
! 1040: Various optimizations or reloading could cause operands 0 and 1 to
! 1041: be in different registers; GNU CC knows no reason not to do so. For
! 1042: example, the compiler might find a copy of the value of `foo' in one
! 1043: register and use it for operand 1, but generate the output operand 0 in
! 1044: a different register (copying it afterward to `foo''s own address). Of
! 1045: course, since the register for operand 1 is not even mentioned in the
! 1046: assembler code, the result will not work, but GNU CC can't tell that.
! 1047:
! 1048: Some instructions clobber specific hard registers. To describe
! 1049: this, write a third colon after the input operands, followed by the
! 1050: names of the clobbered hard registers (given as strings). Here is a
! 1051: realistic example for the Vax:
! 1052:
! 1053: asm volatile ("movc3 %0,%1,%2"
! 1054: : /* no outputs */
! 1055: : "g" (from), "g" (to), "g" (count)
! 1056: : "r0", "r1", "r2", "r3", "r4", "r5");
! 1057:
! 1058: If you refer to a particular hardware register from the assembler
! 1059: code, then you will probably have to list the register after the third
! 1060: colon to tell the compiler that the register's value is modified. In
! 1061: many assemblers, the register names begin with `%'; to produce one `%'
! 1062: in the assembler code, you must write `%%' in the input.
! 1063:
! 1064: If your assembler instruction can alter the condition code register,
! 1065: add `cc' to the list of clobbered registers. GNU CC on some machines
! 1066: represents the condition codes as a specific hardware register; `cc'
! 1067: serves to name this register. On other machines, the condition code is
! 1068: handled differently, and specifying `cc' has no effect. But it is
! 1069: valid no matter what the machine.
! 1070:
! 1071: If your assembler instruction modifies memory in an unpredictable
! 1072: fashion, add `memory' to the list of clobbered registers. This will
! 1073: cause GNU CC to not keep memory values cached in registers across the
! 1074: assembler instruction.
! 1075:
! 1076: You can put multiple assembler instructions together in a single
! 1077: `asm' template, separated either with newlines (written as `\n') or with
! 1078: semicolons if the assembler allows such semicolons. The GNU assembler
! 1079: allows semicolons and all Unix assemblers seem to do so. The input
! 1080: operands are guaranteed not to use any of the clobbered registers, and
! 1081: neither will the output operands' addresses, so you can read and write
! 1082: the clobbered registers as many times as you like. Here is an example
! 1083: of multiple instructions in a template; it assumes that the subroutine
! 1084: `_foo' accepts arguments in registers 9 and 10:
! 1085:
! 1086: asm ("movl %0,r9;movl %1,r10;call _foo"
! 1087: : /* no outputs */
! 1088: : "g" (from), "g" (to)
! 1089: : "r9", "r10");
! 1090:
! 1091: Unless an output operand has the `&' constraint modifier, GNU CC may
! 1092: allocate it in the same register as an unrelated input operand, on the
! 1093: assumption that the inputs are consumed before the outputs are produced.
! 1094: This assumption may be false if the assembler code actually consists of
! 1095: more than one instruction. In such a case, use `&' for each output
! 1096: operand that may not overlap an input. *Note Modifiers::.
! 1097:
! 1098: If you want to test the condition code produced by an assembler
! 1099: instruction, you must include a branch and a label in the `asm'
! 1100: construct, as follows:
! 1101:
! 1102: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
! 1103: : "g" (result)
! 1104: : "g" (input));
! 1105:
! 1106: This assumes your assembler supports local labels, as the GNU assembler
! 1107: and most Unix assemblers do.
! 1108:
! 1109: Speaking of labels, jumps from one `asm' to another are not
! 1110: supported. The compiler's optimizers do not know about these jumps,
! 1111: and therefore they cannot take account of them when deciding how to
! 1112: optimize.
! 1113:
! 1114: Usually the most convenient way to use these `asm' instructions is to
! 1115: encapsulate them in macros that look like functions. For example,
! 1116:
! 1117: #define sin(x) \
! 1118: ({ double __value, __arg = (x); \
! 1119: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
! 1120: __value; })
! 1121:
! 1122: Here the variable `__arg' is used to make sure that the instruction
! 1123: operates on a proper `double' value, and to accept only those arguments
! 1124: `x' which can convert automatically to a `double'.
! 1125:
! 1126: Another way to make sure the instruction operates on the correct
! 1127: data type is to use a cast in the `asm'. This is different from using a
! 1128: variable `__arg' in that it converts more different types. For
! 1129: example, if the desired type were `int', casting the argument to `int'
! 1130: would accept a pointer with no complaint, while assigning the argument
! 1131: to an `int' variable named `__arg' would warn about using a pointer
! 1132: unless the caller explicitly casts it.
! 1133:
! 1134: If an `asm' has output operands, GNU CC assumes for optimization
! 1135: purposes that the instruction has no side effects except to change the
! 1136: output operands. This does not mean that instructions with a side
! 1137: effect cannot be used, but you must be careful, because the compiler
! 1138: may eliminate them if the output operands aren't used, or move them out
! 1139: of loops, or replace two with one if they constitute a common
! 1140: subexpression. Also, if your instruction does have a side effect on a
! 1141: variable that otherwise appears not to change, the old value of the
! 1142: variable may be reused later if it happens to be found in a register.
! 1143:
! 1144: You can prevent an `asm' instruction from being deleted, moved
! 1145: significantly, or combined, by writing the keyword `volatile' after the
! 1146: `asm'. For example:
! 1147:
! 1148: #define set_priority(x) \
! 1149: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
! 1150:
! 1151: An instruction without output operands will not be deleted or moved
! 1152: significantly, regardless, unless it is unreachable.
! 1153:
! 1154: Note that even a volatile `asm' instruction can be moved in ways
! 1155: that appear insignificant to the compiler, such as across jump
! 1156: instructions. You can't expect a sequence of volatile `asm'
! 1157: instructions to remain perfectly consecutive. If you want consecutive
! 1158: output, use a single `asm'.
! 1159:
! 1160: It is a natural idea to look for a way to give access to the
! 1161: condition code left by the assembler instruction. However, when we
! 1162: attempted to implement this, we found no way to make it work reliably.
! 1163: The problem is that output operands might need reloading, which would
! 1164: result in additional following "store" instructions. On most machines,
! 1165: these instructions would alter the condition code before there was time
! 1166: to test it. This problem doesn't arise for ordinary "test" and
! 1167: "compare" instructions because they don't have any output operands.
1.1.1.5 root 1168:
1.1.1.8 ! root 1169: If you are writing a header file that should be includable in ANSI C
! 1170: programs, write `__asm__' instead of `asm'. *Note Alternate Keywords::.
1.1.1.2 root 1171:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.