OSDN Git Service

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