OSDN Git Service

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