]>
Commit | Line | Data |
---|---|---|
336b436a JL |
1 | This is Info file gcc.info, produced by Makeinfo version 1.68 from the |
2 | input 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, 1996, 1997 Free | |
10 | Software 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 | \1f | |
33 | File: gcc.info, Node: Variable Length, Next: Macro Varargs, Prev: Zero Length, Up: C Extensions | |
34 | ||
35 | Arrays of Variable Length | |
36 | ========================= | |
37 | ||
38 | Variable-length automatic arrays are allowed in GNU C. These arrays | |
39 | are declared like any other automatic arrays, but with a length that is | |
40 | not a constant expression. The storage is allocated at the point of | |
41 | declaration and deallocated when the brace-level is exited. For | |
42 | example: | |
43 | ||
44 | FILE * | |
45 | concat_fopen (char *s1, char *s2, char *mode) | |
46 | { | |
47 | char str[strlen (s1) + strlen (s2) + 1]; | |
48 | strcpy (str, s1); | |
49 | strcat (str, s2); | |
50 | return fopen (str, mode); | |
51 | } | |
52 | ||
53 | Jumping or breaking out of the scope of the array name deallocates | |
54 | the storage. Jumping into the scope is not allowed; you get an error | |
55 | message for it. | |
56 | ||
57 | You can use the function `alloca' to get an effect much like | |
58 | variable-length arrays. The function `alloca' is available in many | |
59 | other C implementations (but not in all). On the other hand, | |
60 | variable-length arrays are more elegant. | |
61 | ||
62 | There are other differences between these two methods. Space | |
63 | allocated with `alloca' exists until the containing *function* returns. | |
64 | The space for a variable-length array is deallocated as soon as the | |
65 | array name's scope ends. (If you use both variable-length arrays and | |
66 | `alloca' in the same function, deallocation of a variable-length array | |
67 | will also deallocate anything more recently allocated with `alloca'.) | |
68 | ||
69 | You can also use variable-length arrays as arguments to functions: | |
70 | ||
71 | struct entry | |
72 | tester (int len, char data[len][len]) | |
73 | { | |
74 | ... | |
75 | } | |
76 | ||
77 | The length of an array is computed once when the storage is allocated | |
78 | and is remembered for the scope of the array in case you access it with | |
79 | `sizeof'. | |
80 | ||
81 | If you want to pass the array first and the length afterward, you can | |
82 | use a forward declaration in the parameter list--another GNU extension. | |
83 | ||
84 | struct entry | |
85 | tester (int len; char data[len][len], int len) | |
86 | { | |
87 | ... | |
88 | } | |
89 | ||
90 | The `int len' before the semicolon is a "parameter forward | |
91 | declaration", and it serves the purpose of making the name `len' known | |
92 | when the declaration of `data' is parsed. | |
93 | ||
94 | You can write any number of such parameter forward declarations in | |
95 | the parameter list. They can be separated by commas or semicolons, but | |
96 | the last one must end with a semicolon, which is followed by the "real" | |
97 | parameter declarations. Each forward declaration must match a "real" | |
98 | declaration in parameter name and data type. | |
99 | ||
100 | \1f | |
101 | File: gcc.info, Node: Macro Varargs, Next: Subscripting, Prev: Variable Length, Up: C Extensions | |
102 | ||
103 | Macros with Variable Numbers of Arguments | |
104 | ========================================= | |
105 | ||
106 | In GNU C, a macro can accept a variable number of arguments, much as | |
107 | a function can. The syntax for defining the macro looks much like that | |
108 | used for a function. Here is an example: | |
109 | ||
110 | #define eprintf(format, args...) \ | |
111 | fprintf (stderr, format , ## args) | |
112 | ||
113 | Here `args' is a "rest argument": it takes in zero or more | |
114 | arguments, as many as the call contains. All of them plus the commas | |
115 | between them form the value of `args', which is substituted into the | |
116 | macro body where `args' is used. Thus, we have this expansion: | |
117 | ||
118 | eprintf ("%s:%d: ", input_file_name, line_number) | |
119 | ==> | |
120 | fprintf (stderr, "%s:%d: " , input_file_name, line_number) | |
121 | ||
122 | Note that the comma after the string constant comes from the definition | |
123 | of `eprintf', whereas the last comma comes from the value of `args'. | |
124 | ||
125 | The reason for using `##' is to handle the case when `args' matches | |
126 | no arguments at all. In this case, `args' has an empty value. In this | |
127 | case, the second comma in the definition becomes an embarrassment: if | |
128 | it got through to the expansion of the macro, we would get something | |
129 | like this: | |
130 | ||
131 | fprintf (stderr, "success!\n" , ) | |
132 | ||
133 | which is invalid C syntax. `##' gets rid of the comma, so we get the | |
134 | following instead: | |
135 | ||
136 | fprintf (stderr, "success!\n") | |
137 | ||
138 | This is a special feature of the GNU C preprocessor: `##' before a | |
139 | rest argument that is empty discards the preceding sequence of | |
140 | non-whitespace characters from the macro definition. (If another macro | |
141 | argument precedes, none of it is discarded.) | |
142 | ||
143 | It might be better to discard the last preprocessor token instead of | |
144 | the last preceding sequence of non-whitespace characters; in fact, we | |
145 | may someday change this feature to do so. We advise you to write the | |
146 | macro definition so that the preceding sequence of non-whitespace | |
147 | characters is just a single token, so that the meaning will not change | |
148 | if we change the definition of this feature. | |
149 | ||
150 | \1f | |
151 | File: gcc.info, Node: Subscripting, Next: Pointer Arith, Prev: Macro Varargs, Up: C Extensions | |
152 | ||
153 | Non-Lvalue Arrays May Have Subscripts | |
154 | ===================================== | |
155 | ||
156 | Subscripting is allowed on arrays that are not lvalues, even though | |
157 | the unary `&' operator is not. For example, this is valid in GNU C | |
158 | though not valid in other C dialects: | |
159 | ||
160 | struct foo {int a[4];}; | |
161 | ||
162 | struct foo f(); | |
163 | ||
164 | bar (int index) | |
165 | { | |
166 | return f().a[index]; | |
167 | } | |
168 | ||
169 | \1f | |
170 | File: gcc.info, Node: Pointer Arith, Next: Initializers, Prev: Subscripting, Up: C Extensions | |
171 | ||
172 | Arithmetic on `void'- and Function-Pointers | |
173 | =========================================== | |
174 | ||
175 | In GNU C, addition and subtraction operations are supported on | |
176 | pointers to `void' and on pointers to functions. This is done by | |
177 | treating the size of a `void' or of a function as 1. | |
178 | ||
179 | A consequence of this is that `sizeof' is also allowed on `void' and | |
180 | on function types, and returns 1. | |
181 | ||
182 | The option `-Wpointer-arith' requests a warning if these extensions | |
183 | are used. | |
184 | ||
185 | \1f | |
186 | File: gcc.info, Node: Initializers, Next: Constructors, Prev: Pointer Arith, Up: C Extensions | |
187 | ||
188 | Non-Constant Initializers | |
189 | ========================= | |
190 | ||
191 | As in standard C++, the elements of an aggregate initializer for an | |
192 | automatic variable are not required to be constant expressions in GNU C. | |
193 | Here is an example of an initializer with run-time varying elements: | |
194 | ||
195 | foo (float f, float g) | |
196 | { | |
197 | float beat_freqs[2] = { f-g, f+g }; | |
198 | ... | |
199 | } | |
200 | ||
201 | \1f | |
202 | File: gcc.info, Node: Constructors, Next: Labeled Elements, Prev: Initializers, Up: C Extensions | |
203 | ||
204 | Constructor Expressions | |
205 | ======================= | |
206 | ||
207 | GNU C supports constructor expressions. A constructor looks like a | |
208 | cast containing an initializer. Its value is an object of the type | |
209 | specified in the cast, containing the elements specified in the | |
210 | initializer. | |
211 | ||
212 | Usually, the specified type is a structure. Assume that `struct | |
213 | foo' and `structure' are declared as shown: | |
214 | ||
215 | struct foo {int a; char b[2];} structure; | |
216 | ||
217 | Here is an example of constructing a `struct foo' with a constructor: | |
218 | ||
219 | structure = ((struct foo) {x + y, 'a', 0}); | |
220 | ||
221 | This is equivalent to writing the following: | |
222 | ||
223 | { | |
224 | struct foo temp = {x + y, 'a', 0}; | |
225 | structure = temp; | |
226 | } | |
227 | ||
228 | You can also construct an array. If all the elements of the | |
229 | constructor are (made up of) simple constant expressions, suitable for | |
230 | use in initializers, then the constructor is an lvalue and can be | |
231 | coerced to a pointer to its first element, as shown here: | |
232 | ||
233 | char **foo = (char *[]) { "x", "y", "z" }; | |
234 | ||
235 | Array constructors whose elements are not simple constants are not | |
236 | very useful, because the constructor is not an lvalue. There are only | |
237 | two valid ways to use it: to subscript it, or initialize an array | |
238 | variable with it. The former is probably slower than a `switch' | |
239 | statement, while the latter does the same thing an ordinary C | |
240 | initializer would do. Here is an example of subscripting an array | |
241 | constructor: | |
242 | ||
243 | output = ((int[]) { 2, x, 28 }) [input]; | |
244 | ||
245 | Constructor expressions for scalar types and union types are is also | |
246 | allowed, but then the constructor expression is equivalent to a cast. | |
247 | ||
248 | \1f | |
249 | File: gcc.info, Node: Labeled Elements, Next: Cast to Union, Prev: Constructors, Up: C Extensions | |
250 | ||
251 | Labeled Elements in Initializers | |
252 | ================================ | |
253 | ||
254 | Standard C requires the elements of an initializer to appear in a | |
255 | fixed order, the same as the order of the elements in the array or | |
256 | structure being initialized. | |
257 | ||
258 | In GNU C you can give the elements in any order, specifying the array | |
259 | indices or structure field names they apply to. This extension is not | |
260 | implemented in GNU C++. | |
261 | ||
262 | To specify an array index, write `[INDEX]' or `[INDEX] =' before the | |
263 | element value. For example, | |
264 | ||
265 | int a[6] = { [4] 29, [2] = 15 }; | |
266 | ||
267 | is equivalent to | |
268 | ||
269 | int a[6] = { 0, 0, 15, 0, 29, 0 }; | |
270 | ||
271 | The index values must be constant expressions, even if the array being | |
272 | initialized is automatic. | |
273 | ||
274 | To initialize a range of elements to the same value, write `[FIRST | |
275 | ... LAST] = VALUE'. For example, | |
276 | ||
277 | int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 }; | |
278 | ||
279 | Note that the length of the array is the highest value specified plus | |
280 | one. | |
281 | ||
282 | In a structure initializer, specify the name of a field to initialize | |
283 | with `FIELDNAME:' before the element value. For example, given the | |
284 | following structure, | |
285 | ||
286 | struct point { int x, y; }; | |
287 | ||
288 | the following initialization | |
289 | ||
290 | struct point p = { y: yvalue, x: xvalue }; | |
291 | ||
292 | is equivalent to | |
293 | ||
294 | struct point p = { xvalue, yvalue }; | |
295 | ||
296 | Another syntax which has the same meaning is `.FIELDNAME ='., as | |
297 | shown here: | |
298 | ||
299 | struct point p = { .y = yvalue, .x = xvalue }; | |
300 | ||
301 | You can also use an element label (with either the colon syntax or | |
302 | the period-equal syntax) when initializing a union, to specify which | |
303 | element of the union should be used. For example, | |
304 | ||
305 | union foo { int i; double d; }; | |
306 | ||
307 | union foo f = { d: 4 }; | |
308 | ||
309 | will convert 4 to a `double' to store it in the union using the second | |
310 | element. By contrast, casting 4 to type `union foo' would store it | |
311 | into the union as the integer `i', since it is an integer. (*Note Cast | |
312 | to Union::.) | |
313 | ||
314 | You can combine this technique of naming elements with ordinary C | |
315 | initialization of successive elements. Each initializer element that | |
316 | does not have a label applies to the next consecutive element of the | |
317 | array or structure. For example, | |
318 | ||
319 | int a[6] = { [1] = v1, v2, [4] = v4 }; | |
320 | ||
321 | is equivalent to | |
322 | ||
323 | int a[6] = { 0, v1, v2, 0, v4, 0 }; | |
324 | ||
325 | Labeling the elements of an array initializer is especially useful | |
326 | when the indices are characters or belong to an `enum' type. For | |
327 | example: | |
328 | ||
329 | int whitespace[256] | |
330 | = { [' '] = 1, ['\t'] = 1, ['\h'] = 1, | |
331 | ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 }; | |
332 | ||
333 | \1f | |
334 | File: gcc.info, Node: Case Ranges, Next: Function Attributes, Prev: Cast to Union, Up: C Extensions | |
335 | ||
336 | Case Ranges | |
337 | =========== | |
338 | ||
339 | You can specify a range of consecutive values in a single `case' | |
340 | label, like this: | |
341 | ||
342 | case LOW ... HIGH: | |
343 | ||
344 | This has the same effect as the proper number of individual `case' | |
345 | labels, one for each integer value from LOW to HIGH, inclusive. | |
346 | ||
347 | This feature is especially useful for ranges of ASCII character | |
348 | codes: | |
349 | ||
350 | case 'A' ... 'Z': | |
351 | ||
352 | *Be careful:* Write spaces around the `...', for otherwise it may be | |
353 | parsed wrong when you use it with integer values. For example, write | |
354 | this: | |
355 | ||
356 | case 1 ... 5: | |
357 | ||
358 | rather than this: | |
359 | ||
360 | case 1...5: | |
361 | ||
362 | \1f | |
363 | File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Labeled Elements, Up: C Extensions | |
364 | ||
365 | Cast to a Union Type | |
366 | ==================== | |
367 | ||
368 | A cast to union type is similar to other casts, except that the type | |
369 | specified is a union type. You can specify the type either with `union | |
370 | TAG' or with a typedef name. A cast to union is actually a constructor | |
371 | though, not a cast, and hence does not yield an lvalue like normal | |
372 | casts. (*Note Constructors::.) | |
373 | ||
374 | The types that may be cast to the union type are those of the members | |
375 | of the union. Thus, given the following union and variables: | |
376 | ||
377 | union foo { int i; double d; }; | |
378 | int x; | |
379 | double y; | |
380 | ||
381 | both `x' and `y' can be cast to type `union' foo. | |
382 | ||
383 | Using the cast as the right-hand side of an assignment to a variable | |
384 | of union type is equivalent to storing in a member of the union: | |
385 | ||
386 | union foo u; | |
387 | ... | |
388 | u = (union foo) x == u.i = x | |
389 | u = (union foo) y == u.d = y | |
390 | ||
391 | You can also use the union cast as a function argument: | |
392 | ||
393 | void hack (union foo); | |
394 | ... | |
395 | hack ((union foo) x); | |
396 | ||
397 | \1f | |
398 | File: gcc.info, Node: Function Attributes, Next: Function Prototypes, Prev: Case Ranges, Up: C Extensions | |
399 | ||
400 | Declaring Attributes of Functions | |
401 | ================================= | |
402 | ||
403 | In GNU C, you declare certain things about functions called in your | |
404 | program which help the compiler optimize function calls and check your | |
405 | code more carefully. | |
406 | ||
407 | The keyword `__attribute__' allows you to specify special attributes | |
408 | when making a declaration. This keyword is followed by an attribute | |
409 | specification inside double parentheses. Eight attributes, `noreturn', | |
410 | `const', `format', `section', `constructor', `destructor', `unused' and | |
411 | `weak' are currently defined for functions. Other attributes, including | |
412 | `section' are supported for variables declarations (*note Variable | |
413 | Attributes::.) and for types (*note Type Attributes::.). | |
414 | ||
415 | You may also specify attributes with `__' preceding and following | |
416 | each keyword. This allows you to use them in header files without | |
417 | being concerned about a possible macro of the same name. For example, | |
418 | you may use `__noreturn__' instead of `noreturn'. | |
419 | ||
420 | `noreturn' | |
421 | A few standard library functions, such as `abort' and `exit', | |
422 | cannot return. GNU CC knows this automatically. Some programs | |
423 | define their own functions that never return. You can declare them | |
424 | `noreturn' to tell the compiler this fact. For example, | |
425 | ||
426 | void fatal () __attribute__ ((noreturn)); | |
427 | ||
428 | void | |
429 | fatal (...) | |
430 | { | |
431 | ... /* Print error message. */ ... | |
432 | exit (1); | |
433 | } | |
434 | ||
435 | The `noreturn' keyword tells the compiler to assume that `fatal' | |
436 | cannot return. It can then optimize without regard to what would | |
437 | happen if `fatal' ever did return. This makes slightly better | |
438 | code. More importantly, it helps avoid spurious warnings of | |
439 | uninitialized variables. | |
440 | ||
441 | Do not assume that registers saved by the calling function are | |
442 | restored before calling the `noreturn' function. | |
443 | ||
444 | It does not make sense for a `noreturn' function to have a return | |
445 | type other than `void'. | |
446 | ||
447 | The attribute `noreturn' is not implemented in GNU C versions | |
448 | earlier than 2.5. An alternative way to declare that a function | |
449 | does not return, which works in the current version and in some | |
450 | older versions, is as follows: | |
451 | ||
452 | typedef void voidfn (); | |
453 | ||
454 | volatile voidfn fatal; | |
455 | ||
456 | `const' | |
457 | Many functions do not examine any values except their arguments, | |
458 | and have no effects except the return value. Such a function can | |
459 | be subject to common subexpression elimination and loop | |
460 | optimization just as an arithmetic operator would be. These | |
461 | functions should be declared with the attribute `const'. For | |
462 | example, | |
463 | ||
464 | int square (int) __attribute__ ((const)); | |
465 | ||
466 | says that the hypothetical function `square' is safe to call fewer | |
467 | times than the program says. | |
468 | ||
469 | The attribute `const' is not implemented in GNU C versions earlier | |
470 | than 2.5. An alternative way to declare that a function has no | |
471 | side effects, which works in the current version and in some older | |
472 | versions, is as follows: | |
473 | ||
474 | typedef int intfn (); | |
475 | ||
476 | extern const intfn square; | |
477 | ||
478 | This approach does not work in GNU C++ from 2.6.0 on, since the | |
479 | language specifies that the `const' must be attached to the return | |
480 | value. | |
481 | ||
482 | Note that a function that has pointer arguments and examines the | |
483 | data pointed to must *not* be declared `const'. Likewise, a | |
484 | function that calls a non-`const' function usually must not be | |
485 | `const'. It does not make sense for a `const' function to return | |
486 | `void'. | |
487 | ||
488 | `format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)' | |
489 | The `format' attribute specifies that a function takes `printf' or | |
490 | `scanf' style arguments which should be type-checked against a | |
491 | format string. For example, the declaration: | |
492 | ||
493 | extern int | |
494 | my_printf (void *my_object, const char *my_format, ...) | |
495 | __attribute__ ((format (printf, 2, 3))); | |
496 | ||
497 | causes the compiler to check the arguments in calls to `my_printf' | |
498 | for consistency with the `printf' style format string argument | |
499 | `my_format'. | |
500 | ||
501 | The parameter ARCHETYPE determines how the format string is | |
502 | interpreted, and should be either `printf' or `scanf'. The | |
503 | parameter STRING-INDEX specifies which argument is the format | |
504 | string argument (starting from 1), while FIRST-TO-CHECK is the | |
505 | number of the first argument to check against the format string. | |
506 | For functions where the arguments are not available to be checked | |
507 | (such as `vprintf'), specify the third parameter as zero. In this | |
508 | case the compiler only checks the format string for consistency. | |
509 | ||
510 | In the example above, the format string (`my_format') is the second | |
511 | argument of the function `my_print', and the arguments to check | |
512 | start with the third argument, so the correct parameters for the | |
513 | format attribute are 2 and 3. | |
514 | ||
515 | The `format' attribute allows you to identify your own functions | |
516 | which take format strings as arguments, so that GNU CC can check | |
517 | the calls to these functions for errors. The compiler always | |
518 | checks formats for the ANSI library functions `printf', `fprintf', | |
519 | `sprintf', `scanf', `fscanf', `sscanf', `vprintf', `vfprintf' and | |
520 | `vsprintf' whenever such warnings are requested (using | |
521 | `-Wformat'), so there is no need to modify the header file | |
522 | `stdio.h'. | |
523 | ||
524 | `format_arg (STRING-INDEX)' | |
525 | The `format_arg' attribute specifies that a function takes | |
526 | `printf' or `scanf' style arguments, modifies it (for example, to | |
527 | translate it into another language), and passes it to a `printf' | |
528 | or `scanf' style function. For example, the declaration: | |
529 | ||
530 | extern char * | |
531 | my_dgettext (char *my_domain, const char *my_format) | |
532 | __attribute__ ((format_arg (2))); | |
533 | ||
534 | causes the compiler to check the arguments in calls to | |
535 | `my_dgettext' whose result is passed to a `printf' or `scanf' type | |
536 | function for consistency with the `printf' style format string | |
537 | argument `my_format'. | |
538 | ||
539 | The parameter STRING-INDEX specifies which argument is the format | |
540 | string argument (starting from 1). | |
541 | ||
542 | The `format-arg' attribute allows you to identify your own | |
543 | functions which modify format strings, so that GNU CC can check the | |
544 | calls to `printf' and `scanf' function whose operands are a call | |
545 | to one of your own function. The compiler always treats | |
546 | `gettext', `dgettext', and `dcgettext' in this manner. | |
547 | ||
548 | `section ("section-name")' | |
549 | Normally, the compiler places the code it generates in the `text' | |
550 | section. Sometimes, however, you need additional sections, or you | |
551 | need certain particular functions to appear in special sections. | |
552 | The `section' attribute specifies that a function lives in a | |
553 | particular section. For example, the declaration: | |
554 | ||
555 | extern void foobar (void) __attribute__ ((section ("bar"))); | |
556 | ||
557 | puts the function `foobar' in the `bar' section. | |
558 | ||
559 | Some file formats do not support arbitrary sections so the | |
560 | `section' attribute is not available on all platforms. If you | |
561 | need to map the entire contents of a module to a particular | |
562 | section, consider using the facilities of the linker instead. | |
563 | ||
564 | `constructor' | |
565 | `destructor' | |
566 | The `constructor' attribute causes the function to be called | |
567 | automatically before execution enters `main ()'. Similarly, the | |
568 | `destructor' attribute causes the function to be called | |
569 | automatically after `main ()' has completed or `exit ()' has been | |
570 | called. Functions with these attributes are useful for | |
571 | initializing data that will be used implicitly during the | |
572 | execution of the program. | |
573 | ||
574 | These attributes are not currently implemented for Objective C. | |
575 | ||
576 | `unused' | |
577 | This attribute, attached to a function, means that the function is | |
578 | meant to be possibly unused. GNU CC will not produce a warning | |
579 | for this function. GNU C++ does not currently support this | |
580 | attribute as definitions without parameters are valid in C++. | |
581 | ||
582 | `weak' | |
583 | The `weak' attribute causes the declaration to be emitted as a weak | |
584 | symbol rather than a global. This is primarily useful in defining | |
585 | library functions which can be overridden in user code, though it | |
586 | can also be used with non-function declarations. Weak symbols are | |
587 | supported for ELF targets, and also for a.out targets when using | |
588 | the GNU assembler and linker. | |
589 | ||
590 | `alias ("target")' | |
591 | The `alias' attribute causes the declaration to be emitted as an | |
592 | alias for another symbol, which must be specified. For instance, | |
593 | ||
594 | void __f () { /* do something */; } | |
595 | void f () __attribute__ ((weak, alias ("__f"))); | |
596 | ||
597 | declares `f' to be a weak alias for `__f'. In C++, the mangled | |
598 | name for the target must be used. | |
599 | ||
600 | Not all target machines support this attribute. | |
601 | ||
602 | `regparm (NUMBER)' | |
603 | On the Intel 386, the `regparm' attribute causes the compiler to | |
604 | pass up to NUMBER integer arguments in registers EAX, EDX, and ECX | |
605 | instead of on the stack. Functions that take a variable number of | |
606 | arguments will continue to be passed all of their arguments on the | |
607 | stack. | |
608 | ||
609 | `stdcall' | |
610 | On the Intel 386, the `stdcall' attribute causes the compiler to | |
611 | assume that the called function will pop off the stack space used | |
612 | to pass arguments, unless it takes a variable number of arguments. | |
613 | ||
614 | The PowerPC compiler for Windows NT currently ignores the `stdcall' | |
615 | attribute. | |
616 | ||
617 | `cdecl' | |
618 | On the Intel 386, the `cdecl' attribute causes the compiler to | |
619 | assume that the calling function will pop off the stack space used | |
620 | to pass arguments. This is useful to override the effects of the | |
621 | `-mrtd' switch. | |
622 | ||
623 | The PowerPC compiler for Windows NT currently ignores the `cdecl' | |
624 | attribute. | |
625 | ||
626 | `longcall' | |
627 | On the RS/6000 and PowerPC, the `longcall' attribute causes the | |
628 | compiler to always call the function via a pointer, so that | |
629 | functions which reside further than 64 megabytes (67,108,864 | |
630 | bytes) from the current location can be called. | |
631 | ||
632 | `dllimport' | |
633 | On the PowerPC running Windows NT, the `dllimport' attribute causes | |
634 | the compiler to call the function via a global pointer to the | |
635 | function pointer that is set up by the Windows NT dll library. | |
636 | The pointer name is formed by combining `__imp_' and the function | |
637 | name. | |
638 | ||
639 | `dllexport' | |
640 | On the PowerPC running Windows NT, the `dllexport' attribute causes | |
641 | the compiler to provide a global pointer to the function pointer, | |
642 | so that it can be called with the `dllimport' attribute. The | |
643 | pointer name is formed by combining `__imp_' and the function name. | |
644 | ||
645 | `exception (EXCEPT-FUNC [, EXCEPT-ARG])' | |
646 | On the PowerPC running Windows NT, the `exception' attribute causes | |
647 | the compiler to modify the structured exception table entry it | |
648 | emits for the declared function. The string or identifier | |
649 | EXCEPT-FUNC is placed in the third entry of the structured | |
650 | exception table. It represents a function, which is called by the | |
651 | exception handling mechanism if an exception occurs. If it was | |
652 | specified, the string or identifier EXCEPT-ARG is placed in the | |
653 | fourth entry of the structured exception table. | |
654 | ||
655 | `function_vector' | |
656 | Use this option on the H8/300 and H8/300H to indicate that the | |
657 | specified function should be called through the function vector. | |
658 | Calling a function through the function vector will reduce code | |
659 | size, however; the function vector has a limited size (maximum 128 | |
660 | entries on the H8/300 and 64 entries on the H8/300H) and shares | |
661 | space with the interrupt vector. | |
662 | ||
663 | You must use GAS and GLD from GNU binutils version 2.7 or later for | |
664 | this option to work correctly. | |
665 | ||
666 | `interrupt_handler' | |
667 | Use this option on the H8/300 and H8/300H to indicate that the | |
668 | specified function is an interrupt handler. The compiler will | |
669 | generate function entry and exit sequences suitable for use in an | |
670 | interrupt handler when this attribute is present. | |
671 | ||
672 | `eightbit_data' | |
673 | Use this option on the H8/300 and H8/300H to indicate that the | |
674 | specified variable should be placed into the eight bit data | |
675 | section. The compiler will generate more efficient code for | |
676 | certain operations on data in the eight bit data area. Note the | |
677 | eight bit data area is limited to 256 bytes of data. | |
678 | ||
679 | You must use GAS and GLD from GNU binutils version 2.7 or later for | |
680 | this option to work correctly. | |
681 | ||
682 | `tiny_data' | |
683 | Use this option on the H8/300H to indicate that the specified | |
684 | variable should be placed into the tiny data section. The | |
685 | compiler will generate more efficient code for loads and stores on | |
686 | data in the tiny data section. Note the tiny data area is limited | |
687 | to slightly under 32kbytes of data. | |
688 | ||
689 | `interrupt' | |
690 | Use this option on the M32R/D to indicate that the specified | |
691 | function is an interrupt handler. The compiler will generate | |
692 | function entry and exit sequences suitable for use in an interrupt | |
693 | handler when this attribute is present. | |
694 | ||
695 | `model (MODEL-NAME)' | |
696 | Use this attribute on the M32R/D to set the addressability of an | |
697 | object, and the code generated for a function. The identifier | |
698 | MODEL-NAME is one of `small', `medium', or `large', representing | |
699 | each of the code models. | |
700 | ||
701 | Small model objects live in the lower 16MB of memory (so that their | |
702 | addresses can be loaded with the `ld24' instruction), and are | |
703 | callable with the `bl' instruction. | |
704 | ||
705 | Medium model objects may live anywhere in the 32 bit address space | |
706 | (the compiler will generate `seth/add3' instructions to load their | |
707 | addresses), and are callable with the `bl' instruction. | |
708 | ||
709 | Large model objects may live anywhere in the 32 bit address space | |
710 | (the compiler will generate `seth/add3' instructions to load their | |
711 | addresses), and may not be reachable with the `bl' instruction | |
712 | (the compiler will generate the much slower `seth/add3/jl' | |
713 | instruction sequence). | |
714 | ||
715 | You can specify multiple attributes in a declaration by separating | |
716 | them by commas within the double parentheses or by immediately | |
717 | following an attribute declaration with another attribute declaration. | |
718 | ||
719 | Some people object to the `__attribute__' feature, suggesting that | |
720 | ANSI C's `#pragma' should be used instead. There are two reasons for | |
721 | not doing this. | |
722 | ||
723 | 1. It is impossible to generate `#pragma' commands from a macro. | |
724 | ||
725 | 2. There is no telling what the same `#pragma' might mean in another | |
726 | compiler. | |
727 | ||
728 | These two reasons apply to almost any application that might be | |
729 | proposed for `#pragma'. It is basically a mistake to use `#pragma' for | |
730 | *anything*. | |
731 | ||
732 | \1f | |
733 | File: gcc.info, Node: Function Prototypes, Next: C++ Comments, Prev: Function Attributes, Up: C Extensions | |
734 | ||
735 | Prototypes and Old-Style Function Definitions | |
736 | ============================================= | |
737 | ||
738 | GNU C extends ANSI C to allow a function prototype to override a | |
739 | later old-style non-prototype definition. Consider the following | |
740 | example: | |
741 | ||
742 | /* Use prototypes unless the compiler is old-fashioned. */ | |
743 | #ifdef __STDC__ | |
744 | #define P(x) x | |
745 | #else | |
746 | #define P(x) () | |
747 | #endif | |
748 | ||
749 | /* Prototype function declaration. */ | |
750 | int isroot P((uid_t)); | |
751 | ||
752 | /* Old-style function definition. */ | |
753 | int | |
754 | isroot (x) /* ??? lossage here ??? */ | |
755 | uid_t x; | |
756 | { | |
757 | return x == 0; | |
758 | } | |
759 | ||
760 | Suppose the type `uid_t' happens to be `short'. ANSI C does not | |
761 | allow this example, because subword arguments in old-style | |
762 | non-prototype definitions are promoted. Therefore in this example the | |
763 | function definition's argument is really an `int', which does not match | |
764 | the prototype argument type of `short'. | |
765 | ||
766 | This restriction of ANSI C makes it hard to write code that is | |
767 | portable to traditional C compilers, because the programmer does not | |
768 | know whether the `uid_t' type is `short', `int', or `long'. Therefore, | |
769 | in cases like these GNU C allows a prototype to override a later | |
770 | old-style definition. More precisely, in GNU C, a function prototype | |
771 | argument type overrides the argument type specified by a later | |
772 | old-style definition if the former type is the same as the latter type | |
773 | before promotion. Thus in GNU C the above example is equivalent to the | |
774 | following: | |
775 | ||
776 | int isroot (uid_t); | |
777 | ||
778 | int | |
779 | isroot (uid_t x) | |
780 | { | |
781 | return x == 0; | |
782 | } | |
783 | ||
784 | GNU C++ does not support old-style function definitions, so this | |
785 | extension is irrelevant. | |
786 | ||
787 | \1f | |
788 | File: gcc.info, Node: C++ Comments, Next: Dollar Signs, Prev: Function Prototypes, Up: C Extensions | |
789 | ||
790 | C++ Style Comments | |
791 | ================== | |
792 | ||
793 | In GNU C, you may use C++ style comments, which start with `//' and | |
794 | continue until the end of the line. Many other C implementations allow | |
795 | such comments, and they are likely to be in a future C standard. | |
796 | However, C++ style comments are not recognized if you specify `-ansi' | |
797 | or `-traditional', since they are incompatible with traditional | |
798 | constructs like `dividend//*comment*/divisor'. | |
799 | ||
800 | \1f | |
801 | File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: C++ Comments, Up: C Extensions | |
802 | ||
803 | Dollar Signs in Identifier Names | |
804 | ================================ | |
805 | ||
806 | In GNU C, you may normally use dollar signs in identifier names. | |
807 | This is because many traditional C implementations allow such | |
808 | identifiers. However, dollar signs in identifiers are not supported on | |
809 | a few target machines, typically because the target assembler does not | |
810 | allow them. | |
811 | ||
812 | \1f | |
813 | File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions | |
814 | ||
815 | The Character <ESC> in Constants | |
816 | ================================ | |
817 | ||
818 | You can use the sequence `\e' in a string or character constant to | |
819 | stand for the ASCII character <ESC>. | |
820 | ||
821 | \1f | |
822 | File: gcc.info, Node: Alignment, Next: Inline, Prev: Type Attributes, Up: C Extensions | |
823 | ||
824 | Inquiring on Alignment of Types or Variables | |
825 | ============================================ | |
826 | ||
827 | The keyword `__alignof__' allows you to inquire about how an object | |
828 | is aligned, or the minimum alignment usually required by a type. Its | |
829 | syntax is just like `sizeof'. | |
830 | ||
831 | For example, if the target machine requires a `double' value to be | |
832 | aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This | |
833 | is true on many RISC machines. On more traditional machine designs, | |
834 | `__alignof__ (double)' is 4 or even 2. | |
835 | ||
836 | Some machines never actually require alignment; they allow reference | |
837 | to any data type even at an odd addresses. For these machines, | |
838 | `__alignof__' reports the *recommended* alignment of a type. | |
839 | ||
840 | When the operand of `__alignof__' is an lvalue rather than a type, | |
841 | the value is the largest alignment that the lvalue is known to have. | |
842 | It may have this alignment as a result of its data type, or because it | |
843 | is part of a structure and inherits alignment from that structure. For | |
844 | example, after this declaration: | |
845 | ||
846 | struct foo { int x; char y; } foo1; | |
847 | ||
848 | the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as | |
849 | `__alignof__ (int)', even though the data type of `foo1.y' does not | |
850 | itself demand any alignment. | |
851 | ||
852 | A related feature which lets you specify the alignment of an object | |
853 | is `__attribute__ ((aligned (ALIGNMENT)))'; see the following section. | |
854 | ||
855 | \1f | |
856 | File: gcc.info, Node: Variable Attributes, Next: Type Attributes, Prev: Character Escapes, Up: C Extensions | |
857 | ||
858 | Specifying Attributes of Variables | |
859 | ================================== | |
860 | ||
861 | The keyword `__attribute__' allows you to specify special attributes | |
862 | of variables or structure fields. This keyword is followed by an | |
863 | attribute specification inside double parentheses. Eight attributes | |
864 | are currently defined for variables: `aligned', `mode', `nocommon', | |
865 | `packed', `section', `transparent_union', `unused', and `weak'. Other | |
866 | attributes are available for functions (*note Function Attributes::.) | |
867 | and for types (*note Type Attributes::.). | |
868 | ||
869 | You may also specify attributes with `__' preceding and following | |
870 | each keyword. This allows you to use them in header files without | |
871 | being concerned about a possible macro of the same name. For example, | |
872 | you may use `__aligned__' instead of `aligned'. | |
873 | ||
874 | `aligned (ALIGNMENT)' | |
875 | This attribute specifies a minimum alignment for the variable or | |
876 | structure field, measured in bytes. For example, the declaration: | |
877 | ||
878 | int x __attribute__ ((aligned (16))) = 0; | |
879 | ||
880 | causes the compiler to allocate the global variable `x' on a | |
881 | 16-byte boundary. On a 68040, this could be used in conjunction | |
882 | with an `asm' expression to access the `move16' instruction which | |
883 | requires 16-byte aligned operands. | |
884 | ||
885 | You can also specify the alignment of structure fields. For | |
886 | example, to create a double-word aligned `int' pair, you could | |
887 | write: | |
888 | ||
889 | struct foo { int x[2] __attribute__ ((aligned (8))); }; | |
890 | ||
891 | This is an alternative to creating a union with a `double' member | |
892 | that forces the union to be double-word aligned. | |
893 | ||
894 | It is not possible to specify the alignment of functions; the | |
895 | alignment of functions is determined by the machine's requirements | |
896 | and cannot be changed. You cannot specify alignment for a typedef | |
897 | name because such a name is just an alias, not a distinct type. | |
898 | ||
899 | As in the preceding examples, you can explicitly specify the | |
900 | alignment (in bytes) that you wish the compiler to use for a given | |
901 | variable or structure field. Alternatively, you can leave out the | |
902 | alignment factor and just ask the compiler to align a variable or | |
903 | field to the maximum useful alignment for the target machine you | |
904 | are compiling for. For example, you could write: | |
905 | ||
906 | short array[3] __attribute__ ((aligned)); | |
907 | ||
908 | Whenever you leave out the alignment factor in an `aligned' | |
909 | attribute specification, the compiler automatically sets the | |
910 | alignment for the declared variable or field to the largest | |
911 | alignment which is ever used for any data type on the target | |
912 | machine you are compiling for. Doing this can often make copy | |
913 | operations more efficient, because the compiler can use whatever | |
914 | instructions copy the biggest chunks of memory when performing | |
915 | copies to or from the variables or fields that you have aligned | |
916 | this way. | |
917 | ||
918 | The `aligned' attribute can only increase the alignment; but you | |
919 | can decrease it by specifying `packed' as well. See below. | |
920 | ||
921 | Note that the effectiveness of `aligned' attributes may be limited | |
922 | by inherent limitations in your linker. On many systems, the | |
923 | linker is only able to arrange for variables to be aligned up to a | |
924 | certain maximum alignment. (For some linkers, the maximum | |
925 | supported alignment may be very very small.) If your linker is | |
926 | only able to align variables up to a maximum of 8 byte alignment, | |
927 | then specifying `aligned(16)' in an `__attribute__' will still | |
928 | only provide you with 8 byte alignment. See your linker | |
929 | documentation for further information. | |
930 | ||
931 | `mode (MODE)' | |
932 | This attribute specifies the data type for the | |
933 | declaration--whichever type corresponds to the mode MODE. This in | |
934 | effect lets you request an integer or floating point type | |
935 | according to its width. | |
936 | ||
937 | You may also specify a mode of `byte' or `__byte__' to indicate | |
938 | the mode corresponding to a one-byte integer, `word' or `__word__' | |
939 | for the mode of a one-word integer, and `pointer' or `__pointer__' | |
940 | for the mode used to represent pointers. | |
941 | ||
942 | `nocommon' | |
943 | This attribute specifies requests GNU CC not to place a variable | |
944 | "common" but instead to allocate space for it directly. If you | |
945 | specify the `-fno-common' flag, GNU CC will do this for all | |
946 | variables. | |
947 | ||
948 | Specifying the `nocommon' attribute for a variable provides an | |
949 | initialization of zeros. A variable may only be initialized in one | |
950 | source file. | |
951 | ||
952 | `packed' | |
953 | The `packed' attribute specifies that a variable or structure field | |
954 | should have the smallest possible alignment--one byte for a | |
955 | variable, and one bit for a field, unless you specify a larger | |
956 | value with the `aligned' attribute. | |
957 | ||
958 | Here is a structure in which the field `x' is packed, so that it | |
959 | immediately follows `a': | |
960 | ||
961 | struct foo | |
962 | { | |
963 | char a; | |
964 | int x[2] __attribute__ ((packed)); | |
965 | }; | |
966 | ||
967 | `section ("section-name")' | |
968 | Normally, the compiler places the objects it generates in sections | |
969 | like `data' and `bss'. Sometimes, however, you need additional | |
970 | sections, or you need certain particular variables to appear in | |
971 | special sections, for example to map to special hardware. The | |
972 | `section' attribute specifies that a variable (or function) lives | |
973 | in a particular section. For example, this small program uses | |
974 | several specific section names: | |
975 | ||
976 | struct duart a __attribute__ ((section ("DUART_A"))) = { 0 }; | |
977 | struct duart b __attribute__ ((section ("DUART_B"))) = { 0 }; | |
978 | char stack[10000] __attribute__ ((section ("STACK"))) = { 0 }; | |
979 | int init_data __attribute__ ((section ("INITDATA"))) = 0; | |
980 | ||
981 | main() | |
982 | { | |
983 | /* Initialize stack pointer */ | |
984 | init_sp (stack + sizeof (stack)); | |
985 | ||
986 | /* Initialize initialized data */ | |
987 | memcpy (&init_data, &data, &edata - &data); | |
988 | ||
989 | /* Turn on the serial ports */ | |
990 | init_duart (&a); | |
991 | init_duart (&b); | |
992 | } | |
993 | ||
994 | Use the `section' attribute with an *initialized* definition of a | |
995 | *global* variable, as shown in the example. GNU CC issues a | |
996 | warning and otherwise ignores the `section' attribute in | |
997 | uninitialized variable declarations. | |
998 | ||
999 | You may only use the `section' attribute with a fully initialized | |
1000 | global definition because of the way linkers work. The linker | |
1001 | requires each object be defined once, with the exception that | |
1002 | uninitialized variables tentatively go in the `common' (or `bss') | |
1003 | section and can be multiply "defined". You can force a variable | |
1004 | to be initialized with the `-fno-common' flag or the `nocommon' | |
1005 | attribute. | |
1006 | ||
1007 | Some file formats do not support arbitrary sections so the | |
1008 | `section' attribute is not available on all platforms. If you | |
1009 | need to map the entire contents of a module to a particular | |
1010 | section, consider using the facilities of the linker instead. | |
1011 | ||
1012 | `transparent_union' | |
1013 | This attribute, attached to a function parameter which is a union, | |
1014 | means that the corresponding argument may have the type of any | |
1015 | union member, but the argument is passed as if its type were that | |
1016 | of the first union member. For more details see *Note Type | |
1017 | Attributes::. You can also use this attribute on a `typedef' for | |
1018 | a union data type; then it applies to all function parameters with | |
1019 | that type. | |
1020 | ||
1021 | `unused' | |
1022 | This attribute, attached to a variable, means that the variable is | |
1023 | meant to be possibly unused. GNU CC will not produce a warning | |
1024 | for this variable. | |
1025 | ||
1026 | `weak' | |
1027 | The `weak' attribute is described in *Note Function Attributes::. | |
1028 | ||
1029 | `model (MODEL-NAME)' | |
1030 | Use this attribute on the M32R/D to set the addressability of an | |
1031 | object. The identifier MODEL-NAME is one of `small', `medium', or | |
1032 | `large', representing each of the code models. | |
1033 | ||
1034 | Small model objects live in the lower 16MB of memory (so that their | |
1035 | addresses can be loaded with the `ld24' instruction). | |
1036 | ||
1037 | Medium and large model objects may live anywhere in the 32 bit | |
1038 | address space (the compiler will generate `seth/add3' instructions | |
1039 | to load their addresses). | |
1040 | ||
1041 | To specify multiple attributes, separate them by commas within the | |
1042 | double parentheses: for example, `__attribute__ ((aligned (16), | |
1043 | packed))'. | |
1044 | ||
1045 | \1f | |
1046 | File: gcc.info, Node: Type Attributes, Next: Alignment, Prev: Variable Attributes, Up: C Extensions | |
1047 | ||
1048 | Specifying Attributes of Types | |
1049 | ============================== | |
1050 | ||
1051 | The keyword `__attribute__' allows you to specify special attributes | |
1052 | of `struct' and `union' types when you define such types. This keyword | |
1053 | is followed by an attribute specification inside double parentheses. | |
1054 | Three attributes are currently defined for types: `aligned', `packed', | |
1055 | and `transparent_union'. Other attributes are defined for functions | |
1056 | (*note Function Attributes::.) and for variables (*note Variable | |
1057 | Attributes::.). | |
1058 | ||
1059 | You may also specify any one of these attributes with `__' preceding | |
1060 | and following its keyword. This allows you to use these attributes in | |
1061 | header files without being concerned about a possible macro of the same | |
1062 | name. For example, you may use `__aligned__' instead of `aligned'. | |
1063 | ||
1064 | You may specify the `aligned' and `transparent_union' attributes | |
1065 | either in a `typedef' declaration or just past the closing curly brace | |
1066 | of a complete enum, struct or union type *definition* and the `packed' | |
1067 | attribute only past the closing brace of a definition. | |
1068 | ||
1069 | `aligned (ALIGNMENT)' | |
1070 | This attribute specifies a minimum alignment (in bytes) for | |
1071 | variables of the specified type. For example, the declarations: | |
1072 | ||
1073 | struct S { short f[3]; } __attribute__ ((aligned (8)); | |
1074 | typedef int more_aligned_int __attribute__ ((aligned (8)); | |
1075 | ||
1076 | force the compiler to insure (as far as it can) that each variable | |
1077 | whose type is `struct S' or `more_aligned_int' will be allocated | |
1078 | and aligned *at least* on a 8-byte boundary. On a Sparc, having | |
1079 | all variables of type `struct S' aligned to 8-byte boundaries | |
1080 | allows the compiler to use the `ldd' and `std' (doubleword load and | |
1081 | store) instructions when copying one variable of type `struct S' to | |
1082 | another, thus improving run-time efficiency. | |
1083 | ||
1084 | Note that the alignment of any given `struct' or `union' type is | |
1085 | required by the ANSI C standard to be at least a perfect multiple | |
1086 | of the lowest common multiple of the alignments of all of the | |
1087 | members of the `struct' or `union' in question. This means that | |
1088 | you *can* effectively adjust the alignment of a `struct' or `union' | |
1089 | type by attaching an `aligned' attribute to any one of the members | |
1090 | of such a type, but the notation illustrated in the example above | |
1091 | is a more obvious, intuitive, and readable way to request the | |
1092 | compiler to adjust the alignment of an entire `struct' or `union' | |
1093 | type. | |
1094 | ||
1095 | As in the preceding example, you can explicitly specify the | |
1096 | alignment (in bytes) that you wish the compiler to use for a given | |
1097 | `struct' or `union' type. Alternatively, you can leave out the | |
1098 | alignment factor and just ask the compiler to align a type to the | |
1099 | maximum useful alignment for the target machine you are compiling | |
1100 | for. For example, you could write: | |
1101 | ||
1102 | struct S { short f[3]; } __attribute__ ((aligned)); | |
1103 | ||
1104 | Whenever you leave out the alignment factor in an `aligned' | |
1105 | attribute specification, the compiler automatically sets the | |
1106 | alignment for the type to the largest alignment which is ever used | |
1107 | for any data type on the target machine you are compiling for. | |
1108 | Doing this can often make copy operations more efficient, because | |
1109 | the compiler can use whatever instructions copy the biggest chunks | |
1110 | of memory when performing copies to or from the variables which | |
1111 | have types that you have aligned this way. | |
1112 | ||
1113 | In the example above, if the size of each `short' is 2 bytes, then | |
1114 | the size of the entire `struct S' type is 6 bytes. The smallest | |
1115 | power of two which is greater than or equal to that is 8, so the | |
1116 | compiler sets the alignment for the entire `struct S' type to 8 | |
1117 | bytes. | |
1118 | ||
1119 | Note that although you can ask the compiler to select a | |
1120 | time-efficient alignment for a given type and then declare only | |
1121 | individual stand-alone objects of that type, the compiler's | |
1122 | ability to select a time-efficient alignment is primarily useful | |
1123 | only when you plan to create arrays of variables having the | |
1124 | relevant (efficiently aligned) type. If you declare or use arrays | |
1125 | of variables of an efficiently-aligned type, then it is likely | |
1126 | that your program will also be doing pointer arithmetic (or | |
1127 | subscripting, which amounts to the same thing) on pointers to the | |
1128 | relevant type, and the code that the compiler generates for these | |
1129 | pointer arithmetic operations will often be more efficient for | |
1130 | efficiently-aligned types than for other types. | |
1131 | ||
1132 | The `aligned' attribute can only increase the alignment; but you | |
1133 | can decrease it by specifying `packed' as well. See below. | |
1134 | ||
1135 | Note that the effectiveness of `aligned' attributes may be limited | |
1136 | by inherent limitations in your linker. On many systems, the | |
1137 | linker is only able to arrange for variables to be aligned up to a | |
1138 | certain maximum alignment. (For some linkers, the maximum | |
1139 | supported alignment may be very very small.) If your linker is | |
1140 | only able to align variables up to a maximum of 8 byte alignment, | |
1141 | then specifying `aligned(16)' in an `__attribute__' will still | |
1142 | only provide you with 8 byte alignment. See your linker | |
1143 | documentation for further information. | |
1144 | ||
1145 | `packed' | |
1146 | This attribute, attached to an `enum', `struct', or `union' type | |
1147 | definition, specified that the minimum required memory be used to | |
1148 | represent the type. | |
1149 | ||
1150 | Specifying this attribute for `struct' and `union' types is | |
1151 | equivalent to specifying the `packed' attribute on each of the | |
1152 | structure or union members. Specifying the `-fshort-enums' flag | |
1153 | on the line is equivalent to specifying the `packed' attribute on | |
1154 | all `enum' definitions. | |
1155 | ||
1156 | You may only specify this attribute after a closing curly brace on | |
1157 | an `enum' definition, not in a `typedef' declaration, unless that | |
1158 | declaration also contains the definition of the `enum'. | |
1159 | ||
1160 | `transparent_union' | |
1161 | This attribute, attached to a `union' type definition, indicates | |
1162 | that any function parameter having that union type causes calls to | |
1163 | that function to be treated in a special way. | |
1164 | ||
1165 | First, the argument corresponding to a transparent union type can | |
1166 | be of any type in the union; no cast is required. Also, if the | |
1167 | union contains a pointer type, the corresponding argument can be a | |
1168 | null pointer constant or a void pointer expression; and if the | |
1169 | union contains a void pointer type, the corresponding argument can | |
1170 | be any pointer expression. If the union member type is a pointer, | |
1171 | qualifiers like `const' on the referenced type must be respected, | |
1172 | just as with normal pointer conversions. | |
1173 | ||
1174 | Second, the argument is passed to the function using the calling | |
1175 | conventions of first member of the transparent union, not the | |
1176 | calling conventions of the union itself. All members of the union | |
1177 | must have the same machine representation; this is necessary for | |
1178 | this argument passing to work properly. | |
1179 | ||
1180 | Transparent unions are designed for library functions that have | |
1181 | multiple interfaces for compatibility reasons. For example, | |
1182 | suppose the `wait' function must accept either a value of type | |
1183 | `int *' to comply with Posix, or a value of type `union wait *' to | |
1184 | comply with the 4.1BSD interface. If `wait''s parameter were | |
1185 | `void *', `wait' would accept both kinds of arguments, but it | |
1186 | would also accept any other pointer type and this would make | |
1187 | argument type checking less useful. Instead, `<sys/wait.h>' might | |
1188 | define the interface as follows: | |
1189 | ||
1190 | typedef union | |
1191 | { | |
1192 | int *__ip; | |
1193 | union wait *__up; | |
1194 | } wait_status_ptr_t __attribute__ ((__transparent_union__)); | |
1195 | ||
1196 | pid_t wait (wait_status_ptr_t); | |
1197 | ||
1198 | This interface allows either `int *' or `union wait *' arguments | |
1199 | to be passed, using the `int *' calling convention. The program | |
1200 | can call `wait' with arguments of either type: | |
1201 | ||
1202 | int w1 () { int w; return wait (&w); } | |
1203 | int w2 () { union wait w; return wait (&w); } | |
1204 | ||
1205 | With this interface, `wait''s implementation might look like this: | |
1206 | ||
1207 | pid_t wait (wait_status_ptr_t p) | |
1208 | { | |
1209 | return waitpid (-1, p.__ip, 0); | |
1210 | } | |
1211 | ||
1212 | `unused' | |
1213 | When attached to a type (including a `union' or a `struct'), this | |
1214 | attribute means that variables of that type are meant to appear | |
1215 | possibly unused. GNU CC will not produce a warning for any | |
1216 | variables of that type, even if the variable appears to do | |
1217 | nothing. This is often the case with lock or thread classes, | |
1218 | which are usually defined and then not referenced, but contain | |
1219 | constructors and destructors that have non-trivial bookeeping | |
1220 | functions. | |
1221 | ||
1222 | To specify multiple attributes, separate them by commas within the | |
1223 | double parentheses: for example, `__attribute__ ((aligned (16), | |
1224 | packed))'. | |
1225 |