OSDN Git Service

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