OSDN Git Service

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