OSDN Git Service

PR target/27544
[pf3gnuchains/gcc-fork.git] / gcc / doc / extend.texi
1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
2 @c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
3
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
6
7 @node C Extensions
8 @chapter Extensions to the C Language Family
9 @cindex extensions, C language
10 @cindex C language extensions
11
12 @opindex pedantic
13 GNU C provides several language features not found in ISO standard C@.
14 (The @option{-pedantic} option directs GCC to print a warning message if
15 any of these features is used.)  To test for the availability of these
16 features in conditional compilation, check for a predefined macro
17 @code{__GNUC__}, which is always defined under GCC@.
18
19 These extensions are available in C and Objective-C@.  Most of them are
20 also available in C++.  @xref{C++ Extensions,,Extensions to the
21 C++ Language}, for extensions that apply @emph{only} to C++.
22
23 Some features that are in ISO C99 but not C89 or C++ are also, as
24 extensions, accepted by GCC in C89 mode and in C++.
25
26 @menu
27 * Statement Exprs::     Putting statements and declarations inside expressions.
28 * Local Labels::        Labels local to a block.
29 * Labels as Values::    Getting pointers to labels, and computed gotos.
30 * Nested Functions::    As in Algol and Pascal, lexical scoping of functions.
31 * Constructing Calls::  Dispatching a call to another function.
32 * Typeof::              @code{typeof}: referring to the type of an expression.
33 * Conditionals::        Omitting the middle operand of a @samp{?:} expression.
34 * Long Long::           Double-word integers---@code{long long int}.
35 * Complex::             Data types for complex numbers.
36 * Decimal Float::       Decimal Floating Point.
37 * Hex Floats::          Hexadecimal floating-point constants.
38 * Zero Length::         Zero-length arrays.
39 * Variable Length::     Arrays whose length is computed at run time.
40 * Empty Structures::    Structures with no members.
41 * Variadic Macros::     Macros with a variable number of arguments.
42 * Escaped Newlines::    Slightly looser rules for escaped newlines.
43 * Subscripting::        Any array can be subscripted, even if not an lvalue.
44 * Pointer Arith::       Arithmetic on @code{void}-pointers and function pointers.
45 * Initializers::        Non-constant initializers.
46 * Compound Literals::   Compound literals give structures, unions
47                          or arrays as values.
48 * Designated Inits::    Labeling elements of initializers.
49 * Cast to Union::       Casting to union type from any member of the union.
50 * Case Ranges::         `case 1 ... 9' and such.
51 * Mixed Declarations::  Mixing declarations and code.
52 * Function Attributes:: Declaring that functions have no side effects,
53                          or that they can never return.
54 * Attribute Syntax::    Formal syntax for attributes.
55 * Function Prototypes:: Prototype declarations and old-style definitions.
56 * C++ Comments::        C++ comments are recognized.
57 * Dollar Signs::        Dollar sign is allowed in identifiers.
58 * Character Escapes::   @samp{\e} stands for the character @key{ESC}.
59 * Variable Attributes:: Specifying attributes of variables.
60 * Type Attributes::     Specifying attributes of types.
61 * Alignment::           Inquiring about the alignment of a type or variable.
62 * Inline::              Defining inline functions (as fast as macros).
63 * Extended Asm::        Assembler instructions with C expressions as operands.
64                          (With them you can define ``built-in'' functions.)
65 * Constraints::         Constraints for asm operands
66 * Asm Labels::          Specifying the assembler name to use for a C symbol.
67 * Explicit Reg Vars::   Defining variables residing in specified registers.
68 * Alternate Keywords::  @code{__const__}, @code{__asm__}, etc., for header files.
69 * Incomplete Enums::    @code{enum foo;}, with details to follow.
70 * Function Names::      Printable strings which are the name of the current
71                          function.
72 * Return Address::      Getting the return or frame address of a function.
73 * Vector Extensions::   Using vector instructions through built-in functions.
74 * Offsetof::            Special syntax for implementing @code{offsetof}.
75 * Atomic Builtins::     Built-in functions for atomic memory access.
76 * Object Size Checking:: Built-in functions for limited buffer overflow
77                         checking.
78 * Other Builtins::      Other built-in functions.
79 * Target Builtins::     Built-in functions specific to particular targets.
80 * Target Format Checks:: Format checks specific to particular targets.
81 * Pragmas::             Pragmas accepted by GCC.
82 * Unnamed Fields::      Unnamed struct/union fields within structs/unions.
83 * Thread-Local::        Per-thread variables.
84 @end menu
85
86 @node Statement Exprs
87 @section Statements and Declarations in Expressions
88 @cindex statements inside expressions
89 @cindex declarations inside expressions
90 @cindex expressions containing statements
91 @cindex macros, statements in expressions
92
93 @c the above section title wrapped and causes an underfull hbox.. i
94 @c changed it from "within" to "in". --mew 4feb93
95 A compound statement enclosed in parentheses may appear as an expression
96 in GNU C@.  This allows you to use loops, switches, and local variables
97 within an expression.
98
99 Recall that a compound statement is a sequence of statements surrounded
100 by braces; in this construct, parentheses go around the braces.  For
101 example:
102
103 @smallexample
104 (@{ int y = foo (); int z;
105    if (y > 0) z = y;
106    else z = - y;
107    z; @})
108 @end smallexample
109
110 @noindent
111 is a valid (though slightly more complex than necessary) expression
112 for the absolute value of @code{foo ()}.
113
114 The last thing in the compound statement should be an expression
115 followed by a semicolon; the value of this subexpression serves as the
116 value of the entire construct.  (If you use some other kind of statement
117 last within the braces, the construct has type @code{void}, and thus
118 effectively no value.)
119
120 This feature is especially useful in making macro definitions ``safe'' (so
121 that they evaluate each operand exactly once).  For example, the
122 ``maximum'' function is commonly defined as a macro in standard C as
123 follows:
124
125 @smallexample
126 #define max(a,b) ((a) > (b) ? (a) : (b))
127 @end smallexample
128
129 @noindent
130 @cindex side effects, macro argument
131 But this definition computes either @var{a} or @var{b} twice, with bad
132 results if the operand has side effects.  In GNU C, if you know the
133 type of the operands (here taken as @code{int}), you can define
134 the macro safely as follows:
135
136 @smallexample
137 #define maxint(a,b) \
138   (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
139 @end smallexample
140
141 Embedded statements are not allowed in constant expressions, such as
142 the value of an enumeration constant, the width of a bit-field, or
143 the initial value of a static variable.
144
145 If you don't know the type of the operand, you can still do this, but you
146 must use @code{typeof} (@pxref{Typeof}).
147
148 In G++, the result value of a statement expression undergoes array and
149 function pointer decay, and is returned by value to the enclosing
150 expression.  For instance, if @code{A} is a class, then
151
152 @smallexample
153         A a;
154
155         (@{a;@}).Foo ()
156 @end smallexample
157
158 @noindent
159 will construct a temporary @code{A} object to hold the result of the
160 statement expression, and that will be used to invoke @code{Foo}.
161 Therefore the @code{this} pointer observed by @code{Foo} will not be the
162 address of @code{a}.
163
164 Any temporaries created within a statement within a statement expression
165 will be destroyed at the statement's end.  This makes statement
166 expressions inside macros slightly different from function calls.  In
167 the latter case temporaries introduced during argument evaluation will
168 be destroyed at the end of the statement that includes the function
169 call.  In the statement expression case they will be destroyed during
170 the statement expression.  For instance,
171
172 @smallexample
173 #define macro(a)  (@{__typeof__(a) b = (a); b + 3; @})
174 template<typename T> T function(T a) @{ T b = a; return b + 3; @}
175
176 void foo ()
177 @{
178   macro (X ());
179   function (X ());
180 @}
181 @end smallexample
182
183 @noindent
184 will have different places where temporaries are destroyed.  For the
185 @code{macro} case, the temporary @code{X} will be destroyed just after
186 the initialization of @code{b}.  In the @code{function} case that
187 temporary will be destroyed when the function returns.
188
189 These considerations mean that it is probably a bad idea to use
190 statement-expressions of this form in header files that are designed to
191 work with C++.  (Note that some versions of the GNU C Library contained
192 header files using statement-expression that lead to precisely this
193 bug.)
194
195 Jumping into a statement expression with @code{goto} or using a
196 @code{switch} statement outside the statement expression with a
197 @code{case} or @code{default} label inside the statement expression is
198 not permitted.  Jumping into a statement expression with a computed
199 @code{goto} (@pxref{Labels as Values}) yields undefined behavior.
200 Jumping out of a statement expression is permitted, but if the
201 statement expression is part of a larger expression then it is
202 unspecified which other subexpressions of that expression have been
203 evaluated except where the language definition requires certain
204 subexpressions to be evaluated before or after the statement
205 expression.  In any case, as with a function call the evaluation of a
206 statement expression is not interleaved with the evaluation of other
207 parts of the containing expression.  For example,
208
209 @smallexample
210   foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
211 @end smallexample
212
213 @noindent
214 will call @code{foo} and @code{bar1} and will not call @code{baz} but
215 may or may not call @code{bar2}.  If @code{bar2} is called, it will be
216 called after @code{foo} and before @code{bar1}
217
218 @node Local Labels
219 @section Locally Declared Labels
220 @cindex local labels
221 @cindex macros, local labels
222
223 GCC allows you to declare @dfn{local labels} in any nested block
224 scope.  A local label is just like an ordinary label, but you can
225 only reference it (with a @code{goto} statement, or by taking its
226 address) within the block in which it was declared.
227
228 A local label declaration looks like this:
229
230 @smallexample
231 __label__ @var{label};
232 @end smallexample
233
234 @noindent
235 or
236
237 @smallexample
238 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
239 @end smallexample
240
241 Local label declarations must come at the beginning of the block,
242 before any ordinary declarations or statements.
243
244 The label declaration defines the label @emph{name}, but does not define
245 the label itself.  You must do this in the usual way, with
246 @code{@var{label}:}, within the statements of the statement expression.
247
248 The local label feature is useful for complex macros.  If a macro
249 contains nested loops, a @code{goto} can be useful for breaking out of
250 them.  However, an ordinary label whose scope is the whole function
251 cannot be used: if the macro can be expanded several times in one
252 function, the label will be multiply defined in that function.  A
253 local label avoids this problem.  For example:
254
255 @smallexample
256 #define SEARCH(value, array, target)              \
257 do @{                                              \
258   __label__ found;                                \
259   typeof (target) _SEARCH_target = (target);      \
260   typeof (*(array)) *_SEARCH_array = (array);     \
261   int i, j;                                       \
262   int value;                                      \
263   for (i = 0; i < max; i++)                       \
264     for (j = 0; j < max; j++)                     \
265       if (_SEARCH_array[i][j] == _SEARCH_target)  \
266         @{ (value) = i; goto found; @}              \
267   (value) = -1;                                   \
268  found:;                                          \
269 @} while (0)
270 @end smallexample
271
272 This could also be written using a statement-expression:
273
274 @smallexample
275 #define SEARCH(array, target)                     \
276 (@{                                                \
277   __label__ found;                                \
278   typeof (target) _SEARCH_target = (target);      \
279   typeof (*(array)) *_SEARCH_array = (array);     \
280   int i, j;                                       \
281   int value;                                      \
282   for (i = 0; i < max; i++)                       \
283     for (j = 0; j < max; j++)                     \
284       if (_SEARCH_array[i][j] == _SEARCH_target)  \
285         @{ value = i; goto found; @}                \
286   value = -1;                                     \
287  found:                                           \
288   value;                                          \
289 @})
290 @end smallexample
291
292 Local label declarations also make the labels they declare visible to
293 nested functions, if there are any.  @xref{Nested Functions}, for details.
294
295 @node Labels as Values
296 @section Labels as Values
297 @cindex labels as values
298 @cindex computed gotos
299 @cindex goto with computed label
300 @cindex address of a label
301
302 You can get the address of a label defined in the current function
303 (or a containing function) with the unary operator @samp{&&}.  The
304 value has type @code{void *}.  This value is a constant and can be used
305 wherever a constant of that type is valid.  For example:
306
307 @smallexample
308 void *ptr;
309 /* @r{@dots{}} */
310 ptr = &&foo;
311 @end smallexample
312
313 To use these values, you need to be able to jump to one.  This is done
314 with the computed goto statement@footnote{The analogous feature in
315 Fortran is called an assigned goto, but that name seems inappropriate in
316 C, where one can do more than simply store label addresses in label
317 variables.}, @code{goto *@var{exp};}.  For example,
318
319 @smallexample
320 goto *ptr;
321 @end smallexample
322
323 @noindent
324 Any expression of type @code{void *} is allowed.
325
326 One way of using these constants is in initializing a static array that
327 will serve as a jump table:
328
329 @smallexample
330 static void *array[] = @{ &&foo, &&bar, &&hack @};
331 @end smallexample
332
333 Then you can select a label with indexing, like this:
334
335 @smallexample
336 goto *array[i];
337 @end smallexample
338
339 @noindent
340 Note that this does not check whether the subscript is in bounds---array
341 indexing in C never does that.
342
343 Such an array of label values serves a purpose much like that of the
344 @code{switch} statement.  The @code{switch} statement is cleaner, so
345 use that rather than an array unless the problem does not fit a
346 @code{switch} statement very well.
347
348 Another use of label values is in an interpreter for threaded code.
349 The labels within the interpreter function can be stored in the
350 threaded code for super-fast dispatching.
351
352 You may not use this mechanism to jump to code in a different function.
353 If you do that, totally unpredictable things will happen.  The best way to
354 avoid this is to store the label address only in automatic variables and
355 never pass it as an argument.
356
357 An alternate way to write the above example is
358
359 @smallexample
360 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
361                              &&hack - &&foo @};
362 goto *(&&foo + array[i]);
363 @end smallexample
364
365 @noindent
366 This is more friendly to code living in shared libraries, as it reduces
367 the number of dynamic relocations that are needed, and by consequence,
368 allows the data to be read-only.
369
370 @node Nested Functions
371 @section Nested Functions
372 @cindex nested functions
373 @cindex downward funargs
374 @cindex thunks
375
376 A @dfn{nested function} is a function defined inside another function.
377 (Nested functions are not supported for GNU C++.)  The nested function's
378 name is local to the block where it is defined.  For example, here we
379 define a nested function named @code{square}, and call it twice:
380
381 @smallexample
382 @group
383 foo (double a, double b)
384 @{
385   double square (double z) @{ return z * z; @}
386
387   return square (a) + square (b);
388 @}
389 @end group
390 @end smallexample
391
392 The nested function can access all the variables of the containing
393 function that are visible at the point of its definition.  This is
394 called @dfn{lexical scoping}.  For example, here we show a nested
395 function which uses an inherited variable named @code{offset}:
396
397 @smallexample
398 @group
399 bar (int *array, int offset, int size)
400 @{
401   int access (int *array, int index)
402     @{ return array[index + offset]; @}
403   int i;
404   /* @r{@dots{}} */
405   for (i = 0; i < size; i++)
406     /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
407 @}
408 @end group
409 @end smallexample
410
411 Nested function definitions are permitted within functions in the places
412 where variable definitions are allowed; that is, in any block, mixed
413 with the other declarations and statements in the block.
414
415 It is possible to call the nested function from outside the scope of its
416 name by storing its address or passing the address to another function:
417
418 @smallexample
419 hack (int *array, int size)
420 @{
421   void store (int index, int value)
422     @{ array[index] = value; @}
423
424   intermediate (store, size);
425 @}
426 @end smallexample
427
428 Here, the function @code{intermediate} receives the address of
429 @code{store} as an argument.  If @code{intermediate} calls @code{store},
430 the arguments given to @code{store} are used to store into @code{array}.
431 But this technique works only so long as the containing function
432 (@code{hack}, in this example) does not exit.
433
434 If you try to call the nested function through its address after the
435 containing function has exited, all hell will break loose.  If you try
436 to call it after a containing scope level has exited, and if it refers
437 to some of the variables that are no longer in scope, you may be lucky,
438 but it's not wise to take the risk.  If, however, the nested function
439 does not refer to anything that has gone out of scope, you should be
440 safe.
441
442 GCC implements taking the address of a nested function using a technique
443 called @dfn{trampolines}.  A paper describing them is available as
444
445 @noindent
446 @uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}.
447
448 A nested function can jump to a label inherited from a containing
449 function, provided the label was explicitly declared in the containing
450 function (@pxref{Local Labels}).  Such a jump returns instantly to the
451 containing function, exiting the nested function which did the
452 @code{goto} and any intermediate functions as well.  Here is an example:
453
454 @smallexample
455 @group
456 bar (int *array, int offset, int size)
457 @{
458   __label__ failure;
459   int access (int *array, int index)
460     @{
461       if (index > size)
462         goto failure;
463       return array[index + offset];
464     @}
465   int i;
466   /* @r{@dots{}} */
467   for (i = 0; i < size; i++)
468     /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
469   /* @r{@dots{}} */
470   return 0;
471
472  /* @r{Control comes here from @code{access}
473     if it detects an error.}  */
474  failure:
475   return -1;
476 @}
477 @end group
478 @end smallexample
479
480 A nested function always has no linkage.  Declaring one with
481 @code{extern} or @code{static} is erroneous.  If you need to declare the nested function
482 before its definition, use @code{auto} (which is otherwise meaningless
483 for function declarations).
484
485 @smallexample
486 bar (int *array, int offset, int size)
487 @{
488   __label__ failure;
489   auto int access (int *, int);
490   /* @r{@dots{}} */
491   int access (int *array, int index)
492     @{
493       if (index > size)
494         goto failure;
495       return array[index + offset];
496     @}
497   /* @r{@dots{}} */
498 @}
499 @end smallexample
500
501 @node Constructing Calls
502 @section Constructing Function Calls
503 @cindex constructing calls
504 @cindex forwarding calls
505
506 Using the built-in functions described below, you can record
507 the arguments a function received, and call another function
508 with the same arguments, without knowing the number or types
509 of the arguments.
510
511 You can also record the return value of that function call,
512 and later return that value, without knowing what data type
513 the function tried to return (as long as your caller expects
514 that data type).
515
516 However, these built-in functions may interact badly with some
517 sophisticated features or other extensions of the language.  It
518 is, therefore, not recommended to use them outside very simple
519 functions acting as mere forwarders for their arguments.
520
521 @deftypefn {Built-in Function} {void *} __builtin_apply_args ()
522 This built-in function returns a pointer to data
523 describing how to perform a call with the same arguments as were passed
524 to the current function.
525
526 The function saves the arg pointer register, structure value address,
527 and all registers that might be used to pass arguments to a function
528 into a block of memory allocated on the stack.  Then it returns the
529 address of that block.
530 @end deftypefn
531
532 @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
533 This built-in function invokes @var{function}
534 with a copy of the parameters described by @var{arguments}
535 and @var{size}.
536
537 The value of @var{arguments} should be the value returned by
538 @code{__builtin_apply_args}.  The argument @var{size} specifies the size
539 of the stack argument data, in bytes.
540
541 This function returns a pointer to data describing
542 how to return whatever value was returned by @var{function}.  The data
543 is saved in a block of memory allocated on the stack.
544
545 It is not always simple to compute the proper value for @var{size}.  The
546 value is used by @code{__builtin_apply} to compute the amount of data
547 that should be pushed on the stack and copied from the incoming argument
548 area.
549 @end deftypefn
550
551 @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
552 This built-in function returns the value described by @var{result} from
553 the containing function.  You should specify, for @var{result}, a value
554 returned by @code{__builtin_apply}.
555 @end deftypefn
556
557 @node Typeof
558 @section Referring to a Type with @code{typeof}
559 @findex typeof
560 @findex sizeof
561 @cindex macros, types of arguments
562
563 Another way to refer to the type of an expression is with @code{typeof}.
564 The syntax of using of this keyword looks like @code{sizeof}, but the
565 construct acts semantically like a type name defined with @code{typedef}.
566
567 There are two ways of writing the argument to @code{typeof}: with an
568 expression or with a type.  Here is an example with an expression:
569
570 @smallexample
571 typeof (x[0](1))
572 @end smallexample
573
574 @noindent
575 This assumes that @code{x} is an array of pointers to functions;
576 the type described is that of the values of the functions.
577
578 Here is an example with a typename as the argument:
579
580 @smallexample
581 typeof (int *)
582 @end smallexample
583
584 @noindent
585 Here the type described is that of pointers to @code{int}.
586
587 If you are writing a header file that must work when included in ISO C
588 programs, write @code{__typeof__} instead of @code{typeof}.
589 @xref{Alternate Keywords}.
590
591 A @code{typeof}-construct can be used anywhere a typedef name could be
592 used.  For example, you can use it in a declaration, in a cast, or inside
593 of @code{sizeof} or @code{typeof}.
594
595 @code{typeof} is often useful in conjunction with the
596 statements-within-expressions feature.  Here is how the two together can
597 be used to define a safe ``maximum'' macro that operates on any
598 arithmetic type and evaluates each of its arguments exactly once:
599
600 @smallexample
601 #define max(a,b) \
602   (@{ typeof (a) _a = (a); \
603       typeof (b) _b = (b); \
604     _a > _b ? _a : _b; @})
605 @end smallexample
606
607 @cindex underscores in variables in macros
608 @cindex @samp{_} in variables in macros
609 @cindex local variables in macros
610 @cindex variables, local, in macros
611 @cindex macros, local variables in
612
613 The reason for using names that start with underscores for the local
614 variables is to avoid conflicts with variable names that occur within the
615 expressions that are substituted for @code{a} and @code{b}.  Eventually we
616 hope to design a new form of declaration syntax that allows you to declare
617 variables whose scopes start only after their initializers; this will be a
618 more reliable way to prevent such conflicts.
619
620 @noindent
621 Some more examples of the use of @code{typeof}:
622
623 @itemize @bullet
624 @item
625 This declares @code{y} with the type of what @code{x} points to.
626
627 @smallexample
628 typeof (*x) y;
629 @end smallexample
630
631 @item
632 This declares @code{y} as an array of such values.
633
634 @smallexample
635 typeof (*x) y[4];
636 @end smallexample
637
638 @item
639 This declares @code{y} as an array of pointers to characters:
640
641 @smallexample
642 typeof (typeof (char *)[4]) y;
643 @end smallexample
644
645 @noindent
646 It is equivalent to the following traditional C declaration:
647
648 @smallexample
649 char *y[4];
650 @end smallexample
651
652 To see the meaning of the declaration using @code{typeof}, and why it
653 might be a useful way to write, rewrite it with these macros:
654
655 @smallexample
656 #define pointer(T)  typeof(T *)
657 #define array(T, N) typeof(T [N])
658 @end smallexample
659
660 @noindent
661 Now the declaration can be rewritten this way:
662
663 @smallexample
664 array (pointer (char), 4) y;
665 @end smallexample
666
667 @noindent
668 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
669 pointers to @code{char}.
670 @end itemize
671
672 @emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported
673 a more limited extension which permitted one to write
674
675 @smallexample
676 typedef @var{T} = @var{expr};
677 @end smallexample
678
679 @noindent
680 with the effect of declaring @var{T} to have the type of the expression
681 @var{expr}.  This extension does not work with GCC 3 (versions between
682 3.0 and 3.2 will crash; 3.2.1 and later give an error).  Code which
683 relies on it should be rewritten to use @code{typeof}:
684
685 @smallexample
686 typedef typeof(@var{expr}) @var{T};
687 @end smallexample
688
689 @noindent
690 This will work with all versions of GCC@.
691
692 @node Conditionals
693 @section Conditionals with Omitted Operands
694 @cindex conditional expressions, extensions
695 @cindex omitted middle-operands
696 @cindex middle-operands, omitted
697 @cindex extensions, @code{?:}
698 @cindex @code{?:} extensions
699
700 The middle operand in a conditional expression may be omitted.  Then
701 if the first operand is nonzero, its value is the value of the conditional
702 expression.
703
704 Therefore, the expression
705
706 @smallexample
707 x ? : y
708 @end smallexample
709
710 @noindent
711 has the value of @code{x} if that is nonzero; otherwise, the value of
712 @code{y}.
713
714 This example is perfectly equivalent to
715
716 @smallexample
717 x ? x : y
718 @end smallexample
719
720 @cindex side effect in ?:
721 @cindex ?: side effect
722 @noindent
723 In this simple case, the ability to omit the middle operand is not
724 especially useful.  When it becomes useful is when the first operand does,
725 or may (if it is a macro argument), contain a side effect.  Then repeating
726 the operand in the middle would perform the side effect twice.  Omitting
727 the middle operand uses the value already computed without the undesirable
728 effects of recomputing it.
729
730 @node Long Long
731 @section Double-Word Integers
732 @cindex @code{long long} data types
733 @cindex double-word arithmetic
734 @cindex multiprecision arithmetic
735 @cindex @code{LL} integer suffix
736 @cindex @code{ULL} integer suffix
737
738 ISO C99 supports data types for integers that are at least 64 bits wide,
739 and as an extension GCC supports them in C89 mode and in C++.
740 Simply write @code{long long int} for a signed integer, or
741 @code{unsigned long long int} for an unsigned integer.  To make an
742 integer constant of type @code{long long int}, add the suffix @samp{LL}
743 to the integer.  To make an integer constant of type @code{unsigned long
744 long int}, add the suffix @samp{ULL} to the integer.
745
746 You can use these types in arithmetic like any other integer types.
747 Addition, subtraction, and bitwise boolean operations on these types
748 are open-coded on all types of machines.  Multiplication is open-coded
749 if the machine supports fullword-to-doubleword a widening multiply
750 instruction.  Division and shifts are open-coded only on machines that
751 provide special support.  The operations that are not open-coded use
752 special library routines that come with GCC@.
753
754 There may be pitfalls when you use @code{long long} types for function
755 arguments, unless you declare function prototypes.  If a function
756 expects type @code{int} for its argument, and you pass a value of type
757 @code{long long int}, confusion will result because the caller and the
758 subroutine will disagree about the number of bytes for the argument.
759 Likewise, if the function expects @code{long long int} and you pass
760 @code{int}.  The best way to avoid such problems is to use prototypes.
761
762 @node Complex
763 @section Complex Numbers
764 @cindex complex numbers
765 @cindex @code{_Complex} keyword
766 @cindex @code{__complex__} keyword
767
768 ISO C99 supports complex floating data types, and as an extension GCC
769 supports them in C89 mode and in C++, and supports complex integer data
770 types which are not part of ISO C99.  You can declare complex types
771 using the keyword @code{_Complex}.  As an extension, the older GNU
772 keyword @code{__complex__} is also supported.
773
774 For example, @samp{_Complex double x;} declares @code{x} as a
775 variable whose real part and imaginary part are both of type
776 @code{double}.  @samp{_Complex short int y;} declares @code{y} to
777 have real and imaginary parts of type @code{short int}; this is not
778 likely to be useful, but it shows that the set of complex types is
779 complete.
780
781 To write a constant with a complex data type, use the suffix @samp{i} or
782 @samp{j} (either one; they are equivalent).  For example, @code{2.5fi}
783 has type @code{_Complex float} and @code{3i} has type
784 @code{_Complex int}.  Such a constant always has a pure imaginary
785 value, but you can form any complex value you like by adding one to a
786 real constant.  This is a GNU extension; if you have an ISO C99
787 conforming C library (such as GNU libc), and want to construct complex
788 constants of floating type, you should include @code{<complex.h>} and
789 use the macros @code{I} or @code{_Complex_I} instead.
790
791 @cindex @code{__real__} keyword
792 @cindex @code{__imag__} keyword
793 To extract the real part of a complex-valued expression @var{exp}, write
794 @code{__real__ @var{exp}}.  Likewise, use @code{__imag__} to
795 extract the imaginary part.  This is a GNU extension; for values of
796 floating type, you should use the ISO C99 functions @code{crealf},
797 @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
798 @code{cimagl}, declared in @code{<complex.h>} and also provided as
799 built-in functions by GCC@.
800
801 @cindex complex conjugation
802 The operator @samp{~} performs complex conjugation when used on a value
803 with a complex type.  This is a GNU extension; for values of
804 floating type, you should use the ISO C99 functions @code{conjf},
805 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
806 provided as built-in functions by GCC@.
807
808 GCC can allocate complex automatic variables in a noncontiguous
809 fashion; it's even possible for the real part to be in a register while
810 the imaginary part is on the stack (or vice-versa).  Only the DWARF2
811 debug info format can represent this, so use of DWARF2 is recommended.
812 If you are using the stabs debug info format, GCC describes a noncontiguous
813 complex variable as if it were two separate variables of noncomplex type.
814 If the variable's actual name is @code{foo}, the two fictitious
815 variables are named @code{foo$real} and @code{foo$imag}.  You can
816 examine and set these two fictitious variables with your debugger.
817
818 @node Decimal Float
819 @section Decimal Floating Point
820 @cindex decimal floating point
821 @cindex @code{_Decimal32} data type
822 @cindex @code{_Decimal64} data type
823 @cindex @code{_Decimal128} data type
824 @cindex @code{df} integer suffix
825 @cindex @code{dd} integer suffix
826 @cindex @code{dl} integer suffix
827 @cindex @code{DF} integer suffix
828 @cindex @code{DD} integer suffix
829 @cindex @code{DL} integer suffix
830
831 GNU C supports decimal floating point types in addition to the
832 standard floating-point types.  This extension supports decimal
833 floating-point arithmetic as defined in IEEE-754R, the proposed
834 revision of IEEE-754.  The C language extension is defined in ISO/IEC
835 DTR 24732, Draft 5.  Support for this functionality will change when
836 it is accepted into the C standard and might change for new drafts
837 of the proposal.  Calling conventions for any target might also change.
838 Not all targets support decimal floating point.
839
840 Support for decimal floating point includes the arithmetic operators
841 add, subtract, multiply, divide; unary arithmetic operators;
842 relational operators; equality operators; and conversions to and from
843 integer and other floating-point types.  Use a suffix @samp{df} or
844 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
845 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
846 @code{_Decimal128}.
847
848 Passing a decimal floating-point value as an argument to a function
849 without a prototype is undefined.
850
851 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
852 are supported by the DWARF2 debug information format.
853
854 @node Hex Floats
855 @section Hex Floats
856 @cindex hex floats
857
858 ISO C99 supports floating-point numbers written not only in the usual
859 decimal notation, such as @code{1.55e1}, but also numbers such as
860 @code{0x1.fp3} written in hexadecimal format.  As a GNU extension, GCC
861 supports this in C89 mode (except in some cases when strictly
862 conforming) and in C++.  In that format the
863 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
864 mandatory.  The exponent is a decimal number that indicates the power of
865 2 by which the significant part will be multiplied.  Thus @samp{0x1.f} is
866 @tex
867 $1 {15\over16}$,
868 @end tex
869 @ifnottex
870 1 15/16,
871 @end ifnottex
872 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
873 is the same as @code{1.55e1}.
874
875 Unlike for floating-point numbers in the decimal notation the exponent
876 is always required in the hexadecimal notation.  Otherwise the compiler
877 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}.  This
878 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
879 extension for floating-point constants of type @code{float}.
880
881 @node Zero Length
882 @section Arrays of Length Zero
883 @cindex arrays of length zero
884 @cindex zero-length arrays
885 @cindex length-zero arrays
886 @cindex flexible array members
887
888 Zero-length arrays are allowed in GNU C@.  They are very useful as the
889 last element of a structure which is really a header for a variable-length
890 object:
891
892 @smallexample
893 struct line @{
894   int length;
895   char contents[0];
896 @};
897
898 struct line *thisline = (struct line *)
899   malloc (sizeof (struct line) + this_length);
900 thisline->length = this_length;
901 @end smallexample
902
903 In ISO C90, you would have to give @code{contents} a length of 1, which
904 means either you waste space or complicate the argument to @code{malloc}.
905
906 In ISO C99, you would use a @dfn{flexible array member}, which is
907 slightly different in syntax and semantics:
908
909 @itemize @bullet
910 @item
911 Flexible array members are written as @code{contents[]} without
912 the @code{0}.
913
914 @item
915 Flexible array members have incomplete type, and so the @code{sizeof}
916 operator may not be applied.  As a quirk of the original implementation
917 of zero-length arrays, @code{sizeof} evaluates to zero.
918
919 @item
920 Flexible array members may only appear as the last member of a
921 @code{struct} that is otherwise non-empty.
922
923 @item
924 A structure containing a flexible array member, or a union containing
925 such a structure (possibly recursively), may not be a member of a
926 structure or an element of an array.  (However, these uses are
927 permitted by GCC as extensions.)
928 @end itemize
929
930 GCC versions before 3.0 allowed zero-length arrays to be statically
931 initialized, as if they were flexible arrays.  In addition to those
932 cases that were useful, it also allowed initializations in situations
933 that would corrupt later data.  Non-empty initialization of zero-length
934 arrays is now treated like any case where there are more initializer
935 elements than the array holds, in that a suitable warning about "excess
936 elements in array" is given, and the excess elements (all of them, in
937 this case) are ignored.
938
939 Instead GCC allows static initialization of flexible array members.
940 This is equivalent to defining a new structure containing the original
941 structure followed by an array of sufficient size to contain the data.
942 I.e.@: in the following, @code{f1} is constructed as if it were declared
943 like @code{f2}.
944
945 @smallexample
946 struct f1 @{
947   int x; int y[];
948 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
949
950 struct f2 @{
951   struct f1 f1; int data[3];
952 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
953 @end smallexample
954
955 @noindent
956 The convenience of this extension is that @code{f1} has the desired
957 type, eliminating the need to consistently refer to @code{f2.f1}.
958
959 This has symmetry with normal static arrays, in that an array of
960 unknown size is also written with @code{[]}.
961
962 Of course, this extension only makes sense if the extra data comes at
963 the end of a top-level object, as otherwise we would be overwriting
964 data at subsequent offsets.  To avoid undue complication and confusion
965 with initialization of deeply nested arrays, we simply disallow any
966 non-empty initialization except when the structure is the top-level
967 object.  For example:
968
969 @smallexample
970 struct foo @{ int x; int y[]; @};
971 struct bar @{ struct foo z; @};
972
973 struct foo a = @{ 1, @{ 2, 3, 4 @} @};        // @r{Valid.}
974 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @};    // @r{Invalid.}
975 struct bar c = @{ @{ 1, @{ @} @} @};            // @r{Valid.}
976 struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @};  // @r{Invalid.}
977 @end smallexample
978
979 @node Empty Structures
980 @section Structures With No Members
981 @cindex empty structures
982 @cindex zero-size structures
983
984 GCC permits a C structure to have no members:
985
986 @smallexample
987 struct empty @{
988 @};
989 @end smallexample
990
991 The structure will have size zero.  In C++, empty structures are part
992 of the language.  G++ treats empty structures as if they had a single
993 member of type @code{char}.
994
995 @node Variable Length
996 @section Arrays of Variable Length
997 @cindex variable-length arrays
998 @cindex arrays of variable length
999 @cindex VLAs
1000
1001 Variable-length automatic arrays are allowed in ISO C99, and as an
1002 extension GCC accepts them in C89 mode and in C++.  (However, GCC's
1003 implementation of variable-length arrays does not yet conform in detail
1004 to the ISO C99 standard.)  These arrays are
1005 declared like any other automatic arrays, but with a length that is not
1006 a constant expression.  The storage is allocated at the point of
1007 declaration and deallocated when the brace-level is exited.  For
1008 example:
1009
1010 @smallexample
1011 FILE *
1012 concat_fopen (char *s1, char *s2, char *mode)
1013 @{
1014   char str[strlen (s1) + strlen (s2) + 1];
1015   strcpy (str, s1);
1016   strcat (str, s2);
1017   return fopen (str, mode);
1018 @}
1019 @end smallexample
1020
1021 @cindex scope of a variable length array
1022 @cindex variable-length array scope
1023 @cindex deallocating variable length arrays
1024 Jumping or breaking out of the scope of the array name deallocates the
1025 storage.  Jumping into the scope is not allowed; you get an error
1026 message for it.
1027
1028 @cindex @code{alloca} vs variable-length arrays
1029 You can use the function @code{alloca} to get an effect much like
1030 variable-length arrays.  The function @code{alloca} is available in
1031 many other C implementations (but not in all).  On the other hand,
1032 variable-length arrays are more elegant.
1033
1034 There are other differences between these two methods.  Space allocated
1035 with @code{alloca} exists until the containing @emph{function} returns.
1036 The space for a variable-length array is deallocated as soon as the array
1037 name's scope ends.  (If you use both variable-length arrays and
1038 @code{alloca} in the same function, deallocation of a variable-length array
1039 will also deallocate anything more recently allocated with @code{alloca}.)
1040
1041 You can also use variable-length arrays as arguments to functions:
1042
1043 @smallexample
1044 struct entry
1045 tester (int len, char data[len][len])
1046 @{
1047   /* @r{@dots{}} */
1048 @}
1049 @end smallexample
1050
1051 The length of an array is computed once when the storage is allocated
1052 and is remembered for the scope of the array in case you access it with
1053 @code{sizeof}.
1054
1055 If you want to pass the array first and the length afterward, you can
1056 use a forward declaration in the parameter list---another GNU extension.
1057
1058 @smallexample
1059 struct entry
1060 tester (int len; char data[len][len], int len)
1061 @{
1062   /* @r{@dots{}} */
1063 @}
1064 @end smallexample
1065
1066 @cindex parameter forward declaration
1067 The @samp{int len} before the semicolon is a @dfn{parameter forward
1068 declaration}, and it serves the purpose of making the name @code{len}
1069 known when the declaration of @code{data} is parsed.
1070
1071 You can write any number of such parameter forward declarations in the
1072 parameter list.  They can be separated by commas or semicolons, but the
1073 last one must end with a semicolon, which is followed by the ``real''
1074 parameter declarations.  Each forward declaration must match a ``real''
1075 declaration in parameter name and data type.  ISO C99 does not support
1076 parameter forward declarations.
1077
1078 @node Variadic Macros
1079 @section Macros with a Variable Number of Arguments.
1080 @cindex variable number of arguments
1081 @cindex macro with variable arguments
1082 @cindex rest argument (in macro)
1083 @cindex variadic macros
1084
1085 In the ISO C standard of 1999, a macro can be declared to accept a
1086 variable number of arguments much as a function can.  The syntax for
1087 defining the macro is similar to that of a function.  Here is an
1088 example:
1089
1090 @smallexample
1091 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1092 @end smallexample
1093
1094 Here @samp{@dots{}} is a @dfn{variable argument}.  In the invocation of
1095 such a macro, it represents the zero or more tokens until the closing
1096 parenthesis that ends the invocation, including any commas.  This set of
1097 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1098 wherever it appears.  See the CPP manual for more information.
1099
1100 GCC has long supported variadic macros, and used a different syntax that
1101 allowed you to give a name to the variable arguments just like any other
1102 argument.  Here is an example:
1103
1104 @smallexample
1105 #define debug(format, args...) fprintf (stderr, format, args)
1106 @end smallexample
1107
1108 This is in all ways equivalent to the ISO C example above, but arguably
1109 more readable and descriptive.
1110
1111 GNU CPP has two further variadic macro extensions, and permits them to
1112 be used with either of the above forms of macro definition.
1113
1114 In standard C, you are not allowed to leave the variable argument out
1115 entirely; but you are allowed to pass an empty argument.  For example,
1116 this invocation is invalid in ISO C, because there is no comma after
1117 the string:
1118
1119 @smallexample
1120 debug ("A message")
1121 @end smallexample
1122
1123 GNU CPP permits you to completely omit the variable arguments in this
1124 way.  In the above examples, the compiler would complain, though since
1125 the expansion of the macro still has the extra comma after the format
1126 string.
1127
1128 To help solve this problem, CPP behaves specially for variable arguments
1129 used with the token paste operator, @samp{##}.  If instead you write
1130
1131 @smallexample
1132 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1133 @end smallexample
1134
1135 and if the variable arguments are omitted or empty, the @samp{##}
1136 operator causes the preprocessor to remove the comma before it.  If you
1137 do provide some variable arguments in your macro invocation, GNU CPP
1138 does not complain about the paste operation and instead places the
1139 variable arguments after the comma.  Just like any other pasted macro
1140 argument, these arguments are not macro expanded.
1141
1142 @node Escaped Newlines
1143 @section Slightly Looser Rules for Escaped Newlines
1144 @cindex escaped newlines
1145 @cindex newlines (escaped)
1146
1147 Recently, the preprocessor has relaxed its treatment of escaped
1148 newlines.  Previously, the newline had to immediately follow a
1149 backslash.  The current implementation allows whitespace in the form
1150 of spaces, horizontal and vertical tabs, and form feeds between the
1151 backslash and the subsequent newline.  The preprocessor issues a
1152 warning, but treats it as a valid escaped newline and combines the two
1153 lines to form a single logical line.  This works within comments and
1154 tokens, as well as between tokens.  Comments are @emph{not} treated as
1155 whitespace for the purposes of this relaxation, since they have not
1156 yet been replaced with spaces.
1157
1158 @node Subscripting
1159 @section Non-Lvalue Arrays May Have Subscripts
1160 @cindex subscripting
1161 @cindex arrays, non-lvalue
1162
1163 @cindex subscripting and function values
1164 In ISO C99, arrays that are not lvalues still decay to pointers, and
1165 may be subscripted, although they may not be modified or used after
1166 the next sequence point and the unary @samp{&} operator may not be
1167 applied to them.  As an extension, GCC allows such arrays to be
1168 subscripted in C89 mode, though otherwise they do not decay to
1169 pointers outside C99 mode.  For example,
1170 this is valid in GNU C though not valid in C89:
1171
1172 @smallexample
1173 @group
1174 struct foo @{int a[4];@};
1175
1176 struct foo f();
1177
1178 bar (int index)
1179 @{
1180   return f().a[index];
1181 @}
1182 @end group
1183 @end smallexample
1184
1185 @node Pointer Arith
1186 @section Arithmetic on @code{void}- and Function-Pointers
1187 @cindex void pointers, arithmetic
1188 @cindex void, size of pointer to
1189 @cindex function pointers, arithmetic
1190 @cindex function, size of pointer to
1191
1192 In GNU C, addition and subtraction operations are supported on pointers to
1193 @code{void} and on pointers to functions.  This is done by treating the
1194 size of a @code{void} or of a function as 1.
1195
1196 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1197 and on function types, and returns 1.
1198
1199 @opindex Wpointer-arith
1200 The option @option{-Wpointer-arith} requests a warning if these extensions
1201 are used.
1202
1203 @node Initializers
1204 @section Non-Constant Initializers
1205 @cindex initializers, non-constant
1206 @cindex non-constant initializers
1207
1208 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1209 automatic variable are not required to be constant expressions in GNU C@.
1210 Here is an example of an initializer with run-time varying elements:
1211
1212 @smallexample
1213 foo (float f, float g)
1214 @{
1215   float beat_freqs[2] = @{ f-g, f+g @};
1216   /* @r{@dots{}} */
1217 @}
1218 @end smallexample
1219
1220 @node Compound Literals
1221 @section Compound Literals
1222 @cindex constructor expressions
1223 @cindex initializations in expressions
1224 @cindex structures, constructor expression
1225 @cindex expressions, constructor
1226 @cindex compound literals
1227 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
1228
1229 ISO C99 supports compound literals.  A compound literal looks like
1230 a cast containing an initializer.  Its value is an object of the
1231 type specified in the cast, containing the elements specified in
1232 the initializer; it is an lvalue.  As an extension, GCC supports
1233 compound literals in C89 mode and in C++.
1234
1235 Usually, the specified type is a structure.  Assume that
1236 @code{struct foo} and @code{structure} are declared as shown:
1237
1238 @smallexample
1239 struct foo @{int a; char b[2];@} structure;
1240 @end smallexample
1241
1242 @noindent
1243 Here is an example of constructing a @code{struct foo} with a compound literal:
1244
1245 @smallexample
1246 structure = ((struct foo) @{x + y, 'a', 0@});
1247 @end smallexample
1248
1249 @noindent
1250 This is equivalent to writing the following:
1251
1252 @smallexample
1253 @{
1254   struct foo temp = @{x + y, 'a', 0@};
1255   structure = temp;
1256 @}
1257 @end smallexample
1258
1259 You can also construct an array.  If all the elements of the compound literal
1260 are (made up of) simple constant expressions, suitable for use in
1261 initializers of objects of static storage duration, then the compound
1262 literal can be coerced to a pointer to its first element and used in
1263 such an initializer, as shown here:
1264
1265 @smallexample
1266 char **foo = (char *[]) @{ "x", "y", "z" @};
1267 @end smallexample
1268
1269 Compound literals for scalar types and union types are is
1270 also allowed, but then the compound literal is equivalent
1271 to a cast.
1272
1273 As a GNU extension, GCC allows initialization of objects with static storage
1274 duration by compound literals (which is not possible in ISO C99, because
1275 the initializer is not a constant).
1276 It is handled as if the object was initialized only with the bracket
1277 enclosed list if compound literal's and object types match.
1278 The initializer list of the compound literal must be constant.
1279 If the object being initialized has array type of unknown size, the size is
1280 determined by compound literal size.
1281
1282 @smallexample
1283 static struct foo x = (struct foo) @{1, 'a', 'b'@};
1284 static int y[] = (int []) @{1, 2, 3@};
1285 static int z[] = (int [3]) @{1@};
1286 @end smallexample
1287
1288 @noindent
1289 The above lines are equivalent to the following:
1290 @smallexample
1291 static struct foo x = @{1, 'a', 'b'@};
1292 static int y[] = @{1, 2, 3@};
1293 static int z[] = @{1, 0, 0@};
1294 @end smallexample
1295
1296 @node Designated Inits
1297 @section Designated Initializers
1298 @cindex initializers with labeled elements
1299 @cindex labeled elements in initializers
1300 @cindex case labels in initializers
1301 @cindex designated initializers
1302
1303 Standard C89 requires the elements of an initializer to appear in a fixed
1304 order, the same as the order of the elements in the array or structure
1305 being initialized.
1306
1307 In ISO C99 you can give the elements in any order, specifying the array
1308 indices or structure field names they apply to, and GNU C allows this as
1309 an extension in C89 mode as well.  This extension is not
1310 implemented in GNU C++.
1311
1312 To specify an array index, write
1313 @samp{[@var{index}] =} before the element value.  For example,
1314
1315 @smallexample
1316 int a[6] = @{ [4] = 29, [2] = 15 @};
1317 @end smallexample
1318
1319 @noindent
1320 is equivalent to
1321
1322 @smallexample
1323 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
1324 @end smallexample
1325
1326 @noindent
1327 The index values must be constant expressions, even if the array being
1328 initialized is automatic.
1329
1330 An alternative syntax for this which has been obsolete since GCC 2.5 but
1331 GCC still accepts is to write @samp{[@var{index}]} before the element
1332 value, with no @samp{=}.
1333
1334 To initialize a range of elements to the same value, write
1335 @samp{[@var{first} ... @var{last}] = @var{value}}.  This is a GNU
1336 extension.  For example,
1337
1338 @smallexample
1339 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
1340 @end smallexample
1341
1342 @noindent
1343 If the value in it has side-effects, the side-effects will happen only once,
1344 not for each initialized field by the range initializer.
1345
1346 @noindent
1347 Note that the length of the array is the highest value specified
1348 plus one.
1349
1350 In a structure initializer, specify the name of a field to initialize
1351 with @samp{.@var{fieldname} =} before the element value.  For example,
1352 given the following structure,
1353
1354 @smallexample
1355 struct point @{ int x, y; @};
1356 @end smallexample
1357
1358 @noindent
1359 the following initialization
1360
1361 @smallexample
1362 struct point p = @{ .y = yvalue, .x = xvalue @};
1363 @end smallexample
1364
1365 @noindent
1366 is equivalent to
1367
1368 @smallexample
1369 struct point p = @{ xvalue, yvalue @};
1370 @end smallexample
1371
1372 Another syntax which has the same meaning, obsolete since GCC 2.5, is
1373 @samp{@var{fieldname}:}, as shown here:
1374
1375 @smallexample
1376 struct point p = @{ y: yvalue, x: xvalue @};
1377 @end smallexample
1378
1379 @cindex designators
1380 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
1381 @dfn{designator}.  You can also use a designator (or the obsolete colon
1382 syntax) when initializing a union, to specify which element of the union
1383 should be used.  For example,
1384
1385 @smallexample
1386 union foo @{ int i; double d; @};
1387
1388 union foo f = @{ .d = 4 @};
1389 @end smallexample
1390
1391 @noindent
1392 will convert 4 to a @code{double} to store it in the union using
1393 the second element.  By contrast, casting 4 to type @code{union foo}
1394 would store it into the union as the integer @code{i}, since it is
1395 an integer.  (@xref{Cast to Union}.)
1396
1397 You can combine this technique of naming elements with ordinary C
1398 initialization of successive elements.  Each initializer element that
1399 does not have a designator applies to the next consecutive element of the
1400 array or structure.  For example,
1401
1402 @smallexample
1403 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
1404 @end smallexample
1405
1406 @noindent
1407 is equivalent to
1408
1409 @smallexample
1410 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
1411 @end smallexample
1412
1413 Labeling the elements of an array initializer is especially useful
1414 when the indices are characters or belong to an @code{enum} type.
1415 For example:
1416
1417 @smallexample
1418 int whitespace[256]
1419   = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
1420       ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
1421 @end smallexample
1422
1423 @cindex designator lists
1424 You can also write a series of @samp{.@var{fieldname}} and
1425 @samp{[@var{index}]} designators before an @samp{=} to specify a
1426 nested subobject to initialize; the list is taken relative to the
1427 subobject corresponding to the closest surrounding brace pair.  For
1428 example, with the @samp{struct point} declaration above:
1429
1430 @smallexample
1431 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
1432 @end smallexample
1433
1434 @noindent
1435 If the same field is initialized multiple times, it will have value from
1436 the last initialization.  If any such overridden initialization has
1437 side-effect, it is unspecified whether the side-effect happens or not.
1438 Currently, GCC will discard them and issue a warning.
1439
1440 @node Case Ranges
1441 @section Case Ranges
1442 @cindex case ranges
1443 @cindex ranges in case statements
1444
1445 You can specify a range of consecutive values in a single @code{case} label,
1446 like this:
1447
1448 @smallexample
1449 case @var{low} ... @var{high}:
1450 @end smallexample
1451
1452 @noindent
1453 This has the same effect as the proper number of individual @code{case}
1454 labels, one for each integer value from @var{low} to @var{high}, inclusive.
1455
1456 This feature is especially useful for ranges of ASCII character codes:
1457
1458 @smallexample
1459 case 'A' ... 'Z':
1460 @end smallexample
1461
1462 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
1463 it may be parsed wrong when you use it with integer values.  For example,
1464 write this:
1465
1466 @smallexample
1467 case 1 ... 5:
1468 @end smallexample
1469
1470 @noindent
1471 rather than this:
1472
1473 @smallexample
1474 case 1...5:
1475 @end smallexample
1476
1477 @node Cast to Union
1478 @section Cast to a Union Type
1479 @cindex cast to a union
1480 @cindex union, casting to a
1481
1482 A cast to union type is similar to other casts, except that the type
1483 specified is a union type.  You can specify the type either with
1484 @code{union @var{tag}} or with a typedef name.  A cast to union is actually
1485 a constructor though, not a cast, and hence does not yield an lvalue like
1486 normal casts.  (@xref{Compound Literals}.)
1487
1488 The types that may be cast to the union type are those of the members
1489 of the union.  Thus, given the following union and variables:
1490
1491 @smallexample
1492 union foo @{ int i; double d; @};
1493 int x;
1494 double y;
1495 @end smallexample
1496
1497 @noindent
1498 both @code{x} and @code{y} can be cast to type @code{union foo}.
1499
1500 Using the cast as the right-hand side of an assignment to a variable of
1501 union type is equivalent to storing in a member of the union:
1502
1503 @smallexample
1504 union foo u;
1505 /* @r{@dots{}} */
1506 u = (union foo) x  @equiv{}  u.i = x
1507 u = (union foo) y  @equiv{}  u.d = y
1508 @end smallexample
1509
1510 You can also use the union cast as a function argument:
1511
1512 @smallexample
1513 void hack (union foo);
1514 /* @r{@dots{}} */
1515 hack ((union foo) x);
1516 @end smallexample
1517
1518 @node Mixed Declarations
1519 @section Mixed Declarations and Code
1520 @cindex mixed declarations and code
1521 @cindex declarations, mixed with code
1522 @cindex code, mixed with declarations
1523
1524 ISO C99 and ISO C++ allow declarations and code to be freely mixed
1525 within compound statements.  As an extension, GCC also allows this in
1526 C89 mode.  For example, you could do:
1527
1528 @smallexample
1529 int i;
1530 /* @r{@dots{}} */
1531 i++;
1532 int j = i + 2;
1533 @end smallexample
1534
1535 Each identifier is visible from where it is declared until the end of
1536 the enclosing block.
1537
1538 @node Function Attributes
1539 @section Declaring Attributes of Functions
1540 @cindex function attributes
1541 @cindex declaring attributes of functions
1542 @cindex functions that never return
1543 @cindex functions that return more than once
1544 @cindex functions that have no side effects
1545 @cindex functions in arbitrary sections
1546 @cindex functions that behave like malloc
1547 @cindex @code{volatile} applied to function
1548 @cindex @code{const} applied to function
1549 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
1550 @cindex functions with non-null pointer arguments
1551 @cindex functions that are passed arguments in registers on the 386
1552 @cindex functions that pop the argument stack on the 386
1553 @cindex functions that do not pop the argument stack on the 386
1554
1555 In GNU C, you declare certain things about functions called in your program
1556 which help the compiler optimize function calls and check your code more
1557 carefully.
1558
1559 The keyword @code{__attribute__} allows you to specify special
1560 attributes when making a declaration.  This keyword is followed by an
1561 attribute specification inside double parentheses.  The following
1562 attributes are currently defined for functions on all targets:
1563 @code{noreturn}, @code{returns_twice}, @code{noinline}, @code{always_inline},
1564 @code{flatten}, @code{pure}, @code{const}, @code{nothrow}, @code{sentinel},
1565 @code{format}, @code{format_arg}, @code{no_instrument_function},
1566 @code{section}, @code{constructor}, @code{destructor}, @code{used},
1567 @code{unused}, @code{deprecated}, @code{weak}, @code{malloc},
1568 @code{alias}, @code{warn_unused_result}, @code{nonnull}
1569 and @code{externally_visible}.  Several other
1570 attributes are defined for functions on particular target systems.  Other
1571 attributes, including @code{section} are supported for variables declarations
1572 (@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}).
1573
1574 You may also specify attributes with @samp{__} preceding and following
1575 each keyword.  This allows you to use them in header files without
1576 being concerned about a possible macro of the same name.  For example,
1577 you may use @code{__noreturn__} instead of @code{noreturn}.
1578
1579 @xref{Attribute Syntax}, for details of the exact syntax for using
1580 attributes.
1581
1582 @table @code
1583 @c Keep this table alphabetized by attribute name.  Treat _ as space.
1584
1585 @item alias ("@var{target}")
1586 @cindex @code{alias} attribute
1587 The @code{alias} attribute causes the declaration to be emitted as an
1588 alias for another symbol, which must be specified.  For instance,
1589
1590 @smallexample
1591 void __f () @{ /* @r{Do something.} */; @}
1592 void f () __attribute__ ((weak, alias ("__f")));
1593 @end smallexample
1594
1595 defines @samp{f} to be a weak alias for @samp{__f}.  In C++, the
1596 mangled name for the target must be used.  It is an error if @samp{__f}
1597 is not defined in the same translation unit.
1598
1599 Not all target machines support this attribute.
1600
1601 @item always_inline
1602 @cindex @code{always_inline} function attribute
1603 Generally, functions are not inlined unless optimization is specified.
1604 For functions declared inline, this attribute inlines the function even
1605 if no optimization level was specified.
1606
1607 @cindex @code{flatten} function attribute
1608 @item flatten
1609 Generally, inlining into a function is limited.  For a function marked with
1610 this attribute, every call inside this function will be inlined, if possible.
1611 Whether the function itself is considered for inlining depends on its size and
1612 the current inlining parameters.  The @code{flatten} attribute only works
1613 reliably in unit-at-a-time mode.
1614
1615 @item cdecl
1616 @cindex functions that do pop the argument stack on the 386
1617 @opindex mrtd
1618 On the Intel 386, the @code{cdecl} attribute causes the compiler to
1619 assume that the calling function will pop off the stack space used to
1620 pass arguments.  This is
1621 useful to override the effects of the @option{-mrtd} switch.
1622
1623 @item const
1624 @cindex @code{const} function attribute
1625 Many functions do not examine any values except their arguments, and
1626 have no effects except the return value.  Basically this is just slightly
1627 more strict class than the @code{pure} attribute below, since function is not
1628 allowed to read global memory.
1629
1630 @cindex pointer arguments
1631 Note that a function that has pointer arguments and examines the data
1632 pointed to must @emph{not} be declared @code{const}.  Likewise, a
1633 function that calls a non-@code{const} function usually must not be
1634 @code{const}.  It does not make sense for a @code{const} function to
1635 return @code{void}.
1636
1637 The attribute @code{const} is not implemented in GCC versions earlier
1638 than 2.5.  An alternative way to declare that a function has no side
1639 effects, which works in the current version and in some older versions,
1640 is as follows:
1641
1642 @smallexample
1643 typedef int intfn ();
1644
1645 extern const intfn square;
1646 @end smallexample
1647
1648 This approach does not work in GNU C++ from 2.6.0 on, since the language
1649 specifies that the @samp{const} must be attached to the return value.
1650
1651 @item constructor
1652 @itemx destructor
1653 @cindex @code{constructor} function attribute
1654 @cindex @code{destructor} function attribute
1655 The @code{constructor} attribute causes the function to be called
1656 automatically before execution enters @code{main ()}.  Similarly, the
1657 @code{destructor} attribute causes the function to be called
1658 automatically after @code{main ()} has completed or @code{exit ()} has
1659 been called.  Functions with these attributes are useful for
1660 initializing data that will be used implicitly during the execution of
1661 the program.
1662
1663 These attributes are not currently implemented for Objective-C@.
1664
1665 @item deprecated
1666 @cindex @code{deprecated} attribute.
1667 The @code{deprecated} attribute results in a warning if the function
1668 is used anywhere in the source file.  This is useful when identifying
1669 functions that are expected to be removed in a future version of a
1670 program.  The warning also includes the location of the declaration
1671 of the deprecated function, to enable users to easily find further
1672 information about why the function is deprecated, or what they should
1673 do instead.  Note that the warnings only occurs for uses:
1674
1675 @smallexample
1676 int old_fn () __attribute__ ((deprecated));
1677 int old_fn ();
1678 int (*fn_ptr)() = old_fn;
1679 @end smallexample
1680
1681 results in a warning on line 3 but not line 2.
1682
1683 The @code{deprecated} attribute can also be used for variables and
1684 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
1685
1686 @item dllexport
1687 @cindex @code{__declspec(dllexport)}
1688 On Microsoft Windows targets and Symbian OS targets the
1689 @code{dllexport} attribute causes the compiler to provide a global
1690 pointer to a pointer in a DLL, so that it can be referenced with the
1691 @code{dllimport} attribute.  On Microsoft Windows targets, the pointer
1692 name is formed by combining @code{_imp__} and the function or variable
1693 name.
1694
1695 You can use @code{__declspec(dllexport)} as a synonym for
1696 @code{__attribute__ ((dllexport))} for compatibility with other
1697 compilers.
1698
1699 On systems that support the @code{visibility} attribute, this
1700 attribute also implies ``default'' visibility, unless a
1701 @code{visibility} attribute is explicitly specified.  You should avoid
1702 the use of @code{dllexport} with ``hidden'' or ``internal''
1703 visibility; in the future GCC may issue an error for those cases.
1704
1705 Currently, the @code{dllexport} attribute is ignored for inlined
1706 functions, unless the @option{-fkeep-inline-functions} flag has been
1707 used.  The attribute is also ignored for undefined symbols.
1708
1709 When applied to C++ classes, the attribute marks defined non-inlined
1710 member functions and static data members as exports.  Static consts
1711 initialized in-class are not marked unless they are also defined
1712 out-of-class.
1713
1714 For Microsoft Windows targets there are alternative methods for
1715 including the symbol in the DLL's export table such as using a
1716 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
1717 the @option{--export-all} linker flag.
1718
1719 @item dllimport
1720 @cindex @code{__declspec(dllimport)}
1721 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
1722 attribute causes the compiler to reference a function or variable via
1723 a global pointer to a pointer that is set up by the DLL exporting the
1724 symbol.  The attribute implies @code{extern} storage.  On Microsoft
1725 Windows targets, the pointer name is formed by combining @code{_imp__}
1726 and the function or variable name.
1727
1728 You can use @code{__declspec(dllimport)} as a synonym for
1729 @code{__attribute__ ((dllimport))} for compatibility with other
1730 compilers.
1731
1732 Currently, the attribute is ignored for inlined functions.  If the
1733 attribute is applied to a symbol @emph{definition}, an error is reported.
1734 If a symbol previously declared @code{dllimport} is later defined, the
1735 attribute is ignored in subsequent references, and a warning is emitted.
1736 The attribute is also overridden by a subsequent declaration as
1737 @code{dllexport}.
1738
1739 When applied to C++ classes, the attribute marks non-inlined
1740 member functions and static data members as imports.  However, the
1741 attribute is ignored for virtual methods to allow creation of vtables
1742 using thunks.
1743
1744 On the SH Symbian OS target the @code{dllimport} attribute also has
1745 another affect---it can cause the vtable and run-time type information
1746 for a class to be exported.  This happens when the class has a
1747 dllimport'ed constructor or a non-inline, non-pure virtual function
1748 and, for either of those two conditions, the class also has a inline
1749 constructor or destructor and has a key function that is defined in
1750 the current translation unit.
1751
1752 For Microsoft Windows based targets the use of the @code{dllimport}
1753 attribute on functions is not necessary, but provides a small
1754 performance benefit by eliminating a thunk in the DLL@.  The use of the
1755 @code{dllimport} attribute on imported variables was required on older
1756 versions of the GNU linker, but can now be avoided by passing the
1757 @option{--enable-auto-import} switch to the GNU linker.  As with
1758 functions, using the attribute for a variable eliminates a thunk in
1759 the DLL@.
1760
1761 One drawback to using this attribute is that a pointer to a function
1762 or variable marked as @code{dllimport} cannot be used as a constant
1763 address.  On Microsoft Windows targets, the attribute can be disabled
1764 for functions by setting the @option{-mnop-fun-dllimport} flag.
1765
1766 @item eightbit_data
1767 @cindex eight bit data on the H8/300, H8/300H, and H8S
1768 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
1769 variable should be placed into the eight bit data section.
1770 The compiler will generate more efficient code for certain operations
1771 on data in the eight bit data area.  Note the eight bit data area is limited to
1772 256 bytes of data.
1773
1774 You must use GAS and GLD from GNU binutils version 2.7 or later for
1775 this attribute to work correctly.
1776
1777 @item exception_handler
1778 @cindex exception handler functions on the Blackfin processor
1779 Use this attribute on the Blackfin to indicate that the specified function
1780 is an exception handler.  The compiler will generate function entry and
1781 exit sequences suitable for use in an exception handler when this
1782 attribute is present.
1783
1784 @item far
1785 @cindex functions which handle memory bank switching
1786 On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to
1787 use a calling convention that takes care of switching memory banks when
1788 entering and leaving a function.  This calling convention is also the
1789 default when using the @option{-mlong-calls} option.
1790
1791 On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions
1792 to call and return from a function.
1793
1794 On 68HC11 the compiler will generate a sequence of instructions
1795 to invoke a board-specific routine to switch the memory bank and call the
1796 real function.  The board-specific routine simulates a @code{call}.
1797 At the end of a function, it will jump to a board-specific routine
1798 instead of using @code{rts}.  The board-specific return routine simulates
1799 the @code{rtc}.
1800
1801 @item fastcall
1802 @cindex functions that pop the argument stack on the 386
1803 On the Intel 386, the @code{fastcall} attribute causes the compiler to
1804 pass the first argument (if of integral type) in the register ECX and
1805 the second argument (if of integral type) in the register EDX@.  Subsequent
1806 and other typed arguments are passed on the stack.  The called function will
1807 pop the arguments off the stack.  If the number of arguments is variable all
1808 arguments are pushed on the stack.
1809
1810 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
1811 @cindex @code{format} function attribute
1812 @opindex Wformat
1813 The @code{format} attribute specifies that a function takes @code{printf},
1814 @code{scanf}, @code{strftime} or @code{strfmon} style arguments which
1815 should be type-checked against a format string.  For example, the
1816 declaration:
1817
1818 @smallexample
1819 extern int
1820 my_printf (void *my_object, const char *my_format, ...)
1821       __attribute__ ((format (printf, 2, 3)));
1822 @end smallexample
1823
1824 @noindent
1825 causes the compiler to check the arguments in calls to @code{my_printf}
1826 for consistency with the @code{printf} style format string argument
1827 @code{my_format}.
1828
1829 The parameter @var{archetype} determines how the format string is
1830 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}
1831 or @code{strfmon}.  (You can also use @code{__printf__},
1832 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.)  The
1833 parameter @var{string-index} specifies which argument is the format
1834 string argument (starting from 1), while @var{first-to-check} is the
1835 number of the first argument to check against the format string.  For
1836 functions where the arguments are not available to be checked (such as
1837 @code{vprintf}), specify the third parameter as zero.  In this case the
1838 compiler only checks the format string for consistency.  For
1839 @code{strftime} formats, the third parameter is required to be zero.
1840 Since non-static C++ methods have an implicit @code{this} argument, the
1841 arguments of such methods should be counted from two, not one, when
1842 giving values for @var{string-index} and @var{first-to-check}.
1843
1844 In the example above, the format string (@code{my_format}) is the second
1845 argument of the function @code{my_print}, and the arguments to check
1846 start with the third argument, so the correct parameters for the format
1847 attribute are 2 and 3.
1848
1849 @opindex ffreestanding
1850 @opindex fno-builtin
1851 The @code{format} attribute allows you to identify your own functions
1852 which take format strings as arguments, so that GCC can check the
1853 calls to these functions for errors.  The compiler always (unless
1854 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
1855 for the standard library functions @code{printf}, @code{fprintf},
1856 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
1857 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
1858 warnings are requested (using @option{-Wformat}), so there is no need to
1859 modify the header file @file{stdio.h}.  In C99 mode, the functions
1860 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
1861 @code{vsscanf} are also checked.  Except in strictly conforming C
1862 standard modes, the X/Open function @code{strfmon} is also checked as
1863 are @code{printf_unlocked} and @code{fprintf_unlocked}.
1864 @xref{C Dialect Options,,Options Controlling C Dialect}.
1865
1866 The target may provide additional types of format checks.
1867 @xref{Target Format Checks,,Format Checks Specific to Particular
1868 Target Machines}.
1869
1870 @item format_arg (@var{string-index})
1871 @cindex @code{format_arg} function attribute
1872 @opindex Wformat-nonliteral
1873 The @code{format_arg} attribute specifies that a function takes a format
1874 string for a @code{printf}, @code{scanf}, @code{strftime} or
1875 @code{strfmon} style function and modifies it (for example, to translate
1876 it into another language), so the result can be passed to a
1877 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
1878 function (with the remaining arguments to the format function the same
1879 as they would have been for the unmodified string).  For example, the
1880 declaration:
1881
1882 @smallexample
1883 extern char *
1884 my_dgettext (char *my_domain, const char *my_format)
1885       __attribute__ ((format_arg (2)));
1886 @end smallexample
1887
1888 @noindent
1889 causes the compiler to check the arguments in calls to a @code{printf},
1890 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
1891 format string argument is a call to the @code{my_dgettext} function, for
1892 consistency with the format string argument @code{my_format}.  If the
1893 @code{format_arg} attribute had not been specified, all the compiler
1894 could tell in such calls to format functions would be that the format
1895 string argument is not constant; this would generate a warning when
1896 @option{-Wformat-nonliteral} is used, but the calls could not be checked
1897 without the attribute.
1898
1899 The parameter @var{string-index} specifies which argument is the format
1900 string argument (starting from one).  Since non-static C++ methods have
1901 an implicit @code{this} argument, the arguments of such methods should
1902 be counted from two.
1903
1904 The @code{format-arg} attribute allows you to identify your own
1905 functions which modify format strings, so that GCC can check the
1906 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
1907 type function whose operands are a call to one of your own function.
1908 The compiler always treats @code{gettext}, @code{dgettext}, and
1909 @code{dcgettext} in this manner except when strict ISO C support is
1910 requested by @option{-ansi} or an appropriate @option{-std} option, or
1911 @option{-ffreestanding} or @option{-fno-builtin}
1912 is used.  @xref{C Dialect Options,,Options
1913 Controlling C Dialect}.
1914
1915 @item function_vector
1916 @cindex calling functions through the function vector on the H8/300 processors
1917 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
1918 function should be called through the function vector.  Calling a
1919 function through the function vector will reduce code size, however;
1920 the function vector has a limited size (maximum 128 entries on the H8/300
1921 and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector.
1922
1923 You must use GAS and GLD from GNU binutils version 2.7 or later for
1924 this attribute to work correctly.
1925
1926 @item interrupt
1927 @cindex interrupt handler functions
1928 Use this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, MS1, and Xstormy16
1929 ports to indicate that the specified function is an interrupt handler.
1930 The compiler will generate function entry and exit sequences suitable
1931 for use in an interrupt handler when this attribute is present.
1932
1933 Note, interrupt handlers for the Blackfin, m68k, H8/300, H8/300H, H8S, and
1934 SH processors can be specified via the @code{interrupt_handler} attribute.
1935
1936 Note, on the AVR, interrupts will be enabled inside the function.
1937
1938 Note, for the ARM, you can specify the kind of interrupt to be handled by
1939 adding an optional parameter to the interrupt attribute like this:
1940
1941 @smallexample
1942 void f () __attribute__ ((interrupt ("IRQ")));
1943 @end smallexample
1944
1945 Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@.
1946
1947 @item interrupt_handler
1948 @cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors
1949 Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to
1950 indicate that the specified function is an interrupt handler.  The compiler
1951 will generate function entry and exit sequences suitable for use in an
1952 interrupt handler when this attribute is present.
1953
1954 @item kspisusp
1955 @cindex User stack pointer in interrupts on the Blackfin
1956 When used together with @code{interrupt_handler}, @code{exception_handler}
1957 or @code{nmi_handler}, code will be generated to load the stack pointer
1958 from the USP register in the function prologue.
1959
1960 @item long_call/short_call
1961 @cindex indirect calls on ARM
1962 This attribute specifies how a particular function is called on
1963 ARM@.  Both attributes override the @option{-mlong-calls} (@pxref{ARM Options})
1964 command line switch and @code{#pragma long_calls} settings.  The
1965 @code{long_call} attribute indicates that the function might be far
1966 away from the call site and require a different (more expensive)
1967 calling sequence.   The @code{short_call} attribute always places
1968 the offset to the function from the call site into the @samp{BL}
1969 instruction directly.
1970
1971 @item longcall/shortcall
1972 @cindex functions called via pointer on the RS/6000 and PowerPC
1973 On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute
1974 indicates that the function might be far away from the call site and
1975 require a different (more expensive) calling sequence.  The
1976 @code{shortcall} attribute indicates that the function is always close
1977 enough for the shorter calling sequence to be used.  These attributes
1978 override both the @option{-mlongcall} switch and, on the RS/6000 and
1979 PowerPC, the @code{#pragma longcall} setting.
1980
1981 @xref{RS/6000 and PowerPC Options}, for more information on whether long
1982 calls are necessary.
1983
1984 @item long_call
1985 @cindex indirect calls on MIPS
1986 This attribute specifies how a particular function is called on MIPS@.
1987 The attribute overrides the @option{-mlong-calls} (@pxref{MIPS Options})
1988 command line switch.  This attribute causes the compiler to always call
1989 the function by first loading its address into a register, and then using
1990 the contents of that register.
1991
1992 @item malloc
1993 @cindex @code{malloc} attribute
1994 The @code{malloc} attribute is used to tell the compiler that a function
1995 may be treated as if any non-@code{NULL} pointer it returns cannot
1996 alias any other pointer valid when the function returns.
1997 This will often improve optimization.
1998 Standard functions with this property include @code{malloc} and
1999 @code{calloc}.  @code{realloc}-like functions have this property as
2000 long as the old pointer is never referred to (including comparing it
2001 to the new pointer) after the function returns a non-@code{NULL}
2002 value.
2003
2004 @item model (@var{model-name})
2005 @cindex function addressability on the M32R/D
2006 @cindex variable addressability on the IA-64
2007
2008 On the M32R/D, use this attribute to set the addressability of an
2009 object, and of the code generated for a function.  The identifier
2010 @var{model-name} is one of @code{small}, @code{medium}, or
2011 @code{large}, representing each of the code models.
2012
2013 Small model objects live in the lower 16MB of memory (so that their
2014 addresses can be loaded with the @code{ld24} instruction), and are
2015 callable with the @code{bl} instruction.
2016
2017 Medium model objects may live anywhere in the 32-bit address space (the
2018 compiler will generate @code{seth/add3} instructions to load their addresses),
2019 and are callable with the @code{bl} instruction.
2020
2021 Large model objects may live anywhere in the 32-bit address space (the
2022 compiler will generate @code{seth/add3} instructions to load their addresses),
2023 and may not be reachable with the @code{bl} instruction (the compiler will
2024 generate the much slower @code{seth/add3/jl} instruction sequence).
2025
2026 On IA-64, use this attribute to set the addressability of an object.
2027 At present, the only supported identifier for @var{model-name} is
2028 @code{small}, indicating addressability via ``small'' (22-bit)
2029 addresses (so that their addresses can be loaded with the @code{addl}
2030 instruction).  Caveat: such addressing is by definition not position
2031 independent and hence this attribute must not be used for objects
2032 defined by shared libraries.
2033
2034 @item naked
2035 @cindex function without a prologue/epilogue code
2036 Use this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the
2037 specified function does not need prologue/epilogue sequences generated by
2038 the compiler.  It is up to the programmer to provide these sequences.
2039
2040 @item near
2041 @cindex functions which do not handle memory bank switching on 68HC11/68HC12
2042 On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to
2043 use the normal calling convention based on @code{jsr} and @code{rts}.
2044 This attribute can be used to cancel the effect of the @option{-mlong-calls}
2045 option.
2046
2047 @item nesting
2048 @cindex Allow nesting in an interrupt handler on the Blackfin processor.
2049 Use this attribute together with @code{interrupt_handler},
2050 @code{exception_handler} or @code{nmi_handler} to indicate that the function
2051 entry code should enable nested interrupts or exceptions.
2052
2053 @item nmi_handler
2054 @cindex NMI handler functions on the Blackfin processor
2055 Use this attribute on the Blackfin to indicate that the specified function
2056 is an NMI handler.  The compiler will generate function entry and
2057 exit sequences suitable for use in an NMI handler when this
2058 attribute is present.
2059
2060 @item no_instrument_function
2061 @cindex @code{no_instrument_function} function attribute
2062 @opindex finstrument-functions
2063 If @option{-finstrument-functions} is given, profiling function calls will
2064 be generated at entry and exit of most user-compiled functions.
2065 Functions with this attribute will not be so instrumented.
2066
2067 @item noinline
2068 @cindex @code{noinline} function attribute
2069 This function attribute prevents a function from being considered for
2070 inlining.
2071
2072 @item nonnull (@var{arg-index}, @dots{})
2073 @cindex @code{nonnull} function attribute
2074 The @code{nonnull} attribute specifies that some function parameters should
2075 be non-null pointers.  For instance, the declaration:
2076
2077 @smallexample
2078 extern void *
2079 my_memcpy (void *dest, const void *src, size_t len)
2080         __attribute__((nonnull (1, 2)));
2081 @end smallexample
2082
2083 @noindent
2084 causes the compiler to check that, in calls to @code{my_memcpy},
2085 arguments @var{dest} and @var{src} are non-null.  If the compiler
2086 determines that a null pointer is passed in an argument slot marked
2087 as non-null, and the @option{-Wnonnull} option is enabled, a warning
2088 is issued.  The compiler may also choose to make optimizations based
2089 on the knowledge that certain function arguments will not be null.
2090
2091 If no argument index list is given to the @code{nonnull} attribute,
2092 all pointer arguments are marked as non-null.  To illustrate, the
2093 following declaration is equivalent to the previous example:
2094
2095 @smallexample
2096 extern void *
2097 my_memcpy (void *dest, const void *src, size_t len)
2098         __attribute__((nonnull));
2099 @end smallexample
2100
2101 @item noreturn
2102 @cindex @code{noreturn} function attribute
2103 A few standard library functions, such as @code{abort} and @code{exit},
2104 cannot return.  GCC knows this automatically.  Some programs define
2105 their own functions that never return.  You can declare them
2106 @code{noreturn} to tell the compiler this fact.  For example,
2107
2108 @smallexample
2109 @group
2110 void fatal () __attribute__ ((noreturn));
2111
2112 void
2113 fatal (/* @r{@dots{}} */)
2114 @{
2115   /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
2116   exit (1);
2117 @}
2118 @end group
2119 @end smallexample
2120
2121 The @code{noreturn} keyword tells the compiler to assume that
2122 @code{fatal} cannot return.  It can then optimize without regard to what
2123 would happen if @code{fatal} ever did return.  This makes slightly
2124 better code.  More importantly, it helps avoid spurious warnings of
2125 uninitialized variables.
2126
2127 The @code{noreturn} keyword does not affect the exceptional path when that
2128 applies: a @code{noreturn}-marked function may still return to the caller
2129 by throwing an exception or calling @code{longjmp}.
2130
2131 Do not assume that registers saved by the calling function are
2132 restored before calling the @code{noreturn} function.
2133
2134 It does not make sense for a @code{noreturn} function to have a return
2135 type other than @code{void}.
2136
2137 The attribute @code{noreturn} is not implemented in GCC versions
2138 earlier than 2.5.  An alternative way to declare that a function does
2139 not return, which works in the current version and in some older
2140 versions, is as follows:
2141
2142 @smallexample
2143 typedef void voidfn ();
2144
2145 volatile voidfn fatal;
2146 @end smallexample
2147
2148 This approach does not work in GNU C++.
2149
2150 @item nothrow
2151 @cindex @code{nothrow} function attribute
2152 The @code{nothrow} attribute is used to inform the compiler that a
2153 function cannot throw an exception.  For example, most functions in
2154 the standard C library can be guaranteed not to throw an exception
2155 with the notable exceptions of @code{qsort} and @code{bsearch} that
2156 take function pointer arguments.  The @code{nothrow} attribute is not
2157 implemented in GCC versions earlier than 3.3.
2158
2159 @item pure
2160 @cindex @code{pure} function attribute
2161 Many functions have no effects except the return value and their
2162 return value depends only on the parameters and/or global variables.
2163 Such a function can be subject
2164 to common subexpression elimination and loop optimization just as an
2165 arithmetic operator would be.  These functions should be declared
2166 with the attribute @code{pure}.  For example,
2167
2168 @smallexample
2169 int square (int) __attribute__ ((pure));
2170 @end smallexample
2171
2172 @noindent
2173 says that the hypothetical function @code{square} is safe to call
2174 fewer times than the program says.
2175
2176 Some of common examples of pure functions are @code{strlen} or @code{memcmp}.
2177 Interesting non-pure functions are functions with infinite loops or those
2178 depending on volatile memory or other system resource, that may change between
2179 two consecutive calls (such as @code{feof} in a multithreading environment).
2180
2181 The attribute @code{pure} is not implemented in GCC versions earlier
2182 than 2.96.
2183
2184 @item regparm (@var{number})
2185 @cindex @code{regparm} attribute
2186 @cindex functions that are passed arguments in registers on the 386
2187 On the Intel 386, the @code{regparm} attribute causes the compiler to
2188 pass arguments number one to @var{number} if they are of integral type
2189 in registers EAX, EDX, and ECX instead of on the stack.  Functions that
2190 take a variable number of arguments will continue to be passed all of their
2191 arguments on the stack.
2192
2193 Beware that on some ELF systems this attribute is unsuitable for
2194 global functions in shared libraries with lazy binding (which is the
2195 default).  Lazy binding will send the first call via resolving code in
2196 the loader, which might assume EAX, EDX and ECX can be clobbered, as
2197 per the standard calling conventions.  Solaris 8 is affected by this.
2198 GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be
2199 safe since the loaders there save all registers.  (Lazy binding can be
2200 disabled with the linker or the loader if desired, to avoid the
2201 problem.)
2202
2203 @item sseregparm
2204 @cindex @code{sseregparm} attribute
2205 On the Intel 386 with SSE support, the @code{sseregparm} attribute
2206 causes the compiler to pass up to 8 floating point arguments in
2207 SSE registers instead of on the stack.  Functions that take a
2208 variable number of arguments will continue to pass all of their
2209 floating point arguments on the stack.
2210
2211 @item force_align_arg_pointer
2212 @cindex @code{force_align_arg_pointer} attribute
2213 On the Intel x86, the @code{force_align_arg_pointer} attribute may be
2214 applied to individual function definitions, generating an alternate
2215 prologue and epilogue that realigns the runtime stack.  This supports
2216 mixing legacy codes that run with a 4-byte aligned stack with modern
2217 codes that keep a 16-byte stack for SSE compatibility.  The alternate
2218 prologue and epilogue are slower and bigger than the regular ones, and
2219 the alternate prologue requires a scratch register; this lowers the
2220 number of registers available if used in conjunction with the
2221 @code{regparm} attribute.  The @code{force_align_arg_pointer}
2222 attribute is incompatible with nested functions; this is considered a
2223 hard error.
2224
2225 @item returns_twice
2226 @cindex @code{returns_twice} attribute
2227 The @code{returns_twice} attribute tells the compiler that a function may
2228 return more than one time.  The compiler will ensure that all registers
2229 are dead before calling such a function and will emit a warning about
2230 the variables that may be clobbered after the second return from the
2231 function.  Examples of such functions are @code{setjmp} and @code{vfork}.
2232 The @code{longjmp}-like counterpart of such function, if any, might need
2233 to be marked with the @code{noreturn} attribute.
2234
2235 @item saveall
2236 @cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S
2237 Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that
2238 all registers except the stack pointer should be saved in the prologue
2239 regardless of whether they are used or not.
2240
2241 @item section ("@var{section-name}")
2242 @cindex @code{section} function attribute
2243 Normally, the compiler places the code it generates in the @code{text} section.
2244 Sometimes, however, you need additional sections, or you need certain
2245 particular functions to appear in special sections.  The @code{section}
2246 attribute specifies that a function lives in a particular section.
2247 For example, the declaration:
2248
2249 @smallexample
2250 extern void foobar (void) __attribute__ ((section ("bar")));
2251 @end smallexample
2252
2253 @noindent
2254 puts the function @code{foobar} in the @code{bar} section.
2255
2256 Some file formats do not support arbitrary sections so the @code{section}
2257 attribute is not available on all platforms.
2258 If you need to map the entire contents of a module to a particular
2259 section, consider using the facilities of the linker instead.
2260
2261 @item sentinel
2262 @cindex @code{sentinel} function attribute
2263 This function attribute ensures that a parameter in a function call is
2264 an explicit @code{NULL}.  The attribute is only valid on variadic
2265 functions.  By default, the sentinel is located at position zero, the
2266 last parameter of the function call.  If an optional integer position
2267 argument P is supplied to the attribute, the sentinel must be located at
2268 position P counting backwards from the end of the argument list.
2269
2270 @smallexample
2271 __attribute__ ((sentinel))
2272 is equivalent to
2273 __attribute__ ((sentinel(0)))
2274 @end smallexample
2275
2276 The attribute is automatically set with a position of 0 for the built-in
2277 functions @code{execl} and @code{execlp}.  The built-in function
2278 @code{execle} has the attribute set with a position of 1.
2279
2280 A valid @code{NULL} in this context is defined as zero with any pointer
2281 type.  If your system defines the @code{NULL} macro with an integer type
2282 then you need to add an explicit cast.  GCC replaces @code{stddef.h}
2283 with a copy that redefines NULL appropriately.
2284
2285 The warnings for missing or incorrect sentinels are enabled with
2286 @option{-Wformat}.
2287
2288 @item short_call
2289 See long_call/short_call.
2290
2291 @item shortcall
2292 See longcall/shortcall.
2293
2294 @item signal
2295 @cindex signal handler functions on the AVR processors
2296 Use this attribute on the AVR to indicate that the specified
2297 function is a signal handler.  The compiler will generate function
2298 entry and exit sequences suitable for use in a signal handler when this
2299 attribute is present.  Interrupts will be disabled inside the function.
2300
2301 @item sp_switch
2302 Use this attribute on the SH to indicate an @code{interrupt_handler}
2303 function should switch to an alternate stack.  It expects a string
2304 argument that names a global variable holding the address of the
2305 alternate stack.
2306
2307 @smallexample
2308 void *alt_stack;
2309 void f () __attribute__ ((interrupt_handler,
2310                           sp_switch ("alt_stack")));
2311 @end smallexample
2312
2313 @item stdcall
2314 @cindex functions that pop the argument stack on the 386
2315 On the Intel 386, the @code{stdcall} attribute causes the compiler to
2316 assume that the called function will pop off the stack space used to
2317 pass arguments, unless it takes a variable number of arguments.
2318
2319 @item tiny_data
2320 @cindex tiny data section on the H8/300H and H8S
2321 Use this attribute on the H8/300H and H8S to indicate that the specified
2322 variable should be placed into the tiny data section.
2323 The compiler will generate more efficient code for loads and stores
2324 on data in the tiny data section.  Note the tiny data area is limited to
2325 slightly under 32kbytes of data.
2326
2327 @item trap_exit
2328 Use this attribute on the SH for an @code{interrupt_handler} to return using
2329 @code{trapa} instead of @code{rte}.  This attribute expects an integer
2330 argument specifying the trap number to be used.
2331
2332 @item unused
2333 @cindex @code{unused} attribute.
2334 This attribute, attached to a function, means that the function is meant
2335 to be possibly unused.  GCC will not produce a warning for this
2336 function.
2337
2338 @item used
2339 @cindex @code{used} attribute.
2340 This attribute, attached to a function, means that code must be emitted
2341 for the function even if it appears that the function is not referenced.
2342 This is useful, for example, when the function is referenced only in
2343 inline assembly.
2344
2345 @item visibility ("@var{visibility_type}")
2346 @cindex @code{visibility} attribute
2347 This attribute affects the linkage of the declaration to which it is attached.
2348 There are four supported @var{visibility_type} values: default,
2349 hidden, protected or internal visibility.
2350
2351 @smallexample
2352 void __attribute__ ((visibility ("protected")))
2353 f () @{ /* @r{Do something.} */; @}
2354 int i __attribute__ ((visibility ("hidden")));
2355 @end smallexample
2356
2357 The possible values of @var{visibility_type} correspond to the
2358 visibility settings in the ELF gABI.
2359
2360 @table @dfn
2361 @c keep this list of visibilities in alphabetical order.
2362
2363 @item default
2364 Default visibility is the normal case for the object file format.
2365 This value is available for the visibility attribute to override other
2366 options that may change the assumed visibility of entities.
2367
2368 On ELF, default visibility means that the declaration is visible to other
2369 modules and, in shared libraries, means that the declared entity may be
2370 overridden.
2371
2372 On Darwin, default visibility means that the declaration is visible to
2373 other modules.
2374
2375 Default visibility corresponds to ``external linkage'' in the language.
2376
2377 @item hidden
2378 Hidden visibility indicates that the entity declared will have a new
2379 form of linkage, which we'll call ``hidden linkage''.  Two
2380 declarations of an object with hidden linkage refer to the same object
2381 if they are in the same shared object.
2382
2383 @item internal
2384 Internal visibility is like hidden visibility, but with additional
2385 processor specific semantics.  Unless otherwise specified by the
2386 psABI, GCC defines internal visibility to mean that a function is
2387 @emph{never} called from another module.  Compare this with hidden
2388 functions which, while they cannot be referenced directly by other
2389 modules, can be referenced indirectly via function pointers.  By
2390 indicating that a function cannot be called from outside the module,
2391 GCC may for instance omit the load of a PIC register since it is known
2392 that the calling function loaded the correct value.
2393
2394 @item protected
2395 Protected visibility is like default visibility except that it
2396 indicates that references within the defining module will bind to the
2397 definition in that module.  That is, the declared entity cannot be
2398 overridden by another module.
2399
2400 @end table
2401
2402 All visibilities are supported on many, but not all, ELF targets
2403 (supported when the assembler supports the @samp{.visibility}
2404 pseudo-op).  Default visibility is supported everywhere.  Hidden
2405 visibility is supported on Darwin targets.
2406
2407 The visibility attribute should be applied only to declarations which
2408 would otherwise have external linkage.  The attribute should be applied
2409 consistently, so that the same entity should not be declared with
2410 different settings of the attribute.
2411
2412 In C++, the visibility attribute applies to types as well as functions
2413 and objects, because in C++ types have linkage.  A class must not have
2414 greater visibility than its non-static data member types and bases,
2415 and class members default to the visibility of their class.  Also, a
2416 declaration without explicit visibility is limited to the visibility
2417 of its type.
2418
2419 In C++, you can mark member functions and static member variables of a
2420 class with the visibility attribute.  This is useful if if you know a
2421 particular method or static member variable should only be used from
2422 one shared object; then you can mark it hidden while the rest of the
2423 class has default visibility.  Care must be taken to avoid breaking
2424 the One Definition Rule; for example, it is usually not useful to mark
2425 an inline method as hidden without marking the whole class as hidden.
2426
2427 A C++ namespace declaration can also have the visibility attribute.
2428 This attribute applies only to the particular namespace body, not to
2429 other definitions of the same namespace; it is equivalent to using
2430 @samp{#pragma GCC visibility} before and after the namespace
2431 definition (@pxref{Visibility Pragmas}).
2432
2433 In C++, if a template argument has limited visibility, this
2434 restriction is implicitly propagated to the template instantiation.
2435 Otherwise, template instantiations and specializations default to the
2436 visibility of their template.
2437
2438 If both the template and enclosing class have explicit visibility, the
2439 visibility from the template is used.
2440
2441 @item warn_unused_result
2442 @cindex @code{warn_unused_result} attribute
2443 The @code{warn_unused_result} attribute causes a warning to be emitted
2444 if a caller of the function with this attribute does not use its
2445 return value.  This is useful for functions where not checking
2446 the result is either a security problem or always a bug, such as
2447 @code{realloc}.
2448
2449 @smallexample
2450 int fn () __attribute__ ((warn_unused_result));
2451 int foo ()
2452 @{
2453   if (fn () < 0) return -1;
2454   fn ();
2455   return 0;
2456 @}
2457 @end smallexample
2458
2459 results in warning on line 5.
2460
2461 @item weak
2462 @cindex @code{weak} attribute
2463 The @code{weak} attribute causes the declaration to be emitted as a weak
2464 symbol rather than a global.  This is primarily useful in defining
2465 library functions which can be overridden in user code, though it can
2466 also be used with non-function declarations.  Weak symbols are supported
2467 for ELF targets, and also for a.out targets when using the GNU assembler
2468 and linker.
2469
2470 @item weakref
2471 @itemx weakref ("@var{target}")
2472 @cindex @code{weakref} attribute
2473 The @code{weakref} attribute marks a declaration as a weak reference.
2474 Without arguments, it should be accompanied by an @code{alias} attribute
2475 naming the target symbol.  Optionally, the @var{target} may be given as
2476 an argument to @code{weakref} itself.  In either case, @code{weakref}
2477 implicitly marks the declaration as @code{weak}.  Without a
2478 @var{target}, given as an argument to @code{weakref} or to @code{alias},
2479 @code{weakref} is equivalent to @code{weak}.
2480
2481 @smallexample
2482 static int x() __attribute__ ((weakref ("y")));
2483 /* is equivalent to... */
2484 static int x() __attribute__ ((weak, weakref, alias ("y")));
2485 /* and to... */
2486 static int x() __attribute__ ((weakref));
2487 static int x() __attribute__ ((alias ("y")));
2488 @end smallexample
2489
2490 A weak reference is an alias that does not by itself require a
2491 definition to be given for the target symbol.  If the target symbol is
2492 only referenced through weak references, then the becomes a @code{weak}
2493 undefined symbol.  If it is directly referenced, however, then such
2494 strong references prevail, and a definition will be required for the
2495 symbol, not necessarily in the same translation unit.
2496
2497 The effect is equivalent to moving all references to the alias to a
2498 separate translation unit, renaming the alias to the aliased symbol,
2499 declaring it as weak, compiling the two separate translation units and
2500 performing a reloadable link on them.
2501
2502 At present, a declaration to which @code{weakref} is attached can
2503 only be @code{static}.
2504
2505 @item externally_visible
2506 @cindex @code{externally_visible} attribute.
2507 This attribute, attached to a global variable or function nullify
2508 effect of @option{-fwhole-program} command line option, so the object
2509 remain visible outside the current compilation unit
2510
2511 @end table
2512
2513 You can specify multiple attributes in a declaration by separating them
2514 by commas within the double parentheses or by immediately following an
2515 attribute declaration with another attribute declaration.
2516
2517 @cindex @code{#pragma}, reason for not using
2518 @cindex pragma, reason for not using
2519 Some people object to the @code{__attribute__} feature, suggesting that
2520 ISO C's @code{#pragma} should be used instead.  At the time
2521 @code{__attribute__} was designed, there were two reasons for not doing
2522 this.
2523
2524 @enumerate
2525 @item
2526 It is impossible to generate @code{#pragma} commands from a macro.
2527
2528 @item
2529 There is no telling what the same @code{#pragma} might mean in another
2530 compiler.
2531 @end enumerate
2532
2533 These two reasons applied to almost any application that might have been
2534 proposed for @code{#pragma}.  It was basically a mistake to use
2535 @code{#pragma} for @emph{anything}.
2536
2537 The ISO C99 standard includes @code{_Pragma}, which now allows pragmas
2538 to be generated from macros.  In addition, a @code{#pragma GCC}
2539 namespace is now in use for GCC-specific pragmas.  However, it has been
2540 found convenient to use @code{__attribute__} to achieve a natural
2541 attachment of attributes to their corresponding declarations, whereas
2542 @code{#pragma GCC} is of use for constructs that do not naturally form
2543 part of the grammar.  @xref{Other Directives,,Miscellaneous
2544 Preprocessing Directives, cpp, The GNU C Preprocessor}.
2545
2546 @node Attribute Syntax
2547 @section Attribute Syntax
2548 @cindex attribute syntax
2549
2550 This section describes the syntax with which @code{__attribute__} may be
2551 used, and the constructs to which attribute specifiers bind, for the C
2552 language.  Some details may vary for C++ and Objective-C@.  Because of
2553 infelicities in the grammar for attributes, some forms described here
2554 may not be successfully parsed in all cases.
2555
2556 There are some problems with the semantics of attributes in C++.  For
2557 example, there are no manglings for attributes, although they may affect
2558 code generation, so problems may arise when attributed types are used in
2559 conjunction with templates or overloading.  Similarly, @code{typeid}
2560 does not distinguish between types with different attributes.  Support
2561 for attributes in C++ may be restricted in future to attributes on
2562 declarations only, but not on nested declarators.
2563
2564 @xref{Function Attributes}, for details of the semantics of attributes
2565 applying to functions.  @xref{Variable Attributes}, for details of the
2566 semantics of attributes applying to variables.  @xref{Type Attributes},
2567 for details of the semantics of attributes applying to structure, union
2568 and enumerated types.
2569
2570 An @dfn{attribute specifier} is of the form
2571 @code{__attribute__ ((@var{attribute-list}))}.  An @dfn{attribute list}
2572 is a possibly empty comma-separated sequence of @dfn{attributes}, where
2573 each attribute is one of the following:
2574
2575 @itemize @bullet
2576 @item
2577 Empty.  Empty attributes are ignored.
2578
2579 @item
2580 A word (which may be an identifier such as @code{unused}, or a reserved
2581 word such as @code{const}).
2582
2583 @item
2584 A word, followed by, in parentheses, parameters for the attribute.
2585 These parameters take one of the following forms:
2586
2587 @itemize @bullet
2588 @item
2589 An identifier.  For example, @code{mode} attributes use this form.
2590
2591 @item
2592 An identifier followed by a comma and a non-empty comma-separated list
2593 of expressions.  For example, @code{format} attributes use this form.
2594
2595 @item
2596 A possibly empty comma-separated list of expressions.  For example,
2597 @code{format_arg} attributes use this form with the list being a single
2598 integer constant expression, and @code{alias} attributes use this form
2599 with the list being a single string constant.
2600 @end itemize
2601 @end itemize
2602
2603 An @dfn{attribute specifier list} is a sequence of one or more attribute
2604 specifiers, not separated by any other tokens.
2605
2606 In GNU C, an attribute specifier list may appear after the colon following a
2607 label, other than a @code{case} or @code{default} label.  The only
2608 attribute it makes sense to use after a label is @code{unused}.  This
2609 feature is intended for code generated by programs which contains labels
2610 that may be unused but which is compiled with @option{-Wall}.  It would
2611 not normally be appropriate to use in it human-written code, though it
2612 could be useful in cases where the code that jumps to the label is
2613 contained within an @code{#ifdef} conditional.  GNU C++ does not permit
2614 such placement of attribute lists, as it is permissible for a
2615 declaration, which could begin with an attribute list, to be labelled in
2616 C++.  Declarations cannot be labelled in C90 or C99, so the ambiguity
2617 does not arise there.
2618
2619 An attribute specifier list may appear as part of a @code{struct},
2620 @code{union} or @code{enum} specifier.  It may go either immediately
2621 after the @code{struct}, @code{union} or @code{enum} keyword, or after
2622 the closing brace.  The former syntax is preferred.
2623 Where attribute specifiers follow the closing brace, they are considered
2624 to relate to the structure, union or enumerated type defined, not to any
2625 enclosing declaration the type specifier appears in, and the type
2626 defined is not complete until after the attribute specifiers.
2627 @c Otherwise, there would be the following problems: a shift/reduce
2628 @c conflict between attributes binding the struct/union/enum and
2629 @c binding to the list of specifiers/qualifiers; and "aligned"
2630 @c attributes could use sizeof for the structure, but the size could be
2631 @c changed later by "packed" attributes.
2632
2633 Otherwise, an attribute specifier appears as part of a declaration,
2634 counting declarations of unnamed parameters and type names, and relates
2635 to that declaration (which may be nested in another declaration, for
2636 example in the case of a parameter declaration), or to a particular declarator
2637 within a declaration.  Where an
2638 attribute specifier is applied to a parameter declared as a function or
2639 an array, it should apply to the function or array rather than the
2640 pointer to which the parameter is implicitly converted, but this is not
2641 yet correctly implemented.
2642
2643 Any list of specifiers and qualifiers at the start of a declaration may
2644 contain attribute specifiers, whether or not such a list may in that
2645 context contain storage class specifiers.  (Some attributes, however,
2646 are essentially in the nature of storage class specifiers, and only make
2647 sense where storage class specifiers may be used; for example,
2648 @code{section}.)  There is one necessary limitation to this syntax: the
2649 first old-style parameter declaration in a function definition cannot
2650 begin with an attribute specifier, because such an attribute applies to
2651 the function instead by syntax described below (which, however, is not
2652 yet implemented in this case).  In some other cases, attribute
2653 specifiers are permitted by this grammar but not yet supported by the
2654 compiler.  All attribute specifiers in this place relate to the
2655 declaration as a whole.  In the obsolescent usage where a type of
2656 @code{int} is implied by the absence of type specifiers, such a list of
2657 specifiers and qualifiers may be an attribute specifier list with no
2658 other specifiers or qualifiers.
2659
2660 At present, the first parameter in a function prototype must have some
2661 type specifier which is not an attribute specifier; this resolves an
2662 ambiguity in the interpretation of @code{void f(int
2663 (__attribute__((foo)) x))}, but is subject to change.  At present, if
2664 the parentheses of a function declarator contain only attributes then
2665 those attributes are ignored, rather than yielding an error or warning
2666 or implying a single parameter of type int, but this is subject to
2667 change.
2668
2669 An attribute specifier list may appear immediately before a declarator
2670 (other than the first) in a comma-separated list of declarators in a
2671 declaration of more than one identifier using a single list of
2672 specifiers and qualifiers.  Such attribute specifiers apply
2673 only to the identifier before whose declarator they appear.  For
2674 example, in
2675
2676 @smallexample
2677 __attribute__((noreturn)) void d0 (void),
2678     __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
2679      d2 (void)
2680 @end smallexample
2681
2682 @noindent
2683 the @code{noreturn} attribute applies to all the functions
2684 declared; the @code{format} attribute only applies to @code{d1}.
2685
2686 An attribute specifier list may appear immediately before the comma,
2687 @code{=} or semicolon terminating the declaration of an identifier other
2688 than a function definition.  At present, such attribute specifiers apply
2689 to the declared object or function, but in future they may attach to the
2690 outermost adjacent declarator.  In simple cases there is no difference,
2691 but, for example, in
2692
2693 @smallexample
2694 void (****f)(void) __attribute__((noreturn));
2695 @end smallexample
2696
2697 @noindent
2698 at present the @code{noreturn} attribute applies to @code{f}, which
2699 causes a warning since @code{f} is not a function, but in future it may
2700 apply to the function @code{****f}.  The precise semantics of what
2701 attributes in such cases will apply to are not yet specified.  Where an
2702 assembler name for an object or function is specified (@pxref{Asm
2703 Labels}), at present the attribute must follow the @code{asm}
2704 specification; in future, attributes before the @code{asm} specification
2705 may apply to the adjacent declarator, and those after it to the declared
2706 object or function.
2707
2708 An attribute specifier list may, in future, be permitted to appear after
2709 the declarator in a function definition (before any old-style parameter
2710 declarations or the function body).
2711
2712 Attribute specifiers may be mixed with type qualifiers appearing inside
2713 the @code{[]} of a parameter array declarator, in the C99 construct by
2714 which such qualifiers are applied to the pointer to which the array is
2715 implicitly converted.  Such attribute specifiers apply to the pointer,
2716 not to the array, but at present this is not implemented and they are
2717 ignored.
2718
2719 An attribute specifier list may appear at the start of a nested
2720 declarator.  At present, there are some limitations in this usage: the
2721 attributes correctly apply to the declarator, but for most individual
2722 attributes the semantics this implies are not implemented.
2723 When attribute specifiers follow the @code{*} of a pointer
2724 declarator, they may be mixed with any type qualifiers present.
2725 The following describes the formal semantics of this syntax.  It will make the
2726 most sense if you are familiar with the formal specification of
2727 declarators in the ISO C standard.
2728
2729 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
2730 D1}, where @code{T} contains declaration specifiers that specify a type
2731 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
2732 contains an identifier @var{ident}.  The type specified for @var{ident}
2733 for derived declarators whose type does not include an attribute
2734 specifier is as in the ISO C standard.
2735
2736 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
2737 and the declaration @code{T D} specifies the type
2738 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
2739 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
2740 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
2741
2742 If @code{D1} has the form @code{*
2743 @var{type-qualifier-and-attribute-specifier-list} D}, and the
2744 declaration @code{T D} specifies the type
2745 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
2746 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
2747 @var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for
2748 @var{ident}.
2749
2750 For example,
2751
2752 @smallexample
2753 void (__attribute__((noreturn)) ****f) (void);
2754 @end smallexample
2755
2756 @noindent
2757 specifies the type ``pointer to pointer to pointer to pointer to
2758 non-returning function returning @code{void}''.  As another example,
2759
2760 @smallexample
2761 char *__attribute__((aligned(8))) *f;
2762 @end smallexample
2763
2764 @noindent
2765 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
2766 Note again that this does not work with most attributes; for example,
2767 the usage of @samp{aligned} and @samp{noreturn} attributes given above
2768 is not yet supported.
2769
2770 For compatibility with existing code written for compiler versions that
2771 did not implement attributes on nested declarators, some laxity is
2772 allowed in the placing of attributes.  If an attribute that only applies
2773 to types is applied to a declaration, it will be treated as applying to
2774 the type of that declaration.  If an attribute that only applies to
2775 declarations is applied to the type of a declaration, it will be treated
2776 as applying to that declaration; and, for compatibility with code
2777 placing the attributes immediately before the identifier declared, such
2778 an attribute applied to a function return type will be treated as
2779 applying to the function type, and such an attribute applied to an array
2780 element type will be treated as applying to the array type.  If an
2781 attribute that only applies to function types is applied to a
2782 pointer-to-function type, it will be treated as applying to the pointer
2783 target type; if such an attribute is applied to a function return type
2784 that is not a pointer-to-function type, it will be treated as applying
2785 to the function type.
2786
2787 @node Function Prototypes
2788 @section Prototypes and Old-Style Function Definitions
2789 @cindex function prototype declarations
2790 @cindex old-style function definitions
2791 @cindex promotion of formal parameters
2792
2793 GNU C extends ISO C to allow a function prototype to override a later
2794 old-style non-prototype definition.  Consider the following example:
2795
2796 @smallexample
2797 /* @r{Use prototypes unless the compiler is old-fashioned.}  */
2798 #ifdef __STDC__
2799 #define P(x) x
2800 #else
2801 #define P(x) ()
2802 #endif
2803
2804 /* @r{Prototype function declaration.}  */
2805 int isroot P((uid_t));
2806
2807 /* @r{Old-style function definition.}  */
2808 int
2809 isroot (x)   /* @r{??? lossage here ???} */
2810      uid_t x;
2811 @{
2812   return x == 0;
2813 @}
2814 @end smallexample
2815
2816 Suppose the type @code{uid_t} happens to be @code{short}.  ISO C does
2817 not allow this example, because subword arguments in old-style
2818 non-prototype definitions are promoted.  Therefore in this example the
2819 function definition's argument is really an @code{int}, which does not
2820 match the prototype argument type of @code{short}.
2821
2822 This restriction of ISO C makes it hard to write code that is portable
2823 to traditional C compilers, because the programmer does not know
2824 whether the @code{uid_t} type is @code{short}, @code{int}, or
2825 @code{long}.  Therefore, in cases like these GNU C allows a prototype
2826 to override a later old-style definition.  More precisely, in GNU C, a
2827 function prototype argument type overrides the argument type specified
2828 by a later old-style definition if the former type is the same as the
2829 latter type before promotion.  Thus in GNU C the above example is
2830 equivalent to the following:
2831
2832 @smallexample
2833 int isroot (uid_t);
2834
2835 int
2836 isroot (uid_t x)
2837 @{
2838   return x == 0;
2839 @}
2840 @end smallexample
2841
2842 @noindent
2843 GNU C++ does not support old-style function definitions, so this
2844 extension is irrelevant.
2845
2846 @node C++ Comments
2847 @section C++ Style Comments
2848 @cindex //
2849 @cindex C++ comments
2850 @cindex comments, C++ style
2851
2852 In GNU C, you may use C++ style comments, which start with @samp{//} and
2853 continue until the end of the line.  Many other C implementations allow
2854 such comments, and they are included in the 1999 C standard.  However,
2855 C++ style comments are not recognized if you specify an @option{-std}
2856 option specifying a version of ISO C before C99, or @option{-ansi}
2857 (equivalent to @option{-std=c89}).
2858
2859 @node Dollar Signs
2860 @section Dollar Signs in Identifier Names
2861 @cindex $
2862 @cindex dollar signs in identifier names
2863 @cindex identifier names, dollar signs in
2864
2865 In GNU C, you may normally use dollar signs in identifier names.
2866 This is because many traditional C implementations allow such identifiers.
2867 However, dollar signs in identifiers are not supported on a few target
2868 machines, typically because the target assembler does not allow them.
2869
2870 @node Character Escapes
2871 @section The Character @key{ESC} in Constants
2872
2873 You can use the sequence @samp{\e} in a string or character constant to
2874 stand for the ASCII character @key{ESC}.
2875
2876 @node Alignment
2877 @section Inquiring on Alignment of Types or Variables
2878 @cindex alignment
2879 @cindex type alignment
2880 @cindex variable alignment
2881
2882 The keyword @code{__alignof__} allows you to inquire about how an object
2883 is aligned, or the minimum alignment usually required by a type.  Its
2884 syntax is just like @code{sizeof}.
2885
2886 For example, if the target machine requires a @code{double} value to be
2887 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
2888 This is true on many RISC machines.  On more traditional machine
2889 designs, @code{__alignof__ (double)} is 4 or even 2.
2890
2891 Some machines never actually require alignment; they allow reference to any
2892 data type even at an odd address.  For these machines, @code{__alignof__}
2893 reports the @emph{recommended} alignment of a type.
2894
2895 If the operand of @code{__alignof__} is an lvalue rather than a type,
2896 its value is the required alignment for its type, taking into account
2897 any minimum alignment specified with GCC's @code{__attribute__}
2898 extension (@pxref{Variable Attributes}).  For example, after this
2899 declaration:
2900
2901 @smallexample
2902 struct foo @{ int x; char y; @} foo1;
2903 @end smallexample
2904
2905 @noindent
2906 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
2907 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
2908
2909 It is an error to ask for the alignment of an incomplete type.
2910
2911 @node Variable Attributes
2912 @section Specifying Attributes of Variables
2913 @cindex attribute of variables
2914 @cindex variable attributes
2915
2916 The keyword @code{__attribute__} allows you to specify special
2917 attributes of variables or structure fields.  This keyword is followed
2918 by an attribute specification inside double parentheses.  Some
2919 attributes are currently defined generically for variables.
2920 Other attributes are defined for variables on particular target
2921 systems.  Other attributes are available for functions
2922 (@pxref{Function Attributes}) and for types (@pxref{Type Attributes}).
2923 Other front ends might define more attributes
2924 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
2925
2926 You may also specify attributes with @samp{__} preceding and following
2927 each keyword.  This allows you to use them in header files without
2928 being concerned about a possible macro of the same name.  For example,
2929 you may use @code{__aligned__} instead of @code{aligned}.
2930
2931 @xref{Attribute Syntax}, for details of the exact syntax for using
2932 attributes.
2933
2934 @table @code
2935 @cindex @code{aligned} attribute
2936 @item aligned (@var{alignment})
2937 This attribute specifies a minimum alignment for the variable or
2938 structure field, measured in bytes.  For example, the declaration:
2939
2940 @smallexample
2941 int x __attribute__ ((aligned (16))) = 0;
2942 @end smallexample
2943
2944 @noindent
2945 causes the compiler to allocate the global variable @code{x} on a
2946 16-byte boundary.  On a 68040, this could be used in conjunction with
2947 an @code{asm} expression to access the @code{move16} instruction which
2948 requires 16-byte aligned operands.
2949
2950 You can also specify the alignment of structure fields.  For example, to
2951 create a double-word aligned @code{int} pair, you could write:
2952
2953 @smallexample
2954 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
2955 @end smallexample
2956
2957 @noindent
2958 This is an alternative to creating a union with a @code{double} member
2959 that forces the union to be double-word aligned.
2960
2961 As in the preceding examples, you can explicitly specify the alignment
2962 (in bytes) that you wish the compiler to use for a given variable or
2963 structure field.  Alternatively, you can leave out the alignment factor
2964 and just ask the compiler to align a variable or field to the maximum
2965 useful alignment for the target machine you are compiling for.  For
2966 example, you could write:
2967
2968 @smallexample
2969 short array[3] __attribute__ ((aligned));
2970 @end smallexample
2971
2972 Whenever you leave out the alignment factor in an @code{aligned} attribute
2973 specification, the compiler automatically sets the alignment for the declared
2974 variable or field to the largest alignment which is ever used for any data
2975 type on the target machine you are compiling for.  Doing this can often make
2976 copy operations more efficient, because the compiler can use whatever
2977 instructions copy the biggest chunks of memory when performing copies to
2978 or from the variables or fields that you have aligned this way.
2979
2980 The @code{aligned} attribute can only increase the alignment; but you
2981 can decrease it by specifying @code{packed} as well.  See below.
2982
2983 Note that the effectiveness of @code{aligned} attributes may be limited
2984 by inherent limitations in your linker.  On many systems, the linker is
2985 only able to arrange for variables to be aligned up to a certain maximum
2986 alignment.  (For some linkers, the maximum supported alignment may
2987 be very very small.)  If your linker is only able to align variables
2988 up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
2989 in an @code{__attribute__} will still only provide you with 8 byte
2990 alignment.  See your linker documentation for further information.
2991
2992 @item cleanup (@var{cleanup_function})
2993 @cindex @code{cleanup} attribute
2994 The @code{cleanup} attribute runs a function when the variable goes
2995 out of scope.  This attribute can only be applied to auto function
2996 scope variables; it may not be applied to parameters or variables
2997 with static storage duration.  The function must take one parameter,
2998 a pointer to a type compatible with the variable.  The return value
2999 of the function (if any) is ignored.
3000
3001 If @option{-fexceptions} is enabled, then @var{cleanup_function}
3002 will be run during the stack unwinding that happens during the
3003 processing of the exception.  Note that the @code{cleanup} attribute
3004 does not allow the exception to be caught, only to perform an action.
3005 It is undefined what happens if @var{cleanup_function} does not
3006 return normally.
3007
3008 @item common
3009 @itemx nocommon
3010 @cindex @code{common} attribute
3011 @cindex @code{nocommon} attribute
3012 @opindex fcommon
3013 @opindex fno-common
3014 The @code{common} attribute requests GCC to place a variable in
3015 ``common'' storage.  The @code{nocommon} attribute requests the
3016 opposite---to allocate space for it directly.
3017
3018 These attributes override the default chosen by the
3019 @option{-fno-common} and @option{-fcommon} flags respectively.
3020
3021 @item deprecated
3022 @cindex @code{deprecated} attribute
3023 The @code{deprecated} attribute results in a warning if the variable
3024 is used anywhere in the source file.  This is useful when identifying
3025 variables that are expected to be removed in a future version of a
3026 program.  The warning also includes the location of the declaration
3027 of the deprecated variable, to enable users to easily find further
3028 information about why the variable is deprecated, or what they should
3029 do instead.  Note that the warning only occurs for uses:
3030
3031 @smallexample
3032 extern int old_var __attribute__ ((deprecated));
3033 extern int old_var;
3034 int new_fn () @{ return old_var; @}
3035 @end smallexample
3036
3037 results in a warning on line 3 but not line 2.
3038
3039 The @code{deprecated} attribute can also be used for functions and
3040 types (@pxref{Function Attributes}, @pxref{Type Attributes}.)
3041
3042 @item mode (@var{mode})
3043 @cindex @code{mode} attribute
3044 This attribute specifies the data type for the declaration---whichever
3045 type corresponds to the mode @var{mode}.  This in effect lets you
3046 request an integer or floating point type according to its width.
3047
3048 You may also specify a mode of @samp{byte} or @samp{__byte__} to
3049 indicate the mode corresponding to a one-byte integer, @samp{word} or
3050 @samp{__word__} for the mode of a one-word integer, and @samp{pointer}
3051 or @samp{__pointer__} for the mode used to represent pointers.
3052
3053 @item packed
3054 @cindex @code{packed} attribute
3055 The @code{packed} attribute specifies that a variable or structure field
3056 should have the smallest possible alignment---one byte for a variable,
3057 and one bit for a field, unless you specify a larger value with the
3058 @code{aligned} attribute.
3059
3060 Here is a structure in which the field @code{x} is packed, so that it
3061 immediately follows @code{a}:
3062
3063 @smallexample
3064 struct foo
3065 @{
3066   char a;
3067   int x[2] __attribute__ ((packed));
3068 @};
3069 @end smallexample
3070
3071 @item section ("@var{section-name}")
3072 @cindex @code{section} variable attribute
3073 Normally, the compiler places the objects it generates in sections like
3074 @code{data} and @code{bss}.  Sometimes, however, you need additional sections,
3075 or you need certain particular variables to appear in special sections,
3076 for example to map to special hardware.  The @code{section}
3077 attribute specifies that a variable (or function) lives in a particular
3078 section.  For example, this small program uses several specific section names:
3079
3080 @smallexample
3081 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
3082 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
3083 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
3084 int init_data __attribute__ ((section ("INITDATA"))) = 0;
3085
3086 main()
3087 @{
3088   /* @r{Initialize stack pointer} */
3089   init_sp (stack + sizeof (stack));
3090
3091   /* @r{Initialize initialized data} */
3092   memcpy (&init_data, &data, &edata - &data);
3093
3094   /* @r{Turn on the serial ports} */
3095   init_duart (&a);
3096   init_duart (&b);
3097 @}
3098 @end smallexample
3099
3100 @noindent
3101 Use the @code{section} attribute with an @emph{initialized} definition
3102 of a @emph{global} variable, as shown in the example.  GCC issues
3103 a warning and otherwise ignores the @code{section} attribute in
3104 uninitialized variable declarations.
3105
3106 You may only use the @code{section} attribute with a fully initialized
3107 global definition because of the way linkers work.  The linker requires
3108 each object be defined once, with the exception that uninitialized
3109 variables tentatively go in the @code{common} (or @code{bss}) section
3110 and can be multiply ``defined''.  You can force a variable to be
3111 initialized with the @option{-fno-common} flag or the @code{nocommon}
3112 attribute.
3113
3114 Some file formats do not support arbitrary sections so the @code{section}
3115 attribute is not available on all platforms.
3116 If you need to map the entire contents of a module to a particular
3117 section, consider using the facilities of the linker instead.
3118
3119 @item shared
3120 @cindex @code{shared} variable attribute
3121 On Microsoft Windows, in addition to putting variable definitions in a named
3122 section, the section can also be shared among all running copies of an
3123 executable or DLL@.  For example, this small program defines shared data
3124 by putting it in a named section @code{shared} and marking the section
3125 shareable:
3126
3127 @smallexample
3128 int foo __attribute__((section ("shared"), shared)) = 0;
3129
3130 int
3131 main()
3132 @{
3133   /* @r{Read and write foo.  All running
3134      copies see the same value.}  */
3135   return 0;
3136 @}
3137 @end smallexample
3138
3139 @noindent
3140 You may only use the @code{shared} attribute along with @code{section}
3141 attribute with a fully initialized global definition because of the way
3142 linkers work.  See @code{section} attribute for more information.
3143
3144 The @code{shared} attribute is only available on Microsoft Windows@.
3145
3146 @item tls_model ("@var{tls_model}")
3147 @cindex @code{tls_model} attribute
3148 The @code{tls_model} attribute sets thread-local storage model
3149 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
3150 overriding @option{-ftls-model=} command line switch on a per-variable
3151 basis.
3152 The @var{tls_model} argument should be one of @code{global-dynamic},
3153 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
3154
3155 Not all targets support this attribute.
3156
3157 @item unused
3158 This attribute, attached to a variable, means that the variable is meant
3159 to be possibly unused.  GCC will not produce a warning for this
3160 variable.
3161
3162 @item vector_size (@var{bytes})
3163 This attribute specifies the vector size for the variable, measured in
3164 bytes.  For example, the declaration:
3165
3166 @smallexample
3167 int foo __attribute__ ((vector_size (16)));
3168 @end smallexample
3169
3170 @noindent
3171 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
3172 divided into @code{int} sized units.  Assuming a 32-bit int (a vector of
3173 4 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@.
3174
3175 This attribute is only applicable to integral and float scalars,
3176 although arrays, pointers, and function return values are allowed in
3177 conjunction with this construct.
3178
3179 Aggregates with this attribute are invalid, even if they are of the same
3180 size as a corresponding scalar.  For example, the declaration:
3181
3182 @smallexample
3183 struct S @{ int a; @};
3184 struct S  __attribute__ ((vector_size (16))) foo;
3185 @end smallexample
3186
3187 @noindent
3188 is invalid even if the size of the structure is the same as the size of
3189 the @code{int}.
3190
3191 @item selectany
3192 The @code{selectany} attribute causes an initialized global variable to
3193 have link-once semantics.  When multiple definitions of the variable are
3194 encountered by the linker, the first is selected and the remainder are
3195 discarded.  Following usage by the Microsoft compiler, the linker is told
3196 @emph{not} to warn about size or content differences of the multiple
3197 definitions.
3198
3199 Although the primary usage of this attribute is for POD types, the
3200 attribute can also be applied to global C++ objects that are initialized
3201 by a constructor.  In this case, the static initialization and destruction
3202 code for the object is emitted in each translation defining the object,
3203 but the calls to the constructor and destructor are protected by a
3204 link-once guard variable.
3205
3206 The @code{selectany} attribute is only available on Microsoft Windows
3207 targets.  You can use @code{__declspec (selectany)} as a synonym for
3208 @code{__attribute__ ((selectany))} for compatibility with other
3209 compilers.
3210
3211 @item weak
3212 The @code{weak} attribute is described in @xref{Function Attributes}.
3213
3214 @item dllimport
3215 The @code{dllimport} attribute is described in @xref{Function Attributes}.
3216
3217 @item dlexport
3218 The @code{dllexport} attribute is described in @xref{Function Attributes}.
3219
3220 @end table
3221
3222 @subsection M32R/D Variable Attributes
3223
3224 One attribute is currently defined for the M32R/D@.
3225
3226 @table @code
3227 @item model (@var{model-name})
3228 @cindex variable addressability on the M32R/D
3229 Use this attribute on the M32R/D to set the addressability of an object.
3230 The identifier @var{model-name} is one of @code{small}, @code{medium},
3231 or @code{large}, representing each of the code models.
3232
3233 Small model objects live in the lower 16MB of memory (so that their
3234 addresses can be loaded with the @code{ld24} instruction).
3235
3236 Medium and large model objects may live anywhere in the 32-bit address space
3237 (the compiler will generate @code{seth/add3} instructions to load their
3238 addresses).
3239 @end table
3240
3241 @anchor{i386 Variable Attributes}
3242 @subsection i386 Variable Attributes
3243
3244 Two attributes are currently defined for i386 configurations:
3245 @code{ms_struct} and @code{gcc_struct}
3246
3247 @table @code
3248 @item ms_struct
3249 @itemx gcc_struct
3250 @cindex @code{ms_struct} attribute
3251 @cindex @code{gcc_struct} attribute
3252
3253 If @code{packed} is used on a structure, or if bit-fields are used
3254 it may be that the Microsoft ABI packs them differently
3255 than GCC would normally pack them.  Particularly when moving packed
3256 data between functions compiled with GCC and the native Microsoft compiler
3257 (either via function call or as data in a file), it may be necessary to access
3258 either format.
3259
3260 Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
3261 compilers to match the native Microsoft compiler.
3262
3263 The Microsoft structure layout algorithm is fairly simple with the exception
3264 of the bitfield packing:
3265
3266 The padding and alignment of members of structures and whether a bit field
3267 can straddle a storage-unit boundary
3268
3269 @enumerate
3270 @item Structure members are stored sequentially in the order in which they are
3271 declared: the first member has the lowest memory address and the last member
3272 the highest.
3273
3274 @item Every data object has an alignment-requirement. The alignment-requirement
3275 for all data except structures, unions, and arrays is either the size of the
3276 object or the current packing size (specified with either the aligned attribute
3277 or the pack pragma), whichever is less. For structures,  unions, and arrays,
3278 the alignment-requirement is the largest alignment-requirement of its members.
3279 Every object is allocated an offset so that:
3280
3281 offset %  alignment-requirement == 0
3282
3283 @item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation
3284 unit if the integral types are the same size and if the next bit field fits
3285 into the current allocation unit without crossing the boundary imposed by the
3286 common alignment requirements of the bit fields.
3287 @end enumerate
3288
3289 Handling of zero-length bitfields:
3290
3291 MSVC interprets zero-length bitfields in the following ways:
3292
3293 @enumerate
3294 @item If a zero-length bitfield is inserted between two bitfields that would
3295 normally be coalesced, the bitfields will not be coalesced.
3296
3297 For example:
3298
3299 @smallexample
3300 struct
3301  @{
3302    unsigned long bf_1 : 12;
3303    unsigned long : 0;
3304    unsigned long bf_2 : 12;
3305  @} t1;
3306 @end smallexample
3307
3308 The size of @code{t1} would be 8 bytes with the zero-length bitfield.  If the
3309 zero-length bitfield were removed, @code{t1}'s size would be 4 bytes.
3310
3311 @item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the
3312 alignment of the zero-length bitfield is greater than the member that follows it,
3313 @code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield.
3314
3315 For example:
3316
3317 @smallexample
3318 struct
3319  @{
3320    char foo : 4;
3321    short : 0;
3322    char bar;
3323  @} t2;
3324
3325 struct
3326  @{
3327    char foo : 4;
3328    short : 0;
3329    double bar;
3330  @} t3;
3331 @end smallexample
3332
3333 For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1.
3334 Accordingly, the size of @code{t2} will be 4.  For @code{t3}, the zero-length
3335 bitfield will not affect the alignment of @code{bar} or, as a result, the size
3336 of the structure.
3337
3338 Taking this into account, it is important to note the following:
3339
3340 @enumerate
3341 @item If a zero-length bitfield follows a normal bitfield, the type of the
3342 zero-length bitfield may affect the alignment of the structure as whole. For
3343 example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a
3344 normal bitfield, and is of type short.
3345
3346 @item Even if a zero-length bitfield is not followed by a normal bitfield, it may
3347 still affect the alignment of the structure:
3348
3349 @smallexample
3350 struct
3351  @{
3352    char foo : 6;
3353    long : 0;
3354  @} t4;
3355 @end smallexample
3356
3357 Here, @code{t4} will take up 4 bytes.
3358 @end enumerate
3359
3360 @item Zero-length bitfields following non-bitfield members are ignored:
3361
3362 @smallexample
3363 struct
3364  @{
3365    char foo;
3366    long : 0;
3367    char bar;
3368  @} t5;
3369 @end smallexample
3370
3371 Here, @code{t5} will take up 2 bytes.
3372 @end enumerate
3373 @end table
3374
3375 @subsection PowerPC Variable Attributes
3376
3377 Three attributes currently are defined for PowerPC configurations:
3378 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
3379
3380 For full documentation of the struct attributes please see the
3381 documentation in the @xref{i386 Variable Attributes}, section.
3382
3383 For documentation of @code{altivec} attribute please see the
3384 documentation in the @xref{PowerPC Type Attributes}, section.
3385
3386 @subsection Xstormy16 Variable Attributes
3387
3388 One attribute is currently defined for xstormy16 configurations:
3389 @code{below100}
3390
3391 @table @code
3392 @item below100
3393 @cindex @code{below100} attribute
3394
3395 If a variable has the @code{below100} attribute (@code{BELOW100} is
3396 allowed also), GCC will place the variable in the first 0x100 bytes of
3397 memory and use special opcodes to access it.  Such variables will be
3398 placed in either the @code{.bss_below100} section or the
3399 @code{.data_below100} section.
3400
3401 @end table
3402
3403 @node Type Attributes
3404 @section Specifying Attributes of Types
3405 @cindex attribute of types
3406 @cindex type attributes
3407
3408 The keyword @code{__attribute__} allows you to specify special
3409 attributes of @code{struct} and @code{union} types when you define
3410 such types.  This keyword is followed by an attribute specification
3411 inside double parentheses.  Seven attributes are currently defined for
3412 types: @code{aligned}, @code{packed}, @code{transparent_union},
3413 @code{unused}, @code{deprecated}, @code{visibility}, and
3414 @code{may_alias}.  Other attributes are defined for functions
3415 (@pxref{Function Attributes}) and for variables (@pxref{Variable
3416 Attributes}).
3417
3418 You may also specify any one of these attributes with @samp{__}
3419 preceding and following its keyword.  This allows you to use these
3420 attributes in header files without being concerned about a possible
3421 macro of the same name.  For example, you may use @code{__aligned__}
3422 instead of @code{aligned}.
3423
3424 You may specify type attributes either in a @code{typedef} declaration
3425 or in an enum, struct or union type declaration or definition.
3426
3427 For an enum, struct or union type, you may specify attributes either
3428 between the enum, struct or union tag and the name of the type, or
3429 just past the closing curly brace of the @emph{definition}.  The
3430 former syntax is preferred.
3431
3432 @xref{Attribute Syntax}, for details of the exact syntax for using
3433 attributes.
3434
3435 @table @code
3436 @cindex @code{aligned} attribute
3437 @item aligned (@var{alignment})
3438 This attribute specifies a minimum alignment (in bytes) for variables
3439 of the specified type.  For example, the declarations:
3440
3441 @smallexample
3442 struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
3443 typedef int more_aligned_int __attribute__ ((aligned (8)));
3444 @end smallexample
3445
3446 @noindent
3447 force the compiler to insure (as far as it can) that each variable whose
3448 type is @code{struct S} or @code{more_aligned_int} will be allocated and
3449 aligned @emph{at least} on a 8-byte boundary.  On a SPARC, having all
3450 variables of type @code{struct S} aligned to 8-byte boundaries allows
3451 the compiler to use the @code{ldd} and @code{std} (doubleword load and
3452 store) instructions when copying one variable of type @code{struct S} to
3453 another, thus improving run-time efficiency.
3454
3455 Note that the alignment of any given @code{struct} or @code{union} type
3456 is required by the ISO C standard to be at least a perfect multiple of
3457 the lowest common multiple of the alignments of all of the members of
3458 the @code{struct} or @code{union} in question.  This means that you @emph{can}
3459 effectively adjust the alignment of a @code{struct} or @code{union}
3460 type by attaching an @code{aligned} attribute to any one of the members
3461 of such a type, but the notation illustrated in the example above is a
3462 more obvious, intuitive, and readable way to request the compiler to
3463 adjust the alignment of an entire @code{struct} or @code{union} type.
3464
3465 As in the preceding example, you can explicitly specify the alignment
3466 (in bytes) that you wish the compiler to use for a given @code{struct}
3467 or @code{union} type.  Alternatively, you can leave out the alignment factor
3468 and just ask the compiler to align a type to the maximum
3469 useful alignment for the target machine you are compiling for.  For
3470 example, you could write:
3471
3472 @smallexample
3473 struct S @{ short f[3]; @} __attribute__ ((aligned));
3474 @end smallexample
3475
3476 Whenever you leave out the alignment factor in an @code{aligned}
3477 attribute specification, the compiler automatically sets the alignment
3478 for the type to the largest alignment which is ever used for any data
3479 type on the target machine you are compiling for.  Doing this can often
3480 make copy operations more efficient, because the compiler can use
3481 whatever instructions copy the biggest chunks of memory when performing
3482 copies to or from the variables which have types that you have aligned
3483 this way.
3484
3485 In the example above, if the size of each @code{short} is 2 bytes, then
3486 the size of the entire @code{struct S} type is 6 bytes.  The smallest
3487 power of two which is greater than or equal to that is 8, so the
3488 compiler sets the alignment for the entire @code{struct S} type to 8
3489 bytes.
3490
3491 Note that although you can ask the compiler to select a time-efficient
3492 alignment for a given type and then declare only individual stand-alone
3493 objects of that type, the compiler's ability to select a time-efficient
3494 alignment is primarily useful only when you plan to create arrays of
3495 variables having the relevant (efficiently aligned) type.  If you
3496 declare or use arrays of variables of an efficiently-aligned type, then
3497 it is likely that your program will also be doing pointer arithmetic (or
3498 subscripting, which amounts to the same thing) on pointers to the
3499 relevant type, and the code that the compiler generates for these
3500 pointer arithmetic operations will often be more efficient for
3501 efficiently-aligned types than for other types.
3502
3503 The @code{aligned} attribute can only increase the alignment; but you
3504 can decrease it by specifying @code{packed} as well.  See below.
3505
3506 Note that the effectiveness of @code{aligned} attributes may be limited
3507 by inherent limitations in your linker.  On many systems, the linker is
3508 only able to arrange for variables to be aligned up to a certain maximum
3509 alignment.  (For some linkers, the maximum supported alignment may
3510 be very very small.)  If your linker is only able to align variables
3511 up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
3512 in an @code{__attribute__} will still only provide you with 8 byte
3513 alignment.  See your linker documentation for further information.
3514
3515 @item packed
3516 This attribute, attached to @code{struct} or @code{union} type
3517 definition, specifies that each member (other than zero-width bitfields)
3518 of the structure or union is placed to minimize the memory required.  When
3519 attached to an @code{enum} definition, it indicates that the smallest
3520 integral type should be used.
3521
3522 @opindex fshort-enums
3523 Specifying this attribute for @code{struct} and @code{union} types is
3524 equivalent to specifying the @code{packed} attribute on each of the
3525 structure or union members.  Specifying the @option{-fshort-enums}
3526 flag on the line is equivalent to specifying the @code{packed}
3527 attribute on all @code{enum} definitions.
3528
3529 In the following example @code{struct my_packed_struct}'s members are
3530 packed closely together, but the internal layout of its @code{s} member
3531 is not packed---to do that, @code{struct my_unpacked_struct} would need to
3532 be packed too.
3533
3534 @smallexample
3535 struct my_unpacked_struct
3536  @{
3537     char c;
3538     int i;
3539  @};
3540
3541 struct __attribute__ ((__packed__)) my_packed_struct
3542   @{
3543      char c;
3544      int  i;
3545      struct my_unpacked_struct s;
3546   @};
3547 @end smallexample
3548
3549 You may only specify this attribute on the definition of a @code{enum},
3550 @code{struct} or @code{union}, not on a @code{typedef} which does not
3551 also define the enumerated type, structure or union.
3552
3553 @item transparent_union
3554 This attribute, attached to a @code{union} type definition, indicates
3555 that any function parameter having that union type causes calls to that
3556 function to be treated in a special way.
3557
3558 First, the argument corresponding to a transparent union type can be of
3559 any type in the union; no cast is required.  Also, if the union contains
3560 a pointer type, the corresponding argument can be a null pointer
3561 constant or a void pointer expression; and if the union contains a void
3562 pointer type, the corresponding argument can be any pointer expression.
3563 If the union member type is a pointer, qualifiers like @code{const} on
3564 the referenced type must be respected, just as with normal pointer
3565 conversions.
3566
3567 Second, the argument is passed to the function using the calling
3568 conventions of the first member of the transparent union, not the calling
3569 conventions of the union itself.  All members of the union must have the
3570 same machine representation; this is necessary for this argument passing
3571 to work properly.
3572
3573 Transparent unions are designed for library functions that have multiple
3574 interfaces for compatibility reasons.  For example, suppose the
3575 @code{wait} function must accept either a value of type @code{int *} to
3576 comply with Posix, or a value of type @code{union wait *} to comply with
3577 the 4.1BSD interface.  If @code{wait}'s parameter were @code{void *},
3578 @code{wait} would accept both kinds of arguments, but it would also
3579 accept any other pointer type and this would make argument type checking
3580 less useful.  Instead, @code{<sys/wait.h>} might define the interface
3581 as follows:
3582
3583 @smallexample
3584 typedef union
3585   @{
3586     int *__ip;
3587     union wait *__up;
3588   @} wait_status_ptr_t __attribute__ ((__transparent_union__));