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