OSDN Git Service

788cbfc14a0339194691c60e10d7ac4edfe29c1d
[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, 2007 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 Types. 
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 Types
820 @cindex decimal floating types
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 As an extension, the GNU C compiler supports decimal floating types as
832 defined in the N1176 draft of ISO/IEC WDTR24732.  Support for decimal
833 floating types in GCC will evolve as the draft technical report changes.
834 Calling conventions for any target might also change.  Not all targets
835 support decimal floating types.
836
837 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
838 @code{_Decimal128}.  They use a radix of ten, unlike the floating types
839 @code{float}, @code{double}, and @code{long double} whose radix is not
840 specified by the C standard but is usually two.
841
842 Support for decimal floating types includes the arithmetic operators
843 add, subtract, multiply, divide; unary arithmetic operators;
844 relational operators; equality operators; and conversions to and from
845 integer and other floating types.  Use a suffix @samp{df} or
846 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
847 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
848 @code{_Decimal128}.
849
850 GCC support of decimal float as specified by the draft technical report
851 is incomplete:
852
853 @itemize @bullet
854 @item
855 Translation time data type (TTDT) is not supported.
856
857 @item
858 When the value of a decimal floating type cannot be represented in the
859 integer type to which it is being converted, the result is undefined
860 rather than the result value specified by the draft technical report.
861 @end itemize
862
863 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
864 are supported by the DWARF2 debug information format.
865
866 @node Hex Floats
867 @section Hex Floats
868 @cindex hex floats
869
870 ISO C99 supports floating-point numbers written not only in the usual
871 decimal notation, such as @code{1.55e1}, but also numbers such as
872 @code{0x1.fp3} written in hexadecimal format.  As a GNU extension, GCC
873 supports this in C89 mode (except in some cases when strictly
874 conforming) and in C++.  In that format the
875 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
876 mandatory.  The exponent is a decimal number that indicates the power of
877 2 by which the significant part will be multiplied.  Thus @samp{0x1.f} is
878 @tex
879 $1 {15\over16}$,
880 @end tex
881 @ifnottex
882 1 15/16,
883 @end ifnottex
884 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
885 is the same as @code{1.55e1}.
886
887 Unlike for floating-point numbers in the decimal notation the exponent
888 is always required in the hexadecimal notation.  Otherwise the compiler
889 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}.  This
890 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
891 extension for floating-point constants of type @code{float}.
892
893 @node Zero Length
894 @section Arrays of Length Zero
895 @cindex arrays of length zero
896 @cindex zero-length arrays
897 @cindex length-zero arrays
898 @cindex flexible array members
899
900 Zero-length arrays are allowed in GNU C@.  They are very useful as the
901 last element of a structure which is really a header for a variable-length
902 object:
903
904 @smallexample
905 struct line @{
906   int length;
907   char contents[0];
908 @};
909
910 struct line *thisline = (struct line *)
911   malloc (sizeof (struct line) + this_length);
912 thisline->length = this_length;
913 @end smallexample
914
915 In ISO C90, you would have to give @code{contents} a length of 1, which
916 means either you waste space or complicate the argument to @code{malloc}.
917
918 In ISO C99, you would use a @dfn{flexible array member}, which is
919 slightly different in syntax and semantics:
920
921 @itemize @bullet
922 @item
923 Flexible array members are written as @code{contents[]} without
924 the @code{0}.
925
926 @item
927 Flexible array members have incomplete type, and so the @code{sizeof}
928 operator may not be applied.  As a quirk of the original implementation
929 of zero-length arrays, @code{sizeof} evaluates to zero.
930
931 @item
932 Flexible array members may only appear as the last member of a
933 @code{struct} that is otherwise non-empty.
934
935 @item
936 A structure containing a flexible array member, or a union containing
937 such a structure (possibly recursively), may not be a member of a
938 structure or an element of an array.  (However, these uses are
939 permitted by GCC as extensions.)
940 @end itemize
941
942 GCC versions before 3.0 allowed zero-length arrays to be statically
943 initialized, as if they were flexible arrays.  In addition to those
944 cases that were useful, it also allowed initializations in situations
945 that would corrupt later data.  Non-empty initialization of zero-length
946 arrays is now treated like any case where there are more initializer
947 elements than the array holds, in that a suitable warning about "excess
948 elements in array" is given, and the excess elements (all of them, in
949 this case) are ignored.
950
951 Instead GCC allows static initialization of flexible array members.
952 This is equivalent to defining a new structure containing the original
953 structure followed by an array of sufficient size to contain the data.
954 I.e.@: in the following, @code{f1} is constructed as if it were declared
955 like @code{f2}.
956
957 @smallexample
958 struct f1 @{
959   int x; int y[];
960 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
961
962 struct f2 @{
963   struct f1 f1; int data[3];
964 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
965 @end smallexample
966
967 @noindent
968 The convenience of this extension is that @code{f1} has the desired
969 type, eliminating the need to consistently refer to @code{f2.f1}.
970
971 This has symmetry with normal static arrays, in that an array of
972 unknown size is also written with @code{[]}.
973
974 Of course, this extension only makes sense if the extra data comes at
975 the end of a top-level object, as otherwise we would be overwriting
976 data at subsequent offsets.  To avoid undue complication and confusion
977 with initialization of deeply nested arrays, we simply disallow any
978 non-empty initialization except when the structure is the top-level
979 object.  For example:
980
981 @smallexample
982 struct foo @{ int x; int y[]; @};
983 struct bar @{ struct foo z; @};
984
985 struct foo a = @{ 1, @{ 2, 3, 4 @} @};        // @r{Valid.}
986 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @};    // @r{Invalid.}
987 struct bar c = @{ @{ 1, @{ @} @} @};            // @r{Valid.}
988 struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @};  // @r{Invalid.}
989 @end smallexample
990
991 @node Empty Structures
992 @section Structures With No Members
993 @cindex empty structures
994 @cindex zero-size structures
995
996 GCC permits a C structure to have no members:
997
998 @smallexample
999 struct empty @{
1000 @};
1001 @end smallexample
1002
1003 The structure will have size zero.  In C++, empty structures are part
1004 of the language.  G++ treats empty structures as if they had a single
1005 member of type @code{char}.
1006
1007 @node Variable Length
1008 @section Arrays of Variable Length
1009 @cindex variable-length arrays
1010 @cindex arrays of variable length
1011 @cindex VLAs
1012
1013 Variable-length automatic arrays are allowed in ISO C99, and as an
1014 extension GCC accepts them in C89 mode and in C++.  (However, GCC's
1015 implementation of variable-length arrays does not yet conform in detail
1016 to the ISO C99 standard.)  These arrays are
1017 declared like any other automatic arrays, but with a length that is not
1018 a constant expression.  The storage is allocated at the point of
1019 declaration and deallocated when the brace-level is exited.  For
1020 example:
1021
1022 @smallexample
1023 FILE *
1024 concat_fopen (char *s1, char *s2, char *mode)
1025 @{
1026   char str[strlen (s1) + strlen (s2) + 1];
1027   strcpy (str, s1);
1028   strcat (str, s2);
1029   return fopen (str, mode);
1030 @}
1031 @end smallexample
1032
1033 @cindex scope of a variable length array
1034 @cindex variable-length array scope
1035 @cindex deallocating variable length arrays
1036 Jumping or breaking out of the scope of the array name deallocates the
1037 storage.  Jumping into the scope is not allowed; you get an error
1038 message for it.
1039
1040 @cindex @code{alloca} vs variable-length arrays
1041 You can use the function @code{alloca} to get an effect much like
1042 variable-length arrays.  The function @code{alloca} is available in
1043 many other C implementations (but not in all).  On the other hand,
1044 variable-length arrays are more elegant.
1045
1046 There are other differences between these two methods.  Space allocated
1047 with @code{alloca} exists until the containing @emph{function} returns.
1048 The space for a variable-length array is deallocated as soon as the array
1049 name's scope ends.  (If you use both variable-length arrays and
1050 @code{alloca} in the same function, deallocation of a variable-length array
1051 will also deallocate anything more recently allocated with @code{alloca}.)
1052
1053 You can also use variable-length arrays as arguments to functions:
1054
1055 @smallexample
1056 struct entry
1057 tester (int len, char data[len][len])
1058 @{
1059   /* @r{@dots{}} */
1060 @}
1061 @end smallexample
1062
1063 The length of an array is computed once when the storage is allocated
1064 and is remembered for the scope of the array in case you access it with
1065 @code{sizeof}.
1066
1067 If you want to pass the array first and the length afterward, you can
1068 use a forward declaration in the parameter list---another GNU extension.
1069
1070 @smallexample
1071 struct entry
1072 tester (int len; char data[len][len], int len)
1073 @{
1074   /* @r{@dots{}} */
1075 @}
1076 @end smallexample
1077
1078 @cindex parameter forward declaration
1079 The @samp{int len} before the semicolon is a @dfn{parameter forward
1080 declaration}, and it serves the purpose of making the name @code{len}
1081 known when the declaration of @code{data} is parsed.
1082
1083 You can write any number of such parameter forward declarations in the
1084 parameter list.  They can be separated by commas or semicolons, but the
1085 last one must end with a semicolon, which is followed by the ``real''
1086 parameter declarations.  Each forward declaration must match a ``real''
1087 declaration in parameter name and data type.  ISO C99 does not support
1088 parameter forward declarations.
1089
1090 @node Variadic Macros
1091 @section Macros with a Variable Number of Arguments.
1092 @cindex variable number of arguments
1093 @cindex macro with variable arguments
1094 @cindex rest argument (in macro)
1095 @cindex variadic macros
1096
1097 In the ISO C standard of 1999, a macro can be declared to accept a
1098 variable number of arguments much as a function can.  The syntax for
1099 defining the macro is similar to that of a function.  Here is an
1100 example:
1101
1102 @smallexample
1103 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1104 @end smallexample
1105
1106 Here @samp{@dots{}} is a @dfn{variable argument}.  In the invocation of
1107 such a macro, it represents the zero or more tokens until the closing
1108 parenthesis that ends the invocation, including any commas.  This set of
1109 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1110 wherever it appears.  See the CPP manual for more information.
1111
1112 GCC has long supported variadic macros, and used a different syntax that
1113 allowed you to give a name to the variable arguments just like any other
1114 argument.  Here is an example:
1115
1116 @smallexample
1117 #define debug(format, args...) fprintf (stderr, format, args)
1118 @end smallexample
1119
1120 This is in all ways equivalent to the ISO C example above, but arguably
1121 more readable and descriptive.
1122
1123 GNU CPP has two further variadic macro extensions, and permits them to
1124 be used with either of the above forms of macro definition.
1125
1126 In standard C, you are not allowed to leave the variable argument out
1127 entirely; but you are allowed to pass an empty argument.  For example,
1128 this invocation is invalid in ISO C, because there is no comma after
1129 the string:
1130
1131 @smallexample
1132 debug ("A message")
1133 @end smallexample
1134
1135 GNU CPP permits you to completely omit the variable arguments in this
1136 way.  In the above examples, the compiler would complain, though since
1137 the expansion of the macro still has the extra comma after the format
1138 string.
1139
1140 To help solve this problem, CPP behaves specially for variable arguments
1141 used with the token paste operator, @samp{##}.  If instead you write
1142
1143 @smallexample
1144 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1145 @end smallexample
1146
1147 and if the variable arguments are omitted or empty, the @samp{##}
1148 operator causes the preprocessor to remove the comma before it.  If you
1149 do provide some variable arguments in your macro invocation, GNU CPP
1150 does not complain about the paste operation and instead places the
1151 variable arguments after the comma.  Just like any other pasted macro
1152 argument, these arguments are not macro expanded.
1153
1154 @node Escaped Newlines
1155 @section Slightly Looser Rules for Escaped Newlines
1156 @cindex escaped newlines
1157 @cindex newlines (escaped)
1158
1159 Recently, the preprocessor has relaxed its treatment of escaped
1160 newlines.  Previously, the newline had to immediately follow a
1161 backslash.  The current implementation allows whitespace in the form
1162 of spaces, horizontal and vertical tabs, and form feeds between the
1163 backslash and the subsequent newline.  The preprocessor issues a
1164 warning, but treats it as a valid escaped newline and combines the two
1165 lines to form a single logical line.  This works within comments and
1166 tokens, as well as between tokens.  Comments are @emph{not} treated as
1167 whitespace for the purposes of this relaxation, since they have not
1168 yet been replaced with spaces.
1169
1170 @node Subscripting
1171 @section Non-Lvalue Arrays May Have Subscripts
1172 @cindex subscripting
1173 @cindex arrays, non-lvalue
1174
1175 @cindex subscripting and function values
1176 In ISO C99, arrays that are not lvalues still decay to pointers, and
1177 may be subscripted, although they may not be modified or used after
1178 the next sequence point and the unary @samp{&} operator may not be
1179 applied to them.  As an extension, GCC allows such arrays to be
1180 subscripted in C89 mode, though otherwise they do not decay to
1181 pointers outside C99 mode.  For example,
1182 this is valid in GNU C though not valid in C89:
1183
1184 @smallexample
1185 @group
1186 struct foo @{int a[4];@};
1187
1188 struct foo f();
1189
1190 bar (int index)
1191 @{
1192   return f().a[index];
1193 @}
1194 @end group
1195 @end smallexample
1196
1197 @node Pointer Arith
1198 @section Arithmetic on @code{void}- and Function-Pointers
1199 @cindex void pointers, arithmetic
1200 @cindex void, size of pointer to
1201 @cindex function pointers, arithmetic
1202 @cindex function, size of pointer to
1203
1204 In GNU C, addition and subtraction operations are supported on pointers to
1205 @code{void} and on pointers to functions.  This is done by treating the
1206 size of a @code{void} or of a function as 1.
1207
1208 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1209 and on function types, and returns 1.
1210
1211 @opindex Wpointer-arith
1212 The option @option{-Wpointer-arith} requests a warning if these extensions
1213 are used.
1214
1215 @node Initializers
1216 @section Non-Constant Initializers
1217 @cindex initializers, non-constant
1218 @cindex non-constant initializers
1219
1220 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1221 automatic variable are not required to be constant expressions in GNU C@.
1222 Here is an example of an initializer with run-time varying elements:
1223
1224 @smallexample
1225 foo (float f, float g)
1226 @{
1227   float beat_freqs[2] = @{ f-g, f+g @};
1228   /* @r{@dots{}} */
1229 @}
1230 @end smallexample
1231
1232 @node Compound Literals
1233 @section Compound Literals
1234 @cindex constructor expressions
1235 @cindex initializations in expressions
1236 @cindex structures, constructor expression
1237 @cindex expressions, constructor
1238 @cindex compound literals
1239 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
1240
1241 ISO C99 supports compound literals.  A compound literal looks like
1242 a cast containing an initializer.  Its value is an object of the
1243 type specified in the cast, containing the elements specified in
1244 the initializer; it is an lvalue.  As an extension, GCC supports
1245 compound literals in C89 mode and in C++.
1246
1247 Usually, the specified type is a structure.  Assume that
1248 @code{struct foo} and @code{structure} are declared as shown:
1249
1250 @smallexample
1251 struct foo @{int a; char b[2];@} structure;
1252 @end smallexample
1253
1254 @noindent
1255 Here is an example of constructing a @code{struct foo} with a compound literal:
1256
1257 @smallexample
1258 structure = ((struct foo) @{x + y, 'a', 0@});
1259 @end smallexample
1260
1261 @noindent
1262 This is equivalent to writing the following:
1263
1264 @smallexample
1265 @{
1266   struct foo temp = @{x + y, 'a', 0@};
1267   structure = temp;
1268 @}
1269 @end smallexample
1270
1271 You can also construct an array.  If all the elements of the compound literal
1272 are (made up of) simple constant expressions, suitable for use in
1273 initializers of objects of static storage duration, then the compound
1274 literal can be coerced to a pointer to its first element and used in
1275 such an initializer, as shown here:
1276
1277 @smallexample
1278 char **foo = (char *[]) @{ "x", "y", "z" @};
1279 @end smallexample
1280
1281 Compound literals for scalar types and union types are is
1282 also allowed, but then the compound literal is equivalent
1283 to a cast.
1284
1285 As a GNU extension, GCC allows initialization of objects with static storage
1286 duration by compound literals (which is not possible in ISO C99, because
1287 the initializer is not a constant).
1288 It is handled as if the object was initialized only with the bracket
1289 enclosed list if the types of the compound literal and the object match.
1290 The initializer list of the compound literal must be constant.
1291 If the object being initialized has array type of unknown size, the size is
1292 determined by compound literal size.
1293
1294 @smallexample
1295 static struct foo x = (struct foo) @{1, 'a', 'b'@};
1296 static int y[] = (int []) @{1, 2, 3@};
1297 static int z[] = (int [3]) @{1@};
1298 @end smallexample
1299
1300 @noindent
1301 The above lines are equivalent to the following:
1302 @smallexample
1303 static struct foo x = @{1, 'a', 'b'@};
1304 static int y[] = @{1, 2, 3@};
1305 static int z[] = @{1, 0, 0@};
1306 @end smallexample
1307
1308 @node Designated Inits
1309 @section Designated Initializers
1310 @cindex initializers with labeled elements
1311 @cindex labeled elements in initializers
1312 @cindex case labels in initializers
1313 @cindex designated initializers
1314
1315 Standard C89 requires the elements of an initializer to appear in a fixed
1316 order, the same as the order of the elements in the array or structure
1317 being initialized.
1318
1319 In ISO C99 you can give the elements in any order, specifying the array
1320 indices or structure field names they apply to, and GNU C allows this as
1321 an extension in C89 mode as well.  This extension is not
1322 implemented in GNU C++.
1323
1324 To specify an array index, write
1325 @samp{[@var{index}] =} before the element value.  For example,
1326
1327 @smallexample
1328 int a[6] = @{ [4] = 29, [2] = 15 @};
1329 @end smallexample
1330
1331 @noindent
1332 is equivalent to
1333
1334 @smallexample
1335 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
1336 @end smallexample
1337
1338 @noindent
1339 The index values must be constant expressions, even if the array being
1340 initialized is automatic.
1341
1342 An alternative syntax for this which has been obsolete since GCC 2.5 but
1343 GCC still accepts is to write @samp{[@var{index}]} before the element
1344 value, with no @samp{=}.
1345
1346 To initialize a range of elements to the same value, write
1347 @samp{[@var{first} ... @var{last}] = @var{value}}.  This is a GNU
1348 extension.  For example,
1349
1350 @smallexample
1351 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
1352 @end smallexample
1353
1354 @noindent
1355 If the value in it has side-effects, the side-effects will happen only once,
1356 not for each initialized field by the range initializer.
1357
1358 @noindent
1359 Note that the length of the array is the highest value specified
1360 plus one.
1361
1362 In a structure initializer, specify the name of a field to initialize
1363 with @samp{.@var{fieldname} =} before the element value.  For example,
1364 given the following structure,
1365
1366 @smallexample
1367 struct point @{ int x, y; @};
1368 @end smallexample
1369
1370 @noindent
1371 the following initialization
1372
1373 @smallexample
1374 struct point p = @{ .y = yvalue, .x = xvalue @};
1375 @end smallexample
1376
1377 @noindent
1378 is equivalent to
1379
1380 @smallexample
1381 struct point p = @{ xvalue, yvalue @};
1382 @end smallexample
1383
1384 Another syntax which has the same meaning, obsolete since GCC 2.5, is
1385 @samp{@var{fieldname}:}, as shown here:
1386
1387 @smallexample
1388 struct point p = @{ y: yvalue, x: xvalue @};
1389 @end smallexample
1390
1391 @cindex designators
1392 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
1393 @dfn{designator}.  You can also use a designator (or the obsolete colon
1394 syntax) when initializing a union, to specify which element of the union
1395 should be used.  For example,
1396
1397 @smallexample
1398 union foo @{ int i; double d; @};
1399
1400 union foo f = @{ .d = 4 @};
1401 @end smallexample
1402
1403 @noindent
1404 will convert 4 to a @code{double} to store it in the union using
1405 the second element.  By contrast, casting 4 to type @code{union foo}
1406 would store it into the union as the integer @code{i}, since it is
1407 an integer.  (@xref{Cast to Union}.)
1408
1409 You can combine this technique of naming elements with ordinary C
1410 initialization of successive elements.  Each initializer element that
1411 does not have a designator applies to the next consecutive element of the
1412 array or structure.  For example,
1413
1414 @smallexample
1415 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
1416 @end smallexample
1417
1418 @noindent
1419 is equivalent to
1420
1421 @smallexample
1422 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
1423 @end smallexample
1424
1425 Labeling the elements of an array initializer is especially useful
1426 when the indices are characters or belong to an @code{enum} type.
1427 For example:
1428
1429 @smallexample
1430 int whitespace[256]
1431   = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
1432       ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
1433 @end smallexample
1434
1435 @cindex designator lists
1436 You can also write a series of @samp{.@var{fieldname}} and
1437 @samp{[@var{index}]} designators before an @samp{=} to specify a
1438 nested subobject to initialize; the list is taken relative to the
1439 subobject corresponding to the closest surrounding brace pair.  For
1440 example, with the @samp{struct point} declaration above:
1441
1442 @smallexample
1443 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
1444 @end smallexample
1445
1446 @noindent
1447 If the same field is initialized multiple times, it will have value from
1448 the last initialization.  If any such overridden initialization has
1449 side-effect, it is unspecified whether the side-effect happens or not.
1450 Currently, GCC will discard them and issue a warning.
1451
1452 @node Case Ranges
1453 @section Case Ranges
1454 @cindex case ranges
1455 @cindex ranges in case statements
1456
1457 You can specify a range of consecutive values in a single @code{case} label,
1458 like this:
1459
1460 @smallexample
1461 case @var{low} ... @var{high}:
1462 @end smallexample
1463
1464 @noindent
1465 This has the same effect as the proper number of individual @code{case}
1466 labels, one for each integer value from @var{low} to @var{high}, inclusive.
1467
1468 This feature is especially useful for ranges of ASCII character codes:
1469
1470 @smallexample
1471 case 'A' ... 'Z':
1472 @end smallexample
1473
1474 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
1475 it may be parsed wrong when you use it with integer values.  For example,
1476 write this:
1477
1478 @smallexample
1479 case 1 ... 5:
1480 @end smallexample
1481
1482 @noindent
1483 rather than this:
1484
1485 @smallexample
1486 case 1...5:
1487 @end smallexample
1488
1489 @node Cast to Union
1490 @section Cast to a Union Type
1491 @cindex cast to a union
1492 @cindex union, casting to a
1493
1494 A cast to union type is similar to other casts, except that the type
1495 specified is a union type.  You can specify the type either with
1496 @code{union @var{tag}} or with a typedef name.  A cast to union is actually
1497 a constructor though, not a cast, and hence does not yield an lvalue like
1498 normal casts.  (@xref{Compound Literals}.)
1499
1500 The types that may be cast to the union type are those of the members
1501 of the union.  Thus, given the following union and variables:
1502
1503 @smallexample
1504 union foo @{ int i; double d; @};
1505 int x;
1506 double y;
1507 @end smallexample
1508
1509 @noindent
1510 both @code{x} and @code{y} can be cast to type @code{union foo}.
1511
1512 Using the cast as the right-hand side of an assignment to a variable of
1513 union type is equivalent to storing in a member of the union:
1514
1515 @smallexample
1516 union foo u;
1517 /* @r{@dots{}} */
1518 u = (union foo) x  @equiv{}  u.i = x
1519 u = (union foo) y  @equiv{}  u.d = y
1520 @end smallexample
1521
1522 You can also use the union cast as a function argument:
1523
1524 @smallexample
1525 void hack (union foo);
1526 /* @r{@dots{}} */
1527 hack ((union foo) x);
1528 @end smallexample
1529
1530 @node Mixed Declarations
1531 @section Mixed Declarations and Code
1532 @cindex mixed declarations and code
1533 @cindex declarations, mixed with code
1534 @cindex code, mixed with declarations
1535
1536 ISO C99 and ISO C++ allow declarations and code to be freely mixed
1537 within compound statements.  As an extension, GCC also allows this in
1538 C89 mode.  For example, you could do:
1539
1540 @smallexample
1541 int i;
1542 /* @r{@dots{}} */
1543 i++;
1544 int j = i + 2;
1545 @end smallexample
1546
1547 Each identifier is visible from where it is declared until the end of
1548 the enclosing block.
1549
1550 @node Function Attributes
1551 @section Declaring Attributes of Functions
1552 @cindex function attributes
1553 @cindex declaring attributes of functions
1554 @cindex functions that never return
1555 @cindex functions that return more than once
1556 @cindex functions that have no side effects
1557 @cindex functions in arbitrary sections
1558 @cindex functions that behave like malloc
1559 @cindex @code{volatile} applied to function
1560 @cindex @code{const} applied to function
1561 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
1562 @cindex functions with non-null pointer arguments
1563 @cindex functions that are passed arguments in registers on the 386
1564 @cindex functions that pop the argument stack on the 386
1565 @cindex functions that do not pop the argument stack on the 386
1566
1567 In GNU C, you declare certain things about functions called in your program
1568 which help the compiler optimize function calls and check your code more
1569 carefully.
1570
1571 The keyword @code{__attribute__} allows you to specify special
1572 attributes when making a declaration.  This keyword is followed by an
1573 attribute specification inside double parentheses.  The following
1574 attributes are currently defined for functions on all targets:
1575 @code{noreturn}, @code{returns_twice}, @code{noinline}, @code{always_inline},
1576 @code{flatten}, @code{pure}, @code{const}, @code{nothrow}, @code{sentinel},
1577 @code{format}, @code{format_arg}, @code{no_instrument_function},
1578 @code{section}, @code{constructor}, @code{destructor}, @code{used},
1579 @code{unused}, @code{deprecated}, @code{weak}, @code{malloc},
1580 @code{alias}, @code{warn_unused_result}, @code{nonnull},
1581 @code{gnu_inline} and @code{externally_visible}, @code{hot}, @code{cold}.
1582 Several other attributes are defined for functions on particular target
1583 systems.  Other attributes, including @code{section} are supported for
1584 variables declarations (@pxref{Variable Attributes}) and for types (@pxref{Type
1585 Attributes}).
1586
1587 You may also specify attributes with @samp{__} preceding and following
1588 each keyword.  This allows you to use them in header files without
1589 being concerned about a possible macro of the same name.  For example,
1590 you may use @code{__noreturn__} instead of @code{noreturn}.
1591
1592 @xref{Attribute Syntax}, for details of the exact syntax for using
1593 attributes.
1594
1595 @table @code
1596 @c Keep this table alphabetized by attribute name.  Treat _ as space.
1597
1598 @item alias ("@var{target}")
1599 @cindex @code{alias} attribute
1600 The @code{alias} attribute causes the declaration to be emitted as an
1601 alias for another symbol, which must be specified.  For instance,
1602
1603 @smallexample
1604 void __f () @{ /* @r{Do something.} */; @}
1605 void f () __attribute__ ((weak, alias ("__f")));
1606 @end smallexample
1607
1608 defines @samp{f} to be a weak alias for @samp{__f}.  In C++, the
1609 mangled name for the target must be used.  It is an error if @samp{__f}
1610 is not defined in the same translation unit.
1611
1612 Not all target machines support this attribute.
1613
1614 @item always_inline
1615 @cindex @code{always_inline} function attribute
1616 Generally, functions are not inlined unless optimization is specified.
1617 For functions declared inline, this attribute inlines the function even
1618 if no optimization level was specified.
1619
1620 @item gnu_inline
1621 @cindex @code{gnu_inline} function attribute
1622 This attribute should be used with a function which is also declared
1623 with the @code{inline} keyword.  It directs GCC to treat the function
1624 as if it were defined in gnu89 mode even when compiling in C99 or
1625 gnu99 mode.
1626
1627 If the function is declared @code{extern}, then this definition of the
1628 function is used only for inlining.  In no case is the function
1629 compiled as a standalone function, not even if you take its address
1630 explicitly.  Such an address becomes an external reference, as if you
1631 had only declared the function, and had not defined it.  This has
1632 almost the effect of a macro.  The way to use this is to put a
1633 function definition in a header file with this attribute, and put
1634 another copy of the function, without @code{extern}, in a library
1635 file.  The definition in the header file will cause most calls to the
1636 function to be inlined.  If any uses of the function remain, they will
1637 refer to the single copy in the library.  Note that the two
1638 definitions of the functions need not be precisely the same, although
1639 if they do not have the same effect your program may behave oddly.
1640
1641 If the function is neither @code{extern} nor @code{static}, then the
1642 function is compiled as a standalone function, as well as being
1643 inlined where possible.
1644
1645 This is how GCC traditionally handled functions declared
1646 @code{inline}.  Since ISO C99 specifies a different semantics for
1647 @code{inline}, this function attribute is provided as a transition
1648 measure and as a useful feature in its own right.  This attribute is
1649 available in GCC 4.1.3 and later.  It is available if either of the
1650 preprocessor macros @code{__GNUC_GNU_INLINE__} or
1651 @code{__GNUC_STDC_INLINE__} are defined.  @xref{Inline,,An Inline
1652 Function is As Fast As a Macro}.
1653
1654 @cindex @code{flatten} function attribute
1655 @item flatten
1656 Generally, inlining into a function is limited.  For a function marked with
1657 this attribute, every call inside this function will be inlined, if possible.
1658 Whether the function itself is considered for inlining depends on its size and
1659 the current inlining parameters.  The @code{flatten} attribute only works
1660 reliably in unit-at-a-time mode.
1661
1662 @item cdecl
1663 @cindex functions that do pop the argument stack on the 386
1664 @opindex mrtd
1665 On the Intel 386, the @code{cdecl} attribute causes the compiler to
1666 assume that the calling function will pop off the stack space used to
1667 pass arguments.  This is
1668 useful to override the effects of the @option{-mrtd} switch.
1669
1670 @item const
1671 @cindex @code{const} function attribute
1672 Many functions do not examine any values except their arguments, and
1673 have no effects except the return value.  Basically this is just slightly
1674 more strict class than the @code{pure} attribute below, since function is not
1675 allowed to read global memory.
1676
1677 @cindex pointer arguments
1678 Note that a function that has pointer arguments and examines the data
1679 pointed to must @emph{not} be declared @code{const}.  Likewise, a
1680 function that calls a non-@code{const} function usually must not be
1681 @code{const}.  It does not make sense for a @code{const} function to
1682 return @code{void}.
1683
1684 The attribute @code{const} is not implemented in GCC versions earlier
1685 than 2.5.  An alternative way to declare that a function has no side
1686 effects, which works in the current version and in some older versions,
1687 is as follows:
1688
1689 @smallexample
1690 typedef int intfn ();
1691
1692 extern const intfn square;
1693 @end smallexample
1694
1695 This approach does not work in GNU C++ from 2.6.0 on, since the language
1696 specifies that the @samp{const} must be attached to the return value.
1697
1698 @item constructor
1699 @itemx destructor
1700 @itemx constructor (@var{priority})
1701 @itemx destructor (@var{priority})
1702 @cindex @code{constructor} function attribute
1703 @cindex @code{destructor} function attribute
1704 The @code{constructor} attribute causes the function to be called
1705 automatically before execution enters @code{main ()}.  Similarly, the
1706 @code{destructor} attribute causes the function to be called
1707 automatically after @code{main ()} has completed or @code{exit ()} has
1708 been called.  Functions with these attributes are useful for
1709 initializing data that will be used implicitly during the execution of
1710 the program.
1711
1712 You may provide an optional integer priority to control the order in
1713 which constructor and destructor functions are run.  A constructor
1714 with a smaller priority number runs before a constructor with a larger
1715 priority number; the opposite relationship holds for destructors.  So,
1716 if you have a constructor that allocates a resource and a destructor
1717 that deallocates the same resource, both functions typically have the
1718 same priority.  The priorities for constructor and destructor
1719 functions are the same as those specified for namespace-scope C++
1720 objects (@pxref{C++ Attributes}).
1721
1722 These attributes are not currently implemented for Objective-C@.
1723
1724 @item deprecated
1725 @cindex @code{deprecated} attribute.
1726 The @code{deprecated} attribute results in a warning if the function
1727 is used anywhere in the source file.  This is useful when identifying
1728 functions that are expected to be removed in a future version of a
1729 program.  The warning also includes the location of the declaration
1730 of the deprecated function, to enable users to easily find further
1731 information about why the function is deprecated, or what they should
1732 do instead.  Note that the warnings only occurs for uses:
1733
1734 @smallexample
1735 int old_fn () __attribute__ ((deprecated));
1736 int old_fn ();
1737 int (*fn_ptr)() = old_fn;
1738 @end smallexample
1739
1740 results in a warning on line 3 but not line 2.
1741
1742 The @code{deprecated} attribute can also be used for variables and
1743 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
1744
1745 @item dllexport
1746 @cindex @code{__declspec(dllexport)}
1747 On Microsoft Windows targets and Symbian OS targets the
1748 @code{dllexport} attribute causes the compiler to provide a global
1749 pointer to a pointer in a DLL, so that it can be referenced with the
1750 @code{dllimport} attribute.  On Microsoft Windows targets, the pointer
1751 name is formed by combining @code{_imp__} and the function or variable
1752 name.
1753
1754 You can use @code{__declspec(dllexport)} as a synonym for
1755 @code{__attribute__ ((dllexport))} for compatibility with other
1756 compilers.
1757
1758 On systems that support the @code{visibility} attribute, this
1759 attribute also implies ``default'' visibility, unless a
1760 @code{visibility} attribute is explicitly specified.  You should avoid
1761 the use of @code{dllexport} with ``hidden'' or ``internal''
1762 visibility; in the future GCC may issue an error for those cases.
1763
1764 Currently, the @code{dllexport} attribute is ignored for inlined
1765 functions, unless the @option{-fkeep-inline-functions} flag has been
1766 used.  The attribute is also ignored for undefined symbols.
1767
1768 When applied to C++ classes, the attribute marks defined non-inlined
1769 member functions and static data members as exports.  Static consts
1770 initialized in-class are not marked unless they are also defined
1771 out-of-class.
1772
1773 For Microsoft Windows targets there are alternative methods for
1774 including the symbol in the DLL's export table such as using a
1775 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
1776 the @option{--export-all} linker flag.
1777
1778 @item dllimport
1779 @cindex @code{__declspec(dllimport)}
1780 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
1781 attribute causes the compiler to reference a function or variable via
1782 a global pointer to a pointer that is set up by the DLL exporting the
1783 symbol.  The attribute implies @code{extern} storage.  On Microsoft
1784 Windows targets, the pointer name is formed by combining @code{_imp__}
1785 and the function or variable name.
1786
1787 You can use @code{__declspec(dllimport)} as a synonym for
1788 @code{__attribute__ ((dllimport))} for compatibility with other
1789 compilers.
1790
1791 Currently, the attribute is ignored for inlined functions.  If the
1792 attribute is applied to a symbol @emph{definition}, an error is reported.
1793 If a symbol previously declared @code{dllimport} is later defined, the
1794 attribute is ignored in subsequent references, and a warning is emitted.
1795 The attribute is also overridden by a subsequent declaration as
1796 @code{dllexport}.
1797
1798 When applied to C++ classes, the attribute marks non-inlined
1799 member functions and static data members as imports.  However, the
1800 attribute is ignored for virtual methods to allow creation of vtables
1801 using thunks.
1802
1803 On the SH Symbian OS target the @code{dllimport} attribute also has
1804 another affect---it can cause the vtable and run-time type information
1805 for a class to be exported.  This happens when the class has a
1806 dllimport'ed constructor or a non-inline, non-pure virtual function
1807 and, for either of those two conditions, the class also has a inline
1808 constructor or destructor and has a key function that is defined in
1809 the current translation unit.
1810
1811 For Microsoft Windows based targets the use of the @code{dllimport}
1812 attribute on functions is not necessary, but provides a small
1813 performance benefit by eliminating a thunk in the DLL@.  The use of the
1814 @code{dllimport} attribute on imported variables was required on older
1815 versions of the GNU linker, but can now be avoided by passing the
1816 @option{--enable-auto-import} switch to the GNU linker.  As with
1817 functions, using the attribute for a variable eliminates a thunk in
1818 the DLL@.
1819
1820 One drawback to using this attribute is that a pointer to a function
1821 or variable marked as @code{dllimport} cannot be used as a constant
1822 address.  On Microsoft Windows targets, the attribute can be disabled
1823 for functions by setting the @option{-mnop-fun-dllimport} flag.
1824
1825 @item eightbit_data
1826 @cindex eight bit data on the H8/300, H8/300H, and H8S
1827 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
1828 variable should be placed into the eight bit data section.
1829 The compiler will generate more efficient code for certain operations
1830 on data in the eight bit data area.  Note the eight bit data area is limited to
1831 256 bytes of data.
1832
1833 You must use GAS and GLD from GNU binutils version 2.7 or later for
1834 this attribute to work correctly.
1835
1836 @item exception_handler
1837 @cindex exception handler functions on the Blackfin processor
1838 Use this attribute on the Blackfin to indicate that the specified function
1839 is an exception handler.  The compiler will generate function entry and
1840 exit sequences suitable for use in an exception handler when this
1841 attribute is present.
1842
1843 @item far
1844 @cindex functions which handle memory bank switching
1845 On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to
1846 use a calling convention that takes care of switching memory banks when
1847 entering and leaving a function.  This calling convention is also the
1848 default when using the @option{-mlong-calls} option.
1849
1850 On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions
1851 to call and return from a function.
1852
1853 On 68HC11 the compiler will generate a sequence of instructions
1854 to invoke a board-specific routine to switch the memory bank and call the
1855 real function.  The board-specific routine simulates a @code{call}.
1856 At the end of a function, it will jump to a board-specific routine
1857 instead of using @code{rts}.  The board-specific return routine simulates
1858 the @code{rtc}.
1859
1860 @item fastcall
1861 @cindex functions that pop the argument stack on the 386
1862 On the Intel 386, the @code{fastcall} attribute causes the compiler to
1863 pass the first argument (if of integral type) in the register ECX and
1864 the second argument (if of integral type) in the register EDX@.  Subsequent
1865 and other typed arguments are passed on the stack.  The called function will
1866 pop the arguments off the stack.  If the number of arguments is variable all
1867 arguments are pushed on the stack.
1868
1869 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
1870 @cindex @code{format} function attribute
1871 @opindex Wformat
1872 The @code{format} attribute specifies that a function takes @code{printf},
1873 @code{scanf}, @code{strftime} or @code{strfmon} style arguments which
1874 should be type-checked against a format string.  For example, the
1875 declaration:
1876
1877 @smallexample
1878 extern int
1879 my_printf (void *my_object, const char *my_format, ...)
1880       __attribute__ ((format (printf, 2, 3)));
1881 @end smallexample
1882
1883 @noindent
1884 causes the compiler to check the arguments in calls to @code{my_printf}
1885 for consistency with the @code{printf} style format string argument
1886 @code{my_format}.
1887
1888 The parameter @var{archetype} determines how the format string is
1889 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}
1890 or @code{strfmon}.  (You can also use @code{__printf__},
1891 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.)  The
1892 parameter @var{string-index} specifies which argument is the format
1893 string argument (starting from 1), while @var{first-to-check} is the
1894 number of the first argument to check against the format string.  For
1895 functions where the arguments are not available to be checked (such as
1896 @code{vprintf}), specify the third parameter as zero.  In this case the
1897 compiler only checks the format string for consistency.  For
1898 @code{strftime} formats, the third parameter is required to be zero.
1899 Since non-static C++ methods have an implicit @code{this} argument, the
1900 arguments of such methods should be counted from two, not one, when
1901 giving values for @var{string-index} and @var{first-to-check}.
1902
1903 In the example above, the format string (@code{my_format}) is the second
1904 argument of the function @code{my_print}, and the arguments to check
1905 start with the third argument, so the correct parameters for the format
1906 attribute are 2 and 3.
1907
1908 @opindex ffreestanding
1909 @opindex fno-builtin
1910 The @code{format} attribute allows you to identify your own functions
1911 which take format strings as arguments, so that GCC can check the
1912 calls to these functions for errors.  The compiler always (unless
1913 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
1914 for the standard library functions @code{printf}, @code{fprintf},
1915 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
1916 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
1917 warnings are requested (using @option{-Wformat}), so there is no need to
1918 modify the header file @file{stdio.h}.  In C99 mode, the functions
1919 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
1920 @code{vsscanf} are also checked.  Except in strictly conforming C
1921 standard modes, the X/Open function @code{strfmon} is also checked as
1922 are @code{printf_unlocked} and @code{fprintf_unlocked}.
1923 @xref{C Dialect Options,,Options Controlling C Dialect}.
1924
1925 The target may provide additional types of format checks.
1926 @xref{Target Format Checks,,Format Checks Specific to Particular
1927 Target Machines}.
1928
1929 @item format_arg (@var{string-index})
1930 @cindex @code{format_arg} function attribute
1931 @opindex Wformat-nonliteral
1932 The @code{format_arg} attribute specifies that a function takes a format
1933 string for a @code{printf}, @code{scanf}, @code{strftime} or
1934 @code{strfmon} style function and modifies it (for example, to translate
1935 it into another language), so the result can be passed to a
1936 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
1937 function (with the remaining arguments to the format function the same
1938 as they would have been for the unmodified string).  For example, the
1939 declaration:
1940
1941 @smallexample
1942 extern char *
1943 my_dgettext (char *my_domain, const char *my_format)
1944       __attribute__ ((format_arg (2)));
1945 @end smallexample
1946
1947 @noindent
1948 causes the compiler to check the arguments in calls to a @code{printf},
1949 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
1950 format string argument is a call to the @code{my_dgettext} function, for
1951 consistency with the format string argument @code{my_format}.  If the
1952 @code{format_arg} attribute had not been specified, all the compiler
1953 could tell in such calls to format functions would be that the format
1954 string argument is not constant; this would generate a warning when
1955 @option{-Wformat-nonliteral} is used, but the calls could not be checked
1956 without the attribute.
1957
1958 The parameter @var{string-index} specifies which argument is the format
1959 string argument (starting from one).  Since non-static C++ methods have
1960 an implicit @code{this} argument, the arguments of such methods should
1961 be counted from two.
1962
1963 The @code{format-arg} attribute allows you to identify your own
1964 functions which modify format strings, so that GCC can check the
1965 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
1966 type function whose operands are a call to one of your own function.
1967 The compiler always treats @code{gettext}, @code{dgettext}, and
1968 @code{dcgettext} in this manner except when strict ISO C support is
1969 requested by @option{-ansi} or an appropriate @option{-std} option, or
1970 @option{-ffreestanding} or @option{-fno-builtin}
1971 is used.  @xref{C Dialect Options,,Options
1972 Controlling C Dialect}.
1973
1974 @item function_vector
1975 @cindex calling functions through the function vector on the H8/300 processors
1976 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
1977 function should be called through the function vector.  Calling a
1978 function through the function vector will reduce code size, however;
1979 the function vector has a limited size (maximum 128 entries on the H8/300
1980 and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector.
1981
1982 You must use GAS and GLD from GNU binutils version 2.7 or later for
1983 this attribute to work correctly.
1984
1985 @item interrupt
1986 @cindex interrupt handler functions
1987 Use this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, MS1, and Xstormy16
1988 ports to indicate that the specified function is an interrupt handler.
1989 The compiler will generate function entry and exit sequences suitable
1990 for use in an interrupt handler when this attribute is present.
1991
1992 Note, interrupt handlers for the Blackfin, m68k, H8/300, H8/300H, H8S, and
1993 SH processors can be specified via the @code{interrupt_handler} attribute.
1994
1995 Note, on the AVR, interrupts will be enabled inside the function.
1996
1997 Note, for the ARM, you can specify the kind of interrupt to be handled by
1998 adding an optional parameter to the interrupt attribute like this:
1999
2000 @smallexample
2001 void f () __attribute__ ((interrupt ("IRQ")));
2002 @end smallexample
2003
2004 Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@.
2005
2006 On ARMv7-M the interrupt type is ignored, and the attribute means the function
2007 may be called with a word aligned stack pointer.
2008
2009 @item interrupt_handler
2010 @cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors
2011 Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to
2012 indicate that the specified function is an interrupt handler.  The compiler
2013 will generate function entry and exit sequences suitable for use in an
2014 interrupt handler when this attribute is present.
2015
2016 @item kspisusp
2017 @cindex User stack pointer in interrupts on the Blackfin
2018 When used together with @code{interrupt_handler}, @code{exception_handler}
2019 or @code{nmi_handler}, code will be generated to load the stack pointer
2020 from the USP register in the function prologue.
2021
2022 @item long_call/short_call
2023 @cindex indirect calls on ARM
2024 This attribute specifies how a particular function is called on
2025 ARM@.  Both attributes override the @option{-mlong-calls} (@pxref{ARM Options})
2026 command line switch and @code{#pragma long_calls} settings.  The
2027 @code{long_call} attribute indicates that the function might be far
2028 away from the call site and require a different (more expensive)
2029 calling sequence.   The @code{short_call} attribute always places
2030 the offset to the function from the call site into the @samp{BL}
2031 instruction directly.
2032
2033 @item longcall/shortcall
2034 @cindex functions called via pointer on the RS/6000 and PowerPC
2035 On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute
2036 indicates that the function might be far away from the call site and
2037 require a different (more expensive) calling sequence.  The
2038 @code{shortcall} attribute indicates that the function is always close
2039 enough for the shorter calling sequence to be used.  These attributes
2040 override both the @option{-mlongcall} switch and, on the RS/6000 and
2041 PowerPC, the @code{#pragma longcall} setting.
2042
2043 @xref{RS/6000 and PowerPC Options}, for more information on whether long
2044 calls are necessary.
2045
2046 @item long_call
2047 @cindex indirect calls on MIPS
2048 This attribute specifies how a particular function is called on MIPS@.
2049 The attribute overrides the @option{-mlong-calls} (@pxref{MIPS Options})
2050 command line switch.  This attribute causes the compiler to always call
2051 the function by first loading its address into a register, and then using
2052 the contents of that register.
2053
2054 @item malloc
2055 @cindex @code{malloc} attribute
2056 The @code{malloc} attribute is used to tell the compiler that a function
2057 may be treated as if any non-@code{NULL} pointer it returns cannot
2058 alias any other pointer valid when the function returns.
2059 This will often improve optimization.
2060 Standard functions with this property include @code{malloc} and
2061 @code{calloc}.  @code{realloc}-like functions have this property as
2062 long as the old pointer is never referred to (including comparing it
2063 to the new pointer) after the function returns a non-@code{NULL}
2064 value.
2065
2066 @item model (@var{model-name})
2067 @cindex function addressability on the M32R/D
2068 @cindex variable addressability on the IA-64
2069
2070 On the M32R/D, use this attribute to set the addressability of an
2071 object, and of the code generated for a function.  The identifier
2072 @var{model-name} is one of @code{small}, @code{medium}, or
2073 @code{large}, representing each of the code models.
2074
2075 Small model objects live in the lower 16MB of memory (so that their
2076 addresses can be loaded with the @code{ld24} instruction), and are
2077 callable with the @code{bl} instruction.
2078
2079 Medium model objects may live anywhere in the 32-bit address space (the
2080 compiler will generate @code{seth/add3} instructions to load their addresses),
2081 and are callable with the @code{bl} instruction.
2082
2083 Large model objects may live anywhere in the 32-bit address space (the
2084 compiler will generate @code{seth/add3} instructions to load their addresses),
2085 and may not be reachable with the @code{bl} instruction (the compiler will
2086 generate the much slower @code{seth/add3/jl} instruction sequence).
2087
2088 On IA-64, use this attribute to set the addressability of an object.
2089 At present, the only supported identifier for @var{model-name} is
2090 @code{small}, indicating addressability via ``small'' (22-bit)
2091 addresses (so that their addresses can be loaded with the @code{addl}
2092 instruction).  Caveat: such addressing is by definition not position
2093 independent and hence this attribute must not be used for objects
2094 defined by shared libraries.
2095
2096 @item naked
2097 @cindex function without a prologue/epilogue code
2098 Use this attribute on the ARM, AVR, C4x, IP2K and SPU ports to indicate that
2099 the specified function does not need prologue/epilogue sequences generated by
2100 the compiler.  It is up to the programmer to provide these sequences.
2101
2102 @item near
2103 @cindex functions which do not handle memory bank switching on 68HC11/68HC12
2104 On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to
2105 use the normal calling convention based on @code{jsr} and @code{rts}.
2106 This attribute can be used to cancel the effect of the @option{-mlong-calls}
2107 option.
2108
2109 @item nesting
2110 @cindex Allow nesting in an interrupt handler on the Blackfin processor.
2111 Use this attribute together with @code{interrupt_handler},
2112 @code{exception_handler} or @code{nmi_handler} to indicate that the function
2113 entry code should enable nested interrupts or exceptions.
2114
2115 @item nmi_handler
2116 @cindex NMI handler functions on the Blackfin processor
2117 Use this attribute on the Blackfin to indicate that the specified function
2118 is an NMI handler.  The compiler will generate function entry and
2119 exit sequences suitable for use in an NMI handler when this
2120 attribute is present.
2121
2122 @item no_instrument_function
2123 @cindex @code{no_instrument_function} function attribute
2124 @opindex finstrument-functions
2125 If @option{-finstrument-functions} is given, profiling function calls will
2126 be generated at entry and exit of most user-compiled functions.
2127 Functions with this attribute will not be so instrumented.
2128
2129 @item noinline
2130 @cindex @code{noinline} function attribute
2131 This function attribute prevents a function from being considered for
2132 inlining.
2133
2134 @item nonnull (@var{arg-index}, @dots{})
2135 @cindex @code{nonnull} function attribute
2136 The @code{nonnull} attribute specifies that some function parameters should
2137 be non-null pointers.  For instance, the declaration:
2138
2139 @smallexample
2140 extern void *
2141 my_memcpy (void *dest, const void *src, size_t len)
2142         __attribute__((nonnull (1, 2)));
2143 @end smallexample
2144
2145 @noindent
2146 causes the compiler to check that, in calls to @code{my_memcpy},
2147 arguments @var{dest} and @var{src} are non-null.  If the compiler
2148 determines that a null pointer is passed in an argument slot marked
2149 as non-null, and the @option{-Wnonnull} option is enabled, a warning
2150 is issued.  The compiler may also choose to make optimizations based
2151 on the knowledge that certain function arguments will not be null.
2152
2153 If no argument index list is given to the @code{nonnull} attribute,
2154 all pointer arguments are marked as non-null.  To illustrate, the
2155 following declaration is equivalent to the previous example:
2156
2157 @smallexample
2158 extern void *
2159 my_memcpy (void *dest, const void *src, size_t len)
2160         __attribute__((nonnull));
2161 @end smallexample
2162
2163 @item noreturn
2164 @cindex @code{noreturn} function attribute
2165 A few standard library functions, such as @code{abort} and @code{exit},
2166 cannot return.  GCC knows this automatically.  Some programs define
2167 their own functions that never return.  You can declare them
2168 @code{noreturn} to tell the compiler this fact.  For example,
2169
2170 @smallexample
2171 @group
2172 void fatal () __attribute__ ((noreturn));
2173
2174 void
2175 fatal (/* @r{@dots{}} */)
2176 @{
2177   /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
2178   exit (1);
2179 @}
2180 @end group
2181 @end smallexample
2182
2183 The @code{noreturn} keyword tells the compiler to assume that
2184 @code{fatal} cannot return.  It can then optimize without regard to what
2185 would happen if @code{fatal} ever did return.  This makes slightly
2186 better code.  More importantly, it helps avoid spurious warnings of
2187 uninitialized variables.
2188
2189 The @code{noreturn} keyword does not affect the exceptional path when that
2190 applies: a @code{noreturn}-marked function may still return to the caller
2191 by throwing an exception or calling @code{longjmp}.
2192
2193 Do not assume that registers saved by the calling function are
2194 restored before calling the @code{noreturn} function.
2195
2196 It does not make sense for a @code{noreturn} function to have a return
2197 type other than @code{void}.
2198
2199 The attribute @code{noreturn} is not implemented in GCC versions
2200 earlier than 2.5.  An alternative way to declare that a function does
2201 not return, which works in the current version and in some older
2202 versions, is as follows:
2203
2204 @smallexample
2205 typedef void voidfn ();
2206
2207 volatile voidfn fatal;
2208 @end smallexample
2209
2210 This approach does not work in GNU C++.
2211
2212 @item nothrow
2213 @cindex @code{nothrow} function attribute
2214 The @code{nothrow} attribute is used to inform the compiler that a
2215 function cannot throw an exception.  For example, most functions in
2216 the standard C library can be guaranteed not to throw an exception
2217 with the notable exceptions of @code{qsort} and @code{bsearch} that
2218 take function pointer arguments.  The @code{nothrow} attribute is not
2219 implemented in GCC versions earlier than 3.3.
2220
2221 @item pure
2222 @cindex @code{pure} function attribute
2223 Many functions have no effects except the return value and their
2224 return value depends only on the parameters and/or global variables.
2225 Such a function can be subject
2226 to common subexpression elimination and loop optimization just as an
2227 arithmetic operator would be.  These functions should be declared
2228 with the attribute @code{pure}.  For example,
2229
2230 @smallexample
2231 int square (int) __attribute__ ((pure));
2232 @end smallexample
2233
2234 @noindent
2235 says that the hypothetical function @code{square} is safe to call
2236 fewer times than the program says.
2237
2238 Some of common examples of pure functions are @code{strlen} or @code{memcmp}.
2239 Interesting non-pure functions are functions with infinite loops or those
2240 depending on volatile memory or other system resource, that may change between
2241 two consecutive calls (such as @code{feof} in a multithreading environment).
2242
2243 The attribute @code{pure} is not implemented in GCC versions earlier
2244 than 2.96.
2245
2246 @item hot
2247 @cindex @code{hot} function attribute
2248 The @code{hot} attribute is used to inform the compiler that a function is a
2249 hot spot of the compiled program.  The function is optimized more aggressively
2250 and on many target it is placed into special subsection of the text section so
2251 all hot functions appears close together improving locality.
2252
2253 When profile feedback is available, via @option{-fprofile-use}, hot functions
2254 are automatically detected and this attribute is ignored.
2255
2256 The @code{hot} attribute is not implemented in GCC versions earlier than 4.3.
2257
2258 @item cold
2259 @cindex @code{cold} function attribute
2260 The @code{cold} attribute is used to inform the compiler that a function is
2261 unlikely executed.  The function is optimized for size rather than speed and on
2262 many targets it is placed into special subsection of the text section so all
2263 cold functions appears close together improving code locality of non-cold parts
2264 of program.  The paths leading to call of cold functions within code are marked
2265 as unlikely by the branch prediction mechanizm. It is thus useful to mark
2266 functions used to handle unlikely conditions, such as @code{perror}, as cold to
2267 improve optimization of hot functions that do call marked functions in rare
2268 occasions.
2269
2270 When profile feedback is available, via @option{-fprofile-use}, hot functions
2271 are automatically detected and this attribute is ignored.
2272
2273 The @code{hot} attribute is not implemented in GCC versions earlier than 4.3.
2274
2275 @item regparm (@var{number})
2276 @cindex @code{regparm} attribute
2277 @cindex functions that are passed arguments in registers on the 386
2278 On the Intel 386, the @code{regparm} attribute causes the compiler to
2279 pass arguments number one to @var{number} if they are of integral type
2280 in registers EAX, EDX, and ECX instead of on the stack.  Functions that
2281 take a variable number of arguments will continue to be passed all of their
2282 arguments on the stack.
2283
2284 Beware that on some ELF systems this attribute is unsuitable for
2285 global functions in shared libraries with lazy binding (which is the
2286 default).  Lazy binding will send the first call via resolving code in
2287 the loader, which might assume EAX, EDX and ECX can be clobbered, as
2288 per the standard calling conventions.  Solaris 8 is affected by this.
2289 GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be
2290 safe since the loaders there save all registers.  (Lazy binding can be
2291 disabled with the linker or the loader if desired, to avoid the
2292 problem.)
2293
2294 @item sseregparm
2295 @cindex @code{sseregparm} attribute
2296 On the Intel 386 with SSE support, the @code{sseregparm} attribute
2297 causes the compiler to pass up to 3 floating point arguments in
2298 SSE registers instead of on the stack.  Functions that take a
2299 variable number of arguments will continue to pass all of their
2300 floating point arguments on the stack.
2301
2302 @item force_align_arg_pointer
2303 @cindex @code{force_align_arg_pointer} attribute
2304 On the Intel x86, the @code{force_align_arg_pointer} attribute may be
2305 applied to individual function definitions, generating an alternate
2306 prologue and epilogue that realigns the runtime stack.  This supports
2307 mixing legacy codes that run with a 4-byte aligned stack with modern
2308 codes that keep a 16-byte stack for SSE compatibility.  The alternate
2309 prologue and epilogue are slower and bigger than the regular ones, and
2310 the alternate prologue requires a scratch register; this lowers the
2311 number of registers available if used in conjunction with the
2312 @code{regparm} attribute.  The @code{force_align_arg_pointer}
2313 attribute is incompatible with nested functions; this is considered a
2314 hard error.
2315
2316 @item returns_twice
2317 @cindex @code{returns_twice} attribute
2318 The @code{returns_twice} attribute tells the compiler that a function may
2319 return more than one time.  The compiler will ensure that all registers
2320 are dead before calling such a function and will emit a warning about
2321 the variables that may be clobbered after the second return from the
2322 function.  Examples of such functions are @code{setjmp} and @code{vfork}.
2323 The @code{longjmp}-like counterpart of such function, if any, might need
2324 to be marked with the @code{noreturn} attribute.
2325
2326 @item saveall
2327 @cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S
2328 Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that
2329 all registers except the stack pointer should be saved in the prologue
2330 regardless of whether they are used or not.
2331
2332 @item section ("@var{section-name}")
2333 @cindex @code{section} function attribute
2334 Normally, the compiler places the code it generates in the @code{text} section.
2335 Sometimes, however, you need additional sections, or you need certain
2336 particular functions to appear in special sections.  The @code{section}
2337 attribute specifies that a function lives in a particular section.
2338 For example, the declaration:
2339
2340 @smallexample
2341 extern void foobar (void) __attribute__ ((section ("bar")));
2342 @end smallexample
2343
2344 @noindent
2345 puts the function @code{foobar} in the @code{bar} section.
2346
2347 Some file formats do not support arbitrary sections so the @code{section}
2348 attribute is not available on all platforms.
2349 If you need to map the entire contents of a module to a particular
2350 section, consider using the facilities of the linker instead.
2351
2352 @item sentinel
2353 @cindex @code{sentinel} function attribute
2354 This function attribute ensures that a parameter in a function call is
2355 an explicit @code{NULL}.  The attribute is only valid on variadic
2356 functions.  By default, the sentinel is located at position zero, the
2357 last parameter of the function call.  If an optional integer position
2358 argument P is supplied to the attribute, the sentinel must be located at
2359 position P counting backwards from the end of the argument list.
2360
2361 @smallexample
2362 __attribute__ ((sentinel))
2363 is equivalent to
2364 __attribute__ ((sentinel(0)))
2365 @end smallexample
2366
2367 The attribute is automatically set with a position of 0 for the built-in
2368 functions @code{execl} and @code{execlp}.  The built-in function
2369 @code{execle} has the attribute set with a position of 1.
2370
2371 A valid @code{NULL} in this context is defined as zero with any pointer
2372 type.  If your system defines the @code{NULL} macro with an integer type
2373 then you need to add an explicit cast.  GCC replaces @code{stddef.h}
2374 with a copy that redefines NULL appropriately.
2375
2376 The warnings for missing or incorrect sentinels are enabled with
2377 @option{-Wformat}.
2378
2379 @item short_call
2380 See long_call/short_call.
2381
2382 @item shortcall
2383 See longcall/shortcall.
2384
2385 @item signal
2386 @cindex signal handler functions on the AVR processors
2387 Use this attribute on the AVR to indicate that the specified
2388 function is a signal handler.  The compiler will generate function
2389 entry and exit sequences suitable for use in a signal handler when this
2390 attribute is present.  Interrupts will be disabled inside the function.
2391
2392 @item sp_switch
2393 Use this attribute on the SH to indicate an @code{interrupt_handler}
2394 function should switch to an alternate stack.  It expects a string
2395 argument that names a global variable holding the address of the
2396 alternate stack.
2397
2398 @smallexample
2399 void *alt_stack;
2400 void f () __attribute__ ((interrupt_handler,
2401                           sp_switch ("alt_stack")));
2402 @end smallexample
2403
2404 @item stdcall
2405 @cindex functions that pop the argument stack on the 386
2406 On the Intel 386, the @code{stdcall} attribute causes the compiler to
2407 assume that the called function will pop off the stack space used to
2408 pass arguments, unless it takes a variable number of arguments.
2409
2410 @item tiny_data
2411 @cindex tiny data section on the H8/300H and H8S
2412 Use this attribute on the H8/300H and H8S to indicate that the specified
2413 variable should be placed into the tiny data section.
2414 The compiler will generate more efficient code for loads and stores
2415 on data in the tiny data section.  Note the tiny data area is limited to
2416 slightly under 32kbytes of data.
2417
2418 @item trap_exit
2419 Use this attribute on the SH for an @code{interrupt_handler} to return using
2420 @code{trapa} instead of @code{rte}.  This attribute expects an integer
2421 argument specifying the trap number to be used.
2422
2423 @item unused
2424 @cindex @code{unused} attribute.
2425 This attribute, attached to a function, means that the function is meant
2426 to be possibly unused.  GCC will not produce a warning for this
2427 function.
2428
2429 @item used
2430 @cindex @code{used} attribute.
2431 This attribute, attached to a function, means that code must be emitted
2432 for the function even if it appears that the function is not referenced.
2433 This is useful, for example, when the function is referenced only in
2434 inline assembly.
2435
2436 @item version_id
2437 @cindex @code{version_id} attribute on IA64 HP-UX
2438 This attribute, attached to a global variable or function, renames a
2439 symbol to contain a version string, thus allowing for function level
2440 versioning.  HP-UX system header files may use version level functioning
2441 for some system calls.
2442
2443 @smallexample
2444 extern int foo () __attribute__((version_id ("20040821")));
2445 @end smallexample
2446
2447 Calls to @var{foo} will be mapped to calls to @var{foo@{20040821@}}.
2448
2449 @item visibility ("@var{visibility_type}")
2450 @cindex @code{visibility} attribute
2451 This attribute affects the linkage of the declaration to which it is attached.
2452 There are four supported @var{visibility_type} values: default,
2453 hidden, protected or internal visibility.
2454
2455 @smallexample
2456 void __attribute__ ((visibility ("protected")))
2457 f () @{ /* @r{Do something.} */; @}
2458 int i __attribute__ ((visibility ("hidden")));
2459 @end smallexample
2460
2461 The possible values of @var{visibility_type} correspond to the
2462 visibility settings in the ELF gABI.
2463
2464 @table @dfn
2465 @c keep this list of visibilities in alphabetical order.
2466
2467 @item default
2468 Default visibility is the normal case for the object file format.
2469 This value is available for the visibility attribute to override other
2470 options that may change the assumed visibility of entities.
2471
2472 On ELF, default visibility means that the declaration is visible to other
2473 modules and, in shared libraries, means that the declared entity may be
2474 overridden.
2475
2476 On Darwin, default visibility means that the declaration is visible to
2477 other modules.
2478
2479 Default visibility corresponds to ``external linkage'' in the language.
2480
2481 @item hidden
2482 Hidden visibility indicates that the entity declared will have a new
2483 form of linkage, which we'll call ``hidden linkage''.  Two
2484 declarations of an object with hidden linkage refer to the same object
2485 if they are in the same shared object.
2486
2487 @item internal
2488 Internal visibility is like hidden visibility, but with additional
2489 processor specific semantics.  Unless otherwise specified by the
2490 psABI, GCC defines internal visibility to mean that a function is
2491 @emph{never} called from another module.  Compare this with hidden
2492 functions which, while they cannot be referenced directly by other
2493 modules, can be referenced indirectly via function pointers.  By
2494 indicating that a function cannot be called from outside the module,
2495 GCC may for instance omit the load of a PIC register since it is known
2496 that the calling function loaded the correct value.
2497
2498 @item protected
2499 Protected visibility is like default visibility except that it
2500 indicates that references within the defining module will bind to the
2501 definition in that module.  That is, the declared entity cannot be
2502 overridden by another module.
2503
2504 @end table
2505
2506 All visibilities are supported on many, but not all, ELF targets
2507 (supported when the assembler supports the @samp{.visibility}
2508 pseudo-op).  Default visibility is supported everywhere.  Hidden
2509 visibility is supported on Darwin targets.
2510
2511 The visibility attribute should be applied only to declarations which
2512 would otherwise have external linkage.  The attribute should be applied
2513 consistently, so that the same entity should not be declared with
2514 different settings of the attribute.
2515
2516 In C++, the visibility attribute applies to types as well as functions
2517 and objects, because in C++ types have linkage.  A class must not have
2518 greater visibility than its non-static data member types and bases,
2519 and class members default to the visibility of their class.  Also, a
2520 declaration without explicit visibility is limited to the visibility
2521 of its type.
2522
2523 In C++, you can mark member functions and static member variables of a
2524 class with the visibility attribute.  This is useful if if you know a
2525 particular method or static member variable should only be used from
2526 one shared object; then you can mark it hidden while the rest of the
2527 class has default visibility.  Care must be taken to avoid breaking
2528 the One Definition Rule; for example, it is usually not useful to mark
2529 an inline method as hidden without marking the whole class as hidden.
2530
2531 A C++ namespace declaration can also have the visibility attribute.
2532 This attribute applies only to the particular namespace body, not to
2533 other definitions of the same namespace; it is equivalent to using
2534 @samp{#pragma GCC visibility} before and after the namespace
2535 definition (@pxref{Visibility Pragmas}).
2536
2537 In C++, if a template argument has limited visibility, this
2538 restriction is implicitly propagated to the template instantiation.
2539 Otherwise, template instantiations and specializations default to the
2540 visibility of their template.
2541
2542 If both the template and enclosing class have explicit visibility, the
2543 visibility from the template is used.
2544
2545 @item warn_unused_result
2546 @cindex @code{warn_unused_result} attribute
2547 The @code{warn_unused_result} attribute causes a warning to be emitted
2548 if a caller of the function with this attribute does not use its
2549 return value.  This is useful for functions where not checking
2550 the result is either a security problem or always a bug, such as
2551 @code{realloc}.
2552
2553 @smallexample
2554 int fn () __attribute__ ((warn_unused_result));
2555 int foo ()
2556 @{
2557   if (fn () < 0) return -1;
2558   fn ();
2559   return 0;
2560 @}
2561 @end smallexample
2562
2563 results in warning on line 5.
2564
2565 @item weak
2566 @cindex @code{weak} attribute
2567 The @code{weak} attribute causes the declaration to be emitted as a weak
2568 symbol rather than a global.  This is primarily useful in defining
2569 library functions which can be overridden in user code, though it can
2570 also be used with non-function declarations.  Weak symbols are supported
2571 for ELF targets, and also for a.out targets when using the GNU assembler
2572 and linker.
2573
2574 @item weakref
2575 @itemx weakref ("@var{target}")
2576 @cindex @code{weakref} attribute
2577 The @code{weakref} attribute marks a declaration as a weak reference.
2578 Without arguments, it should be accompanied by an @code{alias} attribute
2579 naming the target symbol.  Optionally, the @var{target} may be given as
2580 an argument to @code{weakref} itself.  In either case, @code{weakref}
2581 implicitly marks the declaration as @code{weak}.  Without a
2582 @var{target}, given as an argument to @code{weakref} or to @code{alias},
2583 @code{weakref} is equivalent to @code{weak}.
2584
2585 @smallexample
2586 static int x() __attribute__ ((weakref ("y")));
2587 /* is equivalent to... */
2588 static int x() __attribute__ ((weak, weakref, alias ("y")));
2589 /* and to... */
2590 static int x() __attribute__ ((weakref));
2591 static int x() __attribute__ ((alias ("y")));
2592 @end smallexample
2593
2594 A weak reference is an alias that does not by itself require a
2595 definition to be given for the target symbol.  If the target symbol is
2596 only referenced through weak references, then the becomes a @code{weak}
2597 undefined symbol.  If it is directly referenced, however, then such
2598 strong references prevail, and a definition will be required for the
2599 symbol, not necessarily in the same translation unit.
2600
2601 The effect is equivalent to moving all references to the alias to a
2602 separate translation unit, renaming the alias to the aliased symbol,
2603 declaring it as weak, compiling the two separate translation units and
2604 performing a reloadable link on them.
2605
2606 At present, a declaration to which @code{weakref} is attached can
2607 only be @code{static}.
2608
2609 @item externally_visible
2610 @cindex @code{externally_visible} attribute.
2611 This attribute, attached to a global variable or function nullify
2612 effect of @option{-fwhole-program} command line option, so the object
2613 remain visible outside the current compilation unit
2614
2615 @end table
2616
2617 You can specify multiple attributes in a declaration by separating them
2618 by commas within the double parentheses or by immediately following an
2619 attribute declaration with another attribute declaration.
2620
2621 @cindex @code{#pragma}, reason for not using
2622 @cindex pragma, reason for not using
2623 Some people object to the @code{__attribute__} feature, suggesting that
2624 ISO C's @code{#pragma} should be used instead.  At the time
2625 @code{__attribute__} was designed, there were two reasons for not doing
2626 this.
2627
2628 @enumerate
2629 @item
2630 It is impossible to generate @code{#pragma} commands from a macro.
2631
2632 @item
2633 There is no telling what the same @code{#pragma} might mean in another
2634 compiler.
2635 @end enumerate
2636
2637 These two reasons applied to almost any application that might have been
2638 proposed for @code{#pragma}.  It was basically a mistake to use
2639 @code{#pragma} for @emph{anything}.
2640
2641 The ISO C99 standard includes @code{_Pragma}, which now allows pragmas
2642 to be generated from macros.  In addition, a @code{#pragma GCC}
2643 namespace is now in use for GCC-specific pragmas.  However, it has been
2644 found convenient to use @code{__attribute__} to achieve a natural
2645 attachment of attributes to their corresponding declarations, whereas
2646 @code{#pragma GCC} is of use for constructs that do not naturally form
2647 part of the grammar.  @xref{Other Directives,,Miscellaneous
2648 Preprocessing Directives, cpp, The GNU C Preprocessor}.
2649
2650 @node Attribute Syntax
2651 @section Attribute Syntax
2652 @cindex attribute syntax
2653
2654 This section describes the syntax with which @code{__attribute__} may be
2655 used, and the constructs to which attribute specifiers bind, for the C
2656 language.  Some details may vary for C++ and Objective-C@.  Because of
2657 infelicities in the grammar for attributes, some forms described here
2658 may not be successfully parsed in all cases.
2659
2660 There are some problems with the semantics of attributes in C++.  For
2661 example, there are no manglings for attributes, although they may affect
2662 code generation, so problems may arise when attributed types are used in
2663 conjunction with templates or overloading.  Similarly, @code{typeid}
2664 does not distinguish between types with different attributes.  Support
2665 for attributes in C++ may be restricted in future to attributes on
2666 declarations only, but not on nested declarators.
2667
2668 @xref{Function Attributes}, for details of the semantics of attributes
2669 applying to functions.  @xref{Variable Attributes}, for details of the
2670 semantics of attributes applying to variables.  @xref{Type Attributes},
2671 for details of the semantics of attributes applying to structure, union
2672 and enumerated types.
2673
2674 An @dfn{attribute specifier} is of the form
2675 @code{__attribute__ ((@var{attribute-list}))}.  An @dfn{attribute list}
2676 is a possibly empty comma-separated sequence of @dfn{attributes}, where
2677 each attribute is one of the following:
2678
2679 @itemize @bullet
2680 @item
2681 Empty.  Empty attributes are ignored.
2682
2683 @item
2684 A word (which may be an identifier such as @code{unused}, or a reserved
2685 word such as @code{const}).
2686
2687 @item
2688 A word, followed by, in parentheses, parameters for the attribute.
2689 These parameters take one of the following forms:
2690
2691 @itemize @bullet
2692 @item
2693 An identifier.  For example, @code{mode} attributes use this form.
2694
2695 @item
2696 An identifier followed by a comma and a non-empty comma-separated list
2697 of expressions.  For example, @code{format} attributes use this form.
2698
2699 @item
2700 A possibly empty comma-separated list of expressions.  For example,
2701 @code{format_arg} attributes use this form with the list being a single
2702 integer constant expression, and @code{alias} attributes use this form
2703 with the list being a single string constant.
2704 @end itemize
2705 @end itemize
2706
2707 An @dfn{attribute specifier list} is a sequence of one or more attribute
2708 specifiers, not separated by any other tokens.
2709
2710 In GNU C, an attribute specifier list may appear after the colon following a
2711 label, other than a @code{case} or @code{default} label.  The only
2712 attribute it makes sense to use after a label is @code{unused}.  This
2713 feature is intended for code generated by programs which contains labels
2714 that may be unused but which is compiled with @option{-Wall}.  It would
2715 not normally be appropriate to use in it human-written code, though it
2716 could be useful in cases where the code that jumps to the label is
2717 contained within an @code{#ifdef} conditional.  GNU C++ does not permit
2718 such placement of attribute lists, as it is permissible for a
2719 declaration, which could begin with an attribute list, to be labelled in
2720 C++.  Declarations cannot be labelled in C90 or C99, so the ambiguity
2721 does not arise there.
2722
2723 An attribute specifier list may appear as part of a @code{struct},
2724 @code{union} or @code{enum} specifier.  It may go either immediately
2725 after the @code{struct}, @code{union} or @code{enum} keyword, or after
2726 the closing brace.  The former syntax is preferred.
2727 Where attribute specifiers follow the closing brace, they are considered
2728 to relate to the structure, union or enumerated type defined, not to any
2729 enclosing declaration the type specifier appears in, and the type
2730 defined is not complete until after the attribute specifiers.
2731 @c Otherwise, there would be the following problems: a shift/reduce
2732 @c conflict between attributes binding the struct/union/enum and
2733 @c binding to the list of specifiers/qualifiers; and "aligned"
2734 @c attributes could use sizeof for the structure, but the size could be
2735 @c changed later by "packed" attributes.
2736
2737 Otherwise, an attribute specifier appears as part of a declaration,
2738 counting declarations of unnamed parameters and type names, and relates
2739 to that declaration (which may be nested in another declaration, for
2740 example in the case of a parameter declaration), or to a particular declarator
2741 within a declaration.  Where an
2742 attribute specifier is applied to a parameter declared as a function or
2743 an array, it should apply to the function or array rather than the
2744 pointer to which the parameter is implicitly converted, but this is not
2745 yet correctly implemented.
2746
2747 Any list of specifiers and qualifiers at the start of a declaration may
2748 contain attribute specifiers, whether or not such a list may in that
2749 context contain storage class specifiers.  (Some attributes, however,
2750 are essentially in the nature of storage class specifiers, and only make
2751 sense where storage class specifiers may be used; for example,
2752 @code{section}.)  There is one necessary limitation to this syntax: the
2753 first old-style parameter declaration in a function definition cannot
2754 begin with an attribute specifier, because such an attribute applies to
2755 the function instead by syntax described below (which, however, is not
2756 yet implemented in this case).  In some other cases, attribute
2757 specifiers are permitted by this grammar but not yet supported by the
2758 compiler.  All attribute specifiers in this place relate to the
2759 declaration as a whole.  In the obsolescent usage where a type of
2760 @code{int} is implied by the absence of type specifiers, such a list of
2761 specifiers and qualifiers may be an attribute specifier list with no
2762 other specifiers or qualifiers.
2763
2764 At present, the first parameter in a function prototype must have some
2765 type specifier which is not an attribute specifier; this resolves an
2766 ambiguity in the interpretation of @code{void f(int
2767 (__attribute__((foo)) x))}, but is subject to change.  At present, if
2768 the parentheses of a function declarator contain only attributes then
2769 those attributes are ignored, rather than yielding an error or warning
2770 or implying a single parameter of type int, but this is subject to
2771 change.
2772
2773 An attribute specifier list may appear immediately before a declarator
2774 (other than the first) in a comma-separated list of declarators in a
2775 declaration of more than one identifier using a single list of
2776 specifiers and qualifiers.  Such attribute specifiers apply
2777 only to the identifier before whose declarator they appear.  For
2778 example, in
2779
2780 @smallexample
2781 __attribute__((noreturn)) void d0 (void),
2782     __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
2783      d2 (void)
2784 @end smallexample
2785
2786 @noindent
2787 the @code{noreturn} attribute applies to all the functions
2788 declared; the @code{format} attribute only applies to @code{d1}.
2789
2790 An attribute specifier list may appear immediately before the comma,
2791 @code{=} or semicolon terminating the declaration of an identifier other
2792 than a function definition.  At present, such attribute specifiers apply
2793 to the declared object or function, but in future they may attach to the
2794 outermost adjacent declarator.  In simple cases there is no difference,
2795 but, for example, in
2796
2797 @smallexample
2798 void (****f)(void) __attribute__((noreturn));
2799 @end smallexample
2800
2801 @noindent
2802 at present the @code{noreturn} attribute applies to @code{f}, which
2803 causes a warning since @code{f} is not a function, but in future it may
2804 apply to the function @code{****f}.  The precise semantics of what
2805 attributes in such cases will apply to are not yet specified.  Where an
2806 assembler name for an object or function is specified (@pxref{Asm
2807 Labels}), at present the attribute must follow the @code{asm}
2808 specification; in future, attributes before the @code{asm} specification
2809 may apply to the adjacent declarator, and those after it to the declared
2810 object or function.
2811
2812 An attribute specifier list may, in future, be permitted to appear after
2813 the declarator in a function definition (before any old-style parameter
2814 declarations or the function body).
2815
2816 Attribute specifiers may be mixed with type qualifiers appearing inside
2817 the @code{[]} of a parameter array declarator, in the C99 construct by
2818 which such qualifiers are applied to the pointer to which the array is
2819 implicitly converted.  Such attribute specifiers apply to the pointer,
2820 not to the array, but at present this is not implemented and they are
2821 ignored.
2822
2823 An attribute specifier list may appear at the start of a nested
2824 declarator.  At present, there are some limitations in this usage: the
2825 attributes correctly apply to the declarator, but for most individual
2826 attributes the semantics this implies are not implemented.
2827 When attribute specifiers follow the @code{*} of a pointer
2828 declarator, they may be mixed with any type qualifiers present.
2829 The following describes the formal semantics of this syntax.  It will make the
2830 most sense if you are familiar with the formal specification of
2831 declarators in the ISO C standard.
2832
2833 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
2834 D1}, where @code{T} contains declaration specifiers that specify a type
2835 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
2836 contains an identifier @var{ident}.  The type specified for @var{ident}
2837 for derived declarators whose type does not include an attribute
2838 specifier is as in the ISO C standard.
2839
2840 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
2841 and the declaration @code{T D} specifies the type
2842 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
2843 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
2844 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
2845
2846 If @code{D1} has the form @code{*
2847 @var{type-qualifier-and-attribute-specifier-list} D}, and the
2848 declaration @code{T D} specifies the type
2849 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
2850 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
2851 @var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for
2852 @var{ident}.
2853
2854 For example,
2855
2856 @smallexample
2857 void (__attribute__((noreturn)) ****f) (void);
2858 @end smallexample
2859
2860 @noindent
2861 specifies the type ``pointer to pointer to pointer to pointer to
2862 non-returning function returning @code{void}''.  As another example,
2863
2864 @smallexample
2865 char *__attribute__((aligned(8))) *f;
2866 @end smallexample
2867
2868 @noindent
2869 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
2870 Note again that this does not work with most attributes; for example,
2871 the usage of @samp{aligned} and @samp{noreturn} attributes given above
2872 is not yet supported.
2873
2874 For compatibility with existing code written for compiler versions that
2875 did not implement attributes on nested declarators, some laxity is
2876 allowed in the placing of attributes.  If an attribute that only applies
2877 to types is applied to a declaration, it will be treated as applying to
2878 the type of that declaration.  If an attribute that only applies to
2879 declarations is applied to the type of a declaration, it will be treated
2880 as applying to that declaration; and, for compatibility with code
2881 placing the attributes immediately before the identifier declared, such
2882 an attribute applied to a function return type will be treated as
2883 applying to the function type, and such an attribute applied to an array
2884 element type will be treated as applying to the array type.  If an
2885 attribute that only applies to function types is applied to a
2886 pointer-to-function type, it will be treated as applying to the pointer
2887 target type; if such an attribute is applied to a function return type
2888 that is not a pointer-to-function type, it will be treated as applying
2889 to the function type.
2890
2891 @node Function Prototypes
2892 @section Prototypes and Old-Style Function Definitions
2893 @cindex function prototype declarations
2894 @cindex old-style function definitions
2895 @cindex promotion of formal parameters
2896
2897 GNU C extends ISO C to allow a function prototype to override a later
2898 old-style non-prototype definition.  Consider the following example:
2899
2900 @smallexample
2901 /* @r{Use prototypes unless the compiler is old-fashioned.}  */
2902 #ifdef __STDC__
2903 #define P(x) x
2904 #else
2905 #define P(x) ()
2906 #endif
2907
2908 /* @r{Prototype function declaration.}  */
2909 int isroot P((uid_t));
2910
2911 /* @r{Old-style function definition.}  */
2912 int
2913 isroot (x)   /* @r{??? lossage here ???} */
2914      uid_t x;
2915 @{
2916   return x == 0;
2917 @}
2918 @end smallexample
2919
2920 Suppose the type @code{uid_t} happens to be @code{short}.  ISO C does
2921 not allow this example, because subword arguments in old-style
2922 non-prototype definitions are promoted.  Therefore in this example the
2923 function definition's argument is really an @code{int}, which does not
2924 match the prototype argument type of @code{short}.
2925
2926 This restriction of ISO C makes it hard to write code that is portable
2927 to traditional C compilers, because the programmer does not know
2928 whether the @code{uid_t} type is @code{short}, @code{int}, or
2929 @code{long}.  Therefore, in cases like these GNU C allows a prototype
2930 to override a later old-style definition.  More precisely, in GNU C, a
2931 function prototype argument type overrides the argument type specified
2932 by a later old-style definition if the former type is the same as the
2933 latter type before promotion.  Thus in GNU C the above example is
2934 equivalent to the following:
2935
2936 @smallexample
2937 int isroot (uid_t);
2938
2939 int
2940 isroot (uid_t x)
2941 @{
2942   return x == 0;
2943 @}
2944 @end smallexample
2945
2946 @noindent
2947 GNU C++ does not support old-style function definitions, so this
2948 extension is irrelevant.
2949
2950 @node C++ Comments
2951 @section C++ Style Comments
2952 @cindex //
2953 @cindex C++ comments
2954 @cindex comments, C++ style
2955
2956 In GNU C, you may use C++ style comments, which start with @samp{//} and
2957 continue until the end of the line.  Many other C implementations allow
2958 such comments, and they are included in the 1999 C standard.  However,
2959 C++ style comments are not recognized if you specify an @option{-std}
2960 option specifying a version of ISO C before C99, or @option{-ansi}
2961 (equivalent to @option{-std=c89}).
2962
2963 @node Dollar Signs
2964 @section Dollar Signs in Identifier Names
2965 @cindex $
2966 @cindex dollar signs in identifier names
2967 @cindex identifier names, dollar signs in
2968
2969 In GNU C, you may normally use dollar signs in identifier names.
2970 This is because many traditional C implementations allow such identifiers.
2971 However, dollar signs in identifiers are not supported on a few target
2972 machines, typically because the target assembler does not allow them.
2973
2974 @node Character Escapes
2975 @section The Character @key{ESC} in Constants
2976
2977 You can use the sequence @samp{\e} in a string or character constant to
2978 stand for the ASCII character @key{ESC}.
2979
2980 @node Alignment
2981 @section Inquiring on Alignment of Types or Variables
2982 @cindex alignment
2983 @cindex type alignment
2984 @cindex variable alignment
2985
2986 The keyword @code{__alignof__} allows you to inquire about how an object
2987 is aligned, or the minimum alignment usually required by a type.  Its
2988 syntax is just like @code{sizeof}.
2989
2990 For example, if the target machine requires a @code{double} value to be
2991 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
2992 This is true on many RISC machines.  On more traditional machine
2993 designs, @code{__alignof__ (double)} is 4 or even 2.
2994
2995 Some machines never actually require alignment; they allow reference to any
2996 data type even at an odd address.  For these machines, @code{__alignof__}
2997 reports the @emph{recommended} alignment of a type.
2998
2999 If the operand of @code{__alignof__} is an lvalue rather than a type,
3000 its value is the required alignment for its type, taking into account
3001 any minimum alignment specified with GCC's @code{__attribute__}
3002 extension (@pxref{Variable Attributes}).  For example, after this
3003 declaration:
3004
3005 @smallexample
3006 struct foo @{ int x; char y; @} foo1;
3007 @end smallexample
3008
3009 @noindent
3010 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
3011 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
3012
3013 It is an error to ask for the alignment of an incomplete type.
3014
3015 @node Variable Attributes
3016 @section Specifying Attributes of Variables
3017 @cindex attribute of variables
3018 @cindex variable attributes
3019
3020 The keyword @code{__attribute__} allows you to specify special
3021 attributes of variables or structure fields.  This keyword is followed
3022 by an attribute specification inside double parentheses.  Some
3023 attributes are currently defined generically for variables.
3024 Other attributes are defined for variables on particular target
3025 systems.  Other attributes are available for functions
3026 (@pxref{Function Attributes}) and for types (@pxref{Type Attributes}).
3027 Other front ends might define more attributes
3028 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
3029
3030 You may also specify attributes with @samp{__} preceding and following
3031 each keyword.  This allows you to use them in header files without
3032 being concerned about a possible macro of the same name.  For example,
3033 you may use @code{__aligned__} instead of @code{aligned}.
3034
3035 @xref{Attribute Syntax}, for details of the exact syntax for using
3036 attributes.
3037
3038 @table @code
3039 @cindex @code{aligned} attribute
3040 @item aligned (@var{alignment})
3041 This attribute specifies a minimum alignment for the variable or
3042 structure field, measured in bytes.  For example, the declaration:
3043
3044 @smallexample
3045 int x __attribute__ ((aligned (16))) = 0;
3046 @end smallexample
3047
3048 @noindent
3049 causes the compiler to allocate the global variable @code{x} on a
3050 16-byte boundary.  On a 68040, this could be used in conjunction with
3051 an @code{asm} expression to access the @code{move16} instruction which
3052 requires 16-byte aligned operands.
3053
3054 You can also specify the alignment of structure fields.  For example, to
3055 create a double-word aligned @code{int} pair, you could write:
3056
3057 @smallexample
3058 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
3059 @end smallexample
3060
3061 @noindent
3062 This is an alternative to creating a union with a @code{double} member
3063 that forces the union to be double-word aligned.
3064
3065 As in the preceding examples, you can explicitly specify the alignment
3066 (in bytes) that you wish the compiler to use for a given variable or
3067 structure field.  Alternatively, you can leave out the alignment factor
3068 and just ask the compiler to align a variable or field to the maximum
3069 useful alignment for the target machine you are compiling for.  For
3070 example, you could write:
3071
3072 @smallexample
3073 short array[3] __attribute__ ((aligned));
3074 @end smallexample
3075
3076 Whenever you leave out the alignment factor in an @code{aligned} attribute
3077 specification, the compiler automatically sets the alignment for the declared
3078 variable or field to the largest alignment which is ever used for any data
3079 type on the target machine you are compiling for.  Doing this can often make
3080 copy operations more efficient, because the compiler can use whatever
3081 instructions copy the biggest chunks of memory when performing copies to
3082 or from the variables or fields that you have aligned this way.
3083
3084 The @code{aligned} attribute can only increase the alignment; but you
3085 can decrease it by specifying @code{packed} as well.  See below.
3086
3087 Note that the effectiveness of @code{aligned} attributes may be limited
3088 by inherent limitations in your linker.  On many systems, the linker is
3089 only able to arrange for variables to be aligned up to a certain maximum
3090 alignment.  (For some linkers, the maximum supported alignment may
3091 be very very small.)  If your linker is only able to align variables
3092 up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
3093 in an @code{__attribute__} will still only provide you with 8 byte
3094 alignment.  See your linker documentation for further information.
3095
3096 @item cleanup (@var{cleanup_function})
3097 @cindex @code{cleanup} attribute
3098 The @code{cleanup} attribute runs a function when the variable goes
3099 out of scope.  This attribute can only be applied to auto function
3100 scope variables; it may not be applied to parameters or variables
3101 with static storage duration.  The function must take one parameter,
3102 a pointer to a type compatible with the variable.  The return value
3103 of the function (if any) is ignored.
3104
3105 If @option{-fexceptions} is enabled, then @var{cleanup_function}
3106 will be run during the stack unwinding that happens during the
3107 processing of the exception.  Note that the @code{cleanup} attribute
3108 does not allow the exception to be caught, only to perform an action.
3109 It is undefined what happens if @var{cleanup_function} does not
3110 return normally.
3111
3112 @item common
3113 @itemx nocommon
3114 @cindex @code{common} attribute
3115 @cindex @code{nocommon} attribute
3116 @opindex fcommon
3117 @opindex fno-common
3118 The @code{common} attribute requests GCC to place a variable in
3119 ``common'' storage.  The @code{nocommon} attribute requests the
3120 opposite---to allocate space for it directly.
3121
3122 These attributes override the default chosen by the
3123 @option{-fno-common} and @option{-fcommon} flags respectively.
3124
3125 @item deprecated
3126 @cindex @code{deprecated} attribute
3127 The @code{deprecated} attribute results in a warning if the variable
3128 is used anywhere in the source file.  This is useful when identifying
3129 variables that are expected to be removed in a future version of a
3130 program.  The warning also includes the location of the declaration
3131 of the deprecated variable, to enable users to easily find further
3132 information about why the variable is deprecated, or what they should
3133 do instead.  Note that the warning only occurs for uses:
3134
3135 @smallexample
3136 extern int old_var __attribute__ ((deprecated));
3137 extern int old_var;
3138 int new_fn () @{ return old_var; @}
3139 @end smallexample
3140
3141 results in a warning on line 3 but not line 2.
3142
3143 The @code{deprecated} attribute can also be used for functions and
3144 types (@pxref{Function Attributes}, @pxref{Type Attributes}.)
3145
3146 @item mode (@var{mode})
3147 @cindex @code{mode} attribute
3148 This attribute specifies the data type for the declaration---whichever
3149 type corresponds to the mode @var{mode}.  This in effect lets you
3150 request an integer or floating point type according to its width.
3151
3152 You may also specify a mode of @samp{byte} or @samp{__byte__} to
3153 indicate the mode corresponding to a one-byte integer, @samp{word} or
3154 @samp{__word__} for the mode of a one-word integer, and @samp{pointer}
3155 or @samp{__pointer__} for the mode used to represent pointers.
3156
3157 @item packed
3158 @cindex @code{packed} attribute
3159 The @code{packed} attribute specifies that a variable or structure field
3160 should have the smallest possible alignment---one byte for a variable,
3161 and one bit for a field, unless you specify a larger value with the
3162 @code{aligned} attribute.
3163
3164 Here is a structure in which the field @code{x} is packed, so that it
3165 immediately follows @code{a}:
3166
3167 @smallexample
3168 struct foo
3169 @{
3170   char a;
3171   int x[2] __attribute__ ((packed));
3172 @};
3173 @end smallexample
3174
3175 @item section ("@var{section-name}")
3176 @cindex @code{section} variable attribute
3177 Normally, the compiler places the objects it generates in sections like
3178 @code{data} and @code{bss}.  Sometimes, however, you need additional sections,
3179 or you need certain particular variables to appear in special sections,
3180 for example to map to special hardware.  The @code{section}
3181 attribute specifies that a variable (or function) lives in a particular
3182 section.  For example, this small program uses several specific section names:
3183
3184 @smallexample
3185 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
3186 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
3187 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
3188 int init_data __attribute__ ((section ("INITDATA"))) = 0;
3189
3190 main()
3191 @{
3192   /* @r{Initialize stack pointer} */
3193   init_sp (stack + sizeof (stack));
3194
3195   /* @r{Initialize initialized data} */
3196   memcpy (&init_data, &data, &edata - &data);
3197
3198   /* @r{Turn on the serial ports} */
3199   init_duart (&a);
3200   init_duart (&b);
3201 @}
3202 @end smallexample
3203
3204 @noindent
3205 Use the @code{section} attribute with an @emph{initialized} definition
3206 of a @emph{global} variable, as shown in the example.  GCC issues
3207 a warning and otherwise ignores the @code{section} attribute in
3208 uninitialized variable declarations.
3209
3210 You may only use the @code{section} attribute with a fully initialized
3211 global definition because of the way linkers work.  The linker requires
3212 each object be defined once, with the exception that uninitialized
3213 variables tentatively go in the @code{common} (or @code{bss}) section
3214 and can be multiply ``defined''.  You can force a variable to be
3215 initialized with the @option{-fno-common} flag or the @code{nocommon}
3216 attribute.
3217
3218 Some file formats do not support arbitrary sections so the @code{section}
3219 attribute is not available on all platforms.
3220 If you need to map the entire contents of a module to a particular
3221 section, consider using the facilities of the linker instead.
3222
3223 @item shared
3224 @cindex @code{shared} variable attribute
3225 On Microsoft Windows, in addition to putting variable definitions in a named
3226 section, the section can also be shared among all running copies of an
3227 executable or DLL@.  For example, this small program defines shared data
3228 by putting it in a named section @code{shared} and marking the section
3229 shareable:
3230
3231 @smallexample
3232 int foo __attribute__((section ("shared"), shared)) = 0;
3233
3234 int
3235 main()
3236 @{
3237   /* @r{Read and write foo.  All running
3238      copies see the same value.}  */
3239   return 0;
3240 @}
3241 @end smallexample
3242
3243 @noindent
3244 You may only use the @code{shared} attribute along with @code{section}
3245 attribute with a fully initialized global definition because of the way
3246 linkers work.  See @code{section} attribute for more information.
3247
3248 The @code{shared} attribute is only available on Microsoft Windows@.
3249
3250 @item tls_model ("@var{tls_model}")
3251 @cindex @code{tls_model} attribute
3252 The @code{tls_model} attribute sets thread-local storage model
3253 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
3254 overriding @option{-ftls-model=} command line switch on a per-variable
3255 basis.
3256 The @var{tls_model} argument should be one of @code{global-dynamic},
3257 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
3258
3259 Not all targets support this attribute.
3260
3261 @item unused
3262 This attribute, attached to a variable, means that the variable is meant
3263 to be possibly unused.  GCC will not produce a warning for this
3264 variable.
3265
3266 @item used
3267 This attribute, attached to a variable, means that the variable must be
3268 emitted even if it appears that the variable is not referenced.
3269
3270 @item vector_size (@var{bytes})
3271 This attribute specifies the vector size for the variable, measured in
3272 bytes.  For example, the declaration:
3273
3274 @smallexample
3275 int foo __attribute__ ((vector_size (16)));
3276 @end smallexample
3277
3278 @noindent
3279 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
3280 divided into @code{int} sized units.  Assuming a 32-bit int (a vector of
3281 4 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@.
3282
3283 This attribute is only applicable to integral and float scalars,
3284 although arrays, pointers, and function return values are allowed in
3285 conjunction with this construct.
3286
3287 Aggregates with this attribute are invalid, even if they are of the same
3288 size as a corresponding scalar.  For example, the declaration:
3289
3290 @smallexample
3291 struct S @{ int a; @};
3292 struct S  __attribute__ ((vector_size (16))) foo;
3293 @end smallexample
3294
3295 @noindent
3296 is invalid even if the size of the structure is the same as the size of
3297 the @code{int}.
3298
3299 @item selectany
3300 The @code{selectany} attribute causes an initialized global variable to
3301 have link-once semantics.  When multiple definitions of the variable are
3302 encountered by the linker, the first is selected and the remainder are
3303 discarded.  Following usage by the Microsoft compiler, the linker is told
3304 @emph{not} to warn about size or content differences of the multiple
3305 definitions.
3306
3307 Although the primary usage of this attribute is for POD types, the
3308 attribute can also be applied to global C++ objects that are initialized
3309 by a constructor.  In this case, the static initialization and destruction
3310 code for the object is emitted in each translation defining the object,
3311 but the calls to the constructor and destructor are protected by a
3312 link-once guard variable.
3313
3314 The @code{selectany} attribute is only available on Microsoft Windows
3315 targets.  You can use @code{__declspec (selectany)} as a synonym for
3316 @code{__attribute__ ((selectany))} for compatibility with other
3317 compilers.
3318
3319 @item weak
3320 The @code{weak} attribute is described in @xref{Function Attributes}.
3321
3322 @item dllimport
3323 The @code{dllimport} attribute is described in @xref{Function Attributes}.
3324
3325 @item dllexport
3326 The @code{dllexport} attribute is described in @xref{Function Attributes}.
3327
3328 @end table
3329
3330 @subsection M32R/D Variable Attributes
3331
3332 One attribute is currently defined for the M32R/D@.
3333
3334 @table @code
3335 @item model (@var{model-name})
3336 @cindex variable addressability on the M32R/D
3337 Use this attribute on the M32R/D to set the addressability of an object.
3338 The identifier @var{model-name} is one of @code{small}, @code{medium},
3339 or @code{large}, representing each of the code models.
3340
3341 Small model objects live in the lower 16MB of memory (so that their
3342 addresses can be loaded with the @code{ld24} instruction).
3343
3344 Medium and large model objects may live anywhere in the 32-bit address space
3345 (the compiler will generate @code{seth/add3} instructions to load their
3346 addresses).
3347 @end table
3348
3349 @anchor{i386 Variable Attributes}
3350 @subsection i386 Variable Attributes
3351
3352 Two attributes are currently defined for i386 configurations:
3353 @code{ms_struct} and @code{gcc_struct}
3354
3355 @table @code
3356 @item ms_struct
3357 @itemx gcc_struct
3358 @cindex @code{ms_struct} attribute
3359 @cindex @code{gcc_struct} attribute
3360
3361 If @code{packed} is used on a structure, or if bit-fields are used
3362 it may be that the Microsoft ABI packs them differently
3363 than GCC would normally pack them.  Particularly when moving packed
3364 data between functions compiled with GCC and the native Microsoft compiler
3365 (either via function call or as data in a file), it may be necessary to access
3366 either format.
3367
3368 Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
3369 compilers to match the native Microsoft compiler.
3370
3371 The Microsoft structure layout algorithm is fairly simple with the exception
3372 of the bitfield packing:
3373
3374 The padding and alignment of members of structures and whether a bit field
3375 can straddle a storage-unit boundary
3376
3377 @enumerate
3378 @item Structure members are stored sequentially in the order in which they are
3379 declared: the first member has the lowest memory address and the last member
3380 the highest.
3381
3382 @item Every data object has an alignment-requirement. The alignment-requirement
3383 for all data except structures, unions, and arrays is either the size of the
3384 object or the current packing size (specified with either the aligned attribute
3385 or the pack pragma), whichever is less. For structures,  unions, and arrays,
3386 the alignment-requirement is the largest alignment-requirement of its members.
3387 Every object is allocated an offset so that:
3388
3389 offset %  alignment-requirement == 0
3390
3391 @item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation
3392 unit if the integral types are the same size and if the next bit field fits
3393 into the current allocation unit without crossing the boundary imposed by the
3394 common alignment requirements of the bit fields.
3395 @end enumerate
3396
3397 Handling of zero-length bitfields:
3398
3399 MSVC interprets zero-length bitfields in the following ways:
3400
3401 @enumerate
3402 @item If a zero-length bitfield is inserted between two bitfields that would
3403 normally be coalesced, the bitfields will not be coalesced.
3404
3405 For example:
3406
3407 @smallexample
3408 struct
3409  @{
3410    unsigned long bf_1 : 12;
3411    unsigned long : 0;
3412    unsigned long bf_2 : 12;
3413  @} t1;
3414 @end smallexample
3415
3416 The size of @code{t1} would be 8 bytes with the zero-length bitfield.  If the
3417 zero-length bitfield were removed, @code{t1}'s size would be 4 bytes.
3418
3419 @item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the
3420 alignment of the zero-length bitfield is greater than the member that follows it,
3421 @code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield.
3422
3423 For example:
3424
3425 @smallexample
3426 struct
3427  @{
3428    char foo : 4;
3429    short : 0;
3430    char bar;
3431  @} t2;
3432
3433 struct
3434  @{
3435    char foo : 4;
3436    short : 0;
3437    double bar;
3438  @} t3;
3439 @end smallexample
3440
3441 For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1.
3442 Accordingly, the size of @code{t2} will be 4.  For @code{t3}, the zero-length
3443 bitfield will not affect the alignment of @code{bar} or, as a result, the size
3444 of the structure.
3445
3446 Taking this into account, it is important to note the following:
3447
3448 @enumerate
3449 @item If a zero-length bitfield follows a normal bitfield, the type of the
3450 zero-length bitfield may affect the alignment of the structure as whole. For
3451 example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a
3452 normal bitfield, and is of type short.
3453
3454 @item Even if a zero-length bitfield is not followed by a normal bitfield, it may
3455 still affect the alignment of the structure:
3456
3457 @smallexample
3458 struct
3459  @{
3460    char foo : 6;
3461    long : 0;
3462  @} t4;
3463 @end smallexample
3464
3465 Here, @code{t4} will take up 4 bytes.
3466 @end enumerate
3467
3468 @item Zero-length bitfields following non-bitfield members are ignored:
3469
3470 @smallexample
3471 struct
3472  @{
3473    char foo;
3474    long : 0;
3475    char bar;
3476  @} t5;
3477 @end smallexample
3478
3479 Here, @code{t5} will take up 2 bytes.
3480 @end enumerate
3481 @end table
3482
3483 @subsection PowerPC Variable Attributes
3484
3485 Three attributes currently are defined for PowerPC configurations:
3486 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
3487
3488 For full documentation of the struct attributes please see the
3489 documentation in the @xref{i386 Variable Attributes}, section.
3490
3491 For documentation of @code{altivec} attribute please see the
3492 documentation in the @xref{PowerPC Type Attributes}, section.
3493
3494 @subsection SPU Variable Attributes
3495
3496 The SPU supports the @code{spu_vector} attribute for variables.  For
3497 documentation of this attribute please see the documentation in the
3498 @xref{SPU Type Attributes}, section.
3499
3500 @subsection Xstormy16 Variable Attributes
3501
3502 One attribute is currently defined for xstormy16 configurations:
3503 @code{below100}
3504
3505 @table @code
3506 @item below100
3507 @cindex @code{below100} attribute
3508
3509 If a variable has the @code{below100} attribute (@code{BELOW100} is
3510 allowed also), GCC will place the variable in the first 0x100 bytes of
3511 memory and use special opcodes to access it.  Such variables will be
3512 placed in either the @code{.bss_below100} section or the
3513 @code{.data_below100} section.
3514
3515 @end table
3516
3517 @node Type Attributes
3518 @section Specifying Attributes of Types
3519 @cindex attribute of types
3520 @cindex type attributes
3521
3522 The keyword @code{__attribute__} allows you to specify special
3523 attributes of @code{struct} and @code{union} types when you define
3524 such types.  This keyword is followed by an attribute specification
3525 inside double parentheses.  Seven attributes are currently defined for
3526 types: @code{aligned}, @code{packed}, @code{transparent_union},
3527 @code{unused}, @code{deprecated}, @code{visibility}, and
3528 @code{may_alias}.  Other attributes are defined for functions
3529 (@pxref{Function Attributes}) and for variables (@pxref{Variable
3530 Attributes}).
3531
3532 You may also specify any one of these attributes with @samp{__}
3533 preceding and following its keyword.  This allows you to use these
3534 attributes in header files without being concerned about a possible
3535 macro of the same name.  For example, you may use @code{__aligned__}
3536 instead of @code{aligned}.
3537
3538 You may specify type attributes either in a @code{typedef} declaration
3539 or in an enum, struct or union type declaration or definition.
3540
3541 For an enum, struct or union type, you may specify attributes either
3542 between the enum, struct or union tag and the name of the type, or
3543 just past the closing curly brace of the @emph{definition}.  The
3544 former syntax is preferred.
3545
3546 @xref{Attribute Syntax}, for details of the exact syntax for using
3547 attributes.
3548
3549 @table @code
3550 @cindex @code{aligned} attribute
3551 @item aligned (@var{alignment})
3552 This attribute specifies a minimum alignment (in bytes) for variables
3553 of the specified type.  For example, the declarations:
3554
3555 @smallexample
3556 struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
3557 typedef int more_aligned_int __attribute__ ((aligned (8)));
3558 @end smallexample
3559
3560 @noindent
3561 force the compiler to insure (as far as it can) that each variable whose
3562 type is @code{struct S} or @code{more_aligned_int} will be allocated and
3563 aligned @emph{at least} on a 8-byte boundary.  On a SPARC, having all
3564 variables of type @code{struct S} aligned to 8-byte boundaries allows
3565 the compiler to use the @code{ldd} and @code{std} (doubleword load and
3566 store) instructions when copying one variable of type @code{struct S} to
3567 another, thus improving run-time efficiency.
3568
3569 Note that the alignment of any given @code{struct} or @code{union} type
3570 is required by the ISO C standard to be at least a perfect multiple of
3571 the lowest common multiple of the alignments of all of the members of
3572 the @code{struct} or @code{union} in question.  This means that you @emph{can}
3573 effectively adjust the alignment of a @code{struct} or @code{union}
3574 type by attaching an @code{aligned} attribute to any one of the members
3575 of such a type, but the notation illustrated in the example above is a
3576 more obvious, intuitive, and readable way to request the compiler to
3577 adjust the alignment of an entire @code{struct} or @code{union} type.
3578
3579 As in the preceding example, you can explicitly specify the alignment
3580 (in bytes) that you wish the compiler to use for a given @code{struct}
3581 or @code{union} type.  Alternatively, you can leave out the alignment factor
3582 and just ask the compiler to align a type to the maximum
3583 useful alignment for the target machine you are compiling for.  For
3584 example, you could write:
3585
3586 @smallexample
3587 struct S @{ short f[3]; @} __attribute__ ((aligned));
3588 @end smallexample
3589
3590 Whenever you leave out the alignment factor in an @code{aligned}
3591 attribute specification, the compiler automatically sets the alignment
3592 for the type to the largest alignment which is ever used for any data
3593 type on the target machine you are compiling for.  Doing this can often
3594 make copy operations more efficient, because the compiler can use
3595 whatever instructions copy the biggest chunks of memory when performing
3596 copies to or from the variables which have types that you have aligned
3597 this way.
3598
3599 In the example above, if the size of each @code{short} is 2 bytes, then
3600 the size of the entire @code{struct S} type is 6 bytes.  The smallest
3601 power of two which is greater than or equal to that is 8, so the
3602 compiler sets the alignment for the entire @code{struct S} type to 8
3603 bytes.
3604
3605 Note that although you can ask the compiler to select a time-efficient
3606 alignment for a given type and then declare only individual stand-alone
3607 objects of that type, the compiler's ability to select a time-efficient
3608 alignment is primarily useful only when you plan to create arrays of
3609 variables having the relevant (efficiently aligned) type.  If you
3610 declare or use arrays of variables of an efficiently-aligned type, then
3611 it is likely that your program will also be doing pointer arithmetic (or
3612 subscripting, which amounts to the same thing) on pointers to the
3613 relevant type, and the code that the compiler generates for these
3614 pointer arithmetic operations will often be more efficient for
3615 efficiently-aligned types than for other types.
3616
3617 The @code{aligned} attribute can only increase the alignment; but you
3618 can decrease it by specifying @code{packed} as well.  See below.
3619
3620 Note that the effectiveness of @code{aligned} attributes may be limited
3621 by inherent limitations in your linker.  On many systems, the linker is
3622 only able to arrange for variables to be aligned up to a certain maximum
3623 alignment.  (For some linkers, the maximum supported alignment may
3624 be very very small.)  If your linker is only able to align variables
3625 up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
3626 in an @code{__attribute__} will still only provide you with 8 byte
3627 alignment.  See your linker documentation for further information.
3628
3629 @item packed
3630 This attribute, attached to @code{struct} or @code{union} type
3631 definition, specifies that each member (other than zero-width bitfields)
3632 of the structure or union is placed to minimize the memory required.  When
3633 attached to an @code{enum} definition, it indicates that the smallest
3634 integral type should be used.
3635
3636 @opindex fshort-enums
3637 Specifying this attribute for @code{struct} and @code{union} types is
3638 equivalent to specifying the @code{packed} attribute on each of the
3639 structure or union members.  Specifying the @option{-fshort-enums}
3640 flag on the line is equivalent to specifying the @code{packed}
3641 attribute on all @code{enum} definitions.
3642
3643 In the following example @code{struct my_packed_struct}'s members are
3644 packed closely together, but the internal layout of its @code{s} member
3645 is not packed---to do that, @code{struct my_unpacked_struct} would need to
3646 be packed too.
3647
3648 @smallexample
3649 struct my_unpacked_struct
3650  @{
3651     char c;
3652     int i;
3653  @};
3654
3655 struct __attribute__ ((__packed__)) my_packed_struct
3656   @{
3657      char c;
3658      int  i;
3659      struct my_unpacked_struct s;
3660   @};
3661 @end smallexample
3662
3663 You may only specify this attribute on the definition of a @code{enum},
3664 @code{struct} or @code{union}, not on a @code{typedef} which does not
3665 also define the enumerated type, structure or union.
3666
3667 @item transparent_union
3668 This attribute, attached to a @code{union} type definition, indicates
3669 that any function parameter having that union type causes calls to that
3670 function to be treated in a special way.
3671
3672 First, the argument corresponding to a transparent union type can be of
3673 any type in the union; no cast is required.  Also, if the union contains
3674 a pointer type, the corresponding argument can be a null pointer
3675 constant or a void pointer expression; and if the union contains a void
3676 pointer type, the corresponding argument can be any pointer expression.
3677 If the union member type is a pointer, qualifiers like @code{const} on
3678 the referenced type must be respected, just as with normal pointer
3679 conversions.
3680
3681 Second, the argument is passed to the function using the calling
3682 conventions of the first member of the transparent union, not the calling
3683 conventions of the union itself.  All members of the union must have the
3684 same machine representation; this is necessary for this argument passing
3685 to work properly.
3686
3687 Transparent unions are designed for library functions that have multiple
3688 interfaces for compatibility reasons.  For example, suppose the
3689 @code{wait} function must accept either a value of type @code{int *} to
3690 comply with Posix, or a value of type @code{union wait *} to comply with
3691 the 4.1BSD interface.  If @code{wait}'s parameter were @code{void *},
3692 @code{wait} would accept both kinds of arguments, but it would also
3693 accept any other pointer type and this would make argument type checking
3694 less useful.  Instead, @code{<sys/wait.h>} might define the interface
3695 as follows:
3696
3697 @smallexample
3698 typedef union
3699   @{
3700     int *__ip;
3701     union wait *__up;
3702   @} wait_status_ptr_t __attribute__ ((__transparent_union__));
3703
3704 pid_t wait (wait_status_ptr_t);
3705 @end smallexample
3706
3707 This interface allows either @code{int *} or @code{union wait *}
3708 arguments to be passed, using the @code{int *} calling convention.
3709 The program can call @code{wait} with arguments of either type:
3710
3711 @smallexample
3712 int w1 () @{ int w; return wait (&w); @}
3713 int w2 () @{ union wait w; return wait (&w); @}
3714 @end smallexample
3715
3716 With this interface, @code{wait}'s implementation might look like this:
3717
3718 @smallexample
3719 pid_t wait (wait_status_ptr_t p)
3720 @{
3721   return waitpid (-1, p.__ip, 0);
3722 @}
3723 @end smallexample
3724
3725 @item unused
3726 When attached to a type (including a @code{union} or a @code{struct}),
3727 this attribute means that variables of that type are meant to appear
3728 possibly unused.  GCC will not produce a warning for any variables of
3729 that type, even if the variable appears to do nothing.  This is often
3730 the case with lock or thread classes, which are usually defined and then
3731 not referenced, but contain constructors and destructors that have
3732 nontrivial bookkeeping functions.
3733
3734 @item deprecated
3735 The @code{deprecated} attribute results in a warning if the type
3736 is used anywhere in the source file.  This is useful when identifying
3737 types that are expected to be removed in a future version of a program.
3738 If possible, the warning also includes the location of the declaration
3739 of the deprecated type, to enable users to easily find further
3740 information about why the type is deprecated, or what they should do
3741 instead.  Note that the warnings only occur for uses and then only
3742 if the type is being applied to an identifier that itself is not being
3743 declared as deprecated.
3744
3745 @smallexample
3746 typedef int T1 __attribute__ ((deprecated));
3747 T1 x;
3748 typedef T1 T2;
3749 T2 y;
3750 typedef T1 T3 __attribute__ ((deprecated));
3751 T3 z __attribute__ ((deprecated));
3752 @end smallexample
3753
3754 results in a warning on line 2 and 3 but not lines 4, 5, or 6.  No
3755 warning is issued for line 4 because T2 is not explicitly
3756 deprecated.  Line 5 has no warning because T3 is explicitly
3757 deprecated.  Similarly for line 6.
3758
3759 The @code{deprecated} attribute can also be used for functions and
3760 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
3761
3762 @item may_alias
3763 Accesses to objects with types with this attribute are not subjected to
3764 type-based alias analysis, but are instead assumed to be able to alias
3765 any other type of objects, just like the @code{char} type.  See
3766 @option{-fstrict-aliasing} for more information on aliasing issues.
3767
3768 Example of use:
3769
3770 @smallexample
3771 typedef short __attribute__((__may_alias__)) short_a;
3772
3773 int
3774 main (void)
3775 @{
3776   int a = 0x12345678;
3777   short_a *b = (short_a *) &a;
3778
3779   b[1] = 0;
3780
3781   if (a == 0x12345678)
3782     abort();
3783
3784   exit(0);
3785 @}
3786 @end smallexample
3787
3788 If you replaced @code{short_a} with @code{short} in the variable
3789 declaration, the above program would abort when compiled with
3790 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
3791 above in recent GCC versions.
3792
3793 @item visibility
3794 In C++, attribute visibility (@pxref{Function Attributes}) can also be
3795 applied to class, struct, union and enum types.  Unlike other type
3796 attributes, the attribute must appear between the initial keyword and
3797 the name of the type; it cannot appear after the body of the type.
3798
3799 Note that the type visibility is applied to vague linkage entities
3800 associated with the class (vtable, typeinfo node, etc.).  In
3801 particular, if a class is thrown as an exception in one shared object
3802 and caught in another, the class must have default visibility.
3803 Otherwise the two shared objects will be unable to use the same
3804 typeinfo node and exception handling will break.
3805
3806 @subsection ARM Type Attributes
3807
3808 On those ARM targets that support @code{dllimport} (such as Symbian
3809 OS), you can use the @code{notshared} attribute to indicate that the
3810 virtual table and other similar data for a class should not be
3811 exported from a DLL@.  For example:
3812
3813 @smallexample
3814 class __declspec(notshared) C @{
3815 public:
3816   __declspec(dllimport) C();
3817   virtual void f();
3818 @}
3819
3820 __declspec(dllexport)
3821 C::C() @{@}
3822 @end smallexample
3823
3824 In this code, @code{C::C} is exported from the current DLL, but the
3825 virtual table for @code{C} is not exported.  (You can use
3826 @code{__attribute__} instead of @code{__declspec} if you prefer, but
3827 most Symbian OS code uses @code{__declspec}.)
3828
3829 @anchor{i386 Type Attributes}
3830 @subsection i386 Type Attributes
3831
3832 Two attributes are currently defined for i386 configurations:
3833 @code{ms_struct} and @code{gcc_struct}
3834
3835 @item ms_struct
3836 @itemx gcc_struct
3837 @cindex @code{ms_struct}
3838 @cindex @code{gcc_struct}
3839
3840 If @code{packed} is used on a structure, or if bit-fields are used
3841 it may be that the Microsoft ABI packs them differently
3842 than GCC would normally pack them.  Particularly when moving packed
3843 data between functions compiled with GCC and the native Microsoft compiler
3844 (either via function call or as data in a file), it may be necessary to access
3845 either format.
3846
3847 Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
3848 compilers to match the native Microsoft compiler.
3849 @end table
3850
3851 To specify multiple attributes, separate them by commas within the
3852 double parentheses: for example, @samp{__attribute__ ((aligned (16),
3853 packed))}.
3854
3855 @anchor{PowerPC Type Attributes}
3856 @subsection PowerPC Type Attributes
3857
3858 Three attributes currently are defined for PowerPC configurations:
3859 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
3860
3861 For full documentation of the struct attributes please see the
3862 documentation in the @xref{i386 Type Attributes}, section.
3863
3864 The @code{altivec} attribute allows one to declare AltiVec vector data
3865 types supported by the AltiVec Programming Interface Manual.  The
3866 attribute requires an argument to specify one of three vector types:
3867 @code{vector__}, @code{pixel__} (always followed by unsigned short),
3868 and @code{bool__} (always followed by unsigned).
3869
3870 @smallexample
3871 __attribute__((altivec(vector__)))
3872 __attribute__((altivec(pixel__))) unsigned short
3873 __attribute__((altivec(bool__))) unsigned
3874 @end smallexample
3875
3876 These attributes mainly are intended to support the @code{__vector},
3877 @code{__pixel}, and @code{__bool} AltiVec keywords.
3878
3879 @anchor{SPU Type Attributes}
3880 @subsection SPU Type Attributes
3881
3882 The SPU supports the @code{spu_vector} attribute for types.  This attribute
3883 allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
3884 Language Extensions Specification.  It is intended to support the
3885 @code{__vector} keyword.
3886
3887
3888 @node Inline
3889 @section An Inline Function is As Fast As a Macro
3890 @cindex inline functions
3891 @cindex integrating function code
3892 @cindex open coding
3893 @cindex macros, inline alternative
3894
3895 By declaring a function inline, you can direct GCC to make
3896 calls to that function faster.  One way GCC can achieve this is to
3897 integrate that function's code into the code for its callers.  This
3898 makes execution faster by eliminating the function-call overhead; in
3899 addition, if any of the actual argument values are constant, their
3900 known values may permit simplifications at compile time so that not
3901 all of the inline function's code needs to be included.  The effect on
3902 code size is less predictable; object code may be larger or smaller
3903 with function inlining, depending on the particular case.  You can
3904 also direct GCC to try to integrate all ``simple enough'' functions
3905 into their callers with the option @option{-finline-functions}.
3906
3907 GCC implements three different semantics of declaring a function
3908 inline.  One is available with @option{-std=gnu89} or
3909 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
3910 on all inline declarations, another when @option{-std=c99} or
3911 @option{-std=gnu99} (without @option{-fgnu89-inline}), and the third
3912 is used when compiling C++.
3913
3914 To declare a function inline, use the @code{inline} keyword in its
3915 declaration, like this:
3916
3917 @smallexample
3918 static inline int
3919 inc (int *a)
3920 @{
3921   (*a)++;
3922 @}
3923 @end smallexample
3924
3925 If you are writing a header file to be included in ISO C89 programs, write
3926 @code{__inline__} instead of @code{inline}.  @xref{Alternate Keywords}.
3927
3928 The three types of inlining behave similarly in two important cases:
3929 when the @code{inline} keyword is used on a @code{static} function,
3930 like the example above, and when a function is first declared without
3931 using the @code{inline} keyword and then is defined with
3932 @code{inline}, like this:
3933
3934 @smallexample
3935 extern int inc (int *a);
3936 inline int
3937 inc (int *a)
3938 @{
3939   (*a)++;
3940 @}
3941 @end smallexample
3942
3943 In both of these common cases, the program behaves the same as if you
3944 had not used the @code{inline} keyword, except for its speed.
3945
3946 @cindex inline functions, omission of
3947 @opindex fkeep-inline-functions
3948 When a function is both inline and @code{static}, if all calls to the
3949 function are integrated into the caller, and the function's address is
3950 never used, then the function's own assembler code is never referenced.
3951 In this case, GCC does not actually output assembler code for the
3952 function, unless you specify the option @option{-fkeep-inline-functions}.
3953 Some calls cannot be integrated for various reasons (in particular,
3954 calls that precede the function's definition cannot be integrated, and
3955 neither can recursive calls within the definition).  If there is a
3956 nonintegrated call, then the function is compiled to assembler code as
3957 usual.  The function must also be compiled as usual if the program
3958 refers to its address, because that can't be inlined.
3959
3960 @opindex Winline
3961 Note that certain usages in a function definition can make it unsuitable
3962 for inline substitution.  Among these usages are: use of varargs, use of
3963 alloca, use of variable sized data types (@pxref{Variable Length}),
3964 use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
3965 and nested functions (@pxref{Nested Functions}).  Using @option{-Winline}
3966 will warn when a function marked @code{inline} could not be substituted,
3967 and will give the reason for the failure.
3968
3969 @cindex automatic @code{inline} for C++ member fns
3970 @cindex @code{inline} automatic for C++ member fns
3971 @cindex member fns, automatically @code{inline}
3972 @cindex C++ member fns, automatically @code{inline}
3973 @opindex fno-default-inline
3974 As required by ISO C++, GCC considers member functions defined within
3975 the body of a class to be marked inline even if they are
3976 not explicitly declared with the @code{inline} keyword.  You can
3977 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
3978 Options,,Options Controlling C++ Dialect}.
3979
3980 GCC does not inline any functions when not optimizing unless you specify
3981 the @samp{always_inline} attribute for the function, like this:
3982
3983 @smallexample
3984 /* @r{Prototype.}  */
3985 inline void foo (const char) __attribute__((always_inline));
3986 @end smallexample
3987
3988 The remainder of this section is specific to GNU C89 inlining.
3989
3990 @cindex non-static inline function
3991 When an inline function is not @code{static}, then the compiler must assume
3992 that there may be calls from other source files; since a global symbol can
3993 be defined only once in any program, the function must not be defined in
3994 the other source files, so the calls therein cannot be integrated.
3995 Therefore, a non-@code{static} inline function is always compiled on its
3996 own in the usual fashion.
3997
3998 If you specify both @code{inline} and @code{extern} in the function
3999 definition, then the definition is used only for inlining.  In no case
4000 is the function compiled on its own, not even if you refer to its
4001 address explicitly.  Such an address becomes an external reference, as
4002 if you had only declared the function, and had not defined it.
4003
4004 This combination of @code{inline} and @code{extern} has almost the
4005 effect of a macro.  The way to use it is to put a function definition in
4006 a header file with these keywords, and put another copy of the
4007 definition (lacking @code{inline} and @code{extern}) in a library file.
4008 The definition in the header file will cause most calls to the function
4009 to be inlined.  If any uses of the function remain, they will refer to
4010 the single copy in the library.
4011
4012 @node Extended Asm
4013 @section Assembler Instructions with C Expression Operands
4014 @cindex extended @code{asm}
4015 @cindex @code{asm} expressions
4016 @cindex assembler instructions
4017 @cindex registers
4018
4019 In an assembler instruction using @code{asm}, you can specify the
4020 operands of the instruction using C expressions.  This means you need not
4021 guess which registers or memory locations will contain the data you want
4022 to use.
4023
4024 You must specify an assembler instruction template much like what
4025 appears in a machine description, plus an operand constraint string for
4026 each operand.
4027
4028 For example, here is how to use the 68881's @code{fsinx} instruction:
4029
4030 @smallexample
4031 asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
4032 @end smallexample
4033
4034 @noindent
4035 Here @code{angle} is the C expression for the input operand while
4036 @code{result} is that of the output operand.  Each has @samp{"f"} as its
4037 operand constraint, saying that a floating point register is required.
4038 The @samp{=} in @samp{=f} indicates that the operand is an output; all
4039 output operands' constraints must use @samp{=}.  The constraints use the
4040 same language used in the machine description (@pxref{Constraints}).
4041
4042 Each operand is described by an operand-constraint string followed by
4043 the C expression in parentheses.  A colon separates the assembler
4044 template from the first output operand and another separates the last
4045 output operand from the first input, if any.  Commas separate the
4046 operands within each group.  The total number of operands is currently
4047 limited to 30; this limitation may be lifted in some future version of
4048 GCC@.
4049
4050 If there are no output operands but there are input operands, you must
4051 place two consecutive colons surrounding the place where the output
4052 operands would go.
4053
4054 As of GCC version 3.1, it is also possible to specify input and output
4055 operands using symbolic names which can be referenced within the
4056 assembler code.  These names are specified inside square brackets
4057 preceding the constraint string, and can be referenced inside the
4058 assembler code using @code{%[@var{name}]} instead of a percentage sign
4059 followed by the operand number.  Using named operands the above example
4060 could look like:
4061
4062 @smallexample
4063 asm ("fsinx %[angle],%[output]"
4064      : [output] "=f" (result)
4065      : [angle] "f" (angle));
4066 @end smallexample
4067
4068 @noindent
4069 Note that the symbolic operand names have no relation whatsoever to
4070 other C identifiers.  You may use any name you like, even those of
4071 existing C symbols, but you must ensure that no two operands within the same
4072 assembler construct use the same symbolic name.
4073
4074 Output operand expressions must be lvalues; the compiler can check this.
4075 The input operands need not be lvalues.  The compiler cannot check
4076 whether the operands have data types that are reasonable for the
4077 instruction being executed.  It does not parse the assembler instruction
4078 template and does not know what it means or even whether it is valid
4079 assembler input.  The extended @code{asm} feature is most often used for
4080 machine instructions the compiler itself does not know exist.  If
4081 the output expression cannot be directly addressed (for example, it is a
4082 bit-field), your constraint must allow a register.  In that case, GCC
4083 will use the register as the output of the @code{asm}, and then store
4084 that register into the output.
4085
4086 The ordinary output operands must be write-only; GCC will assume that
4087 the values in these operands before the instruction are dead and need
4088 not be generated.  Extended asm supports input-output or read-write
4089 operands.  Use the constraint character @samp{+} to indicate such an
4090 operand and list it with the output operands.  You should only use
4091 read-write operands when the constraints for the operand (or the
4092 operand in which only some of the bits are to be changed) allow a
4093 register.
4094
4095 You may, as an alternative, logically split its function into two
4096 separate operands, one input operand and one write-only output
4097 operand.  The connection between them is expressed by constraints
4098 which say they need to be in the same location when the instruction
4099 executes.  You can use the same C expression for both operands, or
4100 different expressions.  For example, here we write the (fictitious)
4101 @samp{combine} instruction with @code{bar} as its read-only source
4102 operand and @code{foo} as its read-write destination:
4103
4104 @smallexample
4105 asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
4106 @end smallexample
4107
4108 @noindent
4109 The constraint @samp{"0"} for operand 1 says that it must occupy the
4110 same location as operand 0.  A number in constraint is allowed only in
4111 an input operand and it must refer to an output operand.
4112
4113 Only a number in the constraint can guarantee that one operand will be in
4114 the same place as another.  The mere fact that @code{foo} is the value
4115 of both operands is not enough to guarantee that they will be in the
4116 same place in the generated assembler code.  The following would not
4117 work reliably:
4118
4119 @smallexample
4120 asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
4121 @end smallexample
4122
4123 Various optimizations or reloading could cause operands 0 and 1 to be in
4124 different registers; GCC knows no reason not to do so.  For example, the
4125 compiler might find a copy of the value of @code{foo} in one register and
4126 use it for operand 1, but generate the output operand 0 in a different
4127 register (copying it afterward to @code{foo}'s own address).  Of course,
4128 since the register for operand 1 is not even mentioned in the assembler
4129 code, the result will not work, but GCC can't tell that.
4130
4131 As of GCC version 3.1, one may write @code{[@var{name}]} instead of
4132 the operand number for a matching constraint.  For example:
4133
4134 @smallexample
4135 asm ("cmoveq %1,%2,%[result]"
4136      : [result] "=r"(result)
4137      : "r" (test), "r"(new), "[result]"(old));
4138 @end smallexample
4139
4140 Sometimes you need to make an @code{asm} operand be a specific register,
4141 but there's no matching constraint letter for that register @emph{by
4142 itself}.  To force the operand into that register, use a local variable
4143 for the operand and specify the register in the variable declaration.
4144 @xref{Explicit Reg Vars}.  Then for the @code{asm} operand, use any
4145 register constraint letter that matches the register:
4146
4147 @smallexample
4148 register int *p1 asm ("r0") = @dots{};
4149 register int *p2 asm ("r1") = @dots{};
4150 register int *result asm ("r0");
4151 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
4152 @end smallexample
4153
4154 @anchor{Example of asm with clobbered asm reg}
4155 In the above example, beware that a register that is call-clobbered by
4156 the target ABI will be overwritten by any function call in the
4157 assignment, including library calls for arithmetic operators.
4158 Assuming it is a call-clobbered register, this may happen to @code{r0}
4159 above by the assignment to @code{p2}.  If you have to use such a
4160 register, use temporary variables for expressions between the register
4161 assignment and use:
4162
4163 @smallexample
4164 int t1 = @dots{};
4165 register int *p1 asm ("r0") = @dots{};
4166 register int *p2 asm ("r1") = t1;
4167 register int *result asm ("r0");
4168 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
4169 @end smallexample
4170
4171 Some instructions clobber specific hard registers.  To describe this,
4172 write a third colon after the input operands, followed by the names of
4173 the clobbered hard registers (given as strings).  Here is a realistic
4174 example for the VAX:
4175
4176 @smallexample
4177 asm volatile ("movc3 %0,%1,%2"
4178               : /* @r{no outputs} */
4179               : "g" (from), "g" (to), "g" (count)
4180               : "r0", "r1", "r2", "r3", "r4", "r5");
4181 @end smallexample
4182
4183 You may not write a clobber description in a way that overlaps with an
4184 input or output operand.  For example, you may not have an operand
4185 describing a register class with one member if you mention that register
4186 in the clobber list.  Variables declared to live in specific registers
4187 (@pxref{Explicit Reg Vars}), and used as asm input or output operands must
4188 have no part mentioned in the clobber description.
4189 There is no way for you to specify that an input
4190 operand is modified without also specifying it as an output
4191 operand.  Note that if all the output operands you specify are for this
4192 purpose (and hence unused), you will then also need to specify
4193 @code{volatile} for the @code{asm} construct, as described below, to
4194 prevent GCC from deleting the @code{asm} statement as unused.
4195
4196 If you refer to a particular hardware register from the assembler code,
4197 you will probably have to list the register after the third colon to
4198 tell the compiler the register's value is modified.  In some assemblers,
4199 the register names begin with @samp{%}; to produce one @samp{%} in the
4200 assembler code, you must write @samp{%%} in the input.
4201
4202 If your assembler instruction can alter the condition code register, add
4203 @samp{cc} to the list of clobbered registers.  GCC on some machines
4204 represents the condition codes as a specific hardware register;
4205 @samp{cc} serves to name this register.  On other machines, the
4206 condition code is handled differently, and specifying @samp{cc} has no
4207 effect.  But it is valid no matter what the machine.
4208
4209 If your assembler instructions access memory in an unpredictable
4210 fashion, add @samp{memory} to the list of clobbered registers.  This
4211 will cause GCC to not keep memory values cached in registers across the
4212 assembler instruction and not optimize stores or loads to that memory.
4213 You will also want to add the @code{volatile} keyword if the memory
4214 affected is not listed in the inputs or outputs of the @code{asm}, as
4215 the @samp{memory} clobber does not count as a side-effect of the
4216 @code{asm}.  If you know how large the accessed memory is, you can add
4217 it as input or output but if this is not known,&nb