OSDN Git Service

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