OSDN Git Service

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