[8833] | 1 | This is Info file gcc.info, produced by Makeinfo-1.55 from the input |
---|
| 2 | file gcc.texi. |
---|
| 3 | |
---|
| 4 | This file documents the use and the internals of the GNU compiler. |
---|
| 5 | |
---|
| 6 | Published by the Free Software Foundation 59 Temple Place - Suite 330 |
---|
| 7 | Boston, MA 02111-1307 USA |
---|
| 8 | |
---|
| 9 | Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software |
---|
| 10 | Foundation, Inc. |
---|
| 11 | |
---|
| 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. |
---|
| 15 | |
---|
| 16 | Permission is granted to copy and distribute modified versions of |
---|
| 17 | this manual under the conditions for verbatim copying, provided also |
---|
| 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. |
---|
| 23 | |
---|
| 24 | Permission is granted to copy and distribute translations of this |
---|
| 25 | manual into another language, under the above conditions for modified |
---|
| 26 | versions, except that the sections entitled "GNU General Public |
---|
| 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. |
---|
| 31 | |
---|
| 32 | |
---|
| 33 | File: gcc.info, Node: Constructors, Next: Labeled Elements, Prev: Initializers, Up: C Extensions |
---|
| 34 | |
---|
| 35 | Constructor Expressions |
---|
| 36 | ======================= |
---|
| 37 | |
---|
| 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. |
---|
| 42 | |
---|
| 43 | Usually, the specified type is a structure. Assume that `struct |
---|
| 44 | foo' and `structure' are declared as shown: |
---|
| 45 | |
---|
| 46 | struct foo {int a; char b[2];} structure; |
---|
| 47 | |
---|
| 48 | Here is an example of constructing a `struct foo' with a constructor: |
---|
| 49 | |
---|
| 50 | structure = ((struct foo) {x + y, 'a', 0}); |
---|
| 51 | |
---|
| 52 | This is equivalent to writing the following: |
---|
| 53 | |
---|
| 54 | { |
---|
| 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: |
---|
| 73 | |
---|
| 74 | output = ((int[]) { 2, x, 28 }) [input]; |
---|
| 75 | |
---|
| 76 | Constructor expressions for scalar types and union types are is also |
---|
| 77 | allowed, but then the constructor expression is equivalent to a cast. |
---|
| 78 | |
---|
| 79 | |
---|
| 80 | File: gcc.info, Node: Labeled Elements, Next: Cast to Union, Prev: Constructors, Up: C Extensions |
---|
| 81 | |
---|
| 82 | Labeled Elements in Initializers |
---|
| 83 | ================================ |
---|
| 84 | |
---|
| 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. |
---|
| 88 | |
---|
| 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++. |
---|
| 92 | |
---|
| 93 | To specify an array index, write `[INDEX]' or `[INDEX] =' before the |
---|
| 94 | element value. For example, |
---|
| 95 | |
---|
| 96 | int a[6] = { [4] 29, [2] = 15 }; |
---|
| 97 | |
---|
| 98 | is equivalent to |
---|
| 99 | |
---|
| 100 | int a[6] = { 0, 0, 15, 0, 29, 0 }; |
---|
| 101 | |
---|
| 102 | The index values must be constant expressions, even if the array being |
---|
| 103 | initialized is automatic. |
---|
| 104 | |
---|
| 105 | To initialize a range of elements to the same value, write `[FIRST |
---|
| 106 | ... LAST] = VALUE'. For example, |
---|
| 107 | |
---|
| 108 | int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 }; |
---|
| 109 | |
---|
| 110 | Note that the length of the array is the highest value specified plus |
---|
| 111 | one. |
---|
| 112 | |
---|
| 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, |
---|
| 116 | |
---|
| 117 | struct point { int x, y; }; |
---|
| 118 | |
---|
| 119 | the following initialization |
---|
| 120 | |
---|
| 121 | struct point p = { y: yvalue, x: xvalue }; |
---|
| 122 | |
---|
| 123 | is equivalent to |
---|
| 124 | |
---|
| 125 | struct point p = { xvalue, yvalue }; |
---|
| 126 | |
---|
| 127 | Another syntax which has the same meaning is `.FIELDNAME ='., as |
---|
| 128 | shown here: |
---|
| 129 | |
---|
| 130 | struct point p = { .y = yvalue, .x = xvalue }; |
---|
| 131 | |
---|
| 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, |
---|
| 135 | |
---|
| 136 | union foo { int i; double d; }; |
---|
| 137 | |
---|
| 138 | union foo f = { d: 4 }; |
---|
| 139 | |
---|
| 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::.) |
---|
| 144 | |
---|
| 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, |
---|
| 149 | |
---|
| 150 | int a[6] = { [1] = v1, v2, [4] = v4 }; |
---|
| 151 | |
---|
| 152 | is equivalent to |
---|
| 153 | |
---|
| 154 | int a[6] = { 0, v1, v2, 0, v4, 0 }; |
---|
| 155 | |
---|
| 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: |
---|
| 159 | |
---|
| 160 | int whitespace[256] |
---|
| 161 | = { [' '] = 1, ['\t'] = 1, ['\h'] = 1, |
---|
| 162 | ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 }; |
---|
| 163 | |
---|
| 164 | |
---|
| 165 | File: gcc.info, Node: Case Ranges, Next: Function Attributes, Prev: Cast to Union, Up: C Extensions |
---|
| 166 | |
---|
| 167 | Case Ranges |
---|
| 168 | =========== |
---|
| 169 | |
---|
| 170 | You can specify a range of consecutive values in a single `case' |
---|
| 171 | label, like this: |
---|
| 172 | |
---|
| 173 | case LOW ... HIGH: |
---|
| 174 | |
---|
| 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. |
---|
| 177 | |
---|
| 178 | This feature is especially useful for ranges of ASCII character |
---|
| 179 | codes: |
---|
| 180 | |
---|
| 181 | case 'A' ... 'Z': |
---|
| 182 | |
---|
| 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: |
---|
| 186 | |
---|
| 187 | case 1 ... 5: |
---|
| 188 | |
---|
| 189 | rather than this: |
---|
| 190 | |
---|
| 191 | case 1...5: |
---|
| 192 | |
---|
| 193 | |
---|
| 194 | File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Labeled Elements, Up: C Extensions |
---|
| 195 | |
---|
| 196 | Cast to a Union Type |
---|
| 197 | ==================== |
---|
| 198 | |
---|
| 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::.) |
---|
| 204 | |
---|
| 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: |
---|
| 207 | |
---|
| 208 | union foo { int i; double d; }; |
---|
| 209 | int x; |
---|
| 210 | double y; |
---|
| 211 | |
---|
| 212 | both `x' and `y' can be cast to type `union' foo. |
---|
| 213 | |
---|
| 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: |
---|
| 216 | |
---|
| 217 | union foo u; |
---|
| 218 | ... |
---|
| 219 | u = (union foo) x == u.i = x |
---|
| 220 | u = (union foo) y == u.d = y |
---|
| 221 | |
---|
| 222 | You can also use the union cast as a function argument: |
---|
| 223 | |
---|
| 224 | void hack (union foo); |
---|
| 225 | ... |
---|
| 226 | hack ((union foo) x); |
---|
| 227 | |
---|
| 228 | |
---|
| 229 | File: gcc.info, Node: Function Attributes, Next: Function Prototypes, Prev: Case Ranges, Up: C Extensions |
---|
| 230 | |
---|
| 231 | Declaring Attributes of Functions |
---|
| 232 | ================================= |
---|
| 233 | |
---|
| 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, |
---|
| 256 | |
---|
| 257 | void fatal () __attribute__ ((noreturn)); |
---|
| 258 | |
---|
| 259 | void |
---|
| 260 | fatal (...) |
---|
| 261 | { |
---|
| 262 | ... /* Print error message. */ ... |
---|
| 263 | exit (1); |
---|
| 264 | } |
---|
| 265 | |
---|
| 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: |
---|
| 282 | |
---|
| 283 | typedef void voidfn (); |
---|
| 284 | |
---|
| 285 | volatile voidfn fatal; |
---|
| 286 | |
---|
| 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: |
---|
| 304 | |
---|
| 305 | typedef int intfn (); |
---|
| 306 | |
---|
| 307 | extern const intfn square; |
---|
| 308 | |
---|
| 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*. |
---|
| 440 | |
---|
| 441 | |
---|
| 442 | File: gcc.info, Node: Function Prototypes, Next: C++ Comments, Prev: Function Attributes, Up: C Extensions |
---|
| 443 | |
---|
| 444 | Prototypes and Old-Style Function Definitions |
---|
| 445 | ============================================= |
---|
| 446 | |
---|
| 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 | } |
---|
| 468 | |
---|
| 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 | } |
---|
| 492 | |
---|
| 493 | GNU C++ does not support old-style function definitions, so this |
---|
| 494 | extension is irrelevant. |
---|
| 495 | |
---|
| 496 | |
---|
| 497 | File: gcc.info, Node: C++ Comments, Next: Dollar Signs, Prev: Function Prototypes, Up: C Extensions |
---|
| 498 | |
---|
| 499 | C++ Style Comments |
---|
| 500 | ================== |
---|
| 501 | |
---|
| 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'. |
---|
| 508 | |
---|
| 509 | |
---|
| 510 | File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: C++ Comments, Up: C Extensions |
---|
| 511 | |
---|
| 512 | Dollar Signs in Identifier Names |
---|
| 513 | ================================ |
---|
| 514 | |
---|
| 515 | In GNU C, you may use dollar signs in identifier names. This is |
---|
| 516 | because many traditional C implementations allow such identifiers. |
---|
| 517 | |
---|
| 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) |
---|
| 531 | |
---|
| 532 | |
---|
| 533 | File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions |
---|
| 534 | |
---|
| 535 | The Character ESC in Constants |
---|
| 536 | ============================== |
---|
| 537 | |
---|
| 538 | You can use the sequence `\e' in a string or character constant to |
---|
| 539 | stand for the ASCII character ESC. |
---|
| 540 | |
---|
| 541 | |
---|
| 542 | File: gcc.info, Node: Alignment, Next: Inline, Prev: Type Attributes, Up: C Extensions |
---|
| 543 | |
---|
| 544 | Inquiring on Alignment of Types or Variables |
---|
| 545 | ============================================ |
---|
| 546 | |
---|
| 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. |
---|
| 571 | |
---|
| 572 | A related feature which lets you specify the alignment of an object |
---|
| 573 | is `__attribute__ ((aligned (ALIGNMENT)))'; see the following section. |
---|
| 574 | |
---|
| 575 | |
---|
| 576 | File: gcc.info, Node: Variable Attributes, Next: Type Attributes, Prev: Character Escapes, Up: C Extensions |
---|
| 577 | |
---|
| 578 | Specifying Attributes of Variables |
---|
| 579 | ================================== |
---|
| 580 | |
---|
| 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. |
---|
| 677 | |
---|
| 678 | Here is a structure in which the field `x' is packed, so that it |
---|
| 679 | immediately follows `a': |
---|
| 680 | |
---|
| 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 | } |
---|
| 713 | |
---|
| 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))'. |
---|
| 750 | |
---|
| 751 | |
---|
| 752 | File: gcc.info, Node: Type Attributes, Next: Alignment, Prev: Variable Attributes, Up: C Extensions |
---|
| 753 | |
---|
| 754 | Specifying Attributes of Types |
---|
| 755 | ============================== |
---|
| 756 | |
---|
| 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: |
---|
| 870 | |
---|
| 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))'. |
---|
| 880 | |
---|
| 881 | |
---|
| 882 | File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions |
---|
| 883 | |
---|
| 884 | An Inline Function is As Fast As a Macro |
---|
| 885 | ======================================== |
---|
| 886 | |
---|
| 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. |
---|
| 897 | |
---|
| 898 | To declare a function inline, use the `inline' keyword in its |
---|
| 899 | declaration, like this: |
---|
| 900 | |
---|
| 901 | inline int |
---|
| 902 | inc (int *a) |
---|
| 903 | { |
---|
| 904 | (*a)++; |
---|
| 905 | } |
---|
| 906 | |
---|
| 907 | (If you are writing a header file to be included in ANSI C programs, |
---|
| 908 | write `__inline__' instead of `inline'. *Note Alternate Keywords::.) |
---|
| 909 | |
---|
| 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. |
---|
| 959 | |
---|
| 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. |
---|
| 1168 | |
---|
| 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::. |
---|
| 1171 | |
---|