OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [gcc/] [doc/] [extend.texi] - Blame information for rev 284

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 284 jeremybenn
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
2
@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
3
@c Free Software Foundation, Inc.
4
 
5
@c This is part of the GCC manual.
6
@c For copying conditions, see the file gcc.texi.
7
 
8
@node C Extensions
9
@chapter Extensions to the C Language Family
10
@cindex extensions, C language
11
@cindex C language extensions
12
 
13
@opindex pedantic
14
GNU C provides several language features not found in ISO standard C@.
15
(The @option{-pedantic} option directs GCC to print a warning message if
16
any of these features is used.)  To test for the availability of these
17
features in conditional compilation, check for a predefined macro
18
@code{__GNUC__}, which is always defined under GCC@.
19
 
20
These extensions are available in C and Objective-C@.  Most of them are
21
also available in C++.  @xref{C++ Extensions,,Extensions to the
22
C++ Language}, for extensions that apply @emph{only} to C++.
23
 
24
Some features that are in ISO C99 but not C90 or C++ are also, as
25
extensions, accepted by GCC in C90 mode and in C++.
26
 
27
@menu
28
* Statement Exprs::     Putting statements and declarations inside expressions.
29
* Local Labels::        Labels local to a block.
30
* Labels as Values::    Getting pointers to labels, and computed gotos.
31
* Nested Functions::    As in Algol and Pascal, lexical scoping of functions.
32
* Constructing Calls::  Dispatching a call to another function.
33
* Typeof::              @code{typeof}: referring to the type of an expression.
34
* Conditionals::        Omitting the middle operand of a @samp{?:} expression.
35
* Long Long::           Double-word integers---@code{long long int}.
36
* Complex::             Data types for complex numbers.
37
* Floating Types::      Additional Floating Types.
38
* Half-Precision::      Half-Precision Floating Point.
39
* Decimal Float::       Decimal Floating Types.
40
* Hex Floats::          Hexadecimal floating-point constants.
41
* Fixed-Point::         Fixed-Point Types.
42
* Named Address Spaces::Named address spaces.
43
* Zero Length::         Zero-length arrays.
44
* Variable Length::     Arrays whose length is computed at run time.
45
* Empty Structures::    Structures with no members.
46
* Variadic Macros::     Macros with a variable number of arguments.
47
* Escaped Newlines::    Slightly looser rules for escaped newlines.
48
* Subscripting::        Any array can be subscripted, even if not an lvalue.
49
* Pointer Arith::       Arithmetic on @code{void}-pointers and function pointers.
50
* Initializers::        Non-constant initializers.
51
* Compound Literals::   Compound literals give structures, unions
52
                        or arrays as values.
53
* Designated Inits::    Labeling elements of initializers.
54
* Cast to Union::       Casting to union type from any member of the union.
55
* Case Ranges::         `case 1 ... 9' and such.
56
* Mixed Declarations::  Mixing declarations and code.
57
* Function Attributes:: Declaring that functions have no side effects,
58
                        or that they can never return.
59
* Attribute Syntax::    Formal syntax for attributes.
60
* Function Prototypes:: Prototype declarations and old-style definitions.
61
* C++ Comments::        C++ comments are recognized.
62
* Dollar Signs::        Dollar sign is allowed in identifiers.
63
* Character Escapes::   @samp{\e} stands for the character @key{ESC}.
64
* Variable Attributes:: Specifying attributes of variables.
65
* Type Attributes::     Specifying attributes of types.
66
* Alignment::           Inquiring about the alignment of a type or variable.
67
* Inline::              Defining inline functions (as fast as macros).
68
* Extended Asm::        Assembler instructions with C expressions as operands.
69
                        (With them you can define ``built-in'' functions.)
70
* Constraints::         Constraints for asm operands
71
* Asm Labels::          Specifying the assembler name to use for a C symbol.
72
* Explicit Reg Vars::   Defining variables residing in specified registers.
73
* Alternate Keywords::  @code{__const__}, @code{__asm__}, etc., for header files.
74
* Incomplete Enums::    @code{enum foo;}, with details to follow.
75
* Function Names::      Printable strings which are the name of the current
76
                        function.
77
* Return Address::      Getting the return or frame address of a function.
78
* Vector Extensions::   Using vector instructions through built-in functions.
79
* Offsetof::            Special syntax for implementing @code{offsetof}.
80
* Atomic Builtins::     Built-in functions for atomic memory access.
81
* Object Size Checking:: Built-in functions for limited buffer overflow
82
                        checking.
83
* Other Builtins::      Other built-in functions.
84
* Target Builtins::     Built-in functions specific to particular targets.
85
* Target Format Checks:: Format checks specific to particular targets.
86
* Pragmas::             Pragmas accepted by GCC.
87
* Unnamed Fields::      Unnamed struct/union fields within structs/unions.
88
* Thread-Local::        Per-thread variables.
89
* Binary constants::    Binary constants using the @samp{0b} prefix.
90
@end menu
91
 
92
@node Statement Exprs
93
@section Statements and Declarations in Expressions
94
@cindex statements inside expressions
95
@cindex declarations inside expressions
96
@cindex expressions containing statements
97
@cindex macros, statements in expressions
98
 
99
@c the above section title wrapped and causes an underfull hbox.. i
100
@c changed it from "within" to "in". --mew 4feb93
101
A compound statement enclosed in parentheses may appear as an expression
102
in GNU C@.  This allows you to use loops, switches, and local variables
103
within an expression.
104
 
105
Recall that a compound statement is a sequence of statements surrounded
106
by braces; in this construct, parentheses go around the braces.  For
107
example:
108
 
109
@smallexample
110
(@{ int y = foo (); int z;
111
   if (y > 0) z = y;
112
   else z = - y;
113
   z; @})
114
@end smallexample
115
 
116
@noindent
117
is a valid (though slightly more complex than necessary) expression
118
for the absolute value of @code{foo ()}.
119
 
120
The last thing in the compound statement should be an expression
121
followed by a semicolon; the value of this subexpression serves as the
122
value of the entire construct.  (If you use some other kind of statement
123
last within the braces, the construct has type @code{void}, and thus
124
effectively no value.)
125
 
126
This feature is especially useful in making macro definitions ``safe'' (so
127
that they evaluate each operand exactly once).  For example, the
128
``maximum'' function is commonly defined as a macro in standard C as
129
follows:
130
 
131
@smallexample
132
#define max(a,b) ((a) > (b) ? (a) : (b))
133
@end smallexample
134
 
135
@noindent
136
@cindex side effects, macro argument
137
But this definition computes either @var{a} or @var{b} twice, with bad
138
results if the operand has side effects.  In GNU C, if you know the
139
type of the operands (here taken as @code{int}), you can define
140
the macro safely as follows:
141
 
142
@smallexample
143
#define maxint(a,b) \
144
  (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
145
@end smallexample
146
 
147
Embedded statements are not allowed in constant expressions, such as
148
the value of an enumeration constant, the width of a bit-field, or
149
the initial value of a static variable.
150
 
151
If you don't know the type of the operand, you can still do this, but you
152
must use @code{typeof} (@pxref{Typeof}).
153
 
154
In G++, the result value of a statement expression undergoes array and
155
function pointer decay, and is returned by value to the enclosing
156
expression.  For instance, if @code{A} is a class, then
157
 
158
@smallexample
159
        A a;
160
 
161
        (@{a;@}).Foo ()
162
@end smallexample
163
 
164
@noindent
165
will construct a temporary @code{A} object to hold the result of the
166
statement expression, and that will be used to invoke @code{Foo}.
167
Therefore the @code{this} pointer observed by @code{Foo} will not be the
168
address of @code{a}.
169
 
170
Any temporaries created within a statement within a statement expression
171
will be destroyed at the statement's end.  This makes statement
172
expressions inside macros slightly different from function calls.  In
173
the latter case temporaries introduced during argument evaluation will
174
be destroyed at the end of the statement that includes the function
175
call.  In the statement expression case they will be destroyed during
176
the statement expression.  For instance,
177
 
178
@smallexample
179
#define macro(a)  (@{__typeof__(a) b = (a); b + 3; @})
180
template<typename T> T function(T a) @{ T b = a; return b + 3; @}
181
 
182
void foo ()
183
@{
184
  macro (X ());
185
  function (X ());
186
@}
187
@end smallexample
188
 
189
@noindent
190
will have different places where temporaries are destroyed.  For the
191
@code{macro} case, the temporary @code{X} will be destroyed just after
192
the initialization of @code{b}.  In the @code{function} case that
193
temporary will be destroyed when the function returns.
194
 
195
These considerations mean that it is probably a bad idea to use
196
statement-expressions of this form in header files that are designed to
197
work with C++.  (Note that some versions of the GNU C Library contained
198
header files using statement-expression that lead to precisely this
199
bug.)
200
 
201
Jumping into a statement expression with @code{goto} or using a
202
@code{switch} statement outside the statement expression with a
203
@code{case} or @code{default} label inside the statement expression is
204
not permitted.  Jumping into a statement expression with a computed
205
@code{goto} (@pxref{Labels as Values}) yields undefined behavior.
206
Jumping out of a statement expression is permitted, but if the
207
statement expression is part of a larger expression then it is
208
unspecified which other subexpressions of that expression have been
209
evaluated except where the language definition requires certain
210
subexpressions to be evaluated before or after the statement
211
expression.  In any case, as with a function call the evaluation of a
212
statement expression is not interleaved with the evaluation of other
213
parts of the containing expression.  For example,
214
 
215
@smallexample
216
  foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
217
@end smallexample
218
 
219
@noindent
220
will call @code{foo} and @code{bar1} and will not call @code{baz} but
221
may or may not call @code{bar2}.  If @code{bar2} is called, it will be
222
called after @code{foo} and before @code{bar1}
223
 
224
@node Local Labels
225
@section Locally Declared Labels
226
@cindex local labels
227
@cindex macros, local labels
228
 
229
GCC allows you to declare @dfn{local labels} in any nested block
230
scope.  A local label is just like an ordinary label, but you can
231
only reference it (with a @code{goto} statement, or by taking its
232
address) within the block in which it was declared.
233
 
234
A local label declaration looks like this:
235
 
236
@smallexample
237
__label__ @var{label};
238
@end smallexample
239
 
240
@noindent
241
or
242
 
243
@smallexample
244
__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
245
@end smallexample
246
 
247
Local label declarations must come at the beginning of the block,
248
before any ordinary declarations or statements.
249
 
250
The label declaration defines the label @emph{name}, but does not define
251
the label itself.  You must do this in the usual way, with
252
@code{@var{label}:}, within the statements of the statement expression.
253
 
254
The local label feature is useful for complex macros.  If a macro
255
contains nested loops, a @code{goto} can be useful for breaking out of
256
them.  However, an ordinary label whose scope is the whole function
257
cannot be used: if the macro can be expanded several times in one
258
function, the label will be multiply defined in that function.  A
259
local label avoids this problem.  For example:
260
 
261
@smallexample
262
#define SEARCH(value, array, target)              \
263
do @{                                              \
264
  __label__ found;                                \
265
  typeof (target) _SEARCH_target = (target);      \
266
  typeof (*(array)) *_SEARCH_array = (array);     \
267
  int i, j;                                       \
268
  int value;                                      \
269
  for (i = 0; i < max; i++)                       \
270
    for (j = 0; j < max; j++)                     \
271
      if (_SEARCH_array[i][j] == _SEARCH_target)  \
272
        @{ (value) = i; goto found; @}              \
273
  (value) = -1;                                   \
274
 found:;                                          \
275
@} while (0)
276
@end smallexample
277
 
278
This could also be written using a statement-expression:
279
 
280
@smallexample
281
#define SEARCH(array, target)                     \
282
(@{                                                \
283
  __label__ found;                                \
284
  typeof (target) _SEARCH_target = (target);      \
285
  typeof (*(array)) *_SEARCH_array = (array);     \
286
  int i, j;                                       \
287
  int value;                                      \
288
  for (i = 0; i < max; i++)                       \
289
    for (j = 0; j < max; j++)                     \
290
      if (_SEARCH_array[i][j] == _SEARCH_target)  \
291
        @{ value = i; goto found; @}                \
292
  value = -1;                                     \
293
 found:                                           \
294
  value;                                          \
295
@})
296
@end smallexample
297
 
298
Local label declarations also make the labels they declare visible to
299
nested functions, if there are any.  @xref{Nested Functions}, for details.
300
 
301
@node Labels as Values
302
@section Labels as Values
303
@cindex labels as values
304
@cindex computed gotos
305
@cindex goto with computed label
306
@cindex address of a label
307
 
308
You can get the address of a label defined in the current function
309
(or a containing function) with the unary operator @samp{&&}.  The
310
value has type @code{void *}.  This value is a constant and can be used
311
wherever a constant of that type is valid.  For example:
312
 
313
@smallexample
314
void *ptr;
315
/* @r{@dots{}} */
316
ptr = &&foo;
317
@end smallexample
318
 
319
To use these values, you need to be able to jump to one.  This is done
320
with the computed goto statement@footnote{The analogous feature in
321
Fortran is called an assigned goto, but that name seems inappropriate in
322
C, where one can do more than simply store label addresses in label
323
variables.}, @code{goto *@var{exp};}.  For example,
324
 
325
@smallexample
326
goto *ptr;
327
@end smallexample
328
 
329
@noindent
330
Any expression of type @code{void *} is allowed.
331
 
332
One way of using these constants is in initializing a static array that
333
will serve as a jump table:
334
 
335
@smallexample
336
static void *array[] = @{ &&foo, &&bar, &&hack @};
337
@end smallexample
338
 
339
Then you can select a label with indexing, like this:
340
 
341
@smallexample
342
goto *array[i];
343
@end smallexample
344
 
345
@noindent
346
Note that this does not check whether the subscript is in bounds---array
347
indexing in C never does that.
348
 
349
Such an array of label values serves a purpose much like that of the
350
@code{switch} statement.  The @code{switch} statement is cleaner, so
351
use that rather than an array unless the problem does not fit a
352
@code{switch} statement very well.
353
 
354
Another use of label values is in an interpreter for threaded code.
355
The labels within the interpreter function can be stored in the
356
threaded code for super-fast dispatching.
357
 
358
You may not use this mechanism to jump to code in a different function.
359
If you do that, totally unpredictable things will happen.  The best way to
360
avoid this is to store the label address only in automatic variables and
361
never pass it as an argument.
362
 
363
An alternate way to write the above example is
364
 
365
@smallexample
366
static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
367
                             &&hack - &&foo @};
368
goto *(&&foo + array[i]);
369
@end smallexample
370
 
371
@noindent
372
This is more friendly to code living in shared libraries, as it reduces
373
the number of dynamic relocations that are needed, and by consequence,
374
allows the data to be read-only.
375
 
376
The @code{&&foo} expressions for the same label might have different
377
values if the containing function is inlined or cloned.  If a program
378
relies on them being always the same,
379
@code{__attribute__((__noinline__,__noclone__))} should be used to
380
prevent inlining and cloning.  If @code{&&foo} is used in a static
381
variable initializer, inlining and cloning is forbidden.
382
 
383
@node Nested Functions
384
@section Nested Functions
385
@cindex nested functions
386
@cindex downward funargs
387
@cindex thunks
388
 
389
A @dfn{nested function} is a function defined inside another function.
390
(Nested functions are not supported for GNU C++.)  The nested function's
391
name is local to the block where it is defined.  For example, here we
392
define a nested function named @code{square}, and call it twice:
393
 
394
@smallexample
395
@group
396
foo (double a, double b)
397
@{
398
  double square (double z) @{ return z * z; @}
399
 
400
  return square (a) + square (b);
401
@}
402
@end group
403
@end smallexample
404
 
405
The nested function can access all the variables of the containing
406
function that are visible at the point of its definition.  This is
407
called @dfn{lexical scoping}.  For example, here we show a nested
408
function which uses an inherited variable named @code{offset}:
409
 
410
@smallexample
411
@group
412
bar (int *array, int offset, int size)
413
@{
414
  int access (int *array, int index)
415
    @{ return array[index + offset]; @}
416
  int i;
417
  /* @r{@dots{}} */
418
  for (i = 0; i < size; i++)
419
    /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
420
@}
421
@end group
422
@end smallexample
423
 
424
Nested function definitions are permitted within functions in the places
425
where variable definitions are allowed; that is, in any block, mixed
426
with the other declarations and statements in the block.
427
 
428
It is possible to call the nested function from outside the scope of its
429
name by storing its address or passing the address to another function:
430
 
431
@smallexample
432
hack (int *array, int size)
433
@{
434
  void store (int index, int value)
435
    @{ array[index] = value; @}
436
 
437
  intermediate (store, size);
438
@}
439
@end smallexample
440
 
441
Here, the function @code{intermediate} receives the address of
442
@code{store} as an argument.  If @code{intermediate} calls @code{store},
443
the arguments given to @code{store} are used to store into @code{array}.
444
But this technique works only so long as the containing function
445
(@code{hack}, in this example) does not exit.
446
 
447
If you try to call the nested function through its address after the
448
containing function has exited, all hell will break loose.  If you try
449
to call it after a containing scope level has exited, and if it refers
450
to some of the variables that are no longer in scope, you may be lucky,
451
but it's not wise to take the risk.  If, however, the nested function
452
does not refer to anything that has gone out of scope, you should be
453
safe.
454
 
455
GCC implements taking the address of a nested function using a technique
456
called @dfn{trampolines}.  This technique was described in
457
@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
458
C++ Conference Proceedings, October 17-21, 1988).
459
 
460
A nested function can jump to a label inherited from a containing
461
function, provided the label was explicitly declared in the containing
462
function (@pxref{Local Labels}).  Such a jump returns instantly to the
463
containing function, exiting the nested function which did the
464
@code{goto} and any intermediate functions as well.  Here is an example:
465
 
466
@smallexample
467
@group
468
bar (int *array, int offset, int size)
469
@{
470
  __label__ failure;
471
  int access (int *array, int index)
472
    @{
473
      if (index > size)
474
        goto failure;
475
      return array[index + offset];
476
    @}
477
  int i;
478
  /* @r{@dots{}} */
479
  for (i = 0; i < size; i++)
480
    /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
481
  /* @r{@dots{}} */
482
  return 0;
483
 
484
 /* @r{Control comes here from @code{access}
485
    if it detects an error.}  */
486
 failure:
487
  return -1;
488
@}
489
@end group
490
@end smallexample
491
 
492
A nested function always has no linkage.  Declaring one with
493
@code{extern} or @code{static} is erroneous.  If you need to declare the nested function
494
before its definition, use @code{auto} (which is otherwise meaningless
495
for function declarations).
496
 
497
@smallexample
498
bar (int *array, int offset, int size)
499
@{
500
  __label__ failure;
501
  auto int access (int *, int);
502
  /* @r{@dots{}} */
503
  int access (int *array, int index)
504
    @{
505
      if (index > size)
506
        goto failure;
507
      return array[index + offset];
508
    @}
509
  /* @r{@dots{}} */
510
@}
511
@end smallexample
512
 
513
@node Constructing Calls
514
@section Constructing Function Calls
515
@cindex constructing calls
516
@cindex forwarding calls
517
 
518
Using the built-in functions described below, you can record
519
the arguments a function received, and call another function
520
with the same arguments, without knowing the number or types
521
of the arguments.
522
 
523
You can also record the return value of that function call,
524
and later return that value, without knowing what data type
525
the function tried to return (as long as your caller expects
526
that data type).
527
 
528
However, these built-in functions may interact badly with some
529
sophisticated features or other extensions of the language.  It
530
is, therefore, not recommended to use them outside very simple
531
functions acting as mere forwarders for their arguments.
532
 
533
@deftypefn {Built-in Function} {void *} __builtin_apply_args ()
534
This built-in function returns a pointer to data
535
describing how to perform a call with the same arguments as were passed
536
to the current function.
537
 
538
The function saves the arg pointer register, structure value address,
539
and all registers that might be used to pass arguments to a function
540
into a block of memory allocated on the stack.  Then it returns the
541
address of that block.
542
@end deftypefn
543
 
544
@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
545
This built-in function invokes @var{function}
546
with a copy of the parameters described by @var{arguments}
547
and @var{size}.
548
 
549
The value of @var{arguments} should be the value returned by
550
@code{__builtin_apply_args}.  The argument @var{size} specifies the size
551
of the stack argument data, in bytes.
552
 
553
This function returns a pointer to data describing
554
how to return whatever value was returned by @var{function}.  The data
555
is saved in a block of memory allocated on the stack.
556
 
557
It is not always simple to compute the proper value for @var{size}.  The
558
value is used by @code{__builtin_apply} to compute the amount of data
559
that should be pushed on the stack and copied from the incoming argument
560
area.
561
@end deftypefn
562
 
563
@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
564
This built-in function returns the value described by @var{result} from
565
the containing function.  You should specify, for @var{result}, a value
566
returned by @code{__builtin_apply}.
567
@end deftypefn
568
 
569
@deftypefn {Built-in Function} __builtin_va_arg_pack ()
570
This built-in function represents all anonymous arguments of an inline
571
function.  It can be used only in inline functions which will be always
572
inlined, never compiled as a separate function, such as those using
573
@code{__attribute__ ((__always_inline__))} or
574
@code{__attribute__ ((__gnu_inline__))} extern inline functions.
575
It must be only passed as last argument to some other function
576
with variable arguments.  This is useful for writing small wrapper
577
inlines for variable argument functions, when using preprocessor
578
macros is undesirable.  For example:
579
@smallexample
580
extern int myprintf (FILE *f, const char *format, ...);
581
extern inline __attribute__ ((__gnu_inline__)) int
582
myprintf (FILE *f, const char *format, ...)
583
@{
584
  int r = fprintf (f, "myprintf: ");
585
  if (r < 0)
586
    return r;
587
  int s = fprintf (f, format, __builtin_va_arg_pack ());
588
  if (s < 0)
589
    return s;
590
  return r + s;
591
@}
592
@end smallexample
593
@end deftypefn
594
 
595
@deftypefn {Built-in Function} __builtin_va_arg_pack_len ()
596
This built-in function returns the number of anonymous arguments of
597
an inline function.  It can be used only in inline functions which
598
will be always inlined, never compiled as a separate function, such
599
as those using @code{__attribute__ ((__always_inline__))} or
600
@code{__attribute__ ((__gnu_inline__))} extern inline functions.
601
For example following will do link or runtime checking of open
602
arguments for optimized code:
603
@smallexample
604
#ifdef __OPTIMIZE__
605
extern inline __attribute__((__gnu_inline__)) int
606
myopen (const char *path, int oflag, ...)
607
@{
608
  if (__builtin_va_arg_pack_len () > 1)
609
    warn_open_too_many_arguments ();
610
 
611
  if (__builtin_constant_p (oflag))
612
    @{
613
      if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
614
        @{
615
          warn_open_missing_mode ();
616
          return __open_2 (path, oflag);
617
        @}
618
      return open (path, oflag, __builtin_va_arg_pack ());
619
    @}
620
 
621
  if (__builtin_va_arg_pack_len () < 1)
622
    return __open_2 (path, oflag);
623
 
624
  return open (path, oflag, __builtin_va_arg_pack ());
625
@}
626
#endif
627
@end smallexample
628
@end deftypefn
629
 
630
@node Typeof
631
@section Referring to a Type with @code{typeof}
632
@findex typeof
633
@findex sizeof
634
@cindex macros, types of arguments
635
 
636
Another way to refer to the type of an expression is with @code{typeof}.
637
The syntax of using of this keyword looks like @code{sizeof}, but the
638
construct acts semantically like a type name defined with @code{typedef}.
639
 
640
There are two ways of writing the argument to @code{typeof}: with an
641
expression or with a type.  Here is an example with an expression:
642
 
643
@smallexample
644
typeof (x[0](1))
645
@end smallexample
646
 
647
@noindent
648
This assumes that @code{x} is an array of pointers to functions;
649
the type described is that of the values of the functions.
650
 
651
Here is an example with a typename as the argument:
652
 
653
@smallexample
654
typeof (int *)
655
@end smallexample
656
 
657
@noindent
658
Here the type described is that of pointers to @code{int}.
659
 
660
If you are writing a header file that must work when included in ISO C
661
programs, write @code{__typeof__} instead of @code{typeof}.
662
@xref{Alternate Keywords}.
663
 
664
A @code{typeof}-construct can be used anywhere a typedef name could be
665
used.  For example, you can use it in a declaration, in a cast, or inside
666
of @code{sizeof} or @code{typeof}.
667
 
668
The operand of @code{typeof} is evaluated for its side effects if and
669
only if it is an expression of variably modified type or the name of
670
such a type.
671
 
672
@code{typeof} is often useful in conjunction with the
673
statements-within-expressions feature.  Here is how the two together can
674
be used to define a safe ``maximum'' macro that operates on any
675
arithmetic type and evaluates each of its arguments exactly once:
676
 
677
@smallexample
678
#define max(a,b) \
679
  (@{ typeof (a) _a = (a); \
680
      typeof (b) _b = (b); \
681
    _a > _b ? _a : _b; @})
682
@end smallexample
683
 
684
@cindex underscores in variables in macros
685
@cindex @samp{_} in variables in macros
686
@cindex local variables in macros
687
@cindex variables, local, in macros
688
@cindex macros, local variables in
689
 
690
The reason for using names that start with underscores for the local
691
variables is to avoid conflicts with variable names that occur within the
692
expressions that are substituted for @code{a} and @code{b}.  Eventually we
693
hope to design a new form of declaration syntax that allows you to declare
694
variables whose scopes start only after their initializers; this will be a
695
more reliable way to prevent such conflicts.
696
 
697
@noindent
698
Some more examples of the use of @code{typeof}:
699
 
700
@itemize @bullet
701
@item
702
This declares @code{y} with the type of what @code{x} points to.
703
 
704
@smallexample
705
typeof (*x) y;
706
@end smallexample
707
 
708
@item
709
This declares @code{y} as an array of such values.
710
 
711
@smallexample
712
typeof (*x) y[4];
713
@end smallexample
714
 
715
@item
716
This declares @code{y} as an array of pointers to characters:
717
 
718
@smallexample
719
typeof (typeof (char *)[4]) y;
720
@end smallexample
721
 
722
@noindent
723
It is equivalent to the following traditional C declaration:
724
 
725
@smallexample
726
char *y[4];
727
@end smallexample
728
 
729
To see the meaning of the declaration using @code{typeof}, and why it
730
might be a useful way to write, rewrite it with these macros:
731
 
732
@smallexample
733
#define pointer(T)  typeof(T *)
734
#define array(T, N) typeof(T [N])
735
@end smallexample
736
 
737
@noindent
738
Now the declaration can be rewritten this way:
739
 
740
@smallexample
741
array (pointer (char), 4) y;
742
@end smallexample
743
 
744
@noindent
745
Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
746
pointers to @code{char}.
747
@end itemize
748
 
749
@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported
750
a more limited extension which permitted one to write
751
 
752
@smallexample
753
typedef @var{T} = @var{expr};
754
@end smallexample
755
 
756
@noindent
757
with the effect of declaring @var{T} to have the type of the expression
758
@var{expr}.  This extension does not work with GCC 3 (versions between
759
3.0 and 3.2 will crash; 3.2.1 and later give an error).  Code which
760
relies on it should be rewritten to use @code{typeof}:
761
 
762
@smallexample
763
typedef typeof(@var{expr}) @var{T};
764
@end smallexample
765
 
766
@noindent
767
This will work with all versions of GCC@.
768
 
769
@node Conditionals
770
@section Conditionals with Omitted Operands
771
@cindex conditional expressions, extensions
772
@cindex omitted middle-operands
773
@cindex middle-operands, omitted
774
@cindex extensions, @code{?:}
775
@cindex @code{?:} extensions
776
 
777
The middle operand in a conditional expression may be omitted.  Then
778
if the first operand is nonzero, its value is the value of the conditional
779
expression.
780
 
781
Therefore, the expression
782
 
783
@smallexample
784
x ? : y
785
@end smallexample
786
 
787
@noindent
788
has the value of @code{x} if that is nonzero; otherwise, the value of
789
@code{y}.
790
 
791
This example is perfectly equivalent to
792
 
793
@smallexample
794
x ? x : y
795
@end smallexample
796
 
797
@cindex side effect in ?:
798
@cindex ?: side effect
799
@noindent
800
In this simple case, the ability to omit the middle operand is not
801
especially useful.  When it becomes useful is when the first operand does,
802
or may (if it is a macro argument), contain a side effect.  Then repeating
803
the operand in the middle would perform the side effect twice.  Omitting
804
the middle operand uses the value already computed without the undesirable
805
effects of recomputing it.
806
 
807
@node Long Long
808
@section Double-Word Integers
809
@cindex @code{long long} data types
810
@cindex double-word arithmetic
811
@cindex multiprecision arithmetic
812
@cindex @code{LL} integer suffix
813
@cindex @code{ULL} integer suffix
814
 
815
ISO C99 supports data types for integers that are at least 64 bits wide,
816
and as an extension GCC supports them in C90 mode and in C++.
817
Simply write @code{long long int} for a signed integer, or
818
@code{unsigned long long int} for an unsigned integer.  To make an
819
integer constant of type @code{long long int}, add the suffix @samp{LL}
820
to the integer.  To make an integer constant of type @code{unsigned long
821
long int}, add the suffix @samp{ULL} to the integer.
822
 
823
You can use these types in arithmetic like any other integer types.
824
Addition, subtraction, and bitwise boolean operations on these types
825
are open-coded on all types of machines.  Multiplication is open-coded
826
if the machine supports fullword-to-doubleword a widening multiply
827
instruction.  Division and shifts are open-coded only on machines that
828
provide special support.  The operations that are not open-coded use
829
special library routines that come with GCC@.
830
 
831
There may be pitfalls when you use @code{long long} types for function
832
arguments, unless you declare function prototypes.  If a function
833
expects type @code{int} for its argument, and you pass a value of type
834
@code{long long int}, confusion will result because the caller and the
835
subroutine will disagree about the number of bytes for the argument.
836
Likewise, if the function expects @code{long long int} and you pass
837
@code{int}.  The best way to avoid such problems is to use prototypes.
838
 
839
@node Complex
840
@section Complex Numbers
841
@cindex complex numbers
842
@cindex @code{_Complex} keyword
843
@cindex @code{__complex__} keyword
844
 
845
ISO C99 supports complex floating data types, and as an extension GCC
846
supports them in C90 mode and in C++, and supports complex integer data
847
types which are not part of ISO C99.  You can declare complex types
848
using the keyword @code{_Complex}.  As an extension, the older GNU
849
keyword @code{__complex__} is also supported.
850
 
851
For example, @samp{_Complex double x;} declares @code{x} as a
852
variable whose real part and imaginary part are both of type
853
@code{double}.  @samp{_Complex short int y;} declares @code{y} to
854
have real and imaginary parts of type @code{short int}; this is not
855
likely to be useful, but it shows that the set of complex types is
856
complete.
857
 
858
To write a constant with a complex data type, use the suffix @samp{i} or
859
@samp{j} (either one; they are equivalent).  For example, @code{2.5fi}
860
has type @code{_Complex float} and @code{3i} has type
861
@code{_Complex int}.  Such a constant always has a pure imaginary
862
value, but you can form any complex value you like by adding one to a
863
real constant.  This is a GNU extension; if you have an ISO C99
864
conforming C library (such as GNU libc), and want to construct complex
865
constants of floating type, you should include @code{<complex.h>} and
866
use the macros @code{I} or @code{_Complex_I} instead.
867
 
868
@cindex @code{__real__} keyword
869
@cindex @code{__imag__} keyword
870
To extract the real part of a complex-valued expression @var{exp}, write
871
@code{__real__ @var{exp}}.  Likewise, use @code{__imag__} to
872
extract the imaginary part.  This is a GNU extension; for values of
873
floating type, you should use the ISO C99 functions @code{crealf},
874
@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
875
@code{cimagl}, declared in @code{<complex.h>} and also provided as
876
built-in functions by GCC@.
877
 
878
@cindex complex conjugation
879
The operator @samp{~} performs complex conjugation when used on a value
880
with a complex type.  This is a GNU extension; for values of
881
floating type, you should use the ISO C99 functions @code{conjf},
882
@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
883
provided as built-in functions by GCC@.
884
 
885
GCC can allocate complex automatic variables in a noncontiguous
886
fashion; it's even possible for the real part to be in a register while
887
the imaginary part is on the stack (or vice-versa).  Only the DWARF2
888
debug info format can represent this, so use of DWARF2 is recommended.
889
If you are using the stabs debug info format, GCC describes a noncontiguous
890
complex variable as if it were two separate variables of noncomplex type.
891
If the variable's actual name is @code{foo}, the two fictitious
892
variables are named @code{foo$real} and @code{foo$imag}.  You can
893
examine and set these two fictitious variables with your debugger.
894
 
895
@node Floating Types
896
@section Additional Floating Types
897
@cindex additional floating types
898
@cindex @code{__float80} data type
899
@cindex @code{__float128} data type
900
@cindex @code{w} floating point suffix
901
@cindex @code{q} floating point suffix
902
@cindex @code{W} floating point suffix
903
@cindex @code{Q} floating point suffix
904
 
905
As an extension, the GNU C compiler supports additional floating
906
types, @code{__float80} and @code{__float128} to support 80bit
907
(@code{XFmode}) and 128 bit (@code{TFmode}) floating types.
908
Support for additional types includes the arithmetic operators:
909
add, subtract, multiply, divide; unary arithmetic operators;
910
relational operators; equality operators; and conversions to and from
911
integer and other floating types.  Use a suffix @samp{w} or @samp{W}
912
in a literal constant of type @code{__float80} and @samp{q} or @samp{Q}
913
for @code{_float128}.  You can declare complex types using the
914
corresponding internal complex type, @code{XCmode} for @code{__float80}
915
type and @code{TCmode} for @code{__float128} type:
916
 
917
@smallexample
918
typedef _Complex float __attribute__((mode(TC))) _Complex128;
919
typedef _Complex float __attribute__((mode(XC))) _Complex80;
920
@end smallexample
921
 
922
Not all targets support additional floating point types.  @code{__float80}
923
and @code{__float128} types are supported on i386, x86_64 and ia64 targets.
924
 
925
@node Half-Precision
926
@section Half-Precision Floating Point
927
@cindex half-precision floating point
928
@cindex @code{__fp16} data type
929
 
930
On ARM targets, GCC supports half-precision (16-bit) floating point via
931
the @code{__fp16} type.  You must enable this type explicitly
932
with the @option{-mfp16-format} command-line option in order to use it.
933
 
934
ARM supports two incompatible representations for half-precision
935
floating-point values.  You must choose one of the representations and
936
use it consistently in your program.
937
 
938
Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
939
This format can represent normalized values in the range of @math{2^{-14}} to 65504.
940
There are 11 bits of significand precision, approximately 3
941
decimal digits.
942
 
943
Specifying @option{-mfp16-format=alternative} selects the ARM
944
alternative format.  This representation is similar to the IEEE
945
format, but does not support infinities or NaNs.  Instead, the range
946
of exponents is extended, so that this format can represent normalized
947
values in the range of @math{2^{-14}} to 131008.
948
 
949
The @code{__fp16} type is a storage format only.  For purposes
950
of arithmetic and other operations, @code{__fp16} values in C or C++
951
expressions are automatically promoted to @code{float}.  In addition,
952
you cannot declare a function with a return value or parameters
953
of type @code{__fp16}.
954
 
955
Note that conversions from @code{double} to @code{__fp16}
956
involve an intermediate conversion to @code{float}.  Because
957
of rounding, this can sometimes produce a different result than a
958
direct conversion.
959
 
960
ARM provides hardware support for conversions between
961
@code{__fp16} and @code{float} values
962
as an extension to VFP and NEON (Advanced SIMD).  GCC generates
963
code using these hardware instructions if you compile with
964
options to select an FPU that provides them;
965
for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
966
in addition to the @option{-mfp16-format} option to select
967
a half-precision format.
968
 
969
Language-level support for the @code{__fp16} data type is
970
independent of whether GCC generates code using hardware floating-point
971
instructions.  In cases where hardware support is not specified, GCC
972
implements conversions between @code{__fp16} and @code{float} values
973
as library calls.
974
 
975
@node Decimal Float
976
@section Decimal Floating Types
977
@cindex decimal floating types
978
@cindex @code{_Decimal32} data type
979
@cindex @code{_Decimal64} data type
980
@cindex @code{_Decimal128} data type
981
@cindex @code{df} integer suffix
982
@cindex @code{dd} integer suffix
983
@cindex @code{dl} integer suffix
984
@cindex @code{DF} integer suffix
985
@cindex @code{DD} integer suffix
986
@cindex @code{DL} integer suffix
987
 
988
As an extension, the GNU C compiler supports decimal floating types as
989
defined in the N1312 draft of ISO/IEC WDTR24732.  Support for decimal
990
floating types in GCC will evolve as the draft technical report changes.
991
Calling conventions for any target might also change.  Not all targets
992
support decimal floating types.
993
 
994
The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
995
@code{_Decimal128}.  They use a radix of ten, unlike the floating types
996
@code{float}, @code{double}, and @code{long double} whose radix is not
997
specified by the C standard but is usually two.
998
 
999
Support for decimal floating types includes the arithmetic operators
1000
add, subtract, multiply, divide; unary arithmetic operators;
1001
relational operators; equality operators; and conversions to and from
1002
integer and other floating types.  Use a suffix @samp{df} or
1003
@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1004
or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1005
@code{_Decimal128}.
1006
 
1007
GCC support of decimal float as specified by the draft technical report
1008
is incomplete:
1009
 
1010
@itemize @bullet
1011
@item
1012
When the value of a decimal floating type cannot be represented in the
1013
integer type to which it is being converted, the result is undefined
1014
rather than the result value specified by the draft technical report.
1015
 
1016
@item
1017
GCC does not provide the C library functionality associated with
1018
@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1019
@file{wchar.h}, which must come from a separate C library implementation.
1020
Because of this the GNU C compiler does not define macro
1021
@code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1022
the technical report.
1023
@end itemize
1024
 
1025
Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1026
are supported by the DWARF2 debug information format.
1027
 
1028
@node Hex Floats
1029
@section Hex Floats
1030
@cindex hex floats
1031
 
1032
ISO C99 supports floating-point numbers written not only in the usual
1033
decimal notation, such as @code{1.55e1}, but also numbers such as
1034
@code{0x1.fp3} written in hexadecimal format.  As a GNU extension, GCC
1035
supports this in C90 mode (except in some cases when strictly
1036
conforming) and in C++.  In that format the
1037
@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1038
mandatory.  The exponent is a decimal number that indicates the power of
1039
2 by which the significant part will be multiplied.  Thus @samp{0x1.f} is
1040
@tex
1041
$1 {15\over16}$,
1042
@end tex
1043
@ifnottex
1044
1 15/16,
1045
@end ifnottex
1046
@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1047
is the same as @code{1.55e1}.
1048
 
1049
Unlike for floating-point numbers in the decimal notation the exponent
1050
is always required in the hexadecimal notation.  Otherwise the compiler
1051
would not be able to resolve the ambiguity of, e.g., @code{0x1.f}.  This
1052
could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1053
extension for floating-point constants of type @code{float}.
1054
 
1055
@node Fixed-Point
1056
@section Fixed-Point Types
1057
@cindex fixed-point types
1058
@cindex @code{_Fract} data type
1059
@cindex @code{_Accum} data type
1060
@cindex @code{_Sat} data type
1061
@cindex @code{hr} fixed-suffix
1062
@cindex @code{r} fixed-suffix
1063
@cindex @code{lr} fixed-suffix
1064
@cindex @code{llr} fixed-suffix
1065
@cindex @code{uhr} fixed-suffix
1066
@cindex @code{ur} fixed-suffix
1067
@cindex @code{ulr} fixed-suffix
1068
@cindex @code{ullr} fixed-suffix
1069
@cindex @code{hk} fixed-suffix
1070
@cindex @code{k} fixed-suffix
1071
@cindex @code{lk} fixed-suffix
1072
@cindex @code{llk} fixed-suffix
1073
@cindex @code{uhk} fixed-suffix
1074
@cindex @code{uk} fixed-suffix
1075
@cindex @code{ulk} fixed-suffix
1076
@cindex @code{ullk} fixed-suffix
1077
@cindex @code{HR} fixed-suffix
1078
@cindex @code{R} fixed-suffix
1079
@cindex @code{LR} fixed-suffix
1080
@cindex @code{LLR} fixed-suffix
1081
@cindex @code{UHR} fixed-suffix
1082
@cindex @code{UR} fixed-suffix
1083
@cindex @code{ULR} fixed-suffix
1084
@cindex @code{ULLR} fixed-suffix
1085
@cindex @code{HK} fixed-suffix
1086
@cindex @code{K} fixed-suffix
1087
@cindex @code{LK} fixed-suffix
1088
@cindex @code{LLK} fixed-suffix
1089
@cindex @code{UHK} fixed-suffix
1090
@cindex @code{UK} fixed-suffix
1091
@cindex @code{ULK} fixed-suffix
1092
@cindex @code{ULLK} fixed-suffix
1093
 
1094
As an extension, the GNU C compiler supports fixed-point types as
1095
defined in the N1169 draft of ISO/IEC DTR 18037.  Support for fixed-point
1096
types in GCC will evolve as the draft technical report changes.
1097
Calling conventions for any target might also change.  Not all targets
1098
support fixed-point types.
1099
 
1100
The fixed-point types are
1101
@code{short _Fract},
1102
@code{_Fract},
1103
@code{long _Fract},
1104
@code{long long _Fract},
1105
@code{unsigned short _Fract},
1106
@code{unsigned _Fract},
1107
@code{unsigned long _Fract},
1108
@code{unsigned long long _Fract},
1109
@code{_Sat short _Fract},
1110
@code{_Sat _Fract},
1111
@code{_Sat long _Fract},
1112
@code{_Sat long long _Fract},
1113
@code{_Sat unsigned short _Fract},
1114
@code{_Sat unsigned _Fract},
1115
@code{_Sat unsigned long _Fract},
1116
@code{_Sat unsigned long long _Fract},
1117
@code{short _Accum},
1118
@code{_Accum},
1119
@code{long _Accum},
1120
@code{long long _Accum},
1121
@code{unsigned short _Accum},
1122
@code{unsigned _Accum},
1123
@code{unsigned long _Accum},
1124
@code{unsigned long long _Accum},
1125
@code{_Sat short _Accum},
1126
@code{_Sat _Accum},
1127
@code{_Sat long _Accum},
1128
@code{_Sat long long _Accum},
1129
@code{_Sat unsigned short _Accum},
1130
@code{_Sat unsigned _Accum},
1131
@code{_Sat unsigned long _Accum},
1132
@code{_Sat unsigned long long _Accum}.
1133
 
1134
Fixed-point data values contain fractional and optional integral parts.
1135
The format of fixed-point data varies and depends on the target machine.
1136
 
1137
Support for fixed-point types includes:
1138
@itemize @bullet
1139
@item
1140
prefix and postfix increment and decrement operators (@code{++}, @code{--})
1141
@item
1142
unary arithmetic operators (@code{+}, @code{-}, @code{!})
1143
@item
1144
binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1145
@item
1146
binary shift operators (@code{<<}, @code{>>})
1147
@item
1148
relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1149
@item
1150
equality operators (@code{==}, @code{!=})
1151
@item
1152
assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1153
@code{<<=}, @code{>>=})
1154
@item
1155
conversions to and from integer, floating-point, or fixed-point types
1156
@end itemize
1157
 
1158
Use a suffix in a fixed-point literal constant:
1159
@itemize
1160
@item @samp{hr} or @samp{HR} for @code{short _Fract} and
1161
@code{_Sat short _Fract}
1162
@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1163
@item @samp{lr} or @samp{LR} for @code{long _Fract} and
1164
@code{_Sat long _Fract}
1165
@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1166
@code{_Sat long long _Fract}
1167
@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1168
@code{_Sat unsigned short _Fract}
1169
@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1170
@code{_Sat unsigned _Fract}
1171
@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1172
@code{_Sat unsigned long _Fract}
1173
@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1174
and @code{_Sat unsigned long long _Fract}
1175
@item @samp{hk} or @samp{HK} for @code{short _Accum} and
1176
@code{_Sat short _Accum}
1177
@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1178
@item @samp{lk} or @samp{LK} for @code{long _Accum} and
1179
@code{_Sat long _Accum}
1180
@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1181
@code{_Sat long long _Accum}
1182
@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1183
@code{_Sat unsigned short _Accum}
1184
@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1185
@code{_Sat unsigned _Accum}
1186
@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1187
@code{_Sat unsigned long _Accum}
1188
@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1189
and @code{_Sat unsigned long long _Accum}
1190
@end itemize
1191
 
1192
GCC support of fixed-point types as specified by the draft technical report
1193
is incomplete:
1194
 
1195
@itemize @bullet
1196
@item
1197
Pragmas to control overflow and rounding behaviors are not implemented.
1198
@end itemize
1199
 
1200
Fixed-point types are supported by the DWARF2 debug information format.
1201
 
1202
@node Named Address Spaces
1203
@section Named address spaces
1204
@cindex named address spaces
1205
 
1206
As an extension, the GNU C compiler supports named address spaces as
1207
defined in the N1275 draft of ISO/IEC DTR 18037.  Support for named
1208
address spaces in GCC will evolve as the draft technical report changes.
1209
Calling conventions for any target might also change.  At present, only
1210
the SPU target supports other address spaces.  On the SPU target, for
1211
example, variables may be declared as belonging to another address space
1212
by qualifying the type with the @code{__ea} address space identifier:
1213
 
1214
@smallexample
1215
extern int __ea i;
1216
@end smallexample
1217
 
1218
When the variable @code{i} is accessed, the compiler will generate
1219
special code to access this variable.  It may use runtime library
1220
support, or generate special machine instructions to access that address
1221
space.
1222
 
1223
The @code{__ea} identifier may be used exactly like any other C type
1224
qualifier (e.g., @code{const} or @code{volatile}).  See the N1275
1225
document for more details.
1226
 
1227
@node Zero Length
1228
@section Arrays of Length Zero
1229
@cindex arrays of length zero
1230
@cindex zero-length arrays
1231
@cindex length-zero arrays
1232
@cindex flexible array members
1233
 
1234
Zero-length arrays are allowed in GNU C@.  They are very useful as the
1235
last element of a structure which is really a header for a variable-length
1236
object:
1237
 
1238
@smallexample
1239
struct line @{
1240
  int length;
1241
  char contents[0];
1242
@};
1243
 
1244
struct line *thisline = (struct line *)
1245
  malloc (sizeof (struct line) + this_length);
1246
thisline->length = this_length;
1247
@end smallexample
1248
 
1249
In ISO C90, you would have to give @code{contents} a length of 1, which
1250
means either you waste space or complicate the argument to @code{malloc}.
1251
 
1252
In ISO C99, you would use a @dfn{flexible array member}, which is
1253
slightly different in syntax and semantics:
1254
 
1255
@itemize @bullet
1256
@item
1257
Flexible array members are written as @code{contents[]} without
1258
the @code{0}.
1259
 
1260
@item
1261
Flexible array members have incomplete type, and so the @code{sizeof}
1262
operator may not be applied.  As a quirk of the original implementation
1263
of zero-length arrays, @code{sizeof} evaluates to zero.
1264
 
1265
@item
1266
Flexible array members may only appear as the last member of a
1267
@code{struct} that is otherwise non-empty.
1268
 
1269
@item
1270
A structure containing a flexible array member, or a union containing
1271
such a structure (possibly recursively), may not be a member of a
1272
structure or an element of an array.  (However, these uses are
1273
permitted by GCC as extensions.)
1274
@end itemize
1275
 
1276
GCC versions before 3.0 allowed zero-length arrays to be statically
1277
initialized, as if they were flexible arrays.  In addition to those
1278
cases that were useful, it also allowed initializations in situations
1279
that would corrupt later data.  Non-empty initialization of zero-length
1280
arrays is now treated like any case where there are more initializer
1281
elements than the array holds, in that a suitable warning about "excess
1282
elements in array" is given, and the excess elements (all of them, in
1283
this case) are ignored.
1284
 
1285
Instead GCC allows static initialization of flexible array members.
1286
This is equivalent to defining a new structure containing the original
1287
structure followed by an array of sufficient size to contain the data.
1288
I.e.@: in the following, @code{f1} is constructed as if it were declared
1289
like @code{f2}.
1290
 
1291
@smallexample
1292
struct f1 @{
1293
  int x; int y[];
1294
@} f1 = @{ 1, @{ 2, 3, 4 @} @};
1295
 
1296
struct f2 @{
1297
  struct f1 f1; int data[3];
1298
@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1299
@end smallexample
1300
 
1301
@noindent
1302
The convenience of this extension is that @code{f1} has the desired
1303
type, eliminating the need to consistently refer to @code{f2.f1}.
1304
 
1305
This has symmetry with normal static arrays, in that an array of
1306
unknown size is also written with @code{[]}.
1307
 
1308
Of course, this extension only makes sense if the extra data comes at
1309
the end of a top-level object, as otherwise we would be overwriting
1310
data at subsequent offsets.  To avoid undue complication and confusion
1311
with initialization of deeply nested arrays, we simply disallow any
1312
non-empty initialization except when the structure is the top-level
1313
object.  For example:
1314
 
1315
@smallexample
1316
struct foo @{ int x; int y[]; @};
1317
struct bar @{ struct foo z; @};
1318
 
1319
struct foo a = @{ 1, @{ 2, 3, 4 @} @};        // @r{Valid.}
1320
struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @};    // @r{Invalid.}
1321
struct bar c = @{ @{ 1, @{ @} @} @};            // @r{Valid.}
1322
struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @};  // @r{Invalid.}
1323
@end smallexample
1324
 
1325
@node Empty Structures
1326
@section Structures With No Members
1327
@cindex empty structures
1328
@cindex zero-size structures
1329
 
1330
GCC permits a C structure to have no members:
1331
 
1332
@smallexample
1333
struct empty @{
1334
@};
1335
@end smallexample
1336
 
1337
The structure will have size zero.  In C++, empty structures are part
1338
of the language.  G++ treats empty structures as if they had a single
1339
member of type @code{char}.
1340
 
1341
@node Variable Length
1342
@section Arrays of Variable Length
1343
@cindex variable-length arrays
1344
@cindex arrays of variable length
1345
@cindex VLAs
1346
 
1347
Variable-length automatic arrays are allowed in ISO C99, and as an
1348
extension GCC accepts them in C90 mode and in C++.  (However, GCC's
1349
implementation of variable-length arrays does not yet conform in detail
1350
to the ISO C99 standard.)  These arrays are
1351
declared like any other automatic arrays, but with a length that is not
1352
a constant expression.  The storage is allocated at the point of
1353
declaration and deallocated when the brace-level is exited.  For
1354
example:
1355
 
1356
@smallexample
1357
FILE *
1358
concat_fopen (char *s1, char *s2, char *mode)
1359
@{
1360
  char str[strlen (s1) + strlen (s2) + 1];
1361
  strcpy (str, s1);
1362
  strcat (str, s2);
1363
  return fopen (str, mode);
1364
@}
1365
@end smallexample
1366
 
1367
@cindex scope of a variable length array
1368
@cindex variable-length array scope
1369
@cindex deallocating variable length arrays
1370
Jumping or breaking out of the scope of the array name deallocates the
1371
storage.  Jumping into the scope is not allowed; you get an error
1372
message for it.
1373
 
1374
@cindex @code{alloca} vs variable-length arrays
1375
You can use the function @code{alloca} to get an effect much like
1376
variable-length arrays.  The function @code{alloca} is available in
1377
many other C implementations (but not in all).  On the other hand,
1378
variable-length arrays are more elegant.
1379
 
1380
There are other differences between these two methods.  Space allocated
1381
with @code{alloca} exists until the containing @emph{function} returns.
1382
The space for a variable-length array is deallocated as soon as the array
1383
name's scope ends.  (If you use both variable-length arrays and
1384
@code{alloca} in the same function, deallocation of a variable-length array
1385
will also deallocate anything more recently allocated with @code{alloca}.)
1386
 
1387
You can also use variable-length arrays as arguments to functions:
1388
 
1389
@smallexample
1390
struct entry
1391
tester (int len, char data[len][len])
1392
@{
1393
  /* @r{@dots{}} */
1394
@}
1395
@end smallexample
1396
 
1397
The length of an array is computed once when the storage is allocated
1398
and is remembered for the scope of the array in case you access it with
1399
@code{sizeof}.
1400
 
1401
If you want to pass the array first and the length afterward, you can
1402
use a forward declaration in the parameter list---another GNU extension.
1403
 
1404
@smallexample
1405
struct entry
1406
tester (int len; char data[len][len], int len)
1407
@{
1408
  /* @r{@dots{}} */
1409
@}
1410
@end smallexample
1411
 
1412
@cindex parameter forward declaration
1413
The @samp{int len} before the semicolon is a @dfn{parameter forward
1414
declaration}, and it serves the purpose of making the name @code{len}
1415
known when the declaration of @code{data} is parsed.
1416
 
1417
You can write any number of such parameter forward declarations in the
1418
parameter list.  They can be separated by commas or semicolons, but the
1419
last one must end with a semicolon, which is followed by the ``real''
1420
parameter declarations.  Each forward declaration must match a ``real''
1421
declaration in parameter name and data type.  ISO C99 does not support
1422
parameter forward declarations.
1423
 
1424
@node Variadic Macros
1425
@section Macros with a Variable Number of Arguments.
1426
@cindex variable number of arguments
1427
@cindex macro with variable arguments
1428
@cindex rest argument (in macro)
1429
@cindex variadic macros
1430
 
1431
In the ISO C standard of 1999, a macro can be declared to accept a
1432
variable number of arguments much as a function can.  The syntax for
1433
defining the macro is similar to that of a function.  Here is an
1434
example:
1435
 
1436
@smallexample
1437
#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1438
@end smallexample
1439
 
1440
Here @samp{@dots{}} is a @dfn{variable argument}.  In the invocation of
1441
such a macro, it represents the zero or more tokens until the closing
1442
parenthesis that ends the invocation, including any commas.  This set of
1443
tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1444
wherever it appears.  See the CPP manual for more information.
1445
 
1446
GCC has long supported variadic macros, and used a different syntax that
1447
allowed you to give a name to the variable arguments just like any other
1448
argument.  Here is an example:
1449
 
1450
@smallexample
1451
#define debug(format, args...) fprintf (stderr, format, args)
1452
@end smallexample
1453
 
1454
This is in all ways equivalent to the ISO C example above, but arguably
1455
more readable and descriptive.
1456
 
1457
GNU CPP has two further variadic macro extensions, and permits them to
1458
be used with either of the above forms of macro definition.
1459
 
1460
In standard C, you are not allowed to leave the variable argument out
1461
entirely; but you are allowed to pass an empty argument.  For example,
1462
this invocation is invalid in ISO C, because there is no comma after
1463
the string:
1464
 
1465
@smallexample
1466
debug ("A message")
1467
@end smallexample
1468
 
1469
GNU CPP permits you to completely omit the variable arguments in this
1470
way.  In the above examples, the compiler would complain, though since
1471
the expansion of the macro still has the extra comma after the format
1472
string.
1473
 
1474
To help solve this problem, CPP behaves specially for variable arguments
1475
used with the token paste operator, @samp{##}.  If instead you write
1476
 
1477
@smallexample
1478
#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1479
@end smallexample
1480
 
1481
and if the variable arguments are omitted or empty, the @samp{##}
1482
operator causes the preprocessor to remove the comma before it.  If you
1483
do provide some variable arguments in your macro invocation, GNU CPP
1484
does not complain about the paste operation and instead places the
1485
variable arguments after the comma.  Just like any other pasted macro
1486
argument, these arguments are not macro expanded.
1487
 
1488
@node Escaped Newlines
1489
@section Slightly Looser Rules for Escaped Newlines
1490
@cindex escaped newlines
1491
@cindex newlines (escaped)
1492
 
1493
Recently, the preprocessor has relaxed its treatment of escaped
1494
newlines.  Previously, the newline had to immediately follow a
1495
backslash.  The current implementation allows whitespace in the form
1496
of spaces, horizontal and vertical tabs, and form feeds between the
1497
backslash and the subsequent newline.  The preprocessor issues a
1498
warning, but treats it as a valid escaped newline and combines the two
1499
lines to form a single logical line.  This works within comments and
1500
tokens, as well as between tokens.  Comments are @emph{not} treated as
1501
whitespace for the purposes of this relaxation, since they have not
1502
yet been replaced with spaces.
1503
 
1504
@node Subscripting
1505
@section Non-Lvalue Arrays May Have Subscripts
1506
@cindex subscripting
1507
@cindex arrays, non-lvalue
1508
 
1509
@cindex subscripting and function values
1510
In ISO C99, arrays that are not lvalues still decay to pointers, and
1511
may be subscripted, although they may not be modified or used after
1512
the next sequence point and the unary @samp{&} operator may not be
1513
applied to them.  As an extension, GCC allows such arrays to be
1514
subscripted in C90 mode, though otherwise they do not decay to
1515
pointers outside C99 mode.  For example,
1516
this is valid in GNU C though not valid in C90:
1517
 
1518
@smallexample
1519
@group
1520
struct foo @{int a[4];@};
1521
 
1522
struct foo f();
1523
 
1524
bar (int index)
1525
@{
1526
  return f().a[index];
1527
@}
1528
@end group
1529
@end smallexample
1530
 
1531
@node Pointer Arith
1532
@section Arithmetic on @code{void}- and Function-Pointers
1533
@cindex void pointers, arithmetic
1534
@cindex void, size of pointer to
1535
@cindex function pointers, arithmetic
1536
@cindex function, size of pointer to
1537
 
1538
In GNU C, addition and subtraction operations are supported on pointers to
1539
@code{void} and on pointers to functions.  This is done by treating the
1540
size of a @code{void} or of a function as 1.
1541
 
1542
A consequence of this is that @code{sizeof} is also allowed on @code{void}
1543
and on function types, and returns 1.
1544
 
1545
@opindex Wpointer-arith
1546
The option @option{-Wpointer-arith} requests a warning if these extensions
1547
are used.
1548
 
1549
@node Initializers
1550
@section Non-Constant Initializers
1551
@cindex initializers, non-constant
1552
@cindex non-constant initializers
1553
 
1554
As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1555
automatic variable are not required to be constant expressions in GNU C@.
1556
Here is an example of an initializer with run-time varying elements:
1557
 
1558
@smallexample
1559
foo (float f, float g)
1560
@{
1561
  float beat_freqs[2] = @{ f-g, f+g @};
1562
  /* @r{@dots{}} */
1563
@}
1564
@end smallexample
1565
 
1566
@node Compound Literals
1567
@section Compound Literals
1568
@cindex constructor expressions
1569
@cindex initializations in expressions
1570
@cindex structures, constructor expression
1571
@cindex expressions, constructor
1572
@cindex compound literals
1573
@c The GNU C name for what C99 calls compound literals was "constructor expressions".
1574
 
1575
ISO C99 supports compound literals.  A compound literal looks like
1576
a cast containing an initializer.  Its value is an object of the
1577
type specified in the cast, containing the elements specified in
1578
the initializer; it is an lvalue.  As an extension, GCC supports
1579
compound literals in C90 mode and in C++.
1580
 
1581
Usually, the specified type is a structure.  Assume that
1582
@code{struct foo} and @code{structure} are declared as shown:
1583
 
1584
@smallexample
1585
struct foo @{int a; char b[2];@} structure;
1586
@end smallexample
1587
 
1588
@noindent
1589
Here is an example of constructing a @code{struct foo} with a compound literal:
1590
 
1591
@smallexample
1592
structure = ((struct foo) @{x + y, 'a', 0@});
1593
@end smallexample
1594
 
1595
@noindent
1596
This is equivalent to writing the following:
1597
 
1598
@smallexample
1599
@{
1600
  struct foo temp = @{x + y, 'a', 0@};
1601
  structure = temp;
1602
@}
1603
@end smallexample
1604
 
1605
You can also construct an array.  If all the elements of the compound literal
1606
are (made up of) simple constant expressions, suitable for use in
1607
initializers of objects of static storage duration, then the compound
1608
literal can be coerced to a pointer to its first element and used in
1609
such an initializer, as shown here:
1610
 
1611
@smallexample
1612
char **foo = (char *[]) @{ "x", "y", "z" @};
1613
@end smallexample
1614
 
1615
Compound literals for scalar types and union types are is
1616
also allowed, but then the compound literal is equivalent
1617
to a cast.
1618
 
1619
As a GNU extension, GCC allows initialization of objects with static storage
1620
duration by compound literals (which is not possible in ISO C99, because
1621
the initializer is not a constant).
1622
It is handled as if the object was initialized only with the bracket
1623
enclosed list if the types of the compound literal and the object match.
1624
The initializer list of the compound literal must be constant.
1625
If the object being initialized has array type of unknown size, the size is
1626
determined by compound literal size.
1627
 
1628
@smallexample
1629
static struct foo x = (struct foo) @{1, 'a', 'b'@};
1630
static int y[] = (int []) @{1, 2, 3@};
1631
static int z[] = (int [3]) @{1@};
1632
@end smallexample
1633
 
1634
@noindent
1635
The above lines are equivalent to the following:
1636
@smallexample
1637
static struct foo x = @{1, 'a', 'b'@};
1638
static int y[] = @{1, 2, 3@};
1639
static int z[] = @{1, 0, 0@};
1640
@end smallexample
1641
 
1642
@node Designated Inits
1643
@section Designated Initializers
1644
@cindex initializers with labeled elements
1645
@cindex labeled elements in initializers
1646
@cindex case labels in initializers
1647
@cindex designated initializers
1648
 
1649
Standard C90 requires the elements of an initializer to appear in a fixed
1650
order, the same as the order of the elements in the array or structure
1651
being initialized.
1652
 
1653
In ISO C99 you can give the elements in any order, specifying the array
1654
indices or structure field names they apply to, and GNU C allows this as
1655
an extension in C90 mode as well.  This extension is not
1656
implemented in GNU C++.
1657
 
1658
To specify an array index, write
1659
@samp{[@var{index}] =} before the element value.  For example,
1660
 
1661
@smallexample
1662
int a[6] = @{ [4] = 29, [2] = 15 @};
1663
@end smallexample
1664
 
1665
@noindent
1666
is equivalent to
1667
 
1668
@smallexample
1669
int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
1670
@end smallexample
1671
 
1672
@noindent
1673
The index values must be constant expressions, even if the array being
1674
initialized is automatic.
1675
 
1676
An alternative syntax for this which has been obsolete since GCC 2.5 but
1677
GCC still accepts is to write @samp{[@var{index}]} before the element
1678
value, with no @samp{=}.
1679
 
1680
To initialize a range of elements to the same value, write
1681
@samp{[@var{first} ... @var{last}] = @var{value}}.  This is a GNU
1682
extension.  For example,
1683
 
1684
@smallexample
1685
int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
1686
@end smallexample
1687
 
1688
@noindent
1689
If the value in it has side-effects, the side-effects will happen only once,
1690
not for each initialized field by the range initializer.
1691
 
1692
@noindent
1693
Note that the length of the array is the highest value specified
1694
plus one.
1695
 
1696
In a structure initializer, specify the name of a field to initialize
1697
with @samp{.@var{fieldname} =} before the element value.  For example,
1698
given the following structure,
1699
 
1700
@smallexample
1701
struct point @{ int x, y; @};
1702
@end smallexample
1703
 
1704
@noindent
1705
the following initialization
1706
 
1707
@smallexample
1708
struct point p = @{ .y = yvalue, .x = xvalue @};
1709
@end smallexample
1710
 
1711
@noindent
1712
is equivalent to
1713
 
1714
@smallexample
1715
struct point p = @{ xvalue, yvalue @};
1716
@end smallexample
1717
 
1718
Another syntax which has the same meaning, obsolete since GCC 2.5, is
1719
@samp{@var{fieldname}:}, as shown here:
1720
 
1721
@smallexample
1722
struct point p = @{ y: yvalue, x: xvalue @};
1723
@end smallexample
1724
 
1725
@cindex designators
1726
The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
1727
@dfn{designator}.  You can also use a designator (or the obsolete colon
1728
syntax) when initializing a union, to specify which element of the union
1729
should be used.  For example,
1730
 
1731
@smallexample
1732
union foo @{ int i; double d; @};
1733
 
1734
union foo f = @{ .d = 4 @};
1735
@end smallexample
1736
 
1737
@noindent
1738
will convert 4 to a @code{double} to store it in the union using
1739
the second element.  By contrast, casting 4 to type @code{union foo}
1740
would store it into the union as the integer @code{i}, since it is
1741
an integer.  (@xref{Cast to Union}.)
1742
 
1743
You can combine this technique of naming elements with ordinary C
1744
initialization of successive elements.  Each initializer element that
1745
does not have a designator applies to the next consecutive element of the
1746
array or structure.  For example,
1747
 
1748
@smallexample
1749
int a[6] = @{ [1] = v1, v2, [4] = v4 @};
1750
@end smallexample
1751
 
1752
@noindent
1753
is equivalent to
1754
 
1755
@smallexample
1756
int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
1757
@end smallexample
1758
 
1759
Labeling the elements of an array initializer is especially useful
1760
when the indices are characters or belong to an @code{enum} type.
1761
For example:
1762
 
1763
@smallexample
1764
int whitespace[256]
1765
  = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
1766
      ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
1767
@end smallexample
1768
 
1769
@cindex designator lists
1770
You can also write a series of @samp{.@var{fieldname}} and
1771
@samp{[@var{index}]} designators before an @samp{=} to specify a
1772
nested subobject to initialize; the list is taken relative to the
1773
subobject corresponding to the closest surrounding brace pair.  For
1774
example, with the @samp{struct point} declaration above:
1775
 
1776
@smallexample
1777
struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
1778
@end smallexample
1779
 
1780
@noindent
1781
If the same field is initialized multiple times, it will have value from
1782
the last initialization.  If any such overridden initialization has
1783
side-effect, it is unspecified whether the side-effect happens or not.
1784
Currently, GCC will discard them and issue a warning.
1785
 
1786
@node Case Ranges
1787
@section Case Ranges
1788
@cindex case ranges
1789
@cindex ranges in case statements
1790
 
1791
You can specify a range of consecutive values in a single @code{case} label,
1792
like this:
1793
 
1794
@smallexample
1795
case @var{low} ... @var{high}:
1796
@end smallexample
1797
 
1798
@noindent
1799
This has the same effect as the proper number of individual @code{case}
1800
labels, one for each integer value from @var{low} to @var{high}, inclusive.
1801
 
1802
This feature is especially useful for ranges of ASCII character codes:
1803
 
1804
@smallexample
1805
case 'A' ... 'Z':
1806
@end smallexample
1807
 
1808
@strong{Be careful:} Write spaces around the @code{...}, for otherwise
1809
it may be parsed wrong when you use it with integer values.  For example,
1810
write this:
1811
 
1812
@smallexample
1813
case 1 ... 5:
1814
@end smallexample
1815
 
1816
@noindent
1817
rather than this:
1818
 
1819
@smallexample
1820
case 1...5:
1821
@end smallexample
1822
 
1823
@node Cast to Union
1824
@section Cast to a Union Type
1825
@cindex cast to a union
1826
@cindex union, casting to a
1827
 
1828
A cast to union type is similar to other casts, except that the type
1829
specified is a union type.  You can specify the type either with
1830
@code{union @var{tag}} or with a typedef name.  A cast to union is actually
1831
a constructor though, not a cast, and hence does not yield an lvalue like
1832
normal casts.  (@xref{Compound Literals}.)
1833
 
1834
The types that may be cast to the union type are those of the members
1835
of the union.  Thus, given the following union and variables:
1836
 
1837
@smallexample
1838
union foo @{ int i; double d; @};
1839
int x;
1840
double y;
1841
@end smallexample
1842
 
1843
@noindent
1844
both @code{x} and @code{y} can be cast to type @code{union foo}.
1845
 
1846
Using the cast as the right-hand side of an assignment to a variable of
1847
union type is equivalent to storing in a member of the union:
1848
 
1849
@smallexample
1850
union foo u;
1851
/* @r{@dots{}} */
1852
u = (union foo) x  @equiv{}  u.i = x
1853
u = (union foo) y  @equiv{}  u.d = y
1854
@end smallexample
1855
 
1856
You can also use the union cast as a function argument:
1857
 
1858
@smallexample
1859
void hack (union foo);
1860
/* @r{@dots{}} */
1861
hack ((union foo) x);
1862
@end smallexample
1863
 
1864
@node Mixed Declarations
1865
@section Mixed Declarations and Code
1866
@cindex mixed declarations and code
1867
@cindex declarations, mixed with code
1868
@cindex code, mixed with declarations
1869
 
1870
ISO C99 and ISO C++ allow declarations and code to be freely mixed
1871
within compound statements.  As an extension, GCC also allows this in
1872
C90 mode.  For example, you could do:
1873
 
1874
@smallexample
1875
int i;
1876
/* @r{@dots{}} */
1877
i++;
1878
int j = i + 2;
1879
@end smallexample
1880
 
1881
Each identifier is visible from where it is declared until the end of
1882
the enclosing block.
1883
 
1884
@node Function Attributes
1885
@section Declaring Attributes of Functions
1886
@cindex function attributes
1887
@cindex declaring attributes of functions
1888
@cindex functions that never return
1889
@cindex functions that return more than once
1890
@cindex functions that have no side effects
1891
@cindex functions in arbitrary sections
1892
@cindex functions that behave like malloc
1893
@cindex @code{volatile} applied to function
1894
@cindex @code{const} applied to function
1895
@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
1896
@cindex functions with non-null pointer arguments
1897
@cindex functions that are passed arguments in registers on the 386
1898
@cindex functions that pop the argument stack on the 386
1899
@cindex functions that do not pop the argument stack on the 386
1900
@cindex functions that have different compilation options on the 386
1901
@cindex functions that have different optimization options
1902
 
1903
In GNU C, you declare certain things about functions called in your program
1904
which help the compiler optimize function calls and check your code more
1905
carefully.
1906
 
1907
The keyword @code{__attribute__} allows you to specify special
1908
attributes when making a declaration.  This keyword is followed by an
1909
attribute specification inside double parentheses.  The following
1910
attributes are currently defined for functions on all targets:
1911
@code{aligned}, @code{alloc_size}, @code{noreturn},
1912
@code{returns_twice}, @code{noinline}, @code{noclone},
1913
@code{always_inline}, @code{flatten}, @code{pure}, @code{const},
1914
@code{nothrow}, @code{sentinel}, @code{format}, @code{format_arg},
1915
@code{no_instrument_function}, @code{section}, @code{constructor},
1916
@code{destructor}, @code{used}, @code{unused}, @code{deprecated},
1917
@code{weak}, @code{malloc}, @code{alias}, @code{warn_unused_result},
1918
@code{nonnull}, @code{gnu_inline}, @code{externally_visible},
1919
@code{hot}, @code{cold}, @code{artificial}, @code{error} and
1920
@code{warning}.  Several other attributes are defined for functions on
1921
particular target systems.  Other attributes, including @code{section}
1922
are supported for variables declarations (@pxref{Variable Attributes})
1923
and for types (@pxref{Type Attributes}).
1924
 
1925
GCC plugins may provide their own attributes.
1926
 
1927
You may also specify attributes with @samp{__} preceding and following
1928
each keyword.  This allows you to use them in header files without
1929
being concerned about a possible macro of the same name.  For example,
1930
you may use @code{__noreturn__} instead of @code{noreturn}.
1931
 
1932
@xref{Attribute Syntax}, for details of the exact syntax for using
1933
attributes.
1934
 
1935
@table @code
1936
@c Keep this table alphabetized by attribute name.  Treat _ as space.
1937
 
1938
@item alias ("@var{target}")
1939
@cindex @code{alias} attribute
1940
The @code{alias} attribute causes the declaration to be emitted as an
1941
alias for another symbol, which must be specified.  For instance,
1942
 
1943
@smallexample
1944
void __f () @{ /* @r{Do something.} */; @}
1945
void f () __attribute__ ((weak, alias ("__f")));
1946
@end smallexample
1947
 
1948
defines @samp{f} to be a weak alias for @samp{__f}.  In C++, the
1949
mangled name for the target must be used.  It is an error if @samp{__f}
1950
is not defined in the same translation unit.
1951
 
1952
Not all target machines support this attribute.
1953
 
1954
@item aligned (@var{alignment})
1955
@cindex @code{aligned} attribute
1956
This attribute specifies a minimum alignment for the function,
1957
measured in bytes.
1958
 
1959
You cannot use this attribute to decrease the alignment of a function,
1960
only to increase it.  However, when you explicitly specify a function
1961
alignment this will override the effect of the
1962
@option{-falign-functions} (@pxref{Optimize Options}) option for this
1963
function.
1964
 
1965
Note that the effectiveness of @code{aligned} attributes may be
1966
limited by inherent limitations in your linker.  On many systems, the
1967
linker is only able to arrange for functions to be aligned up to a
1968
certain maximum alignment.  (For some linkers, the maximum supported
1969
alignment may be very very small.)  See your linker documentation for
1970
further information.
1971
 
1972
The @code{aligned} attribute can also be used for variables and fields
1973
(@pxref{Variable Attributes}.)
1974
 
1975
@item alloc_size
1976
@cindex @code{alloc_size} attribute
1977
The @code{alloc_size} attribute is used to tell the compiler that the
1978
function return value points to memory, where the size is given by
1979
one or two of the functions parameters.  GCC uses this
1980
information to improve the correctness of @code{__builtin_object_size}.
1981
 
1982
The function parameter(s) denoting the allocated size are specified by
1983
one or two integer arguments supplied to the attribute.  The allocated size
1984
is either the value of the single function argument specified or the product
1985
of the two function arguments specified.  Argument numbering starts at
1986
one.
1987
 
1988
For instance,
1989
 
1990
@smallexample
1991
void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2)))
1992
void my_realloc(void*, size_t) __attribute__((alloc_size(2)))
1993
@end smallexample
1994
 
1995
declares that my_calloc will return memory of the size given by
1996
the product of parameter 1 and 2 and that my_realloc will return memory
1997
of the size given by parameter 2.
1998
 
1999
@item always_inline
2000
@cindex @code{always_inline} function attribute
2001
Generally, functions are not inlined unless optimization is specified.
2002
For functions declared inline, this attribute inlines the function even
2003
if no optimization level was specified.
2004
 
2005
@item gnu_inline
2006
@cindex @code{gnu_inline} function attribute
2007
This attribute should be used with a function which is also declared
2008
with the @code{inline} keyword.  It directs GCC to treat the function
2009
as if it were defined in gnu90 mode even when compiling in C99 or
2010
gnu99 mode.
2011
 
2012
If the function is declared @code{extern}, then this definition of the
2013
function is used only for inlining.  In no case is the function
2014
compiled as a standalone function, not even if you take its address
2015
explicitly.  Such an address becomes an external reference, as if you
2016
had only declared the function, and had not defined it.  This has
2017
almost the effect of a macro.  The way to use this is to put a
2018
function definition in a header file with this attribute, and put
2019
another copy of the function, without @code{extern}, in a library
2020
file.  The definition in the header file will cause most calls to the
2021
function to be inlined.  If any uses of the function remain, they will
2022
refer to the single copy in the library.  Note that the two
2023
definitions of the functions need not be precisely the same, although
2024
if they do not have the same effect your program may behave oddly.
2025
 
2026
In C, if the function is neither @code{extern} nor @code{static}, then
2027
the function is compiled as a standalone function, as well as being
2028
inlined where possible.
2029
 
2030
This is how GCC traditionally handled functions declared
2031
@code{inline}.  Since ISO C99 specifies a different semantics for
2032
@code{inline}, this function attribute is provided as a transition
2033
measure and as a useful feature in its own right.  This attribute is
2034
available in GCC 4.1.3 and later.  It is available if either of the
2035
preprocessor macros @code{__GNUC_GNU_INLINE__} or
2036
@code{__GNUC_STDC_INLINE__} are defined.  @xref{Inline,,An Inline
2037
Function is As Fast As a Macro}.
2038
 
2039
In C++, this attribute does not depend on @code{extern} in any way,
2040
but it still requires the @code{inline} keyword to enable its special
2041
behavior.
2042
 
2043
@item artificial
2044
@cindex @code{artificial} function attribute
2045
This attribute is useful for small inline wrappers which if possible
2046
should appear during debugging as a unit, depending on the debug
2047
info format it will either mean marking the function as artificial
2048
or using the caller location for all instructions within the inlined
2049
body.
2050
 
2051
@item bank_switch
2052
@cindex interrupt handler functions
2053
When added to an interrupt handler with the M32C port, causes the
2054
prologue and epilogue to use bank switching to preserve the registers
2055
rather than saving them on the stack.
2056
 
2057
@item flatten
2058
@cindex @code{flatten} function attribute
2059
Generally, inlining into a function is limited.  For a function marked with
2060
this attribute, every call inside this function will be inlined, if possible.
2061
Whether the function itself is considered for inlining depends on its size and
2062
the current inlining parameters.
2063
 
2064
@item error ("@var{message}")
2065
@cindex @code{error} function attribute
2066
If this attribute is used on a function declaration and a call to such a function
2067
is not eliminated through dead code elimination or other optimizations, an error
2068
which will include @var{message} will be diagnosed.  This is useful
2069
for compile time checking, especially together with @code{__builtin_constant_p}
2070
and inline functions where checking the inline function arguments is not
2071
possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2072
While it is possible to leave the function undefined and thus invoke
2073
a link failure, when using this attribute the problem will be diagnosed
2074
earlier and with exact location of the call even in presence of inline
2075
functions or when not emitting debugging information.
2076
 
2077
@item warning ("@var{message}")
2078
@cindex @code{warning} function attribute
2079
If this attribute is used on a function declaration and a call to such a function
2080
is not eliminated through dead code elimination or other optimizations, a warning
2081
which will include @var{message} will be diagnosed.  This is useful
2082
for compile time checking, especially together with @code{__builtin_constant_p}
2083
and inline functions.  While it is possible to define the function with
2084
a message in @code{.gnu.warning*} section, when using this attribute the problem
2085
will be diagnosed earlier and with exact location of the call even in presence
2086
of inline functions or when not emitting debugging information.
2087
 
2088
@item cdecl
2089
@cindex functions that do pop the argument stack on the 386
2090
@opindex mrtd
2091
On the Intel 386, the @code{cdecl} attribute causes the compiler to
2092
assume that the calling function will pop off the stack space used to
2093
pass arguments.  This is
2094
useful to override the effects of the @option{-mrtd} switch.
2095
 
2096
@item const
2097
@cindex @code{const} function attribute
2098
Many functions do not examine any values except their arguments, and
2099
have no effects except the return value.  Basically this is just slightly
2100
more strict class than the @code{pure} attribute below, since function is not
2101
allowed to read global memory.
2102
 
2103
@cindex pointer arguments
2104
Note that a function that has pointer arguments and examines the data
2105
pointed to must @emph{not} be declared @code{const}.  Likewise, a
2106
function that calls a non-@code{const} function usually must not be
2107
@code{const}.  It does not make sense for a @code{const} function to
2108
return @code{void}.
2109
 
2110
The attribute @code{const} is not implemented in GCC versions earlier
2111
than 2.5.  An alternative way to declare that a function has no side
2112
effects, which works in the current version and in some older versions,
2113
is as follows:
2114
 
2115
@smallexample
2116
typedef int intfn ();
2117
 
2118
extern const intfn square;
2119
@end smallexample
2120
 
2121
This approach does not work in GNU C++ from 2.6.0 on, since the language
2122
specifies that the @samp{const} must be attached to the return value.
2123
 
2124
@item constructor
2125
@itemx destructor
2126
@itemx constructor (@var{priority})
2127
@itemx destructor (@var{priority})
2128
@cindex @code{constructor} function attribute
2129
@cindex @code{destructor} function attribute
2130
The @code{constructor} attribute causes the function to be called
2131
automatically before execution enters @code{main ()}.  Similarly, the
2132
@code{destructor} attribute causes the function to be called
2133
automatically after @code{main ()} has completed or @code{exit ()} has
2134
been called.  Functions with these attributes are useful for
2135
initializing data that will be used implicitly during the execution of
2136
the program.
2137
 
2138
You may provide an optional integer priority to control the order in
2139
which constructor and destructor functions are run.  A constructor
2140
with a smaller priority number runs before a constructor with a larger
2141
priority number; the opposite relationship holds for destructors.  So,
2142
if you have a constructor that allocates a resource and a destructor
2143
that deallocates the same resource, both functions typically have the
2144
same priority.  The priorities for constructor and destructor
2145
functions are the same as those specified for namespace-scope C++
2146
objects (@pxref{C++ Attributes}).
2147
 
2148
These attributes are not currently implemented for Objective-C@.
2149
 
2150
@item deprecated
2151
@itemx deprecated (@var{msg})
2152
@cindex @code{deprecated} attribute.
2153
The @code{deprecated} attribute results in a warning if the function
2154
is used anywhere in the source file.  This is useful when identifying
2155
functions that are expected to be removed in a future version of a
2156
program.  The warning also includes the location of the declaration
2157
of the deprecated function, to enable users to easily find further
2158
information about why the function is deprecated, or what they should
2159
do instead.  Note that the warnings only occurs for uses:
2160
 
2161
@smallexample
2162
int old_fn () __attribute__ ((deprecated));
2163
int old_fn ();
2164
int (*fn_ptr)() = old_fn;
2165
@end smallexample
2166
 
2167
results in a warning on line 3 but not line 2.  The optional msg
2168
argument, which must be a string, will be printed in the warning if
2169
present.
2170
 
2171
The @code{deprecated} attribute can also be used for variables and
2172
types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2173
 
2174
@item disinterrupt
2175
@cindex @code{disinterrupt} attribute
2176
On MeP targets, this attribute causes the compiler to emit
2177
instructions to disable interrupts for the duration of the given
2178
function.
2179
 
2180
@item dllexport
2181
@cindex @code{__declspec(dllexport)}
2182
On Microsoft Windows targets and Symbian OS targets the
2183
@code{dllexport} attribute causes the compiler to provide a global
2184
pointer to a pointer in a DLL, so that it can be referenced with the
2185
@code{dllimport} attribute.  On Microsoft Windows targets, the pointer
2186
name is formed by combining @code{_imp__} and the function or variable
2187
name.
2188
 
2189
You can use @code{__declspec(dllexport)} as a synonym for
2190
@code{__attribute__ ((dllexport))} for compatibility with other
2191
compilers.
2192
 
2193
On systems that support the @code{visibility} attribute, this
2194
attribute also implies ``default'' visibility.  It is an error to
2195
explicitly specify any other visibility.
2196
 
2197
Currently, the @code{dllexport} attribute is ignored for inlined
2198
functions, unless the @option{-fkeep-inline-functions} flag has been
2199
used.  The attribute is also ignored for undefined symbols.
2200
 
2201
When applied to C++ classes, the attribute marks defined non-inlined
2202
member functions and static data members as exports.  Static consts
2203
initialized in-class are not marked unless they are also defined
2204
out-of-class.
2205
 
2206
For Microsoft Windows targets there are alternative methods for
2207
including the symbol in the DLL's export table such as using a
2208
@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
2209
the @option{--export-all} linker flag.
2210
 
2211
@item dllimport
2212
@cindex @code{__declspec(dllimport)}
2213
On Microsoft Windows and Symbian OS targets, the @code{dllimport}
2214
attribute causes the compiler to reference a function or variable via
2215
a global pointer to a pointer that is set up by the DLL exporting the
2216
symbol.  The attribute implies @code{extern}.  On Microsoft Windows
2217
targets, the pointer name is formed by combining @code{_imp__} and the
2218
function or variable name.
2219
 
2220
You can use @code{__declspec(dllimport)} as a synonym for
2221
@code{__attribute__ ((dllimport))} for compatibility with other
2222
compilers.
2223
 
2224
On systems that support the @code{visibility} attribute, this
2225
attribute also implies ``default'' visibility.  It is an error to
2226
explicitly specify any other visibility.
2227
 
2228
Currently, the attribute is ignored for inlined functions.  If the
2229
attribute is applied to a symbol @emph{definition}, an error is reported.
2230
If a symbol previously declared @code{dllimport} is later defined, the
2231
attribute is ignored in subsequent references, and a warning is emitted.
2232
The attribute is also overridden by a subsequent declaration as
2233
@code{dllexport}.
2234
 
2235
When applied to C++ classes, the attribute marks non-inlined
2236
member functions and static data members as imports.  However, the
2237
attribute is ignored for virtual methods to allow creation of vtables
2238
using thunks.
2239
 
2240
On the SH Symbian OS target the @code{dllimport} attribute also has
2241
another affect---it can cause the vtable and run-time type information
2242
for a class to be exported.  This happens when the class has a
2243
dllimport'ed constructor or a non-inline, non-pure virtual function
2244
and, for either of those two conditions, the class also has an inline
2245
constructor or destructor and has a key function that is defined in
2246
the current translation unit.
2247
 
2248
For Microsoft Windows based targets the use of the @code{dllimport}
2249
attribute on functions is not necessary, but provides a small
2250
performance benefit by eliminating a thunk in the DLL@.  The use of the
2251
@code{dllimport} attribute on imported variables was required on older
2252
versions of the GNU linker, but can now be avoided by passing the
2253
@option{--enable-auto-import} switch to the GNU linker.  As with
2254
functions, using the attribute for a variable eliminates a thunk in
2255
the DLL@.
2256
 
2257
One drawback to using this attribute is that a pointer to a
2258
@emph{variable} marked as @code{dllimport} cannot be used as a constant
2259
address. However, a pointer to a @emph{function} with the
2260
@code{dllimport} attribute can be used as a constant initializer; in
2261
this case, the address of a stub function in the import lib is
2262
referenced.  On Microsoft Windows targets, the attribute can be disabled
2263
for functions by setting the @option{-mnop-fun-dllimport} flag.
2264
 
2265
@item eightbit_data
2266
@cindex eight bit data on the H8/300, H8/300H, and H8S
2267
Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
2268
variable should be placed into the eight bit data section.
2269
The compiler will generate more efficient code for certain operations
2270
on data in the eight bit data area.  Note the eight bit data area is limited to
2271
256 bytes of data.
2272
 
2273
You must use GAS and GLD from GNU binutils version 2.7 or later for
2274
this attribute to work correctly.
2275
 
2276
@item exception_handler
2277
@cindex exception handler functions on the Blackfin processor
2278
Use this attribute on the Blackfin to indicate that the specified function
2279
is an exception handler.  The compiler will generate function entry and
2280
exit sequences suitable for use in an exception handler when this
2281
attribute is present.
2282
 
2283
@item externally_visible
2284
@cindex @code{externally_visible} attribute.
2285
This attribute, attached to a global variable or function, nullifies
2286
the effect of the @option{-fwhole-program} command-line option, so the
2287
object remains visible outside the current compilation unit.
2288
 
2289
@item far
2290
@cindex functions which handle memory bank switching
2291
On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to
2292
use a calling convention that takes care of switching memory banks when
2293
entering and leaving a function.  This calling convention is also the
2294
default when using the @option{-mlong-calls} option.
2295
 
2296
On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions
2297
to call and return from a function.
2298
 
2299
On 68HC11 the compiler will generate a sequence of instructions
2300
to invoke a board-specific routine to switch the memory bank and call the
2301
real function.  The board-specific routine simulates a @code{call}.
2302
At the end of a function, it will jump to a board-specific routine
2303
instead of using @code{rts}.  The board-specific return routine simulates
2304
the @code{rtc}.
2305
 
2306
On MeP targets this causes the compiler to use a calling convention
2307
which assumes the called function is too far away for the built-in
2308
addressing modes.
2309
 
2310
@item fast_interrupt
2311
@cindex interrupt handler functions
2312
Use this attribute on the M32C and RX ports to indicate that the specified
2313
function is a fast interrupt handler.  This is just like the
2314
@code{interrupt} attribute, except that @code{freit} is used to return
2315
instead of @code{reit}.
2316
 
2317
@item fastcall
2318
@cindex functions that pop the argument stack on the 386
2319
On the Intel 386, the @code{fastcall} attribute causes the compiler to
2320
pass the first argument (if of integral type) in the register ECX and
2321
the second argument (if of integral type) in the register EDX@.  Subsequent
2322
and other typed arguments are passed on the stack.  The called function will
2323
pop the arguments off the stack.  If the number of arguments is variable all
2324
arguments are pushed on the stack.
2325
 
2326
@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2327
@cindex @code{format} function attribute
2328
@opindex Wformat
2329
The @code{format} attribute specifies that a function takes @code{printf},
2330
@code{scanf}, @code{strftime} or @code{strfmon} style arguments which
2331
should be type-checked against a format string.  For example, the
2332
declaration:
2333
 
2334
@smallexample
2335
extern int
2336
my_printf (void *my_object, const char *my_format, ...)
2337
      __attribute__ ((format (printf, 2, 3)));
2338
@end smallexample
2339
 
2340
@noindent
2341
causes the compiler to check the arguments in calls to @code{my_printf}
2342
for consistency with the @code{printf} style format string argument
2343
@code{my_format}.
2344
 
2345
The parameter @var{archetype} determines how the format string is
2346
interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2347
@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2348
@code{strfmon}.  (You can also use @code{__printf__},
2349
@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.)  On
2350
MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2351
@code{ms_strftime} are also present.
2352
@var{archtype} values such as @code{printf} refer to the formats accepted
2353
by the system's C run-time library, while @code{gnu_} values always refer
2354
to the formats accepted by the GNU C Library.  On Microsoft Windows
2355
targets, @code{ms_} values refer to the formats accepted by the
2356
@file{msvcrt.dll} library.
2357
The parameter @var{string-index}
2358
specifies which argument is the format string argument (starting
2359
from 1), while @var{first-to-check} is the number of the first
2360
argument to check against the format string.  For functions
2361
where the arguments are not available to be checked (such as
2362
@code{vprintf}), specify the third parameter as zero.  In this case the
2363
compiler only checks the format string for consistency.  For
2364
@code{strftime} formats, the third parameter is required to be zero.
2365
Since non-static C++ methods have an implicit @code{this} argument, the
2366
arguments of such methods should be counted from two, not one, when
2367
giving values for @var{string-index} and @var{first-to-check}.
2368
 
2369
In the example above, the format string (@code{my_format}) is the second
2370
argument of the function @code{my_print}, and the arguments to check
2371
start with the third argument, so the correct parameters for the format
2372
attribute are 2 and 3.
2373
 
2374
@opindex ffreestanding
2375
@opindex fno-builtin
2376
The @code{format} attribute allows you to identify your own functions
2377
which take format strings as arguments, so that GCC can check the
2378
calls to these functions for errors.  The compiler always (unless
2379
@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2380
for the standard library functions @code{printf}, @code{fprintf},
2381
@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2382
@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2383
warnings are requested (using @option{-Wformat}), so there is no need to
2384
modify the header file @file{stdio.h}.  In C99 mode, the functions
2385
@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2386
@code{vsscanf} are also checked.  Except in strictly conforming C
2387
standard modes, the X/Open function @code{strfmon} is also checked as
2388
are @code{printf_unlocked} and @code{fprintf_unlocked}.
2389
@xref{C Dialect Options,,Options Controlling C Dialect}.
2390
 
2391
The target may provide additional types of format checks.
2392
@xref{Target Format Checks,,Format Checks Specific to Particular
2393
Target Machines}.
2394
 
2395
@item format_arg (@var{string-index})
2396
@cindex @code{format_arg} function attribute
2397
@opindex Wformat-nonliteral
2398
The @code{format_arg} attribute specifies that a function takes a format
2399
string for a @code{printf}, @code{scanf}, @code{strftime} or
2400
@code{strfmon} style function and modifies it (for example, to translate
2401
it into another language), so the result can be passed to a
2402
@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2403
function (with the remaining arguments to the format function the same
2404
as they would have been for the unmodified string).  For example, the
2405
declaration:
2406
 
2407
@smallexample
2408
extern char *
2409
my_dgettext (char *my_domain, const char *my_format)
2410
      __attribute__ ((format_arg (2)));
2411
@end smallexample
2412
 
2413
@noindent
2414
causes the compiler to check the arguments in calls to a @code{printf},
2415
@code{scanf}, @code{strftime} or @code{strfmon} type function, whose
2416
format string argument is a call to the @code{my_dgettext} function, for
2417
consistency with the format string argument @code{my_format}.  If the
2418
@code{format_arg} attribute had not been specified, all the compiler
2419
could tell in such calls to format functions would be that the format
2420
string argument is not constant; this would generate a warning when
2421
@option{-Wformat-nonliteral} is used, but the calls could not be checked
2422
without the attribute.
2423
 
2424
The parameter @var{string-index} specifies which argument is the format
2425
string argument (starting from one).  Since non-static C++ methods have
2426
an implicit @code{this} argument, the arguments of such methods should
2427
be counted from two.
2428
 
2429
The @code{format-arg} attribute allows you to identify your own
2430
functions which modify format strings, so that GCC can check the
2431
calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
2432
type function whose operands are a call to one of your own function.
2433
The compiler always treats @code{gettext}, @code{dgettext}, and
2434
@code{dcgettext} in this manner except when strict ISO C support is
2435
requested by @option{-ansi} or an appropriate @option{-std} option, or
2436
@option{-ffreestanding} or @option{-fno-builtin}
2437
is used.  @xref{C Dialect Options,,Options
2438
Controlling C Dialect}.
2439
 
2440
@item function_vector
2441
@cindex calling functions through the function vector on H8/300, M16C, M32C and SH2A processors
2442
Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
2443
function should be called through the function vector.  Calling a
2444
function through the function vector will reduce code size, however;
2445
the function vector has a limited size (maximum 128 entries on the H8/300
2446
and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector.
2447
 
2448
In SH2A target, this attribute declares a function to be called using the
2449
TBR relative addressing mode.  The argument to this attribute is the entry
2450
number of the same function in a vector table containing all the TBR
2451
relative addressable functions.  For the successful jump, register TBR
2452
should contain the start address of this TBR relative vector table.
2453
In the startup routine of the user application, user needs to care of this
2454
TBR register initialization.  The TBR relative vector table can have at
2455
max 256 function entries.  The jumps to these functions will be generated
2456
using a SH2A specific, non delayed branch instruction JSR/N @@(disp8,TBR).
2457
You must use GAS and GLD from GNU binutils version 2.7 or later for
2458
this attribute to work correctly.
2459
 
2460
Please refer the example of M16C target, to see the use of this
2461
attribute while declaring a function,
2462
 
2463
In an application, for a function being called once, this attribute will
2464
save at least 8 bytes of code; and if other successive calls are being
2465
made to the same function, it will save 2 bytes of code per each of these
2466
calls.
2467
 
2468
On M16C/M32C targets, the @code{function_vector} attribute declares a
2469
special page subroutine call function. Use of this attribute reduces
2470
the code size by 2 bytes for each call generated to the
2471
subroutine. The argument to the attribute is the vector number entry
2472
from the special page vector table which contains the 16 low-order
2473
bits of the subroutine's entry address. Each vector table has special
2474
page number (18 to 255) which are used in @code{jsrs} instruction.
2475
Jump addresses of the routines are generated by adding 0x0F0000 (in
2476
case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 2
2477
byte addresses set in the vector table. Therefore you need to ensure
2478
that all the special page vector routines should get mapped within the
2479
address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
2480
(for M32C).
2481
 
2482
In the following example 2 bytes will be saved for each call to
2483
function @code{foo}.
2484
 
2485
@smallexample
2486
void foo (void) __attribute__((function_vector(0x18)));
2487
void foo (void)
2488
@{
2489
@}
2490
 
2491
void bar (void)
2492
@{
2493
    foo();
2494
@}
2495
@end smallexample
2496
 
2497
If functions are defined in one file and are called in another file,
2498
then be sure to write this declaration in both files.
2499
 
2500
This attribute is ignored for R8C target.
2501
 
2502
@item interrupt
2503
@cindex interrupt handler functions
2504
Use this attribute on the ARM, AVR, CRX, M32C, M32R/D, m68k, MeP, MIPS,
2505
RX and Xstormy16 ports to indicate that the specified function is an
2506
interrupt handler.  The compiler will generate function entry and exit
2507
sequences suitable for use in an interrupt handler when this attribute
2508
is present.
2509
 
2510
Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, and
2511
SH processors can be specified via the @code{interrupt_handler} attribute.
2512
 
2513
Note, on the AVR, interrupts will be enabled inside the function.
2514
 
2515
Note, for the ARM, you can specify the kind of interrupt to be handled by
2516
adding an optional parameter to the interrupt attribute like this:
2517
 
2518
@smallexample
2519
void f () __attribute__ ((interrupt ("IRQ")));
2520
@end smallexample
2521
 
2522
Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@.
2523
 
2524
On ARMv7-M the interrupt type is ignored, and the attribute means the function
2525
may be called with a word aligned stack pointer.
2526
 
2527
On MIPS targets, you can use the following attributes to modify the behavior
2528
of an interrupt handler:
2529
@table @code
2530
@item use_shadow_register_set
2531
@cindex @code{use_shadow_register_set} attribute
2532
Assume that the handler uses a shadow register set, instead of
2533
the main general-purpose registers.
2534
 
2535
@item keep_interrupts_masked
2536
@cindex @code{keep_interrupts_masked} attribute
2537
Keep interrupts masked for the whole function.  Without this attribute,
2538
GCC tries to reenable interrupts for as much of the function as it can.
2539
 
2540
@item use_debug_exception_return
2541
@cindex @code{use_debug_exception_return} attribute
2542
Return using the @code{deret} instruction.  Interrupt handlers that don't
2543
have this attribute return using @code{eret} instead.
2544
@end table
2545
 
2546
You can use any combination of these attributes, as shown below:
2547
@smallexample
2548
void __attribute__ ((interrupt)) v0 ();
2549
void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
2550
void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
2551
void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
2552
void __attribute__ ((interrupt, use_shadow_register_set,
2553
                     keep_interrupts_masked)) v4 ();
2554
void __attribute__ ((interrupt, use_shadow_register_set,
2555
                     use_debug_exception_return)) v5 ();
2556
void __attribute__ ((interrupt, keep_interrupts_masked,
2557
                     use_debug_exception_return)) v6 ();
2558
void __attribute__ ((interrupt, use_shadow_register_set,
2559
                     keep_interrupts_masked,
2560
                     use_debug_exception_return)) v7 ();
2561
@end smallexample
2562
 
2563
@item interrupt_handler
2564
@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors
2565
Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to
2566
indicate that the specified function is an interrupt handler.  The compiler
2567
will generate function entry and exit sequences suitable for use in an
2568
interrupt handler when this attribute is present.
2569
 
2570
@item interrupt_thread
2571
@cindex interrupt thread functions on fido
2572
Use this attribute on fido, a subarchitecture of the m68k, to indicate
2573
that the specified function is an interrupt handler that is designed
2574
to run as a thread.  The compiler omits generate prologue/epilogue
2575
sequences and replaces the return instruction with a @code{sleep}
2576
instruction.  This attribute is available only on fido.
2577
 
2578
@item isr
2579
@cindex interrupt service routines on ARM
2580
Use this attribute on ARM to write Interrupt Service Routines. This is an
2581
alias to the @code{interrupt} attribute above.
2582
 
2583
@item kspisusp
2584
@cindex User stack pointer in interrupts on the Blackfin
2585
When used together with @code{interrupt_handler}, @code{exception_handler}
2586
or @code{nmi_handler}, code will be generated to load the stack pointer
2587
from the USP register in the function prologue.
2588
 
2589
@item l1_text
2590
@cindex @code{l1_text} function attribute
2591
This attribute specifies a function to be placed into L1 Instruction
2592
SRAM@. The function will be put into a specific section named @code{.l1.text}.
2593
With @option{-mfdpic}, function calls with a such function as the callee
2594
or caller will use inlined PLT.
2595
 
2596
@item l2
2597
@cindex @code{l2} function attribute
2598
On the Blackfin, this attribute specifies a function to be placed into L2
2599
SRAM. The function will be put into a specific section named
2600
@code{.l1.text}. With @option{-mfdpic}, callers of such functions will use
2601
an inlined PLT.
2602
 
2603
@item long_call/short_call
2604
@cindex indirect calls on ARM
2605
This attribute specifies how a particular function is called on
2606
ARM@.  Both attributes override the @option{-mlong-calls} (@pxref{ARM Options})
2607
command line switch and @code{#pragma long_calls} settings.  The
2608
@code{long_call} attribute indicates that the function might be far
2609
away from the call site and require a different (more expensive)
2610
calling sequence.   The @code{short_call} attribute always places
2611
the offset to the function from the call site into the @samp{BL}
2612
instruction directly.
2613
 
2614
@item longcall/shortcall
2615
@cindex functions called via pointer on the RS/6000 and PowerPC
2616
On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute
2617
indicates that the function might be far away from the call site and
2618
require a different (more expensive) calling sequence.  The
2619
@code{shortcall} attribute indicates that the function is always close
2620
enough for the shorter calling sequence to be used.  These attributes
2621
override both the @option{-mlongcall} switch and, on the RS/6000 and
2622
PowerPC, the @code{#pragma longcall} setting.
2623
 
2624
@xref{RS/6000 and PowerPC Options}, for more information on whether long
2625
calls are necessary.
2626
 
2627
@item long_call/near/far
2628
@cindex indirect calls on MIPS
2629
These attributes specify how a particular function is called on MIPS@.
2630
The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
2631
command-line switch.  The @code{long_call} and @code{far} attributes are
2632
synonyms, and cause the compiler to always call
2633
the function by first loading its address into a register, and then using
2634
the contents of that register.  The @code{near} attribute has the opposite
2635
effect; it specifies that non-PIC calls should be made using the more
2636
efficient @code{jal} instruction.
2637
 
2638
@item malloc
2639
@cindex @code{malloc} attribute
2640
The @code{malloc} attribute is used to tell the compiler that a function
2641
may be treated as if any non-@code{NULL} pointer it returns cannot
2642
alias any other pointer valid when the function returns.
2643
This will often improve optimization.
2644
Standard functions with this property include @code{malloc} and
2645
@code{calloc}.  @code{realloc}-like functions have this property as
2646
long as the old pointer is never referred to (including comparing it
2647
to the new pointer) after the function returns a non-@code{NULL}
2648
value.
2649
 
2650
@item mips16/nomips16
2651
@cindex @code{mips16} attribute
2652
@cindex @code{nomips16} attribute
2653
 
2654
On MIPS targets, you can use the @code{mips16} and @code{nomips16}
2655
function attributes to locally select or turn off MIPS16 code generation.
2656
A function with the @code{mips16} attribute is emitted as MIPS16 code,
2657
while MIPS16 code generation is disabled for functions with the
2658
@code{nomips16} attribute.  These attributes override the
2659
@option{-mips16} and @option{-mno-mips16} options on the command line
2660
(@pxref{MIPS Options}).
2661
 
2662
When compiling files containing mixed MIPS16 and non-MIPS16 code, the
2663
preprocessor symbol @code{__mips16} reflects the setting on the command line,
2664
not that within individual functions.  Mixed MIPS16 and non-MIPS16 code
2665
may interact badly with some GCC extensions such as @code{__builtin_apply}
2666
(@pxref{Constructing Calls}).
2667
 
2668
@item model (@var{model-name})
2669
@cindex function addressability on the M32R/D
2670
@cindex variable addressability on the IA-64
2671
 
2672
On the M32R/D, use this attribute to set the addressability of an
2673
object, and of the code generated for a function.  The identifier
2674
@var{model-name} is one of @code{small}, @code{medium}, or
2675
@code{large}, representing each of the code models.
2676
 
2677
Small model objects live in the lower 16MB of memory (so that their
2678
addresses can be loaded with the @code{ld24} instruction), and are
2679
callable with the @code{bl} instruction.
2680
 
2681
Medium model objects may live anywhere in the 32-bit address space (the
2682
compiler will generate @code{seth/add3} instructions to load their addresses),
2683
and are callable with the @code{bl} instruction.
2684
 
2685
Large model objects may live anywhere in the 32-bit address space (the
2686
compiler will generate @code{seth/add3} instructions to load their addresses),
2687
and may not be reachable with the @code{bl} instruction (the compiler will
2688
generate the much slower @code{seth/add3/jl} instruction sequence).
2689
 
2690
On IA-64, use this attribute to set the addressability of an object.
2691
At present, the only supported identifier for @var{model-name} is
2692
@code{small}, indicating addressability via ``small'' (22-bit)
2693
addresses (so that their addresses can be loaded with the @code{addl}
2694
instruction).  Caveat: such addressing is by definition not position
2695
independent and hence this attribute must not be used for objects
2696
defined by shared libraries.
2697
 
2698
@item ms_abi/sysv_abi
2699
@cindex @code{ms_abi} attribute
2700
@cindex @code{sysv_abi} attribute
2701
 
2702
On 64-bit x86_64-*-* targets, you can use an ABI attribute to indicate
2703
which calling convention should be used for a function.  The @code{ms_abi}
2704
attribute tells the compiler to use the Microsoft ABI, while the
2705
@code{sysv_abi} attribute tells the compiler to use the ABI used on
2706
GNU/Linux and other systems.  The default is to use the Microsoft ABI
2707
when targeting Windows.  On all other systems, the default is the AMD ABI.
2708
 
2709
Note, the @code{ms_abi} attribute for Windows targets currently requires
2710
the @option{-maccumulate-outgoing-args} option.
2711
 
2712
@item ms_hook_prologue
2713
@cindex @code{ms_hook_prologue} attribute
2714
 
2715
On 32 bit i[34567]86-*-* targets, you can use this function attribute to make
2716
gcc generate the "hot-patching" function prologue used in Win32 API
2717
functions in Microsoft Windows XP Service Pack 2 and newer. This requires
2718
support for the swap suffix in the assembler. (GNU Binutils 2.19.51 or later)
2719
 
2720
@item naked
2721
@cindex function without a prologue/epilogue code
2722
Use this attribute on the ARM, AVR, IP2K, RX and SPU ports to indicate that
2723
the specified function does not need prologue/epilogue sequences generated by
2724
the compiler.  It is up to the programmer to provide these sequences. The
2725
only statements that can be safely included in naked functions are
2726
@code{asm} statements that do not have operands.  All other statements,
2727
including declarations of local variables, @code{if} statements, and so
2728
forth, should be avoided.  Naked functions should be used to implement the
2729
body of an assembly function, while allowing the compiler to construct
2730
the requisite function declaration for the assembler.
2731
 
2732
@item near
2733
@cindex functions which do not handle memory bank switching on 68HC11/68HC12
2734
On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to
2735
use the normal calling convention based on @code{jsr} and @code{rts}.
2736
This attribute can be used to cancel the effect of the @option{-mlong-calls}
2737
option.
2738
 
2739
On MeP targets this attribute causes the compiler to assume the called
2740
function is close enough to use the normal calling convention,
2741
overriding the @code{-mtf} command line option.
2742
 
2743
@item nesting
2744
@cindex Allow nesting in an interrupt handler on the Blackfin processor.
2745
Use this attribute together with @code{interrupt_handler},
2746
@code{exception_handler} or @code{nmi_handler} to indicate that the function
2747
entry code should enable nested interrupts or exceptions.
2748
 
2749
@item nmi_handler
2750
@cindex NMI handler functions on the Blackfin processor
2751
Use this attribute on the Blackfin to indicate that the specified function
2752
is an NMI handler.  The compiler will generate function entry and
2753
exit sequences suitable for use in an NMI handler when this
2754
attribute is present.
2755
 
2756
@item no_instrument_function
2757
@cindex @code{no_instrument_function} function attribute
2758
@opindex finstrument-functions
2759
If @option{-finstrument-functions} is given, profiling function calls will
2760
be generated at entry and exit of most user-compiled functions.
2761
Functions with this attribute will not be so instrumented.
2762
 
2763
@item noinline
2764
@cindex @code{noinline} function attribute
2765
This function attribute prevents a function from being considered for
2766
inlining.
2767
@c Don't enumerate the optimizations by name here; we try to be
2768
@c future-compatible with this mechanism.
2769
If the function does not have side-effects, there are optimizations
2770
other than inlining that causes function calls to be optimized away,
2771
although the function call is live.  To keep such calls from being
2772
optimized away, put
2773
@smallexample
2774
asm ("");
2775
@end smallexample
2776
(@pxref{Extended Asm}) in the called function, to serve as a special
2777
side-effect.
2778
 
2779
@item noclone
2780
@cindex @code{noclone} function attribute
2781
This function attribute prevents a function from being considered for
2782
cloning - a mechanism which produces specialized copies of functions
2783
and which is (currently) performed by interprocedural constant
2784
propagation.
2785
 
2786
@item nonnull (@var{arg-index}, @dots{})
2787
@cindex @code{nonnull} function attribute
2788
The @code{nonnull} attribute specifies that some function parameters should
2789
be non-null pointers.  For instance, the declaration:
2790
 
2791
@smallexample
2792
extern void *
2793
my_memcpy (void *dest, const void *src, size_t len)
2794
        __attribute__((nonnull (1, 2)));
2795
@end smallexample
2796
 
2797
@noindent
2798
causes the compiler to check that, in calls to @code{my_memcpy},
2799
arguments @var{dest} and @var{src} are non-null.  If the compiler
2800
determines that a null pointer is passed in an argument slot marked
2801
as non-null, and the @option{-Wnonnull} option is enabled, a warning
2802
is issued.  The compiler may also choose to make optimizations based
2803
on the knowledge that certain function arguments will not be null.
2804
 
2805
If no argument index list is given to the @code{nonnull} attribute,
2806
all pointer arguments are marked as non-null.  To illustrate, the
2807
following declaration is equivalent to the previous example:
2808
 
2809
@smallexample
2810
extern void *
2811
my_memcpy (void *dest, const void *src, size_t len)
2812
        __attribute__((nonnull));
2813
@end smallexample
2814
 
2815
@item noreturn
2816
@cindex @code{noreturn} function attribute
2817
A few standard library functions, such as @code{abort} and @code{exit},
2818
cannot return.  GCC knows this automatically.  Some programs define
2819
their own functions that never return.  You can declare them
2820
@code{noreturn} to tell the compiler this fact.  For example,
2821
 
2822
@smallexample
2823
@group
2824
void fatal () __attribute__ ((noreturn));
2825
 
2826
void
2827
fatal (/* @r{@dots{}} */)
2828
@{
2829
  /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
2830
  exit (1);
2831
@}
2832
@end group
2833
@end smallexample
2834
 
2835
The @code{noreturn} keyword tells the compiler to assume that
2836
@code{fatal} cannot return.  It can then optimize without regard to what
2837
would happen if @code{fatal} ever did return.  This makes slightly
2838
better code.  More importantly, it helps avoid spurious warnings of
2839
uninitialized variables.
2840
 
2841
The @code{noreturn} keyword does not affect the exceptional path when that
2842
applies: a @code{noreturn}-marked function may still return to the caller
2843
by throwing an exception or calling @code{longjmp}.
2844
 
2845
Do not assume that registers saved by the calling function are
2846
restored before calling the @code{noreturn} function.
2847
 
2848
It does not make sense for a @code{noreturn} function to have a return
2849
type other than @code{void}.
2850
 
2851
The attribute @code{noreturn} is not implemented in GCC versions
2852
earlier than 2.5.  An alternative way to declare that a function does
2853
not return, which works in the current version and in some older
2854
versions, is as follows:
2855
 
2856
@smallexample
2857
typedef void voidfn ();
2858
 
2859
volatile voidfn fatal;
2860
@end smallexample
2861
 
2862
This approach does not work in GNU C++.
2863
 
2864
@item nothrow
2865
@cindex @code{nothrow} function attribute
2866
The @code{nothrow} attribute is used to inform the compiler that a
2867
function cannot throw an exception.  For example, most functions in
2868
the standard C library can be guaranteed not to throw an exception
2869
with the notable exceptions of @code{qsort} and @code{bsearch} that
2870
take function pointer arguments.  The @code{nothrow} attribute is not
2871
implemented in GCC versions earlier than 3.3.
2872
 
2873
@item optimize
2874
@cindex @code{optimize} function attribute
2875
The @code{optimize} attribute is used to specify that a function is to
2876
be compiled with different optimization options than specified on the
2877
command line.  Arguments can either be numbers or strings.  Numbers
2878
are assumed to be an optimization level.  Strings that begin with
2879
@code{O} are assumed to be an optimization option, while other options
2880
are assumed to be used with a @code{-f} prefix.  You can also use the
2881
@samp{#pragma GCC optimize} pragma to set the optimization options
2882
that affect more than one function.
2883
@xref{Function Specific Option Pragmas}, for details about the
2884
@samp{#pragma GCC optimize} pragma.
2885
 
2886
This can be used for instance to have frequently executed functions
2887
compiled with more aggressive optimization options that produce faster
2888
and larger code, while other functions can be called with less
2889
aggressive options.
2890
 
2891
@item pcs
2892
@cindex @code{pcs} function attribute
2893
 
2894
The @code{pcs} attribute can be used to control the calling convention
2895
used for a function on ARM.  The attribute takes an argument that specifies
2896
the calling convention to use.
2897
 
2898
When compiling using the AAPCS ABI (or a variant of that) then valid
2899
values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}.  In
2900
order to use a variant other than @code{"aapcs"} then the compiler must
2901
be permitted to use the appropriate co-processor registers (i.e., the
2902
VFP registers must be available in order to use @code{"aapcs-vfp"}).
2903
For example,
2904
 
2905
@smallexample
2906
/* Argument passed in r0, and result returned in r0+r1.  */
2907
double f2d (float) __attribute__((pcs("aapcs")));
2908
@end smallexample
2909
 
2910
Variadic functions always use the @code{"aapcs"} calling convention and
2911
the compiler will reject attempts to specify an alternative.
2912
 
2913
@item pure
2914
@cindex @code{pure} function attribute
2915
Many functions have no effects except the return value and their
2916
return value depends only on the parameters and/or global variables.
2917
Such a function can be subject
2918
to common subexpression elimination and loop optimization just as an
2919
arithmetic operator would be.  These functions should be declared
2920
with the attribute @code{pure}.  For example,
2921
 
2922
@smallexample
2923
int square (int) __attribute__ ((pure));
2924
@end smallexample
2925
 
2926
@noindent
2927
says that the hypothetical function @code{square} is safe to call
2928
fewer times than the program says.
2929
 
2930
Some of common examples of pure functions are @code{strlen} or @code{memcmp}.
2931
Interesting non-pure functions are functions with infinite loops or those
2932
depending on volatile memory or other system resource, that may change between
2933
two consecutive calls (such as @code{feof} in a multithreading environment).
2934
 
2935
The attribute @code{pure} is not implemented in GCC versions earlier
2936
than 2.96.
2937
 
2938
@item hot
2939
@cindex @code{hot} function attribute
2940
The @code{hot} attribute is used to inform the compiler that a function is a
2941
hot spot of the compiled program.  The function is optimized more aggressively
2942
and on many target it is placed into special subsection of the text section so
2943
all hot functions appears close together improving locality.
2944
 
2945
When profile feedback is available, via @option{-fprofile-use}, hot functions
2946
are automatically detected and this attribute is ignored.
2947
 
2948
The @code{hot} attribute is not implemented in GCC versions earlier
2949
than 4.3.
2950
 
2951
@item cold
2952
@cindex @code{cold} function attribute
2953
The @code{cold} attribute is used to inform the compiler that a function is
2954
unlikely executed.  The function is optimized for size rather than speed and on
2955
many targets it is placed into special subsection of the text section so all
2956
cold functions appears close together improving code locality of non-cold parts
2957
of program.  The paths leading to call of cold functions within code are marked
2958
as unlikely by the branch prediction mechanism. It is thus useful to mark
2959
functions used to handle unlikely conditions, such as @code{perror}, as cold to
2960
improve optimization of hot functions that do call marked functions in rare
2961
occasions.
2962
 
2963
When profile feedback is available, via @option{-fprofile-use}, hot functions
2964
are automatically detected and this attribute is ignored.
2965
 
2966
The @code{cold} attribute is not implemented in GCC versions earlier than 4.3.
2967
 
2968
@item regparm (@var{number})
2969
@cindex @code{regparm} attribute
2970
@cindex functions that are passed arguments in registers on the 386
2971
On the Intel 386, the @code{regparm} attribute causes the compiler to
2972
pass arguments number one to @var{number} if they are of integral type
2973
in registers EAX, EDX, and ECX instead of on the stack.  Functions that
2974
take a variable number of arguments will continue to be passed all of their
2975
arguments on the stack.
2976
 
2977
Beware that on some ELF systems this attribute is unsuitable for
2978
global functions in shared libraries with lazy binding (which is the
2979
default).  Lazy binding will send the first call via resolving code in
2980
the loader, which might assume EAX, EDX and ECX can be clobbered, as
2981
per the standard calling conventions.  Solaris 8 is affected by this.
2982
GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be
2983
safe since the loaders there save EAX, EDX and ECX.  (Lazy binding can be
2984
disabled with the linker or the loader if desired, to avoid the
2985
problem.)
2986
 
2987
@item sseregparm
2988
@cindex @code{sseregparm} attribute
2989
On the Intel 386 with SSE support, the @code{sseregparm} attribute
2990
causes the compiler to pass up to 3 floating point arguments in
2991
SSE registers instead of on the stack.  Functions that take a
2992
variable number of arguments will continue to pass all of their
2993
floating point arguments on the stack.
2994
 
2995
@item force_align_arg_pointer
2996
@cindex @code{force_align_arg_pointer} attribute
2997
On the Intel x86, the @code{force_align_arg_pointer} attribute may be
2998
applied to individual function definitions, generating an alternate
2999
prologue and epilogue that realigns the runtime stack if necessary.
3000
This supports mixing legacy codes that run with a 4-byte aligned stack
3001
with modern codes that keep a 16-byte stack for SSE compatibility.
3002
 
3003
@item resbank
3004
@cindex @code{resbank} attribute
3005
On the SH2A target, this attribute enables the high-speed register
3006
saving and restoration using a register bank for @code{interrupt_handler}
3007
routines.  Saving to the bank is performed automatically after the CPU
3008
accepts an interrupt that uses a register bank.
3009
 
3010
The nineteen 32-bit registers comprising general register R0 to R14,
3011
control register GBR, and system registers MACH, MACL, and PR and the
3012
vector table address offset are saved into a register bank.  Register
3013
banks are stacked in first-in last-out (FILO) sequence.  Restoration
3014
from the bank is executed by issuing a RESBANK instruction.
3015
 
3016
@item returns_twice
3017
@cindex @code{returns_twice} attribute
3018
The @code{returns_twice} attribute tells the compiler that a function may
3019
return more than one time.  The compiler will ensure that all registers
3020
are dead before calling such a function and will emit a warning about
3021
the variables that may be clobbered after the second return from the
3022
function.  Examples of such functions are @code{setjmp} and @code{vfork}.
3023
The @code{longjmp}-like counterpart of such function, if any, might need
3024
to be marked with the @code{noreturn} attribute.
3025
 
3026
@item saveall
3027
@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S
3028
Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that
3029
all registers except the stack pointer should be saved in the prologue
3030
regardless of whether they are used or not.
3031
 
3032
@item section ("@var{section-name}")
3033
@cindex @code{section} function attribute
3034
Normally, the compiler places the code it generates in the @code{text} section.
3035
Sometimes, however, you need additional sections, or you need certain
3036
particular functions to appear in special sections.  The @code{section}
3037
attribute specifies that a function lives in a particular section.
3038
For example, the declaration:
3039
 
3040
@smallexample
3041
extern void foobar (void) __attribute__ ((section ("bar")));
3042
@end smallexample
3043
 
3044
@noindent
3045
puts the function @code{foobar} in the @code{bar} section.
3046
 
3047
Some file formats do not support arbitrary sections so the @code{section}
3048
attribute is not available on all platforms.
3049
If you need to map the entire contents of a module to a particular
3050
section, consider using the facilities of the linker instead.
3051
 
3052
@item sentinel
3053
@cindex @code{sentinel} function attribute
3054
This function attribute ensures that a parameter in a function call is
3055
an explicit @code{NULL}.  The attribute is only valid on variadic
3056
functions.  By default, the sentinel is located at position zero, the
3057
last parameter of the function call.  If an optional integer position
3058
argument P is supplied to the attribute, the sentinel must be located at
3059
position P counting backwards from the end of the argument list.
3060
 
3061
@smallexample
3062
__attribute__ ((sentinel))
3063
is equivalent to
3064
__attribute__ ((sentinel(0)))
3065
@end smallexample
3066
 
3067
The attribute is automatically set with a position of 0 for the built-in
3068
functions @code{execl} and @code{execlp}.  The built-in function
3069
@code{execle} has the attribute set with a position of 1.
3070
 
3071
A valid @code{NULL} in this context is defined as zero with any pointer
3072
type.  If your system defines the @code{NULL} macro with an integer type
3073
then you need to add an explicit cast.  GCC replaces @code{stddef.h}
3074
with a copy that redefines NULL appropriately.
3075
 
3076
The warnings for missing or incorrect sentinels are enabled with
3077
@option{-Wformat}.
3078
 
3079
@item short_call
3080
See long_call/short_call.
3081
 
3082
@item shortcall
3083
See longcall/shortcall.
3084
 
3085
@item signal
3086
@cindex signal handler functions on the AVR processors
3087
Use this attribute on the AVR to indicate that the specified
3088
function is a signal handler.  The compiler will generate function
3089
entry and exit sequences suitable for use in a signal handler when this
3090
attribute is present.  Interrupts will be disabled inside the function.
3091
 
3092
@item sp_switch
3093
Use this attribute on the SH to indicate an @code{interrupt_handler}
3094
function should switch to an alternate stack.  It expects a string
3095
argument that names a global variable holding the address of the
3096
alternate stack.
3097
 
3098
@smallexample
3099
void *alt_stack;
3100
void f () __attribute__ ((interrupt_handler,
3101
                          sp_switch ("alt_stack")));
3102
@end smallexample
3103
 
3104
@item stdcall
3105
@cindex functions that pop the argument stack on the 386
3106
On the Intel 386, the @code{stdcall} attribute causes the compiler to
3107
assume that the called function will pop off the stack space used to
3108
pass arguments, unless it takes a variable number of arguments.
3109
 
3110
@item syscall_linkage
3111
@cindex @code{syscall_linkage} attribute
3112
This attribute is used to modify the IA64 calling convention by marking
3113
all input registers as live at all function exits.  This makes it possible
3114
to restart a system call after an interrupt without having to save/restore
3115
the input registers.  This also prevents kernel data from leaking into
3116
application code.
3117
 
3118
@item target
3119
@cindex @code{target} function attribute
3120
The @code{target} attribute is used to specify that a function is to
3121
be compiled with different target options than specified on the
3122
command line.  This can be used for instance to have functions
3123
compiled with a different ISA (instruction set architecture) than the
3124
default.  You can also use the @samp{#pragma GCC target} pragma to set
3125
more than one function to be compiled with specific target options.
3126
@xref{Function Specific Option Pragmas}, for details about the
3127
@samp{#pragma GCC target} pragma.
3128
 
3129
For instance on a 386, you could compile one function with
3130
@code{target("sse4.1,arch=core2")} and another with
3131
@code{target("sse4a,arch=amdfam10")} that would be equivalent to
3132
compiling the first function with @option{-msse4.1} and
3133
@option{-march=core2} options, and the second function with
3134
@option{-msse4a} and @option{-march=amdfam10} options.  It is up to the
3135
user to make sure that a function is only invoked on a machine that
3136
supports the particular ISA it was compiled for (for example by using
3137
@code{cpuid} on 386 to determine what feature bits and architecture
3138
family are used).
3139
 
3140
@smallexample
3141
int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3142
int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3143
@end smallexample
3144
 
3145
On the 386, the following options are allowed:
3146
 
3147
@table @samp
3148
@item abm
3149
@itemx no-abm
3150
@cindex @code{target("abm")} attribute
3151
Enable/disable the generation of the advanced bit instructions.
3152
 
3153
@item aes
3154
@itemx no-aes
3155
@cindex @code{target("aes")} attribute
3156
Enable/disable the generation of the AES instructions.
3157
 
3158
@item mmx
3159
@itemx no-mmx
3160
@cindex @code{target("mmx")} attribute
3161
Enable/disable the generation of the MMX instructions.
3162
 
3163
@item pclmul
3164
@itemx no-pclmul
3165
@cindex @code{target("pclmul")} attribute
3166
Enable/disable the generation of the PCLMUL instructions.
3167
 
3168
@item popcnt
3169
@itemx no-popcnt
3170
@cindex @code{target("popcnt")} attribute
3171
Enable/disable the generation of the POPCNT instruction.
3172
 
3173
@item sse
3174
@itemx no-sse
3175
@cindex @code{target("sse")} attribute
3176
Enable/disable the generation of the SSE instructions.
3177
 
3178
@item sse2
3179
@itemx no-sse2
3180
@cindex @code{target("sse2")} attribute
3181
Enable/disable the generation of the SSE2 instructions.
3182
 
3183
@item sse3
3184
@itemx no-sse3
3185
@cindex @code{target("sse3")} attribute
3186
Enable/disable the generation of the SSE3 instructions.
3187
 
3188
@item sse4
3189
@itemx no-sse4
3190
@cindex @code{target("sse4")} attribute
3191
Enable/disable the generation of the SSE4 instructions (both SSE4.1
3192
and SSE4.2).
3193
 
3194
@item sse4.1
3195
@itemx no-sse4.1
3196
@cindex @code{target("sse4.1")} attribute
3197
Enable/disable the generation of the sse4.1 instructions.
3198
 
3199
@item sse4.2
3200
@itemx no-sse4.2
3201
@cindex @code{target("sse4.2")} attribute
3202
Enable/disable the generation of the sse4.2 instructions.
3203
 
3204
@item sse4a
3205
@itemx no-sse4a
3206
@cindex @code{target("sse4a")} attribute
3207
Enable/disable the generation of the SSE4A instructions.
3208
 
3209
@item fma4
3210
@itemx no-fma4
3211
@cindex @code{target("fma4")} attribute
3212
Enable/disable the generation of the FMA4 instructions.
3213
 
3214
@item xop
3215
@itemx no-xop
3216
@cindex @code{target("xop")} attribute
3217
Enable/disable the generation of the XOP instructions.
3218
 
3219
@item lwp
3220
@itemx no-lwp
3221
@cindex @code{target("lwp")} attribute
3222
Enable/disable the generation of the LWP instructions.
3223
 
3224
@item ssse3
3225
@itemx no-ssse3
3226
@cindex @code{target("ssse3")} attribute
3227
Enable/disable the generation of the SSSE3 instructions.
3228
 
3229
@item cld
3230
@itemx no-cld
3231
@cindex @code{target("cld")} attribute
3232
Enable/disable the generation of the CLD before string moves.
3233
 
3234
@item fancy-math-387
3235
@itemx no-fancy-math-387
3236
@cindex @code{target("fancy-math-387")} attribute
3237
Enable/disable the generation of the @code{sin}, @code{cos}, and
3238
@code{sqrt} instructions on the 387 floating point unit.
3239
 
3240
@item fused-madd
3241
@itemx no-fused-madd
3242
@cindex @code{target("fused-madd")} attribute
3243
Enable/disable the generation of the fused multiply/add instructions.
3244
 
3245
@item ieee-fp
3246
@itemx no-ieee-fp
3247
@cindex @code{target("ieee-fp")} attribute
3248
Enable/disable the generation of floating point that depends on IEEE arithmetic.
3249
 
3250
@item inline-all-stringops
3251
@itemx no-inline-all-stringops
3252
@cindex @code{target("inline-all-stringops")} attribute
3253
Enable/disable inlining of string operations.
3254
 
3255
@item inline-stringops-dynamically
3256
@itemx no-inline-stringops-dynamically
3257
@cindex @code{target("inline-stringops-dynamically")} attribute
3258
Enable/disable the generation of the inline code to do small string
3259
operations and calling the library routines for large operations.
3260
 
3261
@item align-stringops
3262
@itemx no-align-stringops
3263
@cindex @code{target("align-stringops")} attribute
3264
Do/do not align destination of inlined string operations.
3265
 
3266
@item recip
3267
@itemx no-recip
3268
@cindex @code{target("recip")} attribute
3269
Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
3270
instructions followed an additional Newton-Raphson step instead of
3271
doing a floating point division.
3272
 
3273
@item arch=@var{ARCH}
3274
@cindex @code{target("arch=@var{ARCH}")} attribute
3275
Specify the architecture to generate code for in compiling the function.
3276
 
3277
@item tune=@var{TUNE}
3278
@cindex @code{target("tune=@var{TUNE}")} attribute
3279
Specify the architecture to tune for in compiling the function.
3280
 
3281
@item fpmath=@var{FPMATH}
3282
@cindex @code{target("fpmath=@var{FPMATH}")} attribute
3283
Specify which floating point unit to use.  The
3284
@code{target("fpmath=sse,387")} option must be specified as
3285
@code{target("fpmath=sse+387")} because the comma would separate
3286
different options.
3287
@end table
3288
 
3289
On the 386, you can use either multiple strings to specify multiple
3290
options, or you can separate the option with a comma (@code{,}).
3291
 
3292
On the 386, the inliner will not inline a function that has different
3293
target options than the caller, unless the callee has a subset of the
3294
target options of the caller.  For example a function declared with
3295
@code{target("sse3")} can inline a function with
3296
@code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
3297
 
3298
The @code{target} attribute is not implemented in GCC versions earlier
3299
than 4.4, and at present only the 386 uses it.
3300
 
3301
@item tiny_data
3302
@cindex tiny data section on the H8/300H and H8S
3303
Use this attribute on the H8/300H and H8S to indicate that the specified
3304
variable should be placed into the tiny data section.
3305
The compiler will generate more efficient code for loads and stores
3306
on data in the tiny data section.  Note the tiny data area is limited to
3307
slightly under 32kbytes of data.
3308
 
3309
@item trap_exit
3310
Use this attribute on the SH for an @code{interrupt_handler} to return using
3311
@code{trapa} instead of @code{rte}.  This attribute expects an integer
3312
argument specifying the trap number to be used.
3313
 
3314
@item unused
3315
@cindex @code{unused} attribute.
3316
This attribute, attached to a function, means that the function is meant
3317
to be possibly unused.  GCC will not produce a warning for this
3318
function.
3319
 
3320
@item used
3321
@cindex @code{used} attribute.
3322
This attribute, attached to a function, means that code must be emitted
3323
for the function even if it appears that the function is not referenced.
3324
This is useful, for example, when the function is referenced only in
3325
inline assembly.
3326
 
3327
@item version_id
3328
@cindex @code{version_id} attribute
3329
This IA64 HP-UX attribute, attached to a global variable or function, renames a
3330
symbol to contain a version string, thus allowing for function level
3331
versioning.  HP-UX system header files may use version level functioning
3332
for some system calls.
3333
 
3334
@smallexample
3335
extern int foo () __attribute__((version_id ("20040821")));
3336
@end smallexample
3337
 
3338
Calls to @var{foo} will be mapped to calls to @var{foo@{20040821@}}.
3339
 
3340
@item visibility ("@var{visibility_type}")
3341
@cindex @code{visibility} attribute
3342
This attribute affects the linkage of the declaration to which it is attached.
3343
There are four supported @var{visibility_type} values: default,
3344
hidden, protected or internal visibility.
3345
 
3346
@smallexample
3347
void __attribute__ ((visibility ("protected")))
3348
f () @{ /* @r{Do something.} */; @}
3349
int i __attribute__ ((visibility ("hidden")));
3350
@end smallexample
3351
 
3352
The possible values of @var{visibility_type} correspond to the
3353
visibility settings in the ELF gABI.
3354
 
3355
@table @dfn
3356
@c keep this list of visibilities in alphabetical order.
3357
 
3358
@item default
3359
Default visibility is the normal case for the object file format.
3360
This value is available for the visibility attribute to override other
3361
options that may change the assumed visibility of entities.
3362
 
3363
On ELF, default visibility means that the declaration is visible to other
3364
modules and, in shared libraries, means that the declared entity may be
3365
overridden.
3366
 
3367
On Darwin, default visibility means that the declaration is visible to
3368
other modules.
3369
 
3370
Default visibility corresponds to ``external linkage'' in the language.
3371
 
3372
@item hidden
3373
Hidden visibility indicates that the entity declared will have a new
3374
form of linkage, which we'll call ``hidden linkage''.  Two
3375
declarations of an object with hidden linkage refer to the same object
3376
if they are in the same shared object.
3377
 
3378
@item internal
3379
Internal visibility is like hidden visibility, but with additional
3380
processor specific semantics.  Unless otherwise specified by the
3381
psABI, GCC defines internal visibility to mean that a function is
3382
@emph{never} called from another module.  Compare this with hidden
3383
functions which, while they cannot be referenced directly by other
3384
modules, can be referenced indirectly via function pointers.  By
3385
indicating that a function cannot be called from outside the module,
3386
GCC may for instance omit the load of a PIC register since it is known
3387
that the calling function loaded the correct value.
3388
 
3389
@item protected
3390
Protected visibility is like default visibility except that it
3391
indicates that references within the defining module will bind to the
3392
definition in that module.  That is, the declared entity cannot be
3393
overridden by another module.
3394
 
3395
@end table
3396
 
3397
All visibilities are supported on many, but not all, ELF targets
3398
(supported when the assembler supports the @samp{.visibility}
3399
pseudo-op).  Default visibility is supported everywhere.  Hidden
3400
visibility is supported on Darwin targets.
3401
 
3402
The visibility attribute should be applied only to declarations which
3403
would otherwise have external linkage.  The attribute should be applied
3404
consistently, so that the same entity should not be declared with
3405
different settings of the attribute.
3406
 
3407
In C++, the visibility attribute applies to types as well as functions
3408
and objects, because in C++ types have linkage.  A class must not have
3409
greater visibility than its non-static data member types and bases,
3410
and class members default to the visibility of their class.  Also, a
3411
declaration without explicit visibility is limited to the visibility
3412
of its type.
3413
 
3414
In C++, you can mark member functions and static member variables of a
3415
class with the visibility attribute.  This is useful if you know a
3416
particular method or static member variable should only be used from
3417
one shared object; then you can mark it hidden while the rest of the
3418
class has default visibility.  Care must be taken to avoid breaking
3419
the One Definition Rule; for example, it is usually not useful to mark
3420
an inline method as hidden without marking the whole class as hidden.
3421
 
3422
A C++ namespace declaration can also have the visibility attribute.
3423
This attribute applies only to the particular namespace body, not to
3424
other definitions of the same namespace; it is equivalent to using
3425
@samp{#pragma GCC visibility} before and after the namespace
3426
definition (@pxref{Visibility Pragmas}).
3427
 
3428
In C++, if a template argument has limited visibility, this
3429
restriction is implicitly propagated to the template instantiation.
3430
Otherwise, template instantiations and specializations default to the
3431
visibility of their template.
3432
 
3433
If both the template and enclosing class have explicit visibility, the
3434
visibility from the template is used.
3435
 
3436
@item vliw
3437
@cindex @code{vliw} attribute
3438
On MeP, the @code{vliw} attribute tells the compiler to emit
3439
instructions in VLIW mode instead of core mode.  Note that this
3440
attribute is not allowed unless a VLIW coprocessor has been configured
3441
and enabled through command line options.
3442
 
3443
@item warn_unused_result
3444
@cindex @code{warn_unused_result} attribute
3445
The @code{warn_unused_result} attribute causes a warning to be emitted
3446
if a caller of the function with this attribute does not use its
3447
return value.  This is useful for functions where not checking
3448
the result is either a security problem or always a bug, such as
3449
@code{realloc}.
3450
 
3451
@smallexample
3452
int fn () __attribute__ ((warn_unused_result));
3453
int foo ()
3454
@{
3455
  if (fn () < 0) return -1;
3456
  fn ();
3457
  return 0;
3458
@}
3459
@end smallexample
3460
 
3461
results in warning on line 5.
3462
 
3463
@item weak
3464
@cindex @code{weak} attribute
3465
The @code{weak} attribute causes the declaration to be emitted as a weak
3466
symbol rather than a global.  This is primarily useful in defining
3467
library functions which can be overridden in user code, though it can
3468
also be used with non-function declarations.  Weak symbols are supported
3469
for ELF targets, and also for a.out targets when using the GNU assembler
3470
and linker.
3471
 
3472
@item weakref
3473
@itemx weakref ("@var{target}")
3474
@cindex @code{weakref} attribute
3475
The @code{weakref} attribute marks a declaration as a weak reference.
3476
Without arguments, it should be accompanied by an @code{alias} attribute
3477
naming the target symbol.  Optionally, the @var{target} may be given as
3478
an argument to @code{weakref} itself.  In either case, @code{weakref}
3479
implicitly marks the declaration as @code{weak}.  Without a
3480
@var{target}, given as an argument to @code{weakref} or to @code{alias},
3481
@code{weakref} is equivalent to @code{weak}.
3482
 
3483
@smallexample
3484
static int x() __attribute__ ((weakref ("y")));
3485
/* is equivalent to... */
3486
static int x() __attribute__ ((weak, weakref, alias ("y")));
3487
/* and to... */
3488
static int x() __attribute__ ((weakref));
3489
static int x() __attribute__ ((alias ("y")));
3490
@end smallexample
3491
 
3492
A weak reference is an alias that does not by itself require a
3493
definition to be given for the target symbol.  If the target symbol is
3494
only referenced through weak references, then the becomes a @code{weak}
3495
undefined symbol.  If it is directly referenced, however, then such
3496
strong references prevail, and a definition will be required for the
3497
symbol, not necessarily in the same translation unit.
3498
 
3499
The effect is equivalent to moving all references to the alias to a
3500
separate translation unit, renaming the alias to the aliased symbol,
3501
declaring it as weak, compiling the two separate translation units and
3502
performing a reloadable link on them.
3503
 
3504
At present, a declaration to which @code{weakref} is attached can
3505
only be @code{static}.
3506
 
3507
@end table
3508
 
3509
You can specify multiple attributes in a declaration by separating them
3510
by commas within the double parentheses or by immediately following an
3511
attribute declaration with another attribute declaration.
3512
 
3513
@cindex @code{#pragma}, reason for not using
3514
@cindex pragma, reason for not using
3515
Some people object to the @code{__attribute__} feature, suggesting that
3516
ISO C's @code{#pragma} should be used instead.  At the time
3517
@code{__attribute__} was designed, there were two reasons for not doing
3518
this.
3519
 
3520
@enumerate
3521
@item
3522
It is impossible to generate @code{#pragma} commands from a macro.
3523
 
3524
@item
3525
There is no telling what the same @code{#pragma} might mean in another
3526
compiler.
3527
@end enumerate
3528
 
3529
These two reasons applied to almost any application that might have been
3530
proposed for @code{#pragma}.  It was basically a mistake to use
3531
@code{#pragma} for @emph{anything}.
3532
 
3533
The ISO C99 standard includes @code{_Pragma}, which now allows pragmas
3534
to be generated from macros.  In addition, a @code{#pragma GCC}
3535
namespace is now in use for GCC-specific pragmas.  However, it has been
3536
found convenient to use @code{__attribute__} to achieve a natural
3537
attachment of attributes to their corresponding declarations, whereas
3538
@code{#pragma GCC} is of use for constructs that do not naturally form
3539
part of the grammar.  @xref{Other Directives,,Miscellaneous
3540
Preprocessing Directives, cpp, The GNU C Preprocessor}.
3541
 
3542
@node Attribute Syntax
3543
@section Attribute Syntax
3544
@cindex attribute syntax
3545
 
3546
This section describes the syntax with which @code{__attribute__} may be
3547
used, and the constructs to which attribute specifiers bind, for the C
3548
language.  Some details may vary for C++ and Objective-C@.  Because of
3549
infelicities in the grammar for attributes, some forms described here
3550
may not be successfully parsed in all cases.
3551
 
3552
There are some problems with the semantics of attributes in C++.  For
3553
example, there are no manglings for attributes, although they may affect
3554
code generation, so problems may arise when attributed types are used in
3555
conjunction with templates or overloading.  Similarly, @code{typeid}
3556
does not distinguish between types with different attributes.  Support
3557
for attributes in C++ may be restricted in future to attributes on
3558
declarations only, but not on nested declarators.
3559
 
3560
@xref{Function Attributes}, for details of the semantics of attributes
3561
applying to functions.  @xref{Variable Attributes}, for details of the
3562
semantics of attributes applying to variables.  @xref{Type Attributes},
3563
for details of the semantics of attributes applying to structure, union
3564
and enumerated types.
3565
 
3566
An @dfn{attribute specifier} is of the form
3567
@code{__attribute__ ((@var{attribute-list}))}.  An @dfn{attribute list}
3568
is a possibly empty comma-separated sequence of @dfn{attributes}, where
3569
each attribute is one of the following:
3570
 
3571
@itemize @bullet
3572
@item
3573
Empty.  Empty attributes are ignored.
3574
 
3575
@item
3576
A word (which may be an identifier such as @code{unused}, or a reserved
3577
word such as @code{const}).
3578
 
3579
@item
3580
A word, followed by, in parentheses, parameters for the attribute.
3581
These parameters take one of the following forms:
3582
 
3583
@itemize @bullet
3584
@item
3585
An identifier.  For example, @code{mode} attributes use this form.
3586
 
3587
@item
3588
An identifier followed by a comma and a non-empty comma-separated list
3589
of expressions.  For example, @code{format} attributes use this form.
3590
 
3591
@item
3592
A possibly empty comma-separated list of expressions.  For example,
3593
@code{format_arg} attributes use this form with the list being a single
3594
integer constant expression, and @code{alias} attributes use this form
3595
with the list being a single string constant.
3596
@end itemize
3597
@end itemize
3598
 
3599
An @dfn{attribute specifier list} is a sequence of one or more attribute
3600
specifiers, not separated by any other tokens.
3601
 
3602
In GNU C, an attribute specifier list may appear after the colon following a
3603
label, other than a @code{case} or @code{default} label.  The only
3604
attribute it makes sense to use after a label is @code{unused}.  This
3605
feature is intended for code generated by programs which contains labels
3606
that may be unused but which is compiled with @option{-Wall}.  It would
3607
not normally be appropriate to use in it human-written code, though it
3608
could be useful in cases where the code that jumps to the label is
3609
contained within an @code{#ifdef} conditional.  GNU C++ only permits
3610
attributes on labels if the attribute specifier is immediately
3611
followed by a semicolon (i.e., the label applies to an empty
3612
statement).  If the semicolon is missing, C++ label attributes are
3613
ambiguous, as it is permissible for a declaration, which could begin
3614
with an attribute list, to be labelled in C++.  Declarations cannot be
3615
labelled in C90 or C99, so the ambiguity does not arise there.
3616
 
3617
An attribute specifier list may appear as part of a @code{struct},
3618
@code{union} or @code{enum} specifier.  It may go either immediately
3619
after the @code{struct}, @code{union} or @code{enum} keyword, or after
3620
the closing brace.  The former syntax is preferred.
3621
Where attribute specifiers follow the closing brace, they are considered
3622
to relate to the structure, union or enumerated type defined, not to any
3623
enclosing declaration the type specifier appears in, and the type
3624
defined is not complete until after the attribute specifiers.
3625
@c Otherwise, there would be the following problems: a shift/reduce
3626
@c conflict between attributes binding the struct/union/enum and
3627
@c binding to the list of specifiers/qualifiers; and "aligned"
3628
@c attributes could use sizeof for the structure, but the size could be
3629
@c changed later by "packed" attributes.
3630
 
3631
Otherwise, an attribute specifier appears as part of a declaration,
3632
counting declarations of unnamed parameters and type names, and relates
3633
to that declaration (which may be nested in another declaration, for
3634
example in the case of a parameter declaration), or to a particular declarator
3635
within a declaration.  Where an
3636
attribute specifier is applied to a parameter declared as a function or
3637
an array, it should apply to the function or array rather than the
3638
pointer to which the parameter is implicitly converted, but this is not
3639
yet correctly implemented.
3640
 
3641
Any list of specifiers and qualifiers at the start of a declaration may
3642
contain attribute specifiers, whether or not such a list may in that
3643
context contain storage class specifiers.  (Some attributes, however,
3644
are essentially in the nature of storage class specifiers, and only make
3645
sense where storage class specifiers may be used; for example,
3646
@code{section}.)  There is one necessary limitation to this syntax: the
3647
first old-style parameter declaration in a function definition cannot
3648
begin with an attribute specifier, because such an attribute applies to
3649
the function instead by syntax described below (which, however, is not
3650
yet implemented in this case).  In some other cases, attribute
3651
specifiers are permitted by this grammar but not yet supported by the
3652
compiler.  All attribute specifiers in this place relate to the
3653
declaration as a whole.  In the obsolescent usage where a type of
3654
@code{int} is implied by the absence of type specifiers, such a list of
3655
specifiers and qualifiers may be an attribute specifier list with no
3656
other specifiers or qualifiers.
3657
 
3658
At present, the first parameter in a function prototype must have some
3659
type specifier which is not an attribute specifier; this resolves an
3660
ambiguity in the interpretation of @code{void f(int
3661
(__attribute__((foo)) x))}, but is subject to change.  At present, if
3662
the parentheses of a function declarator contain only attributes then
3663
those attributes are ignored, rather than yielding an error or warning
3664
or implying a single parameter of type int, but this is subject to
3665
change.
3666
 
3667
An attribute specifier list may appear immediately before a declarator
3668
(other than the first) in a comma-separated list of declarators in a
3669
declaration of more than one identifier using a single list of
3670
specifiers and qualifiers.  Such attribute specifiers apply
3671
only to the identifier before whose declarator they appear.  For
3672
example, in
3673
 
3674
@smallexample
3675
__attribute__((noreturn)) void d0 (void),
3676
    __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
3677
     d2 (void)
3678
@end smallexample
3679
 
3680
@noindent
3681
the @code{noreturn} attribute applies to all the functions
3682
declared; the @code{format} attribute only applies to @code{d1}.
3683
 
3684
An attribute specifier list may appear immediately before the comma,
3685
@code{=} or semicolon terminating the declaration of an identifier other
3686
than a function definition.  Such attribute specifiers apply
3687
to the declared object or function.  Where an
3688
assembler name for an object or function is specified (@pxref{Asm
3689
Labels}), the attribute must follow the @code{asm}
3690
specification.
3691
 
3692
An attribute specifier list may, in future, be permitted to appear after
3693
the declarator in a function definition (before any old-style parameter
3694
declarations or the function body).
3695
 
3696
Attribute specifiers may be mixed with type qualifiers appearing inside
3697
the @code{[]} of a parameter array declarator, in the C99 construct by
3698
which such qualifiers are applied to the pointer to which the array is
3699
implicitly converted.  Such attribute specifiers apply to the pointer,
3700
not to the array, but at present this is not implemented and they are
3701
ignored.
3702
 
3703
An attribute specifier list may appear at the start of a nested
3704
declarator.  At present, there are some limitations in this usage: the
3705
attributes correctly apply to the declarator, but for most individual
3706
attributes the semantics this implies are not implemented.
3707
When attribute specifiers follow the @code{*} of a pointer
3708
declarator, they may be mixed with any type qualifiers present.
3709
The following describes the formal semantics of this syntax.  It will make the
3710
most sense if you are familiar with the formal specification of
3711
declarators in the ISO C standard.
3712
 
3713
Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
3714
D1}, where @code{T} contains declaration specifiers that specify a type
3715
@var{Type} (such as @code{int}) and @code{D1} is a declarator that
3716
contains an identifier @var{ident}.  The type specified for @var{ident}
3717
for derived declarators whose type does not include an attribute
3718
specifier is as in the ISO C standard.
3719
 
3720
If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
3721
and the declaration @code{T D} specifies the type
3722
``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
3723
@code{T D1} specifies the type ``@var{derived-declarator-type-list}
3724
@var{attribute-specifier-list} @var{Type}'' for @var{ident}.
3725
 
3726
If @code{D1} has the form @code{*
3727
@var{type-qualifier-and-attribute-specifier-list} D}, and the
3728
declaration @code{T D} specifies the type
3729
``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
3730
@code{T D1} specifies the type ``@var{derived-declarator-type-list}
3731
@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for
3732
@var{ident}.
3733
 
3734
For example,
3735
 
3736
@smallexample
3737
void (__attribute__((noreturn)) ****f) (void);
3738
@end smallexample
3739
 
3740
@noindent
3741
specifies the type ``pointer to pointer to pointer to pointer to
3742
non-returning function returning @code{void}''.  As another example,
3743
 
3744
@smallexample
3745
char *__attribute__((aligned(8))) *f;
3746
@end smallexample
3747
 
3748
@noindent
3749
specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
3750
Note again that this does not work with most attributes; for example,
3751
the usage of @samp{aligned} and @samp{noreturn} attributes given above
3752
is not yet supported.
3753
 
3754
For compatibility with existing code written for compiler versions that
3755
did not implement attributes on nested declarators, some laxity is
3756
allowed in the placing of attributes.  If an attribute that only applies
3757
to types is applied to a declaration, it will be treated as applying to
3758
the type of that declaration.  If an attribute that only applies to
3759
declarations is applied to the type of a declaration, it will be treated
3760
as applying to that declaration; and, for compatibility with code
3761
placing the attributes immediately before the identifier declared, such
3762
an attribute applied to a function return type will be treated as
3763
applying to the function type, and such an attribute applied to an array
3764
element type will be treated as applying to the array type.  If an
3765
attribute that only applies to function types is applied to a
3766
pointer-to-function type, it will be treated as applying to the pointer
3767
target type; if such an attribute is applied to a function return type
3768
that is not a pointer-to-function type, it will be treated as applying
3769
to the function type.
3770
 
3771
@node Function Prototypes
3772
@section Prototypes and Old-Style Function Definitions
3773
@cindex function prototype declarations
3774
@cindex old-style function definitions
3775
@cindex promotion of formal parameters
3776
 
3777
GNU C extends ISO C to allow a function prototype to override a later
3778
old-style non-prototype definition.  Consider the following example:
3779
 
3780
@smallexample
3781
/* @r{Use prototypes unless the compiler is old-fashioned.}  */
3782
#ifdef __STDC__
3783
#define P(x) x
3784
#else
3785
#define P(x) ()
3786
#endif
3787
 
3788
/* @r{Prototype function declaration.}  */
3789
int isroot P((uid_t));
3790
 
3791
/* @r{Old-style function definition.}  */
3792
int
3793
isroot (x)   /* @r{??? lossage here ???} */
3794
     uid_t x;
3795
@{
3796
  return x == 0;
3797
@}
3798
@end smallexample
3799
 
3800
Suppose the type @code{uid_t} happens to be @code{short}.  ISO C does
3801
not allow this example, because subword arguments in old-style
3802
non-prototype definitions are promoted.  Therefore in this example the
3803
function definition's argument is really an @code{int}, which does not
3804
match the prototype argument type of @code{short}.
3805
 
3806
This restriction of ISO C makes it hard to write code that is portable
3807
to traditional C compilers, because the programmer does not know
3808
whether the @code{uid_t} type is @code{short}, @code{int}, or
3809
@code{long}.  Therefore, in cases like these GNU C allows a prototype
3810
to override a later old-style definition.  More precisely, in GNU C, a
3811
function prototype argument type overrides the argument type specified
3812
by a later old-style definition if the former type is the same as the
3813
latter type before promotion.  Thus in GNU C the above example is
3814
equivalent to the following:
3815
 
3816
@smallexample
3817
int isroot (uid_t);
3818
 
3819
int
3820
isroot (uid_t x)
3821
@{
3822
  return x == 0;
3823
@}
3824
@end smallexample
3825
 
3826
@noindent
3827
GNU C++ does not support old-style function definitions, so this
3828
extension is irrelevant.
3829
 
3830
@node C++ Comments
3831
@section C++ Style Comments
3832
@cindex //
3833
@cindex C++ comments
3834
@cindex comments, C++ style
3835
 
3836
In GNU C, you may use C++ style comments, which start with @samp{//} and
3837
continue until the end of the line.  Many other C implementations allow
3838
such comments, and they are included in the 1999 C standard.  However,
3839
C++ style comments are not recognized if you specify an @option{-std}
3840
option specifying a version of ISO C before C99, or @option{-ansi}
3841
(equivalent to @option{-std=c90}).
3842
 
3843
@node Dollar Signs
3844
@section Dollar Signs in Identifier Names
3845
@cindex $
3846
@cindex dollar signs in identifier names
3847
@cindex identifier names, dollar signs in
3848
 
3849
In GNU C, you may normally use dollar signs in identifier names.
3850
This is because many traditional C implementations allow such identifiers.
3851
However, dollar signs in identifiers are not supported on a few target
3852
machines, typically because the target assembler does not allow them.
3853
 
3854
@node Character Escapes
3855
@section The Character @key{ESC} in Constants
3856
 
3857
You can use the sequence @samp{\e} in a string or character constant to
3858
stand for the ASCII character @key{ESC}.
3859
 
3860
@node Alignment
3861
@section Inquiring on Alignment of Types or Variables
3862
@cindex alignment
3863
@cindex type alignment
3864
@cindex variable alignment
3865
 
3866
The keyword @code{__alignof__} allows you to inquire about how an object
3867
is aligned, or the minimum alignment usually required by a type.  Its
3868
syntax is just like @code{sizeof}.
3869
 
3870
For example, if the target machine requires a @code{double} value to be
3871
aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
3872
This is true on many RISC machines.  On more traditional machine
3873
designs, @code{__alignof__ (double)} is 4 or even 2.
3874
 
3875
Some machines never actually require alignment; they allow reference to any
3876
data type even at an odd address.  For these machines, @code{__alignof__}
3877
reports the smallest alignment that GCC will give the data type, usually as
3878
mandated by the target ABI.
3879
 
3880
If the operand of @code{__alignof__} is an lvalue rather than a type,
3881
its value is the required alignment for its type, taking into account
3882
any minimum alignment specified with GCC's @code{__attribute__}
3883
extension (@pxref{Variable Attributes}).  For example, after this
3884
declaration:
3885
 
3886
@smallexample
3887
struct foo @{ int x; char y; @} foo1;
3888
@end smallexample
3889
 
3890
@noindent
3891
the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
3892
alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
3893
 
3894
It is an error to ask for the alignment of an incomplete type.
3895
 
3896
@node Variable Attributes
3897
@section Specifying Attributes of Variables
3898
@cindex attribute of variables
3899
@cindex variable attributes
3900
 
3901
The keyword @code{__attribute__} allows you to specify special
3902
attributes of variables or structure fields.  This keyword is followed
3903
by an attribute specification inside double parentheses.  Some
3904
attributes are currently defined generically for variables.
3905
Other attributes are defined for variables on particular target
3906
systems.  Other attributes are available for functions
3907
(@pxref{Function Attributes}) and for types (@pxref{Type Attributes}).
3908
Other front ends might define more attributes
3909
(@pxref{C++ Extensions,,Extensions to the C++ Language}).
3910
 
3911
You may also specify attributes with @samp{__} preceding and following
3912
each keyword.  This allows you to use them in header files without
3913
being concerned about a possible macro of the same name.  For example,
3914
you may use @code{__aligned__} instead of @code{aligned}.
3915
 
3916
@xref{Attribute Syntax}, for details of the exact syntax for using
3917
attributes.
3918
 
3919
@table @code
3920
@cindex @code{aligned} attribute
3921
@item aligned (@var{alignment})
3922
This attribute specifies a minimum alignment for the variable or
3923
structure field, measured in bytes.  For example, the declaration:
3924
 
3925
@smallexample
3926
int x __attribute__ ((aligned (16))) = 0;
3927
@end smallexample
3928
 
3929
@noindent
3930
causes the compiler to allocate the global variable @code{x} on a
3931
16-byte boundary.  On a 68040, this could be used in conjunction with
3932
an @code{asm} expression to access the @code{move16} instruction which
3933
requires 16-byte aligned operands.
3934
 
3935
You can also specify the alignment of structure fields.  For example, to
3936
create a double-word aligned @code{int} pair, you could write:
3937
 
3938
@smallexample
3939
struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
3940
@end smallexample
3941
 
3942
@noindent
3943
This is an alternative to creating a union with a @code{double} member
3944
that forces the union to be double-word aligned.
3945
 
3946
As in the preceding examples, you can explicitly specify the alignment
3947
(in bytes) that you wish the compiler to use for a given variable or
3948
structure field.  Alternatively, you can leave out the alignment factor
3949
and just ask the compiler to align a variable or field to the
3950
default alignment for the target architecture you are compiling for.
3951
The default alignment is sufficient for all scalar types, but may not be
3952
enough for all vector types on a target which supports vector operations.
3953
The default alignment is fixed for a particular target ABI.
3954
 
3955
Gcc also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
3956
which is the largest alignment ever used for any data type on the
3957
target machine you are compiling for.  For example, you could write:
3958
 
3959
@smallexample
3960
short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
3961
@end smallexample
3962
 
3963
The compiler automatically sets the alignment for the declared
3964
variable or field to @code{__BIGGEST_ALIGNMENT__}.  Doing this can
3965
often make copy operations more efficient, because the compiler can
3966
use whatever instructions copy the biggest chunks of memory when
3967
performing copies to or from the variables or fields that you have
3968
aligned this way.  Note that the value of @code{__BIGGEST_ALIGNMENT__}
3969
may change depending on command line options.
3970
 
3971
When used on a struct, or struct member, the @code{aligned} attribute can
3972
only increase the alignment; in order to decrease it, the @code{packed}
3973
attribute must be specified as well.  When used as part of a typedef, the
3974
@code{aligned} attribute can both increase and decrease alignment, and
3975
specifying the @code{packed} attribute will generate a warning.
3976
 
3977
Note that the effectiveness of @code{aligned} attributes may be limited
3978
by inherent limitations in your linker.  On many systems, the linker is
3979
only able to arrange for variables to be aligned up to a certain maximum
3980
alignment.  (For some linkers, the maximum supported alignment may
3981
be very very small.)  If your linker is only able to align variables
3982
up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
3983
in an @code{__attribute__} will still only provide you with 8 byte
3984
alignment.  See your linker documentation for further information.
3985
 
3986
The @code{aligned} attribute can also be used for functions
3987
(@pxref{Function Attributes}.)
3988
 
3989
@item cleanup (@var{cleanup_function})
3990
@cindex @code{cleanup} attribute
3991
The @code{cleanup} attribute runs a function when the variable goes
3992
out of scope.  This attribute can only be applied to auto function
3993
scope variables; it may not be applied to parameters or variables
3994
with static storage duration.  The function must take one parameter,
3995
a pointer to a type compatible with the variable.  The return value
3996
of the function (if any) is ignored.
3997
 
3998
If @option{-fexceptions} is enabled, then @var{cleanup_function}
3999
will be run during the stack unwinding that happens during the
4000
processing of the exception.  Note that the @code{cleanup} attribute
4001
does not allow the exception to be caught, only to perform an action.
4002
It is undefined what happens if @var{cleanup_function} does not
4003
return normally.
4004
 
4005
@item common
4006
@itemx nocommon
4007
@cindex @code{common} attribute
4008
@cindex @code{nocommon} attribute
4009
@opindex fcommon
4010
@opindex fno-common
4011
The @code{common} attribute requests GCC to place a variable in
4012
``common'' storage.  The @code{nocommon} attribute requests the
4013
opposite---to allocate space for it directly.
4014
 
4015
These attributes override the default chosen by the
4016
@option{-fno-common} and @option{-fcommon} flags respectively.
4017
 
4018
@item deprecated
4019
@itemx deprecated (@var{msg})
4020
@cindex @code{deprecated} attribute
4021
The @code{deprecated} attribute results in a warning if the variable
4022
is used anywhere in the source file.  This is useful when identifying
4023
variables that are expected to be removed in a future version of a
4024
program.  The warning also includes the location of the declaration
4025
of the deprecated variable, to enable users to easily find further
4026
information about why the variable is deprecated, or what they should
4027
do instead.  Note that the warning only occurs for uses:
4028
 
4029
@smallexample
4030
extern int old_var __attribute__ ((deprecated));
4031
extern int old_var;
4032
int new_fn () @{ return old_var; @}
4033
@end smallexample
4034
 
4035
results in a warning on line 3 but not line 2.  The optional msg
4036
argument, which must be a string, will be printed in the warning if
4037
present.
4038
 
4039
The @code{deprecated} attribute can also be used for functions and
4040
types (@pxref{Function Attributes}, @pxref{Type Attributes}.)
4041
 
4042
@item mode (@var{mode})
4043
@cindex @code{mode} attribute
4044
This attribute specifies the data type for the declaration---whichever
4045
type corresponds to the mode @var{mode}.  This in effect lets you
4046
request an integer or floating point type according to its width.
4047
 
4048
You may also specify a mode of @samp{byte} or @samp{__byte__} to
4049
indicate the mode corresponding to a one-byte integer, @samp{word} or
4050
@samp{__word__} for the mode of a one-word integer, and @samp{pointer}
4051
or @samp{__pointer__} for the mode used to represent pointers.
4052
 
4053
@item packed
4054
@cindex @code{packed} attribute
4055
The @code{packed} attribute specifies that a variable or structure field
4056
should have the smallest possible alignment---one byte for a variable,
4057
and one bit for a field, unless you specify a larger value with the
4058
@code{aligned} attribute.
4059
 
4060
Here is a structure in which the field @code{x} is packed, so that it
4061
immediately follows @code{a}:
4062
 
4063
@smallexample
4064
struct foo
4065
@{
4066
  char a;
4067
  int x[2] __attribute__ ((packed));
4068
@};
4069
@end smallexample
4070
 
4071
@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
4072
@code{packed} attribute on bit-fields of type @code{char}.  This has
4073
been fixed in GCC 4.4 but the change can lead to differences in the
4074
structure layout.  See the documentation of
4075
@option{-Wpacked-bitfield-compat} for more information.
4076
 
4077
@item section ("@var{section-name}")
4078
@cindex @code{section} variable attribute
4079
Normally, the compiler places the objects it generates in sections like
4080
@code{data} and @code{bss}.  Sometimes, however, you need additional sections,
4081
or you need certain particular variables to appear in special sections,
4082
for example to map to special hardware.  The @code{section}
4083
attribute specifies that a variable (or function) lives in a particular
4084
section.  For example, this small program uses several specific section names:
4085
 
4086
@smallexample
4087
struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
4088
struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
4089
char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
4090
int init_data __attribute__ ((section ("INITDATA")));
4091
 
4092
main()
4093
@{
4094
  /* @r{Initialize stack pointer} */
4095
  init_sp (stack + sizeof (stack));
4096
 
4097
  /* @r{Initialize initialized data} */
4098
  memcpy (&init_data, &data, &edata - &data);
4099
 
4100
  /* @r{Turn on the serial ports} */
4101
  init_duart (&a);
4102
  init_duart (&b);
4103
@}
4104
@end smallexample
4105
 
4106
@noindent
4107
Use the @code{section} attribute with
4108
@emph{global} variables and not @emph{local} variables,
4109
as shown in the example.
4110
 
4111
You may use the @code{section} attribute with initialized or
4112
uninitialized global variables but the linker requires
4113
each object be defined once, with the exception that uninitialized
4114
variables tentatively go in the @code{common} (or @code{bss}) section
4115
and can be multiply ``defined''.  Using the @code{section} attribute
4116
will change what section the variable goes into and may cause the
4117
linker to issue an error if an uninitialized variable has multiple
4118
definitions.  You can force a variable to be initialized with the
4119
@option{-fno-common} flag or the @code{nocommon} attribute.
4120
 
4121
Some file formats do not support arbitrary sections so the @code{section}
4122
attribute is not available on all platforms.
4123
If you need to map the entire contents of a module to a particular
4124
section, consider using the facilities of the linker instead.
4125
 
4126
@item shared
4127
@cindex @code{shared} variable attribute
4128
On Microsoft Windows, in addition to putting variable definitions in a named
4129
section, the section can also be shared among all running copies of an
4130
executable or DLL@.  For example, this small program defines shared data
4131
by putting it in a named section @code{shared} and marking the section
4132
shareable:
4133
 
4134
@smallexample
4135
int foo __attribute__((section ("shared"), shared)) = 0;
4136
 
4137
int
4138
main()
4139
@{
4140
  /* @r{Read and write foo.  All running
4141
     copies see the same value.}  */
4142
  return 0;
4143
@}
4144
@end smallexample
4145
 
4146
@noindent
4147
You may only use the @code{shared} attribute along with @code{section}
4148
attribute with a fully initialized global definition because of the way
4149
linkers work.  See @code{section} attribute for more information.
4150
 
4151
The @code{shared} attribute is only available on Microsoft Windows@.
4152
 
4153
@item tls_model ("@var{tls_model}")
4154
@cindex @code{tls_model} attribute
4155
The @code{tls_model} attribute sets thread-local storage model
4156
(@pxref{Thread-Local}) of a particular @code{__thread} variable,
4157
overriding @option{-ftls-model=} command line switch on a per-variable
4158
basis.
4159
The @var{tls_model} argument should be one of @code{global-dynamic},
4160
@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
4161
 
4162
Not all targets support this attribute.
4163
 
4164
@item unused
4165
This attribute, attached to a variable, means that the variable is meant
4166
to be possibly unused.  GCC will not produce a warning for this
4167
variable.
4168
 
4169
@item used
4170
This attribute, attached to a variable, means that the variable must be
4171
emitted even if it appears that the variable is not referenced.
4172
 
4173
@item vector_size (@var{bytes})
4174
This attribute specifies the vector size for the variable, measured in
4175
bytes.  For example, the declaration:
4176
 
4177
@smallexample
4178
int foo __attribute__ ((vector_size (16)));
4179
@end smallexample
4180
 
4181
@noindent
4182
causes the compiler to set the mode for @code{foo}, to be 16 bytes,
4183
divided into @code{int} sized units.  Assuming a 32-bit int (a vector of
4184
4 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@.
4185
 
4186
This attribute is only applicable to integral and float scalars,
4187
although arrays, pointers, and function return values are allowed in
4188
conjunction with this construct.
4189
 
4190
Aggregates with this attribute are invalid, even if they are of the same
4191
size as a corresponding scalar.  For example, the declaration:
4192
 
4193
@smallexample
4194
struct S @{ int a; @};
4195
struct S  __attribute__ ((vector_size (16))) foo;
4196
@end smallexample
4197
 
4198
@noindent
4199
is invalid even if the size of the structure is the same as the size of
4200
the @code{int}.
4201
 
4202
@item selectany
4203
The @code{selectany} attribute causes an initialized global variable to
4204
have link-once semantics.  When multiple definitions of the variable are
4205
encountered by the linker, the first is selected and the remainder are
4206
discarded.  Following usage by the Microsoft compiler, the linker is told
4207
@emph{not} to warn about size or content differences of the multiple
4208
definitions.
4209
 
4210
Although the primary usage of this attribute is for POD types, the
4211
attribute can also be applied to global C++ objects that are initialized
4212
by a constructor.  In this case, the static initialization and destruction
4213
code for the object is emitted in each translation defining the object,
4214
but the calls to the constructor and destructor are protected by a
4215
link-once guard variable.
4216
 
4217
The @code{selectany} attribute is only available on Microsoft Windows
4218
targets.  You can use @code{__declspec (selectany)} as a synonym for
4219
@code{__attribute__ ((selectany))} for compatibility with other
4220
compilers.
4221
 
4222
@item weak
4223
The @code{weak} attribute is described in @ref{Function Attributes}.
4224
 
4225
@item dllimport
4226
The @code{dllimport} attribute is described in @ref{Function Attributes}.
4227
 
4228
@item dllexport
4229
The @code{dllexport} attribute is described in @ref{Function Attributes}.
4230
 
4231
@end table
4232
 
4233
@subsection Blackfin Variable Attributes
4234
 
4235
Three attributes are currently defined for the Blackfin.
4236
 
4237
@table @code
4238
@item l1_data
4239
@itemx l1_data_A
4240
@itemx l1_data_B
4241
@cindex @code{l1_data} variable attribute
4242
@cindex @code{l1_data_A} variable attribute
4243
@cindex @code{l1_data_B} variable attribute
4244
Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
4245
Variables with @code{l1_data} attribute will be put into the specific section
4246
named @code{.l1.data}. Those with @code{l1_data_A} attribute will be put into
4247
the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
4248
attribute will be put into the specific section named @code{.l1.data.B}.
4249
 
4250
@item l2
4251
@cindex @code{l2} variable attribute
4252
Use this attribute on the Blackfin to place the variable into L2 SRAM.
4253
Variables with @code{l2} attribute will be put into the specific section
4254
named @code{.l2.data}.
4255
@end table
4256
 
4257
@subsection M32R/D Variable Attributes
4258
 
4259
One attribute is currently defined for the M32R/D@.
4260
 
4261
@table @code
4262
@item model (@var{model-name})
4263
@cindex variable addressability on the M32R/D
4264
Use this attribute on the M32R/D to set the addressability of an object.
4265
The identifier @var{model-name} is one of @code{small}, @code{medium},
4266
or @code{large}, representing each of the code models.
4267
 
4268
Small model objects live in the lower 16MB of memory (so that their
4269
addresses can be loaded with the @code{ld24} instruction).
4270
 
4271
Medium and large model objects may live anywhere in the 32-bit address space
4272
(the compiler will generate @code{seth/add3} instructions to load their
4273
addresses).
4274
@end table
4275
 
4276
@anchor{MeP Variable Attributes}
4277
@subsection MeP Variable Attributes
4278
 
4279
The MeP target has a number of addressing modes and busses.  The
4280
@code{near} space spans the standard memory space's first 16 megabytes
4281
(24 bits).  The @code{far} space spans the entire 32-bit memory space.
4282
The @code{based} space is a 128 byte region in the memory space which
4283
is addressed relative to the @code{$tp} register.  The @code{tiny}
4284
space is a 65536 byte region relative to the @code{$gp} register.  In
4285
addition to these memory regions, the MeP target has a separate 16-bit
4286
control bus which is specified with @code{cb} attributes.
4287
 
4288
@table @code
4289
 
4290
@item based
4291
Any variable with the @code{based} attribute will be assigned to the
4292
@code{.based} section, and will be accessed with relative to the
4293
@code{$tp} register.
4294
 
4295
@item tiny
4296
Likewise, the @code{tiny} attribute assigned variables to the
4297
@code{.tiny} section, relative to the @code{$gp} register.
4298
 
4299
@item near
4300
Variables with the @code{near} attribute are assumed to have addresses
4301
that fit in a 24-bit addressing mode.  This is the default for large
4302
variables (@code{-mtiny=4} is the default) but this attribute can
4303
override @code{-mtiny=} for small variables, or override @code{-ml}.
4304
 
4305
@item far
4306
Variables with the @code{far} attribute are addressed using a full
4307
32-bit address.  Since this covers the entire memory space, this
4308
allows modules to make no assumptions about where variables might be
4309
stored.
4310
 
4311
@item io
4312
@itemx io (@var{addr})
4313
Variables with the @code{io} attribute are used to address
4314
memory-mapped peripherals.  If an address is specified, the variable
4315
is assigned that address, else it is not assigned an address (it is
4316
assumed some other module will assign an address).  Example:
4317
 
4318
@example
4319
int timer_count __attribute__((io(0x123)));
4320
@end example
4321
 
4322
@item cb
4323
@itemx cb (@var{addr})
4324
Variables with the @code{cb} attribute are used to access the control
4325
bus, using special instructions.  @code{addr} indicates the control bus
4326
address.  Example:
4327
 
4328
@example
4329
int cpu_clock __attribute__((cb(0x123)));
4330
@end example
4331
 
4332
@end table
4333
 
4334
@anchor{i386 Variable Attributes}
4335
@subsection i386 Variable Attributes
4336
 
4337
Two attributes are currently defined for i386 configurations:
4338
@code{ms_struct} and @code{gcc_struct}
4339
 
4340
@table @code
4341
@item ms_struct
4342
@itemx gcc_struct
4343
@cindex @code{ms_struct} attribute
4344
@cindex @code{gcc_struct} attribute
4345
 
4346
If @code{packed} is used on a structure, or if bit-fields are used
4347
it may be that the Microsoft ABI packs them differently
4348
than GCC would normally pack them.  Particularly when moving packed
4349
data between functions compiled with GCC and the native Microsoft compiler
4350
(either via function call or as data in a file), it may be necessary to access
4351
either format.
4352
 
4353
Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
4354
compilers to match the native Microsoft compiler.
4355
 
4356
The Microsoft structure layout algorithm is fairly simple with the exception
4357
of the bitfield packing:
4358
 
4359
The padding and alignment of members of structures and whether a bit field
4360
can straddle a storage-unit boundary
4361
 
4362
@enumerate
4363
@item Structure members are stored sequentially in the order in which they are
4364
declared: the first member has the lowest memory address and the last member
4365
the highest.
4366
 
4367
@item Every data object has an alignment-requirement. The alignment-requirement
4368
for all data except structures, unions, and arrays is either the size of the
4369
object or the current packing size (specified with either the aligned attribute
4370
or the pack pragma), whichever is less. For structures,  unions, and arrays,
4371
the alignment-requirement is the largest alignment-requirement of its members.
4372
Every object is allocated an offset so that:
4373
 
4374
offset %  alignment-requirement == 0
4375
 
4376
@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation
4377
unit if the integral types are the same size and if the next bit field fits
4378
into the current allocation unit without crossing the boundary imposed by the
4379
common alignment requirements of the bit fields.
4380
@end enumerate
4381
 
4382
Handling of zero-length bitfields:
4383
 
4384
MSVC interprets zero-length bitfields in the following ways:
4385
 
4386
@enumerate
4387
@item If a zero-length bitfield is inserted between two bitfields that would
4388
normally be coalesced, the bitfields will not be coalesced.
4389
 
4390
For example:
4391
 
4392
@smallexample
4393
struct
4394
 @{
4395
   unsigned long bf_1 : 12;
4396
   unsigned long : 0;
4397
   unsigned long bf_2 : 12;
4398
 @} t1;
4399
@end smallexample
4400
 
4401
The size of @code{t1} would be 8 bytes with the zero-length bitfield.  If the
4402
zero-length bitfield were removed, @code{t1}'s size would be 4 bytes.
4403
 
4404
@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the
4405
alignment of the zero-length bitfield is greater than the member that follows it,
4406
@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield.
4407
 
4408
For example:
4409
 
4410
@smallexample
4411
struct
4412
 @{
4413
   char foo : 4;
4414
   short : 0;
4415
   char bar;
4416
 @} t2;
4417
 
4418
struct
4419
 @{
4420
   char foo : 4;
4421
   short : 0;
4422
   double bar;
4423
 @} t3;
4424
@end smallexample
4425
 
4426
For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1.
4427
Accordingly, the size of @code{t2} will be 4.  For @code{t3}, the zero-length
4428
bitfield will not affect the alignment of @code{bar} or, as a result, the size
4429
of the structure.
4430
 
4431
Taking this into account, it is important to note the following:
4432
 
4433
@enumerate
4434
@item If a zero-length bitfield follows a normal bitfield, the type of the
4435
zero-length bitfield may affect the alignment of the structure as whole. For
4436
example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a
4437
normal bitfield, and is of type short.
4438
 
4439
@item Even if a zero-length bitfield is not followed by a normal bitfield, it may
4440
still affect the alignment of the structure:
4441
 
4442
@smallexample
4443
struct
4444
 @{
4445
   char foo : 6;
4446
   long : 0;
4447
 @} t4;
4448
@end smallexample
4449
 
4450
Here, @code{t4} will take up 4 bytes.
4451
@end enumerate
4452
 
4453
@item Zero-length bitfields following non-bitfield members are ignored:
4454
 
4455
@smallexample
4456
struct
4457
 @{
4458
   char foo;
4459
   long : 0;
4460
   char bar;
4461
 @} t5;
4462
@end smallexample
4463
 
4464
Here, @code{t5} will take up 2 bytes.
4465
@end enumerate
4466
@end table
4467
 
4468
@subsection PowerPC Variable Attributes
4469
 
4470
Three attributes currently are defined for PowerPC configurations:
4471
@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
4472
 
4473
For full documentation of the struct attributes please see the
4474
documentation in @ref{i386 Variable Attributes}.
4475
 
4476
For documentation of @code{altivec} attribute please see the
4477
documentation in @ref{PowerPC Type Attributes}.
4478
 
4479
@subsection SPU Variable Attributes
4480
 
4481
The SPU supports the @code{spu_vector} attribute for variables.  For
4482
documentation of this attribute please see the documentation in
4483
@ref{SPU Type Attributes}.
4484
 
4485
@subsection Xstormy16 Variable Attributes
4486
 
4487
One attribute is currently defined for xstormy16 configurations:
4488
@code{below100}.
4489
 
4490
@table @code
4491
@item below100
4492
@cindex @code{below100} attribute
4493
 
4494
If a variable has the @code{below100} attribute (@code{BELOW100} is
4495
allowed also), GCC will place the variable in the first 0x100 bytes of
4496
memory and use special opcodes to access it.  Such variables will be
4497
placed in either the @code{.bss_below100} section or the
4498
@code{.data_below100} section.
4499
 
4500
@end table
4501
 
4502
@subsection AVR Variable Attributes
4503
 
4504
@table @code
4505
@item progmem
4506
@cindex @code{progmem} variable attribute
4507
The @code{progmem} attribute is used on the AVR to place data in the Program
4508
Memory address space. The AVR is a Harvard Architecture processor and data
4509
normally resides in the Data Memory address space.
4510
@end table
4511
 
4512
@node Type Attributes
4513
@section Specifying Attributes of Types
4514
@cindex attribute of types
4515
@cindex type attributes
4516
 
4517
The keyword @code{__attribute__} allows you to specify special
4518
attributes of @code{struct} and @code{union} types when you define
4519
such types.  This keyword is followed by an attribute specification
4520
inside double parentheses.  Seven attributes are currently defined for
4521
types: @code{aligned}, @code{packed}, @code{transparent_union},
4522
@code{unused}, @code{deprecated}, @code{visibility}, and
4523
@code{may_alias}.  Other attributes are defined for functions
4524
(@pxref{Function Attributes}) and for variables (@pxref{Variable
4525
Attributes}).
4526
 
4527
You may also specify any one of these attributes with @samp{__}
4528
preceding and following its keyword.  This allows you to use these
4529
attributes in header files without being concerned about a possible
4530
macro of the same name.  For example, you may use @code{__aligned__}
4531
instead of @code{aligned}.
4532
 
4533
You may specify type attributes in an enum, struct or union type
4534
declaration or definition, or for other types in a @code{typedef}
4535
declaration.
4536
 
4537
For an enum, struct or union type, you may specify attributes either
4538
between the enum, struct or union tag and the name of the type, or
4539
just past the closing curly brace of the @emph{definition}.  The
4540
former syntax is preferred.
4541
 
4542
@xref{Attribute Syntax}, for details of the exact syntax for using
4543
attributes.
4544
 
4545
@table @code
4546
@cindex @code{aligned} attribute
4547
@item aligned (@var{alignment})
4548
This attribute specifies a minimum alignment (in bytes) for variables
4549
of the specified type.  For example, the declarations:
4550
 
4551
@smallexample
4552
struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
4553
typedef int more_aligned_int __attribute__ ((aligned (8)));
4554
@end smallexample
4555
 
4556
@noindent
4557
force the compiler to insure (as far as it can) that each variable whose
4558
type is @code{struct S} or @code{more_aligned_int} will be allocated and
4559
aligned @emph{at least} on a 8-byte boundary.  On a SPARC, having all
4560
variables of type @code{struct S} aligned to 8-byte boundaries allows
4561
the compiler to use the @code{ldd} and @code{std} (doubleword load and
4562
store) instructions when copying one variable of type @code{struct S} to
4563
another, thus improving run-time efficiency.
4564
 
4565
Note that the alignment of any given @code{struct} or @code{union} type
4566
is required by the ISO C standard to be at least a perfect multiple of
4567
the lowest common multiple of the alignments of all of the members of
4568
the @code{struct} or @code{union} in question.  This means that you @emph{can}
4569
effectively adjust the alignment of a @code{struct} or @code{union}
4570
type by attaching an @code{aligned} attribute to any one of the members
4571
of such a type, but the notation illustrated in the example above is a
4572
more obvious, intuitive, and readable way to request the compiler to
4573
adjust the alignment of an entire @code{struct} or @code{union} type.
4574
 
4575
As in the preceding example, you can explicitly specify the alignment
4576
(in bytes) that you wish the compiler to use for a given @code{struct}
4577
or @code{union} type.  Alternatively, you can leave out the alignment factor
4578
and just ask the compiler to align a type to the maximum
4579
useful alignment for the target machine you are compiling for.  For
4580
example, you could write:
4581
 
4582
@smallexample
4583
struct S @{ short f[3]; @} __attribute__ ((aligned));
4584
@end smallexample
4585
 
4586
Whenever you leave out the alignment factor in an @code{aligned}
4587
attribute specification, the compiler automatically sets the alignment
4588
for the type to the largest alignment which is ever used for any data
4589
type on the target machine you are compiling for.  Doing this can often
4590
make copy operations more efficient, because the compiler can use
4591
whatever instructions copy the biggest chunks of memory when performing
4592
copies to or from the variables which have types that you have aligned
4593
this way.
4594
 
4595
In the example above, if the size of each @code{short} is 2 bytes, then
4596
the size of the entire @code{struct S} type is 6 bytes.  The smallest
4597
power of two which is greater than or equal to that is 8, so the
4598
compiler sets the alignment for the entire @code{struct S} type to 8
4599
bytes.
4600
 
4601
Note that although you can ask the compiler to select a time-efficient
4602
alignment for a given type and then declare only individual stand-alone
4603
objects of that type, the compiler's ability to select a time-efficient
4604
alignment is primarily useful only when you plan to create arrays of
4605
variables having the relevant (efficiently aligned) type.  If you
4606
declare or use arrays of variables of an efficiently-aligned type, then
4607
it is likely that your program will also be doing pointer arithmetic (or
4608
subscripting, which amounts to the same thing) on pointers to the
4609
relevant type, and the code that the compiler generates for these
4610
pointer arithmetic operations will often be more efficient for
4611
efficiently-aligned types than for other types.
4612
 
4613
The @code{aligned} attribute can only increase the alignment; but you
4614
can decrease it by specifying @code{packed} as well.  See below.
4615
 
4616
Note that the effectiveness of @code{aligned} attributes may be limited
4617
by inherent limitations in your linker.  On many systems, the linker is
4618
only able to arrange for variables to be aligned up to a certain maximum
4619
alignment.  (For some linkers, the maximum supported alignment may
4620
be very very small.)  If your linker is only able to align variables
4621
up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
4622
in an @code{__attribute__} will still only provide you with 8 byte
4623
alignment.  See your linker documentation for further information.
4624
 
4625
@item packed
4626
This attribute, attached to @code{struct} or @code{union} type
4627
definition, specifies that each member (other than zero-width bitfields)
4628
of the structure or union is placed to minimize the memory required.  When
4629
attached to an @code{enum} definition, it indicates that the smallest
4630
integral type should be used.
4631
 
4632
@opindex fshort-enums
4633
Specifying this attribute for @code{struct} and @code{union} types is
4634
equivalent to specifying the @code{packed} attribute on each of the
4635
structure or union members.  Specifying the @option{-fshort-enums}
4636
flag on the line is equivalent to specifying the @code{packed}
4637
attribute on all @code{enum} definitions.
4638
 
4639
In the following example @code{struct my_packed_struct}'s members are
4640
packed closely together, but the internal layout of its @code{s} member
4641
is not packed---to do that, @code{struct my_unpacked_struct} would need to
4642
be packed too.
4643
 
4644
@smallexample
4645
struct my_unpacked_struct
4646
 @{
4647
    char c;
4648
    int i;
4649
 @};
4650
 
4651
struct __attribute__ ((__packed__)) my_packed_struct
4652
  @{
4653
     char c;
4654
     int  i;
4655
     struct my_unpacked_struct s;
4656
  @};
4657
@end smallexample
4658
 
4659
You may only specify this attribute on the definition of an @code{enum},
4660
@code{struct} or @code{union}, not on a @code{typedef} which does not
4661
also define the enumerated type, structure or union.
4662
 
4663
@item transparent_union
4664
This attribute, attached to a @code{union} type definition, indicates
4665
that any function parameter having that union type causes calls to that
4666
function to be treated in a special way.
4667
 
4668
First, the argument corresponding to a transparent union type can be of
4669
any type in the union; no cast is required.  Also, if the union contains
4670
a pointer type, the corresponding argument can be a null pointer
4671
constant or a void pointer expression; and if the union contains a void
4672
pointer type, the corresponding argument can be any pointer expression.
4673
If the union member type is a pointer, qualifiers like @code{const} on
4674
the referenced type must be respected, just as with normal pointer
4675
conversions.
4676
 
4677
Second, the argument is passed to the function using the calling
4678
conventions of the first member of the transparent union, not the calling
4679
conventions of the union itself.  All members of the union must have the
4680
same machine representation; this is necessary for this argument passing
4681
to work properly.
4682
 
4683
Transparent unions are designed for library functions that have multiple
4684
interfaces for compatibility reasons.  For example, suppose the
4685
@code{wait} function must accept either a value of type @code{int *} to
4686
comply with Posix, or a value of type @code{union wait *} to comply with
4687
the 4.1BSD interface.  If @code{wait}'s parameter were @code{void *},
4688
@code{wait} would accept both kinds of arguments, but it would also
4689
accept any other pointer type and this would make argument type checking
4690
less useful.  Instead, @code{<sys/wait.h>} might define the interface
4691
as follows:
4692
 
4693
@smallexample
4694
typedef union __attribute__ ((__transparent_union__))
4695
  @{
4696
    int *__ip;
4697
    union wait *__up;
4698
  @} wait_status_ptr_t;
4699
 
4700
pid_t wait (wait_status_ptr_t);
4701
@end smallexample
4702
 
4703
This interface allows either @code{int *} or @code{union wait *}
4704
arguments to be passed, using the @code{int *} calling convention.
4705
The program can call @code{wait} with arguments of either type:
4706
 
4707
@smallexample
4708
int w1 () @{ int w; return wait (&w); @}
4709
int w2 () @{ union wait w; return wait (&w); @}
4710
@end smallexample
4711
 
4712
With this interface, @code{wait}'s implementation might look like this:
4713
 
4714
@smallexample
4715
pid_t wait (wait_status_ptr_t p)
4716
@{
4717
  return waitpid (-1, p.__ip, 0);
4718
@}
4719
@end smallexample
4720
 
4721
@item unused
4722
When attached to a type (including a @code{union} or a @code{struct}),
4723
this attribute means that variables of that type are meant to appear
4724
possibly unused.  GCC will not produce a warning for any variables of
4725
that type, even if the variable appears to do nothing.  This is often
4726
the case with lock or thread classes, which are usually defined and then
4727
not referenced, but contain constructors and destructors that have
4728
nontrivial bookkeeping functions.
4729
 
4730
@item deprecated
4731
@itemx deprecated (@var{msg})
4732
The @code{deprecated} attribute results in a warning if the type
4733
is used anywhere in the source file.  This is useful when identifying
4734
types that are expected to be removed in a future version of a program.
4735
If possible, the warning also includes the location of the declaration
4736
of the deprecated type, to enable users to easily find further
4737
information about why the type is deprecated, or what they should do
4738
instead.  Note that the warnings only occur for uses and then only
4739
if the type is being applied to an identifier that itself is not being
4740
declared as deprecated.
4741
 
4742
@smallexample
4743
typedef int T1 __attribute__ ((deprecated));
4744
T1 x;
4745
typedef T1 T2;
4746
T2 y;
4747
typedef T1 T3 __attribute__ ((deprecated));
4748
T3 z __attribute__ ((deprecated));
4749
@end smallexample
4750
 
4751
results in a warning on line 2 and 3 but not lines 4, 5, or 6.  No
4752
warning is issued for line 4 because T2 is not explicitly
4753
deprecated.  Line 5 has no warning because T3 is explicitly
4754
deprecated.  Similarly for line 6.  The optional msg
4755
argument, which must be a string, will be printed in the warning if
4756
present.
4757
 
4758
The @code{deprecated} attribute can also be used for functions and
4759
variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
4760
 
4761
@item may_alias
4762
Accesses through pointers to types with this attribute are not subject
4763
to type-based alias analysis, but are instead assumed to be able to alias
4764
any other type of objects.  In the context of 6.5/7 an lvalue expression
4765
dereferencing such a pointer is treated like having a character type.
4766
See @option{-fstrict-aliasing} for more information on aliasing issues.
4767
This extension exists to support some vector APIs, in which pointers to
4768
one vector type are permitted to alias pointers to a different vector type.
4769
 
4770
Note that an object of a type with this attribute does not have any
4771
special semantics.
4772
 
4773
Example of use:
4774
 
4775
@smallexample
4776
typedef short __attribute__((__may_alias__)) short_a;
4777
 
4778
int
4779
main (void)
4780
@{
4781
  int a = 0x12345678;
4782
  short_a *b = (short_a *) &a;
4783
 
4784
  b[1] = 0;
4785
 
4786
  if (a == 0x12345678)
4787
    abort();
4788
 
4789
  exit(0);
4790
@}
4791
@end smallexample
4792
 
4793
If you replaced @code{short_a} with @code{short} in the variable
4794
declaration, the above program would abort when compiled with
4795
@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
4796
above in recent GCC versions.
4797
 
4798
@item visibility
4799
In C++, attribute visibility (@pxref{Function Attributes}) can also be
4800
applied to class, struct, union and enum types.  Unlike other type
4801
attributes, the attribute must appear between the initial keyword and
4802
the name of the type; it cannot appear after the body of the type.
4803
 
4804
Note that the type visibility is applied to vague linkage entities
4805
associated with the class (vtable, typeinfo node, etc.).  In
4806
particular, if a class is thrown as an exception in one shared object
4807
and caught in another, the class must have default visibility.
4808
Otherwise the two shared objects will be unable to use the same
4809
typeinfo node and exception handling will break.
4810
 
4811
@end table
4812
 
4813
@subsection ARM Type Attributes
4814
 
4815
On those ARM targets that support @code{dllimport} (such as Symbian
4816
OS), you can use the @code{notshared} attribute to indicate that the
4817
virtual table and other similar data for a class should not be
4818
exported from a DLL@.  For example:
4819
 
4820
@smallexample
4821
class __declspec(notshared) C @{
4822
public:
4823
  __declspec(dllimport) C();
4824
  virtual void f();
4825
@}
4826
 
4827
__declspec(dllexport)
4828
C::C() @{@}
4829
@end smallexample
4830
 
4831
In this code, @code{C::C} is exported from the current DLL, but the
4832
virtual table for @code{C} is not exported.  (You can use
4833
@code{__attribute__} instead of @code{__declspec} if you prefer, but
4834
most Symbian OS code uses @code{__declspec}.)
4835
 
4836
@anchor{MeP Type Attributes}
4837
@subsection MeP Type Attributes
4838
 
4839
Many of the MeP variable attributes may be applied to types as well.
4840
Specifically, the @code{based}, @code{tiny}, @code{near}, and
4841
@code{far} attributes may be applied to either.  The @code{io} and
4842
@code{cb} attributes may not be applied to types.
4843
 
4844
@anchor{i386 Type Attributes}
4845
@subsection i386 Type Attributes
4846
 
4847
Two attributes are currently defined for i386 configurations:
4848
@code{ms_struct} and @code{gcc_struct}.
4849
 
4850
@table @code
4851
 
4852
@item ms_struct
4853
@itemx gcc_struct
4854
@cindex @code{ms_struct}
4855
@cindex @code{gcc_struct}
4856
 
4857
If @code{packed} is used on a structure, or if bit-fields are used
4858
it may be that the Microsoft ABI packs them differently
4859
than GCC would normally pack them.  Particularly when moving packed
4860
data between functions compiled with GCC and the native Microsoft compiler
4861
(either via function call or as data in a file), it may be necessary to access
4862
either format.
4863
 
4864
Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
4865
compilers to match the native Microsoft compiler.
4866
@end table
4867
 
4868
To specify multiple attributes, separate them by commas within the
4869
double parentheses: for example, @samp{__attribute__ ((aligned (16),
4870
packed))}.
4871
 
4872
@anchor{PowerPC Type Attributes}
4873
@subsection PowerPC Type Attributes
4874
 
4875
Three attributes currently are defined for PowerPC configurations:
4876
@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
4877
 
4878
For full documentation of the @code{ms_struct} and @code{gcc_struct}
4879
attributes please see the documentation in @ref{i386 Type Attributes}.
4880
 
4881
The @code{altivec} attribute allows one to declare AltiVec vector data
4882
types supported by the AltiVec Programming Interface Manual.  The
4883
attribute requires an argument to specify one of three vector types:
4884
@code{vector__}, @code{pixel__} (always followed by unsigned short),
4885
and @code{bool__} (always followed by unsigned).
4886
 
4887
@smallexample
4888
__attribute__((altivec(vector__)))
4889
__attribute__((altivec(pixel__))) unsigned short
4890
__attribute__((altivec(bool__))) unsigned
4891
@end smallexample
4892
 
4893
These attributes mainly are intended to support the @code{__vector},
4894
@code{__pixel}, and @code{__bool} AltiVec keywords.
4895
 
4896
@anchor{SPU Type Attributes}
4897
@subsection SPU Type Attributes
4898
 
4899
The SPU supports the @code{spu_vector} attribute for types.  This attribute
4900
allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
4901
Language Extensions Specification.  It is intended to support the
4902
@code{__vector} keyword.
4903
 
4904
 
4905
@node Inline
4906
@section An Inline Function is As Fast As a Macro
4907
@cindex inline functions
4908
@cindex integrating function code
4909
@cindex open coding
4910
@cindex macros, inline alternative
4911
 
4912
By declaring a function inline, you can direct GCC to make
4913
calls to that function faster.  One way GCC can achieve this is to
4914
integrate that function's code into the code for its callers.  This
4915
makes execution faster by eliminating the function-call overhead; in
4916
addition, if any of the actual argument values are constant, their
4917
known values may permit simplifications at compile time so that not
4918
all of the inline function's code needs to be included.  The effect on
4919
code size is less predictable; object code may be larger or smaller
4920
with function inlining, depending on the particular case.  You can
4921
also direct GCC to try to integrate all ``simple enough'' functions
4922
into their callers with the option @option{-finline-functions}.
4923
 
4924
GCC implements three different semantics of declaring a function
4925
inline.  One is available with @option{-std=gnu89} or
4926
@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
4927
on all inline declarations, another when @option{-std=c99} or
4928
@option{-std=gnu99} (without @option{-fgnu89-inline}), and the third
4929
is used when compiling C++.
4930
 
4931
To declare a function inline, use the @code{inline} keyword in its
4932
declaration, like this:
4933
 
4934
@smallexample
4935
static inline int
4936
inc (int *a)
4937
@{
4938
  (*a)++;
4939
@}
4940
@end smallexample
4941
 
4942
If you are writing a header file to be included in ISO C90 programs, write
4943
@code{__inline__} instead of @code{inline}.  @xref{Alternate Keywords}.
4944
 
4945
The three types of inlining behave similarly in two important cases:
4946
when the @code{inline} keyword is used on a @code{static} function,
4947
like the example above, and when a function is first declared without
4948
using the @code{inline} keyword and then is defined with
4949
@code{inline}, like this:
4950
 
4951
@smallexample
4952
extern int inc (int *a);
4953
inline int
4954
inc (int *a)
4955
@{
4956
  (*a)++;
4957
@}
4958
@end smallexample
4959
 
4960
In both of these common cases, the program behaves the same as if you
4961
had not used the @code{inline} keyword, except for its speed.
4962
 
4963
@cindex inline functions, omission of
4964
@opindex fkeep-inline-functions
4965
When a function is both inline and @code{static}, if all calls to the
4966
function are integrated into the caller, and the function's address is
4967
never used, then the function's own assembler code is never referenced.
4968
In this case, GCC does not actually output assembler code for the
4969
function, unless you specify the option @option{-fkeep-inline-functions}.
4970
Some calls cannot be integrated for various reasons (in particular,
4971
calls that precede the function's definition cannot be integrated, and
4972
neither can recursive calls within the definition).  If there is a
4973
nonintegrated call, then the function is compiled to assembler code as
4974
usual.  The function must also be compiled as usual if the program
4975
refers to its address, because that can't be inlined.
4976
 
4977
@opindex Winline
4978
Note that certain usages in a function definition can make it unsuitable
4979
for inline substitution.  Among these usages are: use of varargs, use of
4980
alloca, use of variable sized data types (@pxref{Variable Length}),
4981
use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
4982
and nested functions (@pxref{Nested Functions}).  Using @option{-Winline}
4983
will warn when a function marked @code{inline} could not be substituted,
4984
and will give the reason for the failure.
4985
 
4986
@cindex automatic @code{inline} for C++ member fns
4987
@cindex @code{inline} automatic for C++ member fns
4988
@cindex member fns, automatically @code{inline}
4989
@cindex C++ member fns, automatically @code{inline}
4990
@opindex fno-default-inline
4991
As required by ISO C++, GCC considers member functions defined within
4992
the body of a class to be marked inline even if they are
4993
not explicitly declared with the @code{inline} keyword.  You can
4994
override this with @option{-fno-default-inline}; @pxref{C++ Dialect
4995
Options,,Options Controlling C++ Dialect}.
4996
 
4997
GCC does not inline any functions when not optimizing unless you specify
4998
the @samp{always_inline} attribute for the function, like this:
4999
 
5000
@smallexample
5001
/* @r{Prototype.}  */
5002
inline void foo (const char) __attribute__((always_inline));
5003
@end smallexample
5004
 
5005
The remainder of this section is specific to GNU C90 inlining.
5006
 
5007
@cindex non-static inline function
5008
When an inline function is not @code{static}, then the compiler must assume
5009
that there may be calls from other source files; since a global symbol can
5010
be defined only once in any program, the function must not be defined in
5011
the other source files, so the calls therein cannot be integrated.
5012
Therefore, a non-@code{static} inline function is always compiled on its
5013
own in the usual fashion.
5014
 
5015
If you specify both @code{inline} and @code{extern} in the function
5016
definition, then the definition is used only for inlining.  In no case
5017
is the function compiled on its own, not even if you refer to its
5018
address explicitly.  Such an address becomes an external reference, as
5019
if you had only declared the function, and had not defined it.
5020
 
5021
This combination of @code{inline} and @code{extern} has almost the
5022
effect of a macro.  The way to use it is to put a function definition in
5023
a header file with these keywords, and put another copy of the
5024
definition (lacking @code{inline} and @code{extern}) in a library file.
5025
The definition in the header file will cause most calls to the function
5026
to be inlined.  If any uses of the function remain, they will refer to
5027
the single copy in the library.
5028
 
5029
@node Extended Asm
5030
@section Assembler Instructions with C Expression Operands
5031
@cindex extended @code{asm}
5032
@cindex @code{asm} expressions
5033
@cindex assembler instructions
5034
@cindex registers
5035
 
5036
In an assembler instruction using @code{asm}, you can specify the
5037
operands of the instruction using C expressions.  This means you need not
5038
guess which registers or memory locations will contain the data you want
5039
to use.
5040
 
5041
You must specify an assembler instruction template much like what
5042
appears in a machine description, plus an operand constraint string for
5043
each operand.
5044
 
5045
For example, here is how to use the 68881's @code{fsinx} instruction:
5046
 
5047
@smallexample
5048
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
5049
@end smallexample
5050
 
5051
@noindent
5052
Here @code{angle} is the C expression for the input operand while
5053
@code{result} is that of the output operand.  Each has @samp{"f"} as its
5054
operand constraint, saying that a floating point register is required.
5055
The @samp{=} in @samp{=f} indicates that the operand is an output; all
5056
output operands' constraints must use @samp{=}.  The constraints use the
5057
same language used in the machine description (@pxref{Constraints}).
5058
 
5059
Each operand is described by an operand-constraint string followed by
5060
the C expression in parentheses.  A colon separates the assembler
5061
template from the first output operand and another separates the last
5062
output operand from the first input, if any.  Commas separate the
5063
operands within each group.  The total number of operands is currently
5064
limited to 30; this limitation may be lifted in some future version of
5065
GCC@.
5066
 
5067
If there are no output operands but there are input operands, you must
5068
place two consecutive colons surrounding the place where the output
5069
operands would go.
5070
 
5071
As of GCC version 3.1, it is also possible to specify input and output
5072
operands using symbolic names which can be referenced within the
5073
assembler code.  These names are specified inside square brackets
5074
preceding the constraint string, and can be referenced inside the
5075
assembler code using @code{%[@var{name}]} instead of a percentage sign
5076
followed by the operand number.  Using named operands the above example
5077
could look like:
5078
 
5079
@smallexample
5080
asm ("fsinx %[angle],%[output]"
5081
     : [output] "=f" (result)
5082
     : [angle] "f" (angle));
5083
@end smallexample
5084
 
5085
@noindent
5086
Note that the symbolic operand names have no relation whatsoever to
5087
other C identifiers.  You may use any name you like, even those of
5088
existing C symbols, but you must ensure that no two operands within the same
5089
assembler construct use the same symbolic name.
5090
 
5091
Output operand expressions must be lvalues; the compiler can check this.
5092
The input operands need not be lvalues.  The compiler cannot check
5093
whether the operands have data types that are reasonable for the
5094
instruction being executed.  It does not parse the assembler instruction
5095
template and does not know what it means or even whether it is valid
5096
assembler input.  The extended @code{asm} feature is most often used for
5097
machine instructions the compiler itself does not know exist.  If
5098
the output expression cannot be directly addressed (for example, it is a
5099
bit-field), your constraint must allow a register.  In that case, GCC
5100
will use the register as the output of the @code{asm}, and then store
5101
that register into the output.
5102
 
5103
The ordinary output operands must be write-only; GCC will assume that
5104
the values in these operands before the instruction are dead and need
5105
not be generated.  Extended asm supports input-output or read-write
5106
operands.  Use the constraint character @samp{+} to indicate such an
5107
operand and list it with the output operands.  You should only use
5108
read-write operands when the constraints for the operand (or the
5109
operand in which only some of the bits are to be changed) allow a
5110
register.
5111
 
5112
You may, as an alternative, logically split its function into two
5113
separate operands, one input operand and one write-only output
5114
operand.  The connection between them is expressed by constraints
5115
which say they need to be in the same location when the instruction
5116
executes.  You can use the same C expression for both operands, or
5117
different expressions.  For example, here we write the (fictitious)
5118
@samp{combine} instruction with @code{bar} as its read-only source
5119
operand and @code{foo} as its read-write destination:
5120
 
5121
@smallexample
5122
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
5123
@end smallexample
5124
 
5125
@noindent
5126
The constraint @samp{"0"} for operand 1 says that it must occupy the
5127
same location as operand 0.  A number in constraint is allowed only in
5128
an input operand and it must refer to an output operand.
5129
 
5130
Only a number in the constraint can guarantee that one operand will be in
5131
the same place as another.  The mere fact that @code{foo} is the value
5132
of both operands is not enough to guarantee that they will be in the
5133
same place in the generated assembler code.  The following would not
5134
work reliably:
5135
 
5136
@smallexample
5137
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
5138
@end smallexample
5139
 
5140
Various optimizations or reloading could cause operands 0 and 1 to be in
5141
different registers; GCC knows no reason not to do so.  For example, the
5142
compiler might find a copy of the value of @code{foo} in one register and
5143
use it for operand 1, but generate the output operand 0 in a different
5144
register (copying it afterward to @code{foo}'s own address).  Of course,
5145
since the register for operand 1 is not even mentioned in the assembler
5146
code, the result will not work, but GCC can't tell that.
5147
 
5148
As of GCC version 3.1, one may write @code{[@var{name}]} instead of
5149
the operand number for a matching constraint.  For example:
5150
 
5151
@smallexample
5152
asm ("cmoveq %1,%2,%[result]"
5153
     : [result] "=r"(result)
5154
     : "r" (test), "r"(new), "[result]"(old));
5155
@end smallexample
5156
 
5157
Sometimes you need to make an @code{asm} operand be a specific register,
5158
but there's no matching constraint letter for that register @emph{by
5159
itself}.  To force the operand into that register, use a local variable
5160
for the operand and specify the register in the variable declaration.
5161
@xref{Explicit Reg Vars}.  Then for the @code{asm} operand, use any
5162
register constraint letter that matches the register:
5163
 
5164
@smallexample
5165
register int *p1 asm ("r0") = @dots{};
5166
register int *p2 asm ("r1") = @dots{};
5167
register int *result asm ("r0");
5168
asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
5169
@end smallexample
5170
 
5171
@anchor{Example of asm with clobbered asm reg}
5172
In the above example, beware that a register that is call-clobbered by
5173
the target ABI will be overwritten by any function call in the
5174
assignment, including library calls for arithmetic operators.
5175
Also a register may be clobbered when generating some operations,
5176
like variable shift, memory copy or memory move on x86.
5177
Assuming it is a call-clobbered register, this may happen to @code{r0}
5178
above by the assignment to @code{p2}.  If you have to use such a
5179
register, use temporary variables for expressions between the register
5180
assignment and use:
5181
 
5182
@smallexample
5183
int t1 = @dots{};
5184
register int *p1 asm ("r0") = @dots{};
5185
register int *p2 asm ("r1") = t1;
5186
register int *result asm ("r0");
5187
asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
5188
@end smallexample
5189
 
5190
Some instructions clobber specific hard registers.  To describe this,
5191
write a third colon after the input operands, followed by the names of
5192
the clobbered hard registers (given as strings).  Here is a realistic
5193
example for the VAX:
5194
 
5195
@smallexample
5196
asm volatile ("movc3 %0,%1,%2"
5197
              : /* @r{no outputs} */
5198
              : "g" (from), "g" (to), "g" (count)
5199
              : "r0", "r1", "r2", "r3", "r4", "r5");
5200
@end smallexample
5201
 
5202
You may not write a clobber description in a way that overlaps with an
5203
input or output operand.  For example, you may not have an operand
5204
describing a register class with one member if you mention that register
5205
in the clobber list.  Variables declared to live in specific registers
5206
(@pxref{Explicit Reg Vars}), and used as asm input or output operands must
5207
have no part mentioned in the clobber description.
5208
There is no way for you to specify that an input
5209
operand is modified without also specifying it as an output
5210
operand.  Note that if all the output operands you specify are for this
5211
purpose (and hence unused), you will then also need to specify
5212
@code{volatile} for the @code{asm} construct, as described below, to
5213
prevent GCC from deleting the @code{asm} statement as unused.
5214
 
5215
If you refer to a particular hardware register from the assembler code,
5216
you will probably have to list the register after the third colon to
5217
tell the compiler the register's value is modified.  In some assemblers,
5218
the register names begin with @samp{%}; to produce one @samp{%} in the
5219
assembler code, you must write @samp{%%} in the input.
5220
 
5221
If your assembler instruction can alter the condition code register, add
5222
@samp{cc} to the list of clobbered registers.  GCC on some machines
5223
represents the condition codes as a specific hardware register;
5224
@samp{cc} serves to name this register.  On other machines, the
5225
condition code is handled differently, and specifying @samp{cc} has no
5226
effect.  But it is valid no matter what the machine.
5227
 
5228
If your assembler instructions access memory in an unpredictable
5229
fashion, add @samp{memory} to the list of clobbered registers.  This
5230
will cause GCC to not keep memory values cached in registers across the
5231
assembler instruction and not optimize stores or loads to that memory.
5232
You will also want to add the @code{volatile} keyword if the memory
5233
affected is not listed in the inputs or outputs of the @code{asm}, as
5234
the @samp{memory} clobber does not count as a side-effect of the
5235
@code{asm}.  If you know how large the accessed memory is, you can add
5236
it as input or output but if this is not known, you should add
5237
@samp{memory}.  As an example, if you access ten bytes of a string, you
5238
can use a memory input like:
5239
 
5240
@smallexample
5241
@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
5242
@end smallexample
5243
 
5244
Note that in the following example the memory input is necessary,
5245
otherwise GCC might optimize the store to @code{x} away:
5246
@smallexample
5247
int foo ()
5248
@{
5249
  int x = 42;
5250
  int *y = &x;
5251
  int result;
5252
  asm ("magic stuff accessing an 'int' pointed to by '%1'"
5253
        "=&d" (r) : "a" (y), "m" (*y));
5254
  return result;
5255
@}
5256
@end smallexample
5257
 
5258
You can put multiple assembler instructions together in a single
5259
@code{asm} template, separated by the characters normally used in assembly
5260
code for the system.  A combination that works in most places is a newline
5261
to break the line, plus a tab character to move to the instruction field
5262
(written as @samp{\n\t}).  Sometimes semicolons can be used, if the
5263
assembler allows semicolons as a line-breaking character.  Note that some
5264
assembler dialects use semicolons to start a comment.
5265
The input operands are guaranteed not to use any of the clobbered
5266
registers, and neither will the output operands' addresses, so you can
5267
read and write the clobbered registers as many times as you like.  Here
5268
is an example of multiple instructions in a template; it assumes the
5269
subroutine @code{_foo} accepts arguments in registers 9 and 10:
5270
 
5271
@smallexample
5272
asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
5273
     : /* no outputs */
5274
     : "g" (from), "g" (to)
5275
     : "r9", "r10");
5276
@end smallexample
5277
 
5278
Unless an output operand has the @samp{&} constraint modifier, GCC
5279
may allocate it in the same register as an unrelated input operand, on
5280
the assumption the inputs are consumed before the outputs are produced.
5281
This assumption may be false if the assembler code actually consists of
5282
more than one instruction.  In such a case, use @samp{&} for each output
5283
operand that may not overlap an input.  @xref{Modifiers}.
5284
 
5285
If you want to test the condition code produced by an assembler
5286
instruction, you must include a branch and a label in the @code{asm}
5287
construct, as follows:
5288
 
5289
@smallexample
5290
asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
5291
     : "g" (result)
5292
     : "g" (input));
5293
@end smallexample
5294
 
5295
@noindent
5296
This assumes your assembler supports local labels, as the GNU assembler
5297
and most Unix assemblers do.
5298
 
5299
Speaking of labels, jumps from one @code{asm} to another are not
5300
supported.  The compiler's optimizers do not know about these jumps, and
5301
therefore they cannot take account of them when deciding how to
5302
optimize.  @xref{Extended asm with goto}.
5303
 
5304
@cindex macros containing @code{asm}
5305
Usually the most convenient way to use these @code{asm} instructions is to
5306
encapsulate them in macros that look like functions.  For example,
5307
 
5308
@smallexample
5309
#define sin(x)       \
5310
(@{ double __value, __arg = (x);   \
5311
   asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
5312
   __value; @})
5313
@end smallexample
5314
 
5315
@noindent
5316
Here the variable @code{__arg} is used to make sure that the instruction
5317
operates on a proper @code{double} value, and to accept only those
5318
arguments @code{x} which can convert automatically to a @code{double}.
5319
 
5320
Another way to make sure the instruction operates on the correct data
5321
type is to use a cast in the @code{asm}.  This is different from using a
5322
variable @code{__arg} in that it converts more different types.  For
5323
example, if the desired type were @code{int}, casting the argument to
5324
@code{int} would accept a pointer with no complaint, while assigning the
5325
argument to an @code{int} variable named @code{__arg} would warn about
5326
using a pointer unless the caller explicitly casts it.
5327
 
5328
If an @code{asm} has output operands, GCC assumes for optimization
5329
purposes the instruction has no side effects except to change the output
5330
operands.  This does not mean instructions with a side effect cannot be
5331
used, but you must be careful, because the compiler may eliminate them
5332
if the output operands aren't used, or move them out of loops, or
5333
replace two with one if they constitute a common subexpression.  Also,
5334
if your instruction does have a side effect on a variable that otherwise
5335
appears not to change, the old value of the variable may be reused later
5336
if it happens to be found in a register.
5337
 
5338
You can prevent an @code{asm} instruction from being deleted
5339
by writing the keyword @code{volatile} after
5340
the @code{asm}.  For example:
5341
 
5342
@smallexample
5343
#define get_and_set_priority(new)              \
5344
(@{ int __old;                                  \
5345
   asm volatile ("get_and_set_priority %0, %1" \
5346
                 : "=g" (__old) : "g" (new));  \
5347
   __old; @})
5348
@end smallexample
5349
 
5350
@noindent
5351
The @code{volatile} keyword indicates that the instruction has
5352
important side-effects.  GCC will not delete a volatile @code{asm} if
5353
it is reachable.  (The instruction can still be deleted if GCC can
5354
prove that control-flow will never reach the location of the
5355
instruction.)  Note that even a volatile @code{asm} instruction
5356
can be moved relative to other code, including across jump
5357
instructions.  For example, on many targets there is a system
5358
register which can be set to control the rounding mode of
5359
floating point operations.  You might try
5360
setting it with a volatile @code{asm}, like this PowerPC example:
5361
 
5362
@smallexample
5363
       asm volatile("mtfsf 255,%0" : : "f" (fpenv));
5364
       sum = x + y;
5365
@end smallexample
5366
 
5367
@noindent
5368
This will not work reliably, as the compiler may move the addition back
5369
before the volatile @code{asm}.  To make it work you need to add an
5370
artificial dependency to the @code{asm} referencing a variable in the code
5371
you don't want moved, for example:
5372
 
5373
@smallexample
5374
    asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
5375
    sum = x + y;
5376
@end smallexample
5377
 
5378
Similarly, you can't expect a
5379
sequence of volatile @code{asm} instructions to remain perfectly
5380
consecutive.  If you want consecutive output, use a single @code{asm}.
5381
Also, GCC will perform some optimizations across a volatile @code{asm}
5382
instruction; GCC does not ``forget everything'' when it encounters
5383
a volatile @code{asm} instruction the way some other compilers do.
5384
 
5385
An @code{asm} instruction without any output operands will be treated
5386
identically to a volatile @code{asm} instruction.
5387
 
5388
It is a natural idea to look for a way to give access to the condition
5389
code left by the assembler instruction.  However, when we attempted to
5390
implement this, we found no way to make it work reliably.  The problem
5391
is that output operands might need reloading, which would result in
5392
additional following ``store'' instructions.  On most machines, these
5393
instructions would alter the condition code before there was time to
5394
test it.  This problem doesn't arise for ordinary ``test'' and
5395
``compare'' instructions because they don't have any output operands.
5396
 
5397
For reasons similar to those described above, it is not possible to give
5398
an assembler instruction access to the condition code left by previous
5399
instructions.
5400
 
5401
@anchor{Extended asm with goto}
5402
As of GCC version 4.5, @code{asm goto} may be used to have the assembly
5403
jump to one or more C labels.  In this form, a fifth section after the
5404
clobber list contains a list of all C labels to which the assembly may jump.
5405
Each label operand is implicitly self-named.  The @code{asm} is also assumed
5406
to fall through to the next statement.
5407
 
5408
This form of @code{asm} is restricted to not have outputs.  This is due
5409
to a internal restriction in the compiler that control transfer instructions
5410
cannot have outputs.  This restriction on @code{asm goto} may be lifted
5411
in some future version of the compiler.  In the mean time, @code{asm goto}
5412
may include a memory clobber, and so leave outputs in memory.
5413
 
5414
@smallexample
5415
int frob(int x)
5416
@{
5417
  int y;
5418
  asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
5419
            : : "r"(x), "r"(&y) : "r5", "memory" : error);
5420
  return y;
5421
 error:
5422
  return -1;
5423
@}
5424
@end smallexample
5425
 
5426
In this (inefficient) example, the @code{frob} instruction sets the
5427
carry bit to indicate an error.  The @code{jc} instruction detects
5428
this and branches to the @code{error} label.  Finally, the output
5429
of the @code{frob} instruction (@code{%r5}) is stored into the memory
5430
for variable @code{y}, which is later read by the @code{return} statement.
5431
 
5432
@smallexample
5433
void doit(void)
5434
@{
5435
  int i = 0;
5436
  asm goto ("mfsr %%r1, 123; jmp %%r1;"
5437
            ".pushsection doit_table;"
5438
            ".long %l0, %l1, %l2, %l3;"
5439
            ".popsection"
5440
            : : : "r1" : label1, label2, label3, label4);
5441
  __builtin_unreachable ();
5442
 
5443
 label1:
5444
  f1();
5445
  return;
5446
 label2:
5447
  f2();
5448
  return;
5449
 label3:
5450
  i = 1;
5451
 label4:
5452
  f3(i);
5453
@}
5454
@end smallexample
5455
 
5456
In this (also inefficient) example, the @code{mfsr} instruction reads
5457
an address from some out-of-band machine register, and the following
5458
@code{jmp} instruction branches to that address.  The address read by
5459
the @code{mfsr} instruction is assumed to have been previously set via
5460
some application-specific mechanism to be one of the four values stored
5461
in the @code{doit_table} section.  Finally, the @code{asm} is followed
5462
by a call to @code{__builtin_unreachable} to indicate that the @code{asm}
5463
does not in fact fall through.
5464
 
5465
@smallexample
5466
#define TRACE1(NUM)                         \
5467
  do @{                                      \
5468
    asm goto ("0: nop;"                     \
5469
              ".pushsection trace_table;"   \
5470
              ".long 0b, %l0;"              \
5471
              ".popsection"                 \
5472
              : : : : trace#NUM);           \
5473
    if (0) @{ trace#NUM: trace(); @}          \
5474
  @} while (0)
5475
#define TRACE  TRACE1(__COUNTER__)
5476
@end smallexample
5477
 
5478
In this example (which in fact inspired the @code{asm goto} feature)
5479
we want on rare occasions to call the @code{trace} function; on other
5480
occasions we'd like to keep the overhead to the absolute minimum.
5481
The normal code path consists of a single @code{nop} instruction.
5482
However, we record the address of this @code{nop} together with the
5483
address of a label that calls the @code{trace} function.  This allows
5484
the @code{nop} instruction to be patched at runtime to be an
5485
unconditional branch to the stored label.  It is assumed that an
5486
optimizing compiler will move the labeled block out of line, to
5487
optimize the fall through path from the @code{asm}.
5488
 
5489
If you are writing a header file that should be includable in ISO C
5490
programs, write @code{__asm__} instead of @code{asm}.  @xref{Alternate
5491
Keywords}.
5492
 
5493
@subsection Size of an @code{asm}
5494
 
5495
Some targets require that GCC track the size of each instruction used in
5496
order to generate correct code.  Because the final length of an
5497
@code{asm} is only known by the assembler, GCC must make an estimate as
5498
to how big it will be.  The estimate is formed by counting the number of
5499
statements in the pattern of the @code{asm} and multiplying that by the
5500
length of the longest instruction on that processor.  Statements in the
5501
@code{asm} are identified by newline characters and whatever statement
5502
separator characters are supported by the assembler; on most processors
5503
this is the `@code{;}' character.
5504
 
5505
Normally, GCC's estimate is perfectly adequate to ensure that correct
5506
code is generated, but it is possible to confuse the compiler if you use
5507
pseudo instructions or assembler macros that expand into multiple real
5508
instructions or if you use assembler directives that expand to more
5509
space in the object file than would be needed for a single instruction.
5510
If this happens then the assembler will produce a diagnostic saying that
5511
a label is unreachable.
5512
 
5513
@subsection i386 floating point asm operands
5514
 
5515
There are several rules on the usage of stack-like regs in
5516
asm_operands insns.  These rules apply only to the operands that are
5517
stack-like regs:
5518
 
5519
@enumerate
5520
@item
5521
Given a set of input regs that die in an asm_operands, it is
5522
necessary to know which are implicitly popped by the asm, and
5523
which must be explicitly popped by gcc.
5524
 
5525
An input reg that is implicitly popped by the asm must be
5526
explicitly clobbered, unless it is constrained to match an
5527
output operand.
5528
 
5529
@item
5530
For any input reg that is implicitly popped by an asm, it is
5531
necessary to know how to adjust the stack to compensate for the pop.
5532
If any non-popped input is closer to the top of the reg-stack than
5533
the implicitly popped reg, it would not be possible to know what the
5534
stack looked like---it's not clear how the rest of the stack ``slides
5535
up''.
5536
 
5537
All implicitly popped input regs must be closer to the top of
5538
the reg-stack than any input that is not implicitly popped.
5539
 
5540
It is possible that if an input dies in an insn, reload might
5541
use the input reg for an output reload.  Consider this example:
5542
 
5543
@smallexample
5544
asm ("foo" : "=t" (a) : "f" (b));
5545
@end smallexample
5546
 
5547
This asm says that input B is not popped by the asm, and that
5548
the asm pushes a result onto the reg-stack, i.e., the stack is one
5549
deeper after the asm than it was before.  But, it is possible that
5550
reload will think that it can use the same reg for both the input and
5551
the output, if input B dies in this insn.
5552
 
5553
If any input operand uses the @code{f} constraint, all output reg
5554
constraints must use the @code{&} earlyclobber.
5555
 
5556
The asm above would be written as
5557
 
5558
@smallexample
5559
asm ("foo" : "=&t" (a) : "f" (b));
5560
@end smallexample
5561
 
5562
@item
5563
Some operands need to be in particular places on the stack.  All
5564
output operands fall in this category---there is no other way to
5565
know which regs the outputs appear in unless the user indicates
5566
this in the constraints.
5567
 
5568
Output operands must specifically indicate which reg an output
5569
appears in after an asm.  @code{=f} is not allowed: the operand
5570
constraints must select a class with a single reg.
5571
 
5572
@item
5573
Output operands may not be ``inserted'' between existing stack regs.
5574
Since no 387 opcode uses a read/write operand, all output operands
5575
are dead before the asm_operands, and are pushed by the asm_operands.
5576
It makes no sense to push anywhere but the top of the reg-stack.
5577
 
5578
Output operands must start at the top of the reg-stack: output
5579
operands may not ``skip'' a reg.
5580
 
5581
@item
5582
Some asm statements may need extra stack space for internal
5583
calculations.  This can be guaranteed by clobbering stack registers
5584
unrelated to the inputs and outputs.
5585
 
5586
@end enumerate
5587
 
5588
Here are a couple of reasonable asms to want to write.  This asm
5589
takes one input, which is internally popped, and produces two outputs.
5590
 
5591
@smallexample
5592
asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
5593
@end smallexample
5594
 
5595
This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode,
5596
and replaces them with one output.  The user must code the @code{st(1)}
5597
clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs.
5598
 
5599
@smallexample
5600
asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
5601
@end smallexample
5602
 
5603
@include md.texi
5604
 
5605
@node Asm Labels
5606
@section Controlling Names Used in Assembler Code
5607
@cindex assembler names for identifiers
5608
@cindex names used in assembler code
5609
@cindex identifiers, names in assembler code
5610
 
5611
You can specify the name to be used in the assembler code for a C
5612
function or variable by writing the @code{asm} (or @code{__asm__})
5613
keyword after the declarator as follows:
5614
 
5615
@smallexample
5616
int foo asm ("myfoo") = 2;
5617
@end smallexample
5618
 
5619
@noindent
5620
This specifies that the name to be used for the variable @code{foo} in
5621
the assembler code should be @samp{myfoo} rather than the usual
5622
@samp{_foo}.
5623
 
5624
On systems where an underscore is normally prepended to the name of a C
5625
function or variable, this feature allows you to define names for the
5626
linker that do not start with an underscore.
5627
 
5628
It does not make sense to use this feature with a non-static local
5629
variable since such variables do not have assembler names.  If you are
5630
trying to put the variable in a particular register, see @ref{Explicit
5631
Reg Vars}.  GCC presently accepts such code with a warning, but will
5632
probably be changed to issue an error, rather than a warning, in the
5633
future.
5634
 
5635
You cannot use @code{asm} in this way in a function @emph{definition}; but
5636
you can get the same effect by writing a declaration for the function
5637
before its definition and putting @code{asm} there, like this:
5638
 
5639
@smallexample
5640
extern func () asm ("FUNC");
5641
 
5642
func (x, y)
5643
     int x, y;
5644
/* @r{@dots{}} */
5645
@end smallexample
5646
 
5647
It is up to you to make sure that the assembler names you choose do not
5648
conflict with any other assembler symbols.  Also, you must not use a
5649
register name; that would produce completely invalid assembler code.  GCC
5650
does not as yet have the ability to store static variables in registers.
5651
Perhaps that will be added.
5652
 
5653
@node Explicit Reg Vars
5654
@section Variables in Specified Registers
5655
@cindex explicit register variables
5656
@cindex variables in specified registers
5657
@cindex specified registers
5658
@cindex registers, global allocation
5659
 
5660
GNU C allows you to put a few global variables into specified hardware
5661
registers.  You can also specify the register in which an ordinary
5662
register variable should be allocated.
5663
 
5664
@itemize @bullet
5665
@item
5666
Global register variables reserve registers throughout the program.
5667
This may be useful in programs such as programming language
5668
interpreters which have a couple of global variables that are accessed
5669
very often.
5670
 
5671
@item
5672
Local register variables in specific registers do not reserve the
5673
registers, except at the point where they are used as input or output
5674
operands in an @code{asm} statement and the @code{asm} statement itself is
5675
not deleted.  The compiler's data flow analysis is capable of determining
5676
where the specified registers contain live values, and where they are
5677
available for other uses.  Stores into local register variables may be deleted
5678
when they appear to be dead according to dataflow analysis.  References
5679
to local register variables may be deleted or moved or simplified.
5680
 
5681
These local variables are sometimes convenient for use with the extended
5682
@code{asm} feature (@pxref{Extended Asm}), if you want to write one
5683
output of the assembler instruction directly into a particular register.
5684
(This will work provided the register you specify fits the constraints
5685
specified for that operand in the @code{asm}.)
5686
@end itemize
5687
 
5688
@menu
5689
* Global Reg Vars::
5690
* Local Reg Vars::
5691
@end menu
5692
 
5693
@node Global Reg Vars
5694
@subsection Defining Global Register Variables
5695
@cindex global register variables
5696
@cindex registers, global variables in
5697
 
5698
You can define a global register variable in GNU C like this:
5699
 
5700
@smallexample
5701
register int *foo asm ("a5");
5702
@end smallexample
5703
 
5704
@noindent
5705
Here @code{a5} is the name of the register which should be used.  Choose a
5706
register which is normally saved and restored by function calls on your
5707
machine, so that library routines will not clobber it.
5708
 
5709
Naturally the register name is cpu-dependent, so you would need to
5710
conditionalize your program according to cpu type.  The register
5711
@code{a5} would be a good choice on a 68000 for a variable of pointer
5712
type.  On machines with register windows, be sure to choose a ``global''
5713
register that is not affected magically by the function call mechanism.
5714
 
5715
In addition, operating systems on one type of cpu may differ in how they
5716
name the registers; then you would need additional conditionals.  For
5717
example, some 68000 operating systems call this register @code{%a5}.
5718
 
5719
Eventually there may be a way of asking the compiler to choose a register
5720
automatically, but first we need to figure out how it should choose and
5721
how to enable you to guide the choice.  No solution is evident.
5722
 
5723
Defining a global register variable in a certain register reserves that
5724
register entirely for this use, at least within the current compilation.
5725
The register will not be allocated for any other purpose in the functions
5726
in the current compilation.  The register will not be saved and restored by
5727
these functions.  Stores into this register are never deleted even if they
5728
would appear to be dead, but references may be deleted or moved or
5729
simplified.
5730
 
5731
It is not safe to access the global register variables from signal
5732
handlers, or from more than one thread of control, because the system
5733
library routines may temporarily use the register for other things (unless
5734
you recompile them specially for the task at hand).
5735
 
5736
@cindex @code{qsort}, and global register variables
5737
It is not safe for one function that uses a global register variable to
5738
call another such function @code{foo} by way of a third function
5739
@code{lose} that was compiled without knowledge of this variable (i.e.@: in a
5740
different source file in which the variable wasn't declared).  This is
5741
because @code{lose} might save the register and put some other value there.
5742
For example, you can't expect a global register variable to be available in
5743
the comparison-function that you pass to @code{qsort}, since @code{qsort}
5744
might have put something else in that register.  (If you are prepared to
5745
recompile @code{qsort} with the same global register variable, you can
5746
solve this problem.)
5747
 
5748
If you want to recompile @code{qsort} or other source files which do not
5749
actually use your global register variable, so that they will not use that
5750
register for any other purpose, then it suffices to specify the compiler
5751
option @option{-ffixed-@var{reg}}.  You need not actually add a global
5752
register declaration to their source code.
5753
 
5754
A function which can alter the value of a global register variable cannot
5755
safely be called from a function compiled without this variable, because it
5756
could clobber the value the caller expects to find there on return.
5757
Therefore, the function which is the entry point into the part of the
5758
program that uses the global register variable must explicitly save and
5759
restore the value which belongs to its caller.
5760
 
5761
@cindex register variable after @code{longjmp}
5762
@cindex global register after @code{longjmp}
5763
@cindex value after @code{longjmp}
5764
@findex longjmp
5765
@findex setjmp
5766
On most machines, @code{longjmp} will restore to each global register
5767
variable the value it had at the time of the @code{setjmp}.  On some
5768
machines, however, @code{longjmp} will not change the value of global
5769
register variables.  To be portable, the function that called @code{setjmp}
5770
should make other arrangements to save the values of the global register
5771
variables, and to restore them in a @code{longjmp}.  This way, the same
5772
thing will happen regardless of what @code{longjmp} does.
5773
 
5774
All global register variable declarations must precede all function
5775
definitions.  If such a declaration could appear after function
5776
definitions, the declaration would be too late to prevent the register from
5777
being used for other purposes in the preceding functions.
5778
 
5779
Global register variables may not have initial values, because an
5780
executable file has no means to supply initial contents for a register.
5781
 
5782
On the SPARC, there are reports that g3 @dots{} g7 are suitable
5783
registers, but certain library functions, such as @code{getwd}, as well
5784
as the subroutines for division and remainder, modify g3 and g4.  g1 and
5785
g2 are local temporaries.
5786
 
5787
On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
5788
Of course, it will not do to use more than a few of those.
5789
 
5790
@node Local Reg Vars
5791
@subsection Specifying Registers for Local Variables
5792
@cindex local variables, specifying registers
5793
@cindex specifying registers for local variables
5794
@cindex registers for local variables
5795
 
5796
You can define a local register variable with a specified register
5797
like this:
5798
 
5799
@smallexample
5800
register int *foo asm ("a5");
5801
@end smallexample
5802
 
5803
@noindent
5804
Here @code{a5} is the name of the register which should be used.  Note
5805
that this is the same syntax used for defining global register
5806
variables, but for a local variable it would appear within a function.
5807
 
5808
Naturally the register name is cpu-dependent, but this is not a
5809
problem, since specific registers are most often useful with explicit
5810
assembler instructions (@pxref{Extended Asm}).  Both of these things
5811
generally require that you conditionalize your program according to
5812
cpu type.
5813
 
5814
In addition, operating systems on one type of cpu may differ in how they
5815
name the registers; then you would need additional conditionals.  For
5816
example, some 68000 operating systems call this register @code{%a5}.
5817
 
5818
Defining such a register variable does not reserve the register; it
5819
remains available for other uses in places where flow control determines
5820
the variable's value is not live.
5821
 
5822
This option does not guarantee that GCC will generate code that has
5823
this variable in the register you specify at all times.  You may not
5824
code an explicit reference to this register in the @emph{assembler
5825
instruction template} part of an @code{asm} statement and assume it will
5826
always refer to this variable.  However, using the variable as an
5827
@code{asm} @emph{operand} guarantees that the specified register is used
5828
for the operand.
5829
 
5830
Stores into local register variables may be deleted when they appear to be dead
5831
according to dataflow analysis.  References to local register variables may
5832
be deleted or moved or simplified.
5833
 
5834
As for global register variables, it's recommended that you choose a
5835
register which is normally saved and restored by function calls on
5836
your machine, so that library routines will not clobber it.  A common
5837
pitfall is to initialize multiple call-clobbered registers with
5838
arbitrary expressions, where a function call or library call for an
5839
arithmetic operator will overwrite a register value from a previous
5840
assignment, for example @code{r0} below:
5841
@smallexample
5842
register int *p1 asm ("r0") = @dots{};
5843
register int *p2 asm ("r1") = @dots{};
5844
@end smallexample
5845
In those cases, a solution is to use a temporary variable for
5846
each arbitrary expression.   @xref{Example of asm with clobbered asm reg}.
5847
 
5848
@node Alternate Keywords
5849
@section Alternate Keywords
5850
@cindex alternate keywords
5851
@cindex keywords, alternate
5852
 
5853
@option{-ansi} and the various @option{-std} options disable certain
5854
keywords.  This causes trouble when you want to use GNU C extensions, or
5855
a general-purpose header file that should be usable by all programs,
5856
including ISO C programs.  The keywords @code{asm}, @code{typeof} and
5857
@code{inline} are not available in programs compiled with
5858
@option{-ansi} or @option{-std} (although @code{inline} can be used in a
5859
program compiled with @option{-std=c99}).  The ISO C99 keyword
5860
@code{restrict} is only available when @option{-std=gnu99} (which will
5861
eventually be the default) or @option{-std=c99} (or the equivalent
5862
@option{-std=iso9899:1999}) is used.
5863
 
5864
The way to solve these problems is to put @samp{__} at the beginning and
5865
end of each problematical keyword.  For example, use @code{__asm__}
5866
instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
5867
 
5868
Other C compilers won't accept these alternative keywords; if you want to
5869
compile with another compiler, you can define the alternate keywords as
5870
macros to replace them with the customary keywords.  It looks like this:
5871
 
5872
@smallexample
5873
#ifndef __GNUC__
5874
#define __asm__ asm
5875
#endif
5876
@end smallexample
5877
 
5878
@findex __extension__
5879
@opindex pedantic
5880
@option{-pedantic} and other options cause warnings for many GNU C extensions.
5881
You can
5882
prevent such warnings within one expression by writing
5883
@code{__extension__} before the expression.  @code{__extension__} has no
5884
effect aside from this.
5885
 
5886
@node Incomplete Enums
5887
@section Incomplete @code{enum} Types
5888
 
5889
You can define an @code{enum} tag without specifying its possible values.
5890
This results in an incomplete type, much like what you get if you write
5891
@code{struct foo} without describing the elements.  A later declaration
5892
which does specify the possible values completes the type.
5893
 
5894
You can't allocate variables or storage using the type while it is
5895
incomplete.  However, you can work with pointers to that type.
5896
 
5897
This extension may not be very useful, but it makes the handling of
5898
@code{enum} more consistent with the way @code{struct} and @code{union}
5899
are handled.
5900
 
5901
This extension is not supported by GNU C++.
5902
 
5903
@node Function Names
5904
@section Function Names as Strings
5905
@cindex @code{__func__} identifier
5906
@cindex @code{__FUNCTION__} identifier
5907
@cindex @code{__PRETTY_FUNCTION__} identifier
5908
 
5909
GCC provides three magic variables which hold the name of the current
5910
function, as a string.  The first of these is @code{__func__}, which
5911
is part of the C99 standard:
5912
 
5913
The identifier @code{__func__} is implicitly declared by the translator
5914
as if, immediately following the opening brace of each function
5915
definition, the declaration
5916
 
5917
@smallexample
5918
static const char __func__[] = "function-name";
5919
@end smallexample
5920
 
5921
@noindent
5922
appeared, where function-name is the name of the lexically-enclosing
5923
function.  This name is the unadorned name of the function.
5924
 
5925
@code{__FUNCTION__} is another name for @code{__func__}.  Older
5926
versions of GCC recognize only this name.  However, it is not
5927
standardized.  For maximum portability, we recommend you use
5928
@code{__func__}, but provide a fallback definition with the
5929
preprocessor:
5930
 
5931
@smallexample
5932
#if __STDC_VERSION__ < 199901L
5933
# if __GNUC__ >= 2
5934
#  define __func__ __FUNCTION__
5935
# else
5936
#  define __func__ "<unknown>"
5937
# endif
5938
#endif
5939
@end smallexample
5940
 
5941
In C, @code{__PRETTY_FUNCTION__} is yet another name for
5942
@code{__func__}.  However, in C++, @code{__PRETTY_FUNCTION__} contains
5943
the type signature of the function as well as its bare name.  For
5944
example, this program:
5945
 
5946
@smallexample
5947
extern "C" @{
5948
extern int printf (char *, ...);
5949
@}
5950
 
5951
class a @{
5952
 public:
5953
  void sub (int i)
5954
    @{
5955
      printf ("__FUNCTION__ = %s\n", __FUNCTION__);
5956
      printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
5957
    @}
5958
@};
5959
 
5960
int
5961
main (void)
5962
@{
5963
  a ax;
5964
  ax.sub (0);
5965
  return 0;
5966
@}
5967
@end smallexample
5968
 
5969
@noindent
5970
gives this output:
5971
 
5972
@smallexample
5973
__FUNCTION__ = sub
5974
__PRETTY_FUNCTION__ = void a::sub(int)
5975
@end smallexample
5976
 
5977
These identifiers are not preprocessor macros.  In GCC 3.3 and
5978
earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__}
5979
were treated as string literals; they could be used to initialize
5980
@code{char} arrays, and they could be concatenated with other string
5981
literals.  GCC 3.4 and later treat them as variables, like
5982
@code{__func__}.  In C++, @code{__FUNCTION__} and
5983
@code{__PRETTY_FUNCTION__} have always been variables.
5984
 
5985
@node Return Address
5986
@section Getting the Return or Frame Address of a Function
5987
 
5988
These functions may be used to get information about the callers of a
5989
function.
5990
 
5991
@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
5992
This function returns the return address of the current function, or of
5993
one of its callers.  The @var{level} argument is number of frames to
5994
scan up the call stack.  A value of @code{0} yields the return address
5995
of the current function, a value of @code{1} yields the return address
5996
of the caller of the current function, and so forth.  When inlining
5997
the expected behavior is that the function will return the address of
5998
the function that will be returned to.  To work around this behavior use
5999
the @code{noinline} function attribute.
6000
 
6001
The @var{level} argument must be a constant integer.
6002
 
6003
On some machines it may be impossible to determine the return address of
6004
any function other than the current one; in such cases, or when the top
6005
of the stack has been reached, this function will return @code{0} or a
6006
random value.  In addition, @code{__builtin_frame_address} may be used
6007
to determine if the top of the stack has been reached.
6008
 
6009
Additional post-processing of the returned value may be needed, see
6010
@code{__builtin_extract_return_address}.
6011
 
6012
This function should only be used with a nonzero argument for debugging
6013
purposes.
6014
@end deftypefn
6015
 
6016
@deftypefn {Built-in Function} {void *} __builtin_extract_return_address (void *@var{addr})
6017
The address as returned by @code{__builtin_return_address} may have to be fed
6018
through this function to get the actual encoded address.  For example, on the
6019
31-bit S/390 platform the highest bit has to be masked out, or on SPARC
6020
platforms an offset has to be added for the true next instruction to be
6021
executed.
6022
 
6023
If no fixup is needed, this function simply passes through @var{addr}.
6024
@end deftypefn
6025
 
6026
@deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr})
6027
This function does the reverse of @code{__builtin_extract_return_address}.
6028
@end deftypefn
6029
 
6030
@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
6031
This function is similar to @code{__builtin_return_address}, but it
6032
returns the address of the function frame rather than the return address
6033
of the function.  Calling @code{__builtin_frame_address} with a value of
6034
@code{0} yields the frame address of the current function, a value of
6035
@code{1} yields the frame address of the caller of the current function,
6036
and so forth.
6037
 
6038
The frame is the area on the stack which holds local variables and saved
6039
registers.  The frame address is normally the address of the first word
6040
pushed on to the stack by the function.  However, the exact definition
6041
depends upon the processor and the calling convention.  If the processor
6042
has a dedicated frame pointer register, and the function has a frame,
6043
then @code{__builtin_frame_address} will return the value of the frame
6044
pointer register.
6045
 
6046
On some machines it may be impossible to determine the frame address of
6047
any function other than the current one; in such cases, or when the top
6048
of the stack has been reached, this function will return @code{0} if
6049
the first frame pointer is properly initialized by the startup code.
6050
 
6051
This function should only be used with a nonzero argument for debugging
6052
purposes.
6053
@end deftypefn
6054
 
6055
@node Vector Extensions
6056
@section Using vector instructions through built-in functions
6057
 
6058
On some targets, the instruction set contains SIMD vector instructions that
6059
operate on multiple values contained in one large register at the same time.
6060
For example, on the i386 the MMX, 3DNow!@: and SSE extensions can be used
6061
this way.
6062
 
6063
The first step in using these extensions is to provide the necessary data
6064
types.  This should be done using an appropriate @code{typedef}:
6065
 
6066
@smallexample
6067
typedef int v4si __attribute__ ((vector_size (16)));
6068
@end smallexample
6069
 
6070
The @code{int} type specifies the base type, while the attribute specifies
6071
the vector size for the variable, measured in bytes.  For example, the
6072
declaration above causes the compiler to set the mode for the @code{v4si}
6073
type to be 16 bytes wide and divided into @code{int} sized units.  For
6074
a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
6075
corresponding mode of @code{foo} will be @acronym{V4SI}.
6076
 
6077
The @code{vector_size} attribute is only applicable to integral and
6078
float scalars, although arrays, pointers, and function return values
6079
are allowed in conjunction with this construct.
6080
 
6081
All the basic integer types can be used as base types, both as signed
6082
and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
6083
@code{long long}.  In addition, @code{float} and @code{double} can be
6084
used to build floating-point vector types.
6085
 
6086
Specifying a combination that is not valid for the current architecture
6087
will cause GCC to synthesize the instructions using a narrower mode.
6088
For example, if you specify a variable of type @code{V4SI} and your
6089
architecture does not allow for this specific SIMD type, GCC will
6090
produce code that uses 4 @code{SIs}.
6091
 
6092
The types defined in this manner can be used with a subset of normal C
6093
operations.  Currently, GCC will allow using the following operators
6094
on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
6095
 
6096
The operations behave like C++ @code{valarrays}.  Addition is defined as
6097
the addition of the corresponding elements of the operands.  For
6098
example, in the code below, each of the 4 elements in @var{a} will be
6099
added to the corresponding 4 elements in @var{b} and the resulting
6100
vector will be stored in @var{c}.
6101
 
6102
@smallexample
6103
typedef int v4si __attribute__ ((vector_size (16)));
6104
 
6105
v4si a, b, c;
6106
 
6107
c = a + b;
6108
@end smallexample
6109
 
6110
Subtraction, multiplication, division, and the logical operations
6111
operate in a similar manner.  Likewise, the result of using the unary
6112
minus or complement operators on a vector type is a vector whose
6113
elements are the negative or complemented values of the corresponding
6114
elements in the operand.
6115
 
6116
You can declare variables and use them in function calls and returns, as
6117
well as in assignments and some casts.  You can specify a vector type as
6118
a return type for a function.  Vector types can also be used as function
6119
arguments.  It is possible to cast from one vector type to another,
6120
provided they are of the same size (in fact, you can also cast vectors
6121
to and from other datatypes of the same size).
6122
 
6123
You cannot operate between vectors of different lengths or different
6124
signedness without a cast.
6125
 
6126
A port that supports hardware vector operations, usually provides a set
6127
of built-in functions that can be used to operate on vectors.  For
6128
example, a function to add two vectors and multiply the result by a
6129
third could look like this:
6130
 
6131
@smallexample
6132
v4si f (v4si a, v4si b, v4si c)
6133
@{
6134
  v4si tmp = __builtin_addv4si (a, b);
6135
  return __builtin_mulv4si (tmp, c);
6136
@}
6137
 
6138
@end smallexample
6139
 
6140
@node Offsetof
6141
@section Offsetof
6142
@findex __builtin_offsetof
6143
 
6144
GCC implements for both C and C++ a syntactic extension to implement
6145
the @code{offsetof} macro.
6146
 
6147
@smallexample
6148
primary:
6149
        "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
6150
 
6151
offsetof_member_designator:
6152
          @code{identifier}
6153
        | offsetof_member_designator "." @code{identifier}
6154
        | offsetof_member_designator "[" @code{expr} "]"
6155
@end smallexample
6156
 
6157
This extension is sufficient such that
6158
 
6159
@smallexample
6160
#define offsetof(@var{type}, @var{member})  __builtin_offsetof (@var{type}, @var{member})
6161
@end smallexample
6162
 
6163
is a suitable definition of the @code{offsetof} macro.  In C++, @var{type}
6164
may be dependent.  In either case, @var{member} may consist of a single
6165
identifier, or a sequence of member accesses and array references.
6166
 
6167
@node Atomic Builtins
6168
@section Built-in functions for atomic memory access
6169
 
6170
The following builtins are intended to be compatible with those described
6171
in the @cite{Intel Itanium Processor-specific Application Binary Interface},
6172
section 7.4.  As such, they depart from the normal GCC practice of using
6173
the ``__builtin_'' prefix, and further that they are overloaded such that
6174
they work on multiple types.
6175
 
6176
The definition given in the Intel documentation allows only for the use of
6177
the types @code{int}, @code{long}, @code{long long} as well as their unsigned
6178
counterparts.  GCC will allow any integral scalar or pointer type that is
6179
1, 2, 4 or 8 bytes in length.
6180
 
6181
Not all operations are supported by all target processors.  If a particular
6182
operation cannot be implemented on the target processor, a warning will be
6183
generated and a call an external function will be generated.  The external
6184
function will carry the same name as the builtin, with an additional suffix
6185
@samp{_@var{n}} where @var{n} is the size of the data type.
6186
 
6187
@c ??? Should we have a mechanism to suppress this warning?  This is almost
6188
@c useful for implementing the operation under the control of an external
6189
@c mutex.
6190
 
6191
In most cases, these builtins are considered a @dfn{full barrier}.  That is,
6192
no memory operand will be moved across the operation, either forward or
6193
backward.  Further, instructions will be issued as necessary to prevent the
6194
processor from speculating loads across the operation and from queuing stores
6195
after the operation.
6196
 
6197
All of the routines are described in the Intel documentation to take
6198
``an optional list of variables protected by the memory barrier''.  It's
6199
not clear what is meant by that; it could mean that @emph{only} the
6200
following variables are protected, or it could mean that these variables
6201
should in addition be protected.  At present GCC ignores this list and
6202
protects all variables which are globally accessible.  If in the future
6203
we make some use of this list, an empty list will continue to mean all
6204
globally accessible variables.
6205
 
6206
@table @code
6207
@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
6208
@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
6209
@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
6210
@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
6211
@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
6212
@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
6213
@findex __sync_fetch_and_add
6214
@findex __sync_fetch_and_sub
6215
@findex __sync_fetch_and_or
6216
@findex __sync_fetch_and_and
6217
@findex __sync_fetch_and_xor
6218
@findex __sync_fetch_and_nand
6219
These builtins perform the operation suggested by the name, and
6220
returns the value that had previously been in memory.  That is,
6221
 
6222
@smallexample
6223
@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
6224
@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @}   // nand
6225
@end smallexample
6226
 
6227
@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
6228
builtin as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
6229
 
6230
@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
6231
@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
6232
@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
6233
@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
6234
@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
6235
@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
6236
@findex __sync_add_and_fetch
6237
@findex __sync_sub_and_fetch
6238
@findex __sync_or_and_fetch
6239
@findex __sync_and_and_fetch
6240
@findex __sync_xor_and_fetch
6241
@findex __sync_nand_and_fetch
6242
These builtins perform the operation suggested by the name, and
6243
return the new value.  That is,
6244
 
6245
@smallexample
6246
@{ *ptr @var{op}= value; return *ptr; @}
6247
@{ *ptr = ~(*ptr & value); return *ptr; @}   // nand
6248
@end smallexample
6249
 
6250
@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
6251
builtin as @code{*ptr = ~(*ptr & value)} instead of
6252
@code{*ptr = ~*ptr & value}.
6253
 
6254
@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...)
6255
@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...)
6256
@findex __sync_bool_compare_and_swap
6257
@findex __sync_val_compare_and_swap
6258
These builtins perform an atomic compare and swap.  That is, if the current
6259
value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
6260
@code{*@var{ptr}}.
6261
 
6262
The ``bool'' version returns true if the comparison is successful and
6263
@var{newval} was written.  The ``val'' version returns the contents
6264
of @code{*@var{ptr}} before the operation.
6265
 
6266
@item __sync_synchronize (...)
6267
@findex __sync_synchronize
6268
This builtin issues a full memory barrier.
6269
 
6270
@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
6271
@findex __sync_lock_test_and_set
6272
This builtin, as described by Intel, is not a traditional test-and-set
6273
operation, but rather an atomic exchange operation.  It writes @var{value}
6274
into @code{*@var{ptr}}, and returns the previous contents of
6275
@code{*@var{ptr}}.
6276
 
6277
Many targets have only minimal support for such locks, and do not support
6278
a full exchange operation.  In this case, a target may support reduced
6279
functionality here by which the @emph{only} valid value to store is the
6280
immediate constant 1.  The exact value actually stored in @code{*@var{ptr}}
6281
is implementation defined.
6282
 
6283
This builtin is not a full barrier, but rather an @dfn{acquire barrier}.
6284
This means that references after the builtin cannot move to (or be
6285
speculated to) before the builtin, but previous memory stores may not
6286
be globally visible yet, and previous memory loads may not yet be
6287
satisfied.
6288
 
6289
@item void __sync_lock_release (@var{type} *ptr, ...)
6290
@findex __sync_lock_release
6291
This builtin releases the lock acquired by @code{__sync_lock_test_and_set}.
6292
Normally this means writing the constant 0 to @code{*@var{ptr}}.
6293
 
6294
This builtin is not a full barrier, but rather a @dfn{release barrier}.
6295
This means that all previous memory stores are globally visible, and all
6296
previous memory loads have been satisfied, but following memory reads
6297
are not prevented from being speculated to before the barrier.
6298
@end table
6299
 
6300
@node Object Size Checking
6301
@section Object Size Checking Builtins
6302
@findex __builtin_object_size
6303
@findex __builtin___memcpy_chk
6304
@findex __builtin___mempcpy_chk
6305
@findex __builtin___memmove_chk
6306
@findex __builtin___memset_chk
6307
@findex __builtin___strcpy_chk
6308
@findex __builtin___stpcpy_chk
6309
@findex __builtin___strncpy_chk
6310
@findex __builtin___strcat_chk
6311
@findex __builtin___strncat_chk
6312
@findex __builtin___sprintf_chk
6313
@findex __builtin___snprintf_chk
6314
@findex __builtin___vsprintf_chk
6315
@findex __builtin___vsnprintf_chk
6316
@findex __builtin___printf_chk
6317
@findex __builtin___vprintf_chk
6318
@findex __builtin___fprintf_chk
6319
@findex __builtin___vfprintf_chk
6320
 
6321
GCC implements a limited buffer overflow protection mechanism
6322
that can prevent some buffer overflow attacks.
6323
 
6324
@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type})
6325
is a built-in construct that returns a constant number of bytes from
6326
@var{ptr} to the end of the object @var{ptr} pointer points to
6327
(if known at compile time).  @code{__builtin_object_size} never evaluates
6328
its arguments for side-effects.  If there are any side-effects in them, it
6329
returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
6330
for @var{type} 2 or 3.  If there are multiple objects @var{ptr} can
6331
point to and all of them are known at compile time, the returned number
6332
is the maximum of remaining byte counts in those objects if @var{type} & 2 is
6333
 
6334
@var{ptr} points to at compile time, @code{__builtin_object_size} should
6335
return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
6336
for @var{type} 2 or 3.
6337
 
6338
@var{type} is an integer constant from 0 to 3.  If the least significant
6339
bit is clear, objects are whole variables, if it is set, a closest
6340
surrounding subobject is considered the object a pointer points to.
6341
The second bit determines if maximum or minimum of remaining bytes
6342
is computed.
6343
 
6344
@smallexample
6345
struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
6346
char *p = &var.buf1[1], *q = &var.b;
6347
 
6348
/* Here the object p points to is var.  */
6349
assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
6350
/* The subobject p points to is var.buf1.  */
6351
assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
6352
/* The object q points to is var.  */
6353
assert (__builtin_object_size (q, 0)
6354
        == (char *) (&var + 1) - (char *) &var.b);
6355
/* The subobject q points to is var.b.  */
6356
assert (__builtin_object_size (q, 1) == sizeof (var.b));
6357
@end smallexample
6358
@end deftypefn
6359
 
6360
There are built-in functions added for many common string operation
6361
functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
6362
built-in is provided.  This built-in has an additional last argument,
6363
which is the number of bytes remaining in object the @var{dest}
6364
argument points to or @code{(size_t) -1} if the size is not known.
6365
 
6366
The built-in functions are optimized into the normal string functions
6367
like @code{memcpy} if the last argument is @code{(size_t) -1} or if
6368
it is known at compile time that the destination object will not
6369
be overflown.  If the compiler can determine at compile time the
6370
object will be always overflown, it issues a warning.
6371
 
6372
The intended use can be e.g.
6373
 
6374
@smallexample
6375
#undef memcpy
6376
#define bos0(dest) __builtin_object_size (dest, 0)
6377
#define memcpy(dest, src, n) \
6378
  __builtin___memcpy_chk (dest, src, n, bos0 (dest))
6379
 
6380
char *volatile p;
6381
char buf[10];
6382
/* It is unknown what object p points to, so this is optimized
6383
   into plain memcpy - no checking is possible.  */
6384
memcpy (p, "abcde", n);
6385
/* Destination is known and length too.  It is known at compile
6386
   time there will be no overflow.  */
6387
memcpy (&buf[5], "abcde", 5);
6388
/* Destination is known, but the length is not known at compile time.
6389
   This will result in __memcpy_chk call that can check for overflow
6390
   at runtime.  */
6391
memcpy (&buf[5], "abcde", n);
6392
/* Destination is known and it is known at compile time there will
6393
   be overflow.  There will be a warning and __memcpy_chk call that
6394
   will abort the program at runtime.  */
6395
memcpy (&buf[6], "abcde", 5);
6396
@end smallexample
6397
 
6398
Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
6399
@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
6400
@code{strcat} and @code{strncat}.
6401
 
6402
There are also checking built-in functions for formatted output functions.
6403
@smallexample
6404
int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
6405
int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
6406
                              const char *fmt, ...);
6407
int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
6408
                              va_list ap);
6409
int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
6410
                               const char *fmt, va_list ap);
6411
@end smallexample
6412
 
6413
The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
6414
etc.@: functions and can contain implementation specific flags on what
6415
additional security measures the checking function might take, such as
6416
handling @code{%n} differently.
6417
 
6418
The @var{os} argument is the object size @var{s} points to, like in the
6419
other built-in functions.  There is a small difference in the behavior
6420
though, if @var{os} is @code{(size_t) -1}, the built-in functions are
6421
optimized into the non-checking functions only if @var{flag} is 0, otherwise
6422
the checking function is called with @var{os} argument set to
6423
@code{(size_t) -1}.
6424
 
6425
In addition to this, there are checking built-in functions
6426
@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
6427
@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
6428
These have just one additional argument, @var{flag}, right before
6429
format string @var{fmt}.  If the compiler is able to optimize them to
6430
@code{fputc} etc.@: functions, it will, otherwise the checking function
6431
should be called and the @var{flag} argument passed to it.
6432
 
6433
@node Other Builtins
6434
@section Other built-in functions provided by GCC
6435
@cindex built-in functions
6436
@findex __builtin_fpclassify
6437
@findex __builtin_isfinite
6438
@findex __builtin_isnormal
6439
@findex __builtin_isgreater
6440
@findex __builtin_isgreaterequal
6441
@findex __builtin_isinf_sign
6442
@findex __builtin_isless
6443
@findex __builtin_islessequal
6444
@findex __builtin_islessgreater
6445
@findex __builtin_isunordered
6446
@findex __builtin_powi
6447
@findex __builtin_powif
6448
@findex __builtin_powil
6449
@findex _Exit
6450
@findex _exit
6451
@findex abort
6452
@findex abs
6453
@findex acos
6454
@findex acosf
6455
@findex acosh
6456
@findex acoshf
6457
@findex acoshl
6458
@findex acosl
6459
@findex alloca
6460
@findex asin
6461
@findex asinf
6462
@findex asinh
6463
@findex asinhf
6464
@findex asinhl
6465
@findex asinl
6466
@findex atan
6467
@findex atan2
6468
@findex atan2f
6469
@findex atan2l
6470
@findex atanf
6471
@findex atanh
6472
@findex atanhf
6473
@findex atanhl
6474
@findex atanl
6475
@findex bcmp
6476
@findex bzero
6477
@findex cabs
6478
@findex cabsf
6479
@findex cabsl
6480
@findex cacos
6481
@findex cacosf
6482
@findex cacosh
6483
@findex cacoshf
6484
@findex cacoshl
6485
@findex cacosl
6486
@findex calloc
6487
@findex carg
6488
@findex cargf
6489
@findex cargl
6490
@findex casin
6491
@findex casinf
6492
@findex casinh
6493
@findex casinhf
6494
@findex casinhl
6495
@findex casinl
6496
@findex catan
6497
@findex catanf
6498
@findex catanh
6499
@findex catanhf
6500
@findex catanhl
6501
@findex catanl
6502
@findex cbrt
6503
@findex cbrtf
6504
@findex cbrtl
6505
@findex ccos
6506
@findex ccosf
6507
@findex ccosh
6508
@findex ccoshf
6509
@findex ccoshl
6510
@findex ccosl
6511
@findex ceil
6512
@findex ceilf
6513
@findex ceill
6514
@findex cexp
6515
@findex cexpf
6516
@findex cexpl
6517
@findex cimag
6518
@findex cimagf
6519
@findex cimagl
6520
@findex clog
6521
@findex clogf
6522
@findex clogl
6523
@findex conj
6524
@findex conjf
6525
@findex conjl
6526
@findex copysign
6527
@findex copysignf
6528
@findex copysignl
6529
@findex cos
6530
@findex cosf
6531
@findex cosh
6532
@findex coshf
6533
@findex coshl
6534
@findex cosl
6535
@findex cpow
6536
@findex cpowf
6537
@findex cpowl
6538
@findex cproj
6539
@findex cprojf
6540
@findex cprojl
6541
@findex creal
6542
@findex crealf
6543
@findex creall
6544
@findex csin
6545
@findex csinf
6546
@findex csinh
6547
@findex csinhf
6548
@findex csinhl
6549
@findex csinl
6550
@findex csqrt
6551
@findex csqrtf
6552
@findex csqrtl
6553
@findex ctan
6554
@findex ctanf
6555
@findex ctanh
6556
@findex ctanhf
6557
@findex ctanhl
6558
@findex ctanl
6559
@findex dcgettext
6560
@findex dgettext
6561
@findex drem
6562
@findex dremf
6563
@findex dreml
6564
@findex erf
6565
@findex erfc
6566
@findex erfcf
6567
@findex erfcl
6568
@findex erff
6569
@findex erfl
6570
@findex exit
6571
@findex exp
6572
@findex exp10
6573
@findex exp10f
6574
@findex exp10l
6575
@findex exp2
6576
@findex exp2f
6577
@findex exp2l
6578
@findex expf
6579
@findex expl
6580
@findex expm1
6581
@findex expm1f
6582
@findex expm1l
6583
@findex fabs
6584
@findex fabsf
6585
@findex fabsl
6586
@findex fdim
6587
@findex fdimf
6588
@findex fdiml
6589
@findex ffs
6590
@findex floor
6591
@findex floorf
6592
@findex floorl
6593
@findex fma
6594
@findex fmaf
6595
@findex fmal
6596
@findex fmax
6597
@findex fmaxf
6598
@findex fmaxl
6599
@findex fmin
6600
@findex fminf
6601
@findex fminl
6602
@findex fmod
6603
@findex fmodf
6604
@findex fmodl
6605
@findex fprintf
6606
@findex fprintf_unlocked
6607
@findex fputs
6608
@findex fputs_unlocked
6609
@findex frexp
6610
@findex frexpf
6611
@findex frexpl
6612
@findex fscanf
6613
@findex gamma
6614
@findex gammaf
6615
@findex gammal
6616
@findex gamma_r
6617
@findex gammaf_r
6618
@findex gammal_r
6619
@findex gettext
6620
@findex hypot
6621
@findex hypotf
6622
@findex hypotl
6623
@findex ilogb
6624
@findex ilogbf
6625
@findex ilogbl
6626
@findex imaxabs
6627
@findex index
6628
@findex isalnum
6629
@findex isalpha
6630
@findex isascii
6631
@findex isblank
6632
@findex iscntrl
6633
@findex isdigit
6634
@findex isgraph
6635
@findex islower
6636
@findex isprint
6637
@findex ispunct
6638
@findex isspace
6639
@findex isupper
6640
@findex iswalnum
6641
@findex iswalpha
6642
@findex iswblank
6643
@findex iswcntrl
6644
@findex iswdigit
6645
@findex iswgraph
6646
@findex iswlower
6647
@findex iswprint
6648
@findex iswpunct
6649
@findex iswspace
6650
@findex iswupper
6651
@findex iswxdigit
6652
@findex isxdigit
6653
@findex j0
6654
@findex j0f
6655
@findex j0l
6656
@findex j1
6657
@findex j1f
6658
@findex j1l
6659
@findex jn
6660
@findex jnf
6661
@findex jnl
6662
@findex labs
6663
@findex ldexp
6664
@findex ldexpf
6665
@findex ldexpl
6666
@findex lgamma
6667
@findex lgammaf
6668
@findex lgammal
6669
@findex lgamma_r
6670
@findex lgammaf_r
6671
@findex lgammal_r
6672
@findex llabs
6673
@findex llrint
6674
@findex llrintf
6675
@findex llrintl
6676
@findex llround
6677
@findex llroundf
6678
@findex llroundl
6679
@findex log
6680
@findex log10
6681
@findex log10f
6682
@findex log10l
6683
@findex log1p
6684
@findex log1pf
6685
@findex log1pl
6686
@findex log2
6687
@findex log2f
6688
@findex log2l
6689
@findex logb
6690
@findex logbf
6691
@findex logbl
6692
@findex logf
6693
@findex logl
6694
@findex lrint
6695
@findex lrintf
6696
@findex lrintl
6697
@findex lround
6698
@findex lroundf
6699
@findex lroundl
6700
@findex malloc
6701
@findex memchr
6702
@findex memcmp
6703
@findex memcpy
6704
@findex mempcpy
6705
@findex memset
6706
@findex modf
6707
@findex modff
6708
@findex modfl
6709
@findex nearbyint
6710
@findex nearbyintf
6711
@findex nearbyintl
6712
@findex nextafter
6713
@findex nextafterf
6714
@findex nextafterl
6715
@findex nexttoward
6716
@findex nexttowardf
6717
@findex nexttowardl
6718
@findex pow
6719
@findex pow10
6720
@findex pow10f
6721
@findex pow10l
6722
@findex powf
6723
@findex powl
6724
@findex printf
6725
@findex printf_unlocked
6726
@findex putchar
6727
@findex puts
6728
@findex remainder
6729
@findex remainderf
6730
@findex remainderl
6731
@findex remquo
6732
@findex remquof
6733
@findex remquol
6734
@findex rindex
6735
@findex rint
6736
@findex rintf
6737
@findex rintl
6738
@findex round
6739
@findex roundf
6740
@findex roundl
6741
@findex scalb
6742
@findex scalbf
6743
@findex scalbl
6744
@findex scalbln
6745
@findex scalblnf
6746
@findex scalblnf
6747
@findex scalbn
6748
@findex scalbnf
6749
@findex scanfnl
6750
@findex signbit
6751
@findex signbitf
6752
@findex signbitl
6753
@findex signbitd32
6754
@findex signbitd64
6755
@findex signbitd128
6756
@findex significand
6757
@findex significandf
6758
@findex significandl
6759
@findex sin
6760
@findex sincos
6761
@findex sincosf
6762
@findex sincosl
6763
@findex sinf
6764
@findex sinh
6765
@findex sinhf
6766
@findex sinhl
6767
@findex sinl
6768
@findex snprintf
6769
@findex sprintf
6770
@findex sqrt
6771
@findex sqrtf
6772
@findex sqrtl
6773
@findex sscanf
6774
@findex stpcpy
6775
@findex stpncpy
6776
@findex strcasecmp
6777
@findex strcat
6778
@findex strchr
6779
@findex strcmp
6780
@findex strcpy
6781
@findex strcspn
6782
@findex strdup
6783
@findex strfmon
6784
@findex strftime
6785
@findex strlen
6786
@findex strncasecmp
6787
@findex strncat
6788
@findex strncmp
6789
@findex strncpy
6790
@findex strndup
6791
@findex strpbrk
6792
@findex strrchr
6793
@findex strspn
6794
@findex strstr
6795
@findex tan
6796
@findex tanf
6797
@findex tanh
6798
@findex tanhf
6799
@findex tanhl
6800
@findex tanl
6801
@findex tgamma
6802
@findex tgammaf
6803
@findex tgammal
6804
@findex toascii
6805
@findex tolower
6806
@findex toupper
6807
@findex towlower
6808
@findex towupper
6809
@findex trunc
6810
@findex truncf
6811
@findex truncl
6812
@findex vfprintf
6813
@findex vfscanf
6814
@findex vprintf
6815
@findex vscanf
6816
@findex vsnprintf
6817
@findex vsprintf
6818
@findex vsscanf
6819
@findex y0
6820
@findex y0f
6821
@findex y0l
6822
@findex y1
6823
@findex y1f
6824
@findex y1l
6825
@findex yn
6826
@findex ynf
6827
@findex ynl
6828
 
6829
GCC provides a large number of built-in functions other than the ones
6830
mentioned above.  Some of these are for internal use in the processing
6831
of exceptions or variable-length argument lists and will not be
6832
documented here because they may change from time to time; we do not
6833
recommend general use of these functions.
6834
 
6835
The remaining functions are provided for optimization purposes.
6836
 
6837
@opindex fno-builtin
6838
GCC includes built-in versions of many of the functions in the standard
6839
C library.  The versions prefixed with @code{__builtin_} will always be
6840
treated as having the same meaning as the C library function even if you
6841
specify the @option{-fno-builtin} option.  (@pxref{C Dialect Options})
6842
Many of these functions are only optimized in certain cases; if they are
6843
not optimized in a particular case, a call to the library function will
6844
be emitted.
6845
 
6846
@opindex ansi
6847
@opindex std
6848
Outside strict ISO C mode (@option{-ansi}, @option{-std=c90} or
6849
@option{-std=c99}), the functions
6850
@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
6851
@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
6852
@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
6853
@code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
6854
@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
6855
@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
6856
@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
6857
@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
6858
@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
6859
@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
6860
@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb},
6861
@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
6862
@code{signbitd64}, @code{signbitd128}, @code{significandf},
6863
@code{significandl}, @code{significand}, @code{sincosf},
6864
@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
6865
@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
6866
@code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0},
6867
@code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
6868
@code{yn}
6869
may be handled as built-in functions.
6870
All these functions have corresponding versions
6871
prefixed with @code{__builtin_}, which may be used even in strict C90
6872
mode.
6873
 
6874
The ISO C99 functions
6875
@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
6876
@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
6877
@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
6878
@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
6879
@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
6880
@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
6881
@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
6882
@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
6883
@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
6884
@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
6885
@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
6886
@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
6887
@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
6888
@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
6889
@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
6890
@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
6891
@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
6892
@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
6893
@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
6894
@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
6895
@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
6896
@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
6897
@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
6898
@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
6899
@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
6900
@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
6901
@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
6902
@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
6903
@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
6904
@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
6905
@code{nextafterf}, @code{nextafterl}, @code{nextafter},
6906
@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
6907
@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
6908
@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
6909
@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
6910
@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
6911
@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
6912
@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
6913
@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
6914
are handled as built-in functions
6915
except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
6916
 
6917
There are also built-in versions of the ISO C99 functions
6918
@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
6919
@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
6920
@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
6921
@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
6922
@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
6923
@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
6924
@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
6925
@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
6926
@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
6927
that are recognized in any mode since ISO C90 reserves these names for
6928
the purpose to which ISO C99 puts them.  All these functions have
6929
corresponding versions prefixed with @code{__builtin_}.
6930
 
6931
The ISO C94 functions
6932
@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
6933
@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
6934
@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
6935
@code{towupper}
6936
are handled as built-in functions
6937
except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
6938
 
6939
The ISO C90 functions
6940
@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
6941
@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
6942
@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
6943
@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf},
6944
@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
6945
@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
6946
@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
6947
@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
6948
@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
6949
@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
6950
@code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf},
6951
@code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
6952
@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
6953
@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
6954
@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
6955
@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
6956
are all recognized as built-in functions unless
6957
@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
6958
is specified for an individual function).  All of these functions have
6959
corresponding versions prefixed with @code{__builtin_}.
6960
 
6961
GCC provides built-in versions of the ISO C99 floating point comparison
6962
macros that avoid raising exceptions for unordered operands.  They have
6963
the same names as the standard macros ( @code{isgreater},
6964
@code{isgreaterequal}, @code{isless}, @code{islessequal},
6965
@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
6966
prefixed.  We intend for a library implementor to be able to simply
6967
@code{#define} each standard macro to its built-in equivalent.
6968
In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
6969
@code{isinf_sign} and @code{isnormal} built-ins used with
6970
@code{__builtin_} prefixed.  The @code{isinf} and @code{isnan}
6971
builtins appear both with and without the @code{__builtin_} prefix.
6972
 
6973
@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
6974
 
6975
You can use the built-in function @code{__builtin_types_compatible_p} to
6976
determine whether two types are the same.
6977
 
6978
This built-in function returns 1 if the unqualified versions of the
6979
types @var{type1} and @var{type2} (which are types, not expressions) are
6980
compatible, 0 otherwise.  The result of this built-in function can be
6981
used in integer constant expressions.
6982
 
6983
This built-in function ignores top level qualifiers (e.g., @code{const},
6984
@code{volatile}).  For example, @code{int} is equivalent to @code{const
6985
int}.
6986
 
6987
The type @code{int[]} and @code{int[5]} are compatible.  On the other
6988
hand, @code{int} and @code{char *} are not compatible, even if the size
6989
of their types, on the particular architecture are the same.  Also, the
6990
amount of pointer indirection is taken into account when determining
6991
similarity.  Consequently, @code{short *} is not similar to
6992
@code{short **}.  Furthermore, two types that are typedefed are
6993
considered compatible if their underlying types are compatible.
6994
 
6995
An @code{enum} type is not considered to be compatible with another
6996
@code{enum} type even if both are compatible with the same integer
6997
type; this is what the C standard specifies.
6998
For example, @code{enum @{foo, bar@}} is not similar to
6999
@code{enum @{hot, dog@}}.
7000
 
7001
You would typically use this function in code whose execution varies
7002
depending on the arguments' types.  For example:
7003
 
7004
@smallexample
7005
#define foo(x)                                                  \
7006
  (@{                                                           \
7007
    typeof (x) tmp = (x);                                       \
7008
    if (__builtin_types_compatible_p (typeof (x), long double)) \
7009
      tmp = foo_long_double (tmp);                              \
7010
    else if (__builtin_types_compatible_p (typeof (x), double)) \
7011
      tmp = foo_double (tmp);                                   \
7012
    else if (__builtin_types_compatible_p (typeof (x), float))  \
7013
      tmp = foo_float (tmp);                                    \
7014
    else                                                        \
7015
      abort ();                                                 \
7016
    tmp;                                                        \
7017
  @})
7018
@end smallexample
7019
 
7020
@emph{Note:} This construct is only available for C@.
7021
 
7022
@end deftypefn
7023
 
7024
@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
7025
 
7026
You can use the built-in function @code{__builtin_choose_expr} to
7027
evaluate code depending on the value of a constant expression.  This
7028
built-in function returns @var{exp1} if @var{const_exp}, which is an
7029
integer constant expression, is nonzero.  Otherwise it returns 0.
7030
 
7031
This built-in function is analogous to the @samp{? :} operator in C,
7032
except that the expression returned has its type unaltered by promotion
7033
rules.  Also, the built-in function does not evaluate the expression
7034
that was not chosen.  For example, if @var{const_exp} evaluates to true,
7035
@var{exp2} is not evaluated even if it has side-effects.
7036
 
7037
This built-in function can return an lvalue if the chosen argument is an
7038
lvalue.
7039
 
7040
If @var{exp1} is returned, the return type is the same as @var{exp1}'s
7041
type.  Similarly, if @var{exp2} is returned, its return type is the same
7042
as @var{exp2}.
7043
 
7044
Example:
7045
 
7046
@smallexample
7047
#define foo(x)                                                    \
7048
  __builtin_choose_expr (                                         \
7049
    __builtin_types_compatible_p (typeof (x), double),            \
7050
    foo_double (x),                                               \
7051
    __builtin_choose_expr (                                       \
7052
      __builtin_types_compatible_p (typeof (x), float),           \
7053
      foo_float (x),                                              \
7054
      /* @r{The void expression results in a compile-time error}  \
7055
         @r{when assigning the result to something.}  */          \
7056
      (void)0))
7057
@end smallexample
7058
 
7059
@emph{Note:} This construct is only available for C@.  Furthermore, the
7060
unused expression (@var{exp1} or @var{exp2} depending on the value of
7061
@var{const_exp}) may still generate syntax errors.  This may change in
7062
future revisions.
7063
 
7064
@end deftypefn
7065
 
7066
@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
7067
You can use the built-in function @code{__builtin_constant_p} to
7068
determine if a value is known to be constant at compile-time and hence
7069
that GCC can perform constant-folding on expressions involving that
7070
value.  The argument of the function is the value to test.  The function
7071
returns the integer 1 if the argument is known to be a compile-time
7072
constant and 0 if it is not known to be a compile-time constant.  A
7073
return of 0 does not indicate that the value is @emph{not} a constant,
7074
but merely that GCC cannot prove it is a constant with the specified
7075
value of the @option{-O} option.
7076
 
7077
You would typically use this function in an embedded application where
7078
memory was a critical resource.  If you have some complex calculation,
7079
you may want it to be folded if it involves constants, but need to call
7080
a function if it does not.  For example:
7081
 
7082
@smallexample
7083
#define Scale_Value(X)      \
7084
  (__builtin_constant_p (X) \
7085
  ? ((X) * SCALE + OFFSET) : Scale (X))
7086
@end smallexample
7087
 
7088
You may use this built-in function in either a macro or an inline
7089
function.  However, if you use it in an inlined function and pass an
7090
argument of the function as the argument to the built-in, GCC will
7091
never return 1 when you call the inline function with a string constant
7092
or compound literal (@pxref{Compound Literals}) and will not return 1
7093
when you pass a constant numeric value to the inline function unless you
7094
specify the @option{-O} option.
7095
 
7096
You may also use @code{__builtin_constant_p} in initializers for static
7097
data.  For instance, you can write
7098
 
7099
@smallexample
7100
static const int table[] = @{
7101
   __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
7102
   /* @r{@dots{}} */
7103
@};
7104
@end smallexample
7105
 
7106
@noindent
7107
This is an acceptable initializer even if @var{EXPRESSION} is not a
7108
constant expression, including the case where
7109
@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
7110
folded to a constant but @var{EXPRESSION} contains operands that would
7111
not otherwise be permitted in a static initializer (for example,
7112
@code{0 && foo ()}).  GCC must be more conservative about evaluating the
7113
built-in in this case, because it has no opportunity to perform
7114
optimization.
7115
 
7116
Previous versions of GCC did not accept this built-in in data
7117
initializers.  The earliest version where it is completely safe is
7118
3.0.1.
7119
@end deftypefn
7120
 
7121
@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
7122
@opindex fprofile-arcs
7123
You may use @code{__builtin_expect} to provide the compiler with
7124
branch prediction information.  In general, you should prefer to
7125
use actual profile feedback for this (@option{-fprofile-arcs}), as
7126
programmers are notoriously bad at predicting how their programs
7127
actually perform.  However, there are applications in which this
7128
data is hard to collect.
7129
 
7130
The return value is the value of @var{exp}, which should be an integral
7131
expression.  The semantics of the built-in are that it is expected that
7132
@var{exp} == @var{c}.  For example:
7133
 
7134
@smallexample
7135
if (__builtin_expect (x, 0))
7136
  foo ();
7137
@end smallexample
7138
 
7139
@noindent
7140
would indicate that we do not expect to call @code{foo}, since
7141
we expect @code{x} to be zero.  Since you are limited to integral
7142
expressions for @var{exp}, you should use constructions such as
7143
 
7144
@smallexample
7145
if (__builtin_expect (ptr != NULL, 1))
7146
  error ();
7147
@end smallexample
7148
 
7149
@noindent
7150
when testing pointer or floating-point values.
7151
@end deftypefn
7152
 
7153
@deftypefn {Built-in Function} void __builtin_trap (void)
7154
This function causes the program to exit abnormally.  GCC implements
7155
this function by using a target-dependent mechanism (such as
7156
intentionally executing an illegal instruction) or by calling
7157
@code{abort}.  The mechanism used may vary from release to release so
7158
you should not rely on any particular implementation.
7159
@end deftypefn
7160
 
7161
@deftypefn {Built-in Function} void __builtin_unreachable (void)
7162
If control flow reaches the point of the @code{__builtin_unreachable},
7163
the program is undefined.  It is useful in situations where the
7164
compiler cannot deduce the unreachability of the code.
7165
 
7166
One such case is immediately following an @code{asm} statement that
7167
will either never terminate, or one that transfers control elsewhere
7168
and never returns.  In this example, without the
7169
@code{__builtin_unreachable}, GCC would issue a warning that control
7170
reaches the end of a non-void function.  It would also generate code
7171
to return after the @code{asm}.
7172
 
7173
@smallexample
7174
int f (int c, int v)
7175
@{
7176
  if (c)
7177
    @{
7178
      return v;
7179
    @}
7180
  else
7181
    @{
7182
      asm("jmp error_handler");
7183
      __builtin_unreachable ();
7184
    @}
7185
@}
7186
@end smallexample
7187
 
7188
Because the @code{asm} statement unconditionally transfers control out
7189
of the function, control will never reach the end of the function
7190
body.  The @code{__builtin_unreachable} is in fact unreachable and
7191
communicates this fact to the compiler.
7192
 
7193
Another use for @code{__builtin_unreachable} is following a call a
7194
function that never returns but that is not declared
7195
@code{__attribute__((noreturn))}, as in this example:
7196
 
7197
@smallexample
7198
void function_that_never_returns (void);
7199
 
7200
int g (int c)
7201
@{
7202
  if (c)
7203
    @{
7204
      return 1;
7205
    @}
7206
  else
7207
    @{
7208
      function_that_never_returns ();
7209
      __builtin_unreachable ();
7210
    @}
7211
@}
7212
@end smallexample
7213
 
7214
@end deftypefn
7215
 
7216
@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end})
7217
This function is used to flush the processor's instruction cache for
7218
the region of memory between @var{begin} inclusive and @var{end}
7219
exclusive.  Some targets require that the instruction cache be
7220
flushed, after modifying memory containing code, in order to obtain
7221
deterministic behavior.
7222
 
7223
If the target does not require instruction cache flushes,
7224
@code{__builtin___clear_cache} has no effect.  Otherwise either
7225
instructions are emitted in-line to clear the instruction cache or a
7226
call to the @code{__clear_cache} function in libgcc is made.
7227
@end deftypefn
7228
 
7229
@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
7230
This function is used to minimize cache-miss latency by moving data into
7231
a cache before it is accessed.
7232
You can insert calls to @code{__builtin_prefetch} into code for which
7233
you know addresses of data in memory that is likely to be accessed soon.
7234
If the target supports them, data prefetch instructions will be generated.
7235
If the prefetch is done early enough before the access then the data will
7236
be in the cache by the time it is accessed.
7237
 
7238
The value of @var{addr} is the address of the memory to prefetch.
7239
There are two optional arguments, @var{rw} and @var{locality}.
7240
The value of @var{rw} is a compile-time constant one or zero; one
7241
means that the prefetch is preparing for a write to the memory address
7242
and zero, the default, means that the prefetch is preparing for a read.
7243
The value @var{locality} must be a compile-time constant integer between
7244
zero and three.  A value of zero means that the data has no temporal
7245
locality, so it need not be left in the cache after the access.  A value
7246
of three means that the data has a high degree of temporal locality and
7247
should be left in all levels of cache possible.  Values of one and two
7248
mean, respectively, a low or moderate degree of temporal locality.  The
7249
default is three.
7250
 
7251
@smallexample
7252
for (i = 0; i < n; i++)
7253
  @{
7254
    a[i] = a[i] + b[i];
7255
    __builtin_prefetch (&a[i+j], 1, 1);
7256
    __builtin_prefetch (&b[i+j], 0, 1);
7257
    /* @r{@dots{}} */
7258
  @}
7259
@end smallexample
7260
 
7261
Data prefetch does not generate faults if @var{addr} is invalid, but
7262
the address expression itself must be valid.  For example, a prefetch
7263
of @code{p->next} will not fault if @code{p->next} is not a valid
7264
address, but evaluation will fault if @code{p} is not a valid address.
7265
 
7266
If the target does not support data prefetch, the address expression
7267
is evaluated if it includes side effects but no other code is generated
7268
and GCC does not issue a warning.
7269
@end deftypefn
7270
 
7271
@deftypefn {Built-in Function} double __builtin_huge_val (void)
7272
Returns a positive infinity, if supported by the floating-point format,
7273
else @code{DBL_MAX}.  This function is suitable for implementing the
7274
ISO C macro @code{HUGE_VAL}.
7275
@end deftypefn
7276
 
7277
@deftypefn {Built-in Function} float __builtin_huge_valf (void)
7278
Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
7279
@end deftypefn
7280
 
7281
@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
7282
Similar to @code{__builtin_huge_val}, except the return
7283
type is @code{long double}.
7284
@end deftypefn
7285
 
7286
@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
7287
This built-in implements the C99 fpclassify functionality.  The first
7288
five int arguments should be the target library's notion of the
7289
possible FP classes and are used for return values.  They must be
7290
constant values and they must appear in this order: @code{FP_NAN},
7291
@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
7292
@code{FP_ZERO}.  The ellipsis is for exactly one floating point value
7293
to classify.  GCC treats the last argument as type-generic, which
7294
means it does not do default promotion from float to double.
7295
@end deftypefn
7296
 
7297
@deftypefn {Built-in Function} double __builtin_inf (void)
7298
Similar to @code{__builtin_huge_val}, except a warning is generated
7299
if the target floating-point format does not support infinities.
7300
@end deftypefn
7301
 
7302
@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
7303
Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
7304
@end deftypefn
7305
 
7306
@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
7307
Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
7308
@end deftypefn
7309
 
7310
@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
7311
Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
7312
@end deftypefn
7313
 
7314
@deftypefn {Built-in Function} float __builtin_inff (void)
7315
Similar to @code{__builtin_inf}, except the return type is @code{float}.
7316
This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
7317
@end deftypefn
7318
 
7319
@deftypefn {Built-in Function} {long double} __builtin_infl (void)
7320
Similar to @code{__builtin_inf}, except the return
7321
type is @code{long double}.
7322
@end deftypefn
7323
 
7324
@deftypefn {Built-in Function} int __builtin_isinf_sign (...)
7325
Similar to @code{isinf}, except the return value will be negative for
7326
an argument of @code{-Inf}.  Note while the parameter list is an
7327
ellipsis, this function only accepts exactly one floating point
7328
argument.  GCC treats this parameter as type-generic, which means it
7329
does not do default promotion from float to double.
7330
@end deftypefn
7331
 
7332
@deftypefn {Built-in Function} double __builtin_nan (const char *str)
7333
This is an implementation of the ISO C99 function @code{nan}.
7334
 
7335
Since ISO C99 defines this function in terms of @code{strtod}, which we
7336
do not implement, a description of the parsing is in order.  The string
7337
is parsed as by @code{strtol}; that is, the base is recognized by
7338
leading @samp{0} or @samp{0x} prefixes.  The number parsed is placed
7339
in the significand such that the least significant bit of the number
7340
is at the least significant bit of the significand.  The number is
7341
truncated to fit the significand field provided.  The significand is
7342
forced to be a quiet NaN@.
7343
 
7344
This function, if given a string literal all of which would have been
7345
consumed by strtol, is evaluated early enough that it is considered a
7346
compile-time constant.
7347
@end deftypefn
7348
 
7349
@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
7350
Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
7351
@end deftypefn
7352
 
7353
@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
7354
Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
7355
@end deftypefn
7356
 
7357
@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
7358
Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
7359
@end deftypefn
7360
 
7361
@deftypefn {Built-in Function} float __builtin_nanf (const char *str)
7362
Similar to @code{__builtin_nan}, except the return type is @code{float}.
7363
@end deftypefn
7364
 
7365
@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
7366
Similar to @code{__builtin_nan}, except the return type is @code{long double}.
7367
@end deftypefn
7368
 
7369
@deftypefn {Built-in Function} double __builtin_nans (const char *str)
7370
Similar to @code{__builtin_nan}, except the significand is forced
7371
to be a signaling NaN@.  The @code{nans} function is proposed by
7372
@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
7373
@end deftypefn
7374
 
7375
@deftypefn {Built-in Function} float __builtin_nansf (const char *str)
7376
Similar to @code{__builtin_nans}, except the return type is @code{float}.
7377
@end deftypefn
7378
 
7379
@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
7380
Similar to @code{__builtin_nans}, except the return type is @code{long double}.
7381
@end deftypefn
7382
 
7383
@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x)
7384
Returns one plus the index of the least significant 1-bit of @var{x}, or
7385
if @var{x} is zero, returns zero.
7386
@end deftypefn
7387
 
7388
@deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
7389
Returns the number of leading 0-bits in @var{x}, starting at the most
7390
significant bit position.  If @var{x} is 0, the result is undefined.
7391
@end deftypefn
7392
 
7393
@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
7394
Returns the number of trailing 0-bits in @var{x}, starting at the least
7395
significant bit position.  If @var{x} is 0, the result is undefined.
7396
@end deftypefn
7397
 
7398
@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
7399
Returns the number of 1-bits in @var{x}.
7400
@end deftypefn
7401
 
7402
@deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
7403
Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
7404
modulo 2.
7405
@end deftypefn
7406
 
7407
@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long)
7408
Similar to @code{__builtin_ffs}, except the argument type is
7409
@code{unsigned long}.
7410
@end deftypefn
7411
 
7412
@deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
7413
Similar to @code{__builtin_clz}, except the argument type is
7414
@code{unsigned long}.
7415
@end deftypefn
7416
 
7417
@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
7418
Similar to @code{__builtin_ctz}, except the argument type is
7419
@code{unsigned long}.
7420
@end deftypefn
7421
 
7422
@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
7423
Similar to @code{__builtin_popcount}, except the argument type is
7424
@code{unsigned long}.
7425
@end deftypefn
7426
 
7427
@deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
7428
Similar to @code{__builtin_parity}, except the argument type is
7429
@code{unsigned long}.
7430
@end deftypefn
7431
 
7432
@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long)
7433
Similar to @code{__builtin_ffs}, except the argument type is
7434
@code{unsigned long long}.
7435
@end deftypefn
7436
 
7437
@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
7438
Similar to @code{__builtin_clz}, except the argument type is
7439
@code{unsigned long long}.
7440
@end deftypefn
7441
 
7442
@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
7443
Similar to @code{__builtin_ctz}, except the argument type is
7444
@code{unsigned long long}.
7445
@end deftypefn
7446
 
7447
@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
7448
Similar to @code{__builtin_popcount}, except the argument type is
7449
@code{unsigned long long}.
7450
@end deftypefn
7451
 
7452
@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
7453
Similar to @code{__builtin_parity}, except the argument type is
7454
@code{unsigned long long}.
7455
@end deftypefn
7456
 
7457
@deftypefn {Built-in Function} double __builtin_powi (double, int)
7458
Returns the first argument raised to the power of the second.  Unlike the
7459
@code{pow} function no guarantees about precision and rounding are made.
7460
@end deftypefn
7461
 
7462
@deftypefn {Built-in Function} float __builtin_powif (float, int)
7463
Similar to @code{__builtin_powi}, except the argument and return types
7464
are @code{float}.
7465
@end deftypefn
7466
 
7467
@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
7468
Similar to @code{__builtin_powi}, except the argument and return types
7469
are @code{long double}.
7470
@end deftypefn
7471
 
7472
@deftypefn {Built-in Function} int32_t __builtin_bswap32 (int32_t x)
7473
Returns @var{x} with the order of the bytes reversed; for example,
7474
@code{0xaabbccdd} becomes @code{0xddccbbaa}.  Byte here always means
7475
exactly 8 bits.
7476
@end deftypefn
7477
 
7478
@deftypefn {Built-in Function} int64_t __builtin_bswap64 (int64_t x)
7479
Similar to @code{__builtin_bswap32}, except the argument and return types
7480
are 64-bit.
7481
@end deftypefn
7482
 
7483
@node Target Builtins
7484
@section Built-in Functions Specific to Particular Target Machines
7485
 
7486
On some target machines, GCC supports many built-in functions specific
7487
to those machines.  Generally these generate calls to specific machine
7488
instructions, but allow the compiler to schedule those calls.
7489
 
7490
@menu
7491
* Alpha Built-in Functions::
7492
* ARM iWMMXt Built-in Functions::
7493
* ARM NEON Intrinsics::
7494
* Blackfin Built-in Functions::
7495
* FR-V Built-in Functions::
7496
* X86 Built-in Functions::
7497
* MIPS DSP Built-in Functions::
7498
* MIPS Paired-Single Support::
7499
* MIPS Loongson Built-in Functions::
7500
* Other MIPS Built-in Functions::
7501
* picoChip Built-in Functions::
7502
* PowerPC AltiVec/VSX Built-in Functions::
7503
* RX Built-in Functions::
7504
* SPARC VIS Built-in Functions::
7505
* SPU Built-in Functions::
7506
@end menu
7507
 
7508
@node Alpha Built-in Functions
7509
@subsection Alpha Built-in Functions
7510
 
7511
These built-in functions are available for the Alpha family of
7512
processors, depending on the command-line switches used.
7513
 
7514
The following built-in functions are always available.  They
7515
all generate the machine instruction that is part of the name.
7516
 
7517
@smallexample
7518
long __builtin_alpha_implver (void)
7519
long __builtin_alpha_rpcc (void)
7520
long __builtin_alpha_amask (long)
7521
long __builtin_alpha_cmpbge (long, long)
7522
long __builtin_alpha_extbl (long, long)
7523
long __builtin_alpha_extwl (long, long)
7524
long __builtin_alpha_extll (long, long)
7525
long __builtin_alpha_extql (long, long)
7526
long __builtin_alpha_extwh (long, long)
7527
long __builtin_alpha_extlh (long, long)
7528
long __builtin_alpha_extqh (long, long)
7529
long __builtin_alpha_insbl (long, long)
7530
long __builtin_alpha_inswl (long, long)
7531
long __builtin_alpha_insll (long, long)
7532
long __builtin_alpha_insql (long, long)
7533
long __builtin_alpha_inswh (long, long)
7534
long __builtin_alpha_inslh (long, long)
7535
long __builtin_alpha_insqh (long, long)
7536
long __builtin_alpha_mskbl (long, long)
7537
long __builtin_alpha_mskwl (long, long)
7538
long __builtin_alpha_mskll (long, long)
7539
long __builtin_alpha_mskql (long, long)
7540
long __builtin_alpha_mskwh (long, long)
7541
long __builtin_alpha_msklh (long, long)
7542
long __builtin_alpha_mskqh (long, long)
7543
long __builtin_alpha_umulh (long, long)
7544
long __builtin_alpha_zap (long, long)
7545
long __builtin_alpha_zapnot (long, long)
7546
@end smallexample
7547
 
7548
The following built-in functions are always with @option{-mmax}
7549
or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
7550
later.  They all generate the machine instruction that is part
7551
of the name.
7552
 
7553
@smallexample
7554
long __builtin_alpha_pklb (long)
7555
long __builtin_alpha_pkwb (long)
7556
long __builtin_alpha_unpkbl (long)
7557
long __builtin_alpha_unpkbw (long)
7558
long __builtin_alpha_minub8 (long, long)
7559
long __builtin_alpha_minsb8 (long, long)
7560
long __builtin_alpha_minuw4 (long, long)
7561
long __builtin_alpha_minsw4 (long, long)
7562
long __builtin_alpha_maxub8 (long, long)
7563
long __builtin_alpha_maxsb8 (long, long)
7564
long __builtin_alpha_maxuw4 (long, long)
7565
long __builtin_alpha_maxsw4 (long, long)
7566
long __builtin_alpha_perr (long, long)
7567
@end smallexample
7568
 
7569
The following built-in functions are always with @option{-mcix}
7570
or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
7571
later.  They all generate the machine instruction that is part
7572
of the name.
7573
 
7574
@smallexample
7575
long __builtin_alpha_cttz (long)
7576
long __builtin_alpha_ctlz (long)
7577
long __builtin_alpha_ctpop (long)
7578
@end smallexample
7579
 
7580
The following builtins are available on systems that use the OSF/1
7581
PALcode.  Normally they invoke the @code{rduniq} and @code{wruniq}
7582
PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
7583
@code{rdval} and @code{wrval}.
7584
 
7585
@smallexample
7586
void *__builtin_thread_pointer (void)
7587
void __builtin_set_thread_pointer (void *)
7588
@end smallexample
7589
 
7590
@node ARM iWMMXt Built-in Functions
7591
@subsection ARM iWMMXt Built-in Functions
7592
 
7593
These built-in functions are available for the ARM family of
7594
processors when the @option{-mcpu=iwmmxt} switch is used:
7595
 
7596
@smallexample
7597
typedef int v2si __attribute__ ((vector_size (8)));
7598
typedef short v4hi __attribute__ ((vector_size (8)));
7599
typedef char v8qi __attribute__ ((vector_size (8)));
7600
 
7601
int __builtin_arm_getwcx (int)
7602
void __builtin_arm_setwcx (int, int)
7603
int __builtin_arm_textrmsb (v8qi, int)
7604
int __builtin_arm_textrmsh (v4hi, int)
7605
int __builtin_arm_textrmsw (v2si, int)
7606
int __builtin_arm_textrmub (v8qi, int)
7607
int __builtin_arm_textrmuh (v4hi, int)
7608
int __builtin_arm_textrmuw (v2si, int)
7609
v8qi __builtin_arm_tinsrb (v8qi, int)
7610
v4hi __builtin_arm_tinsrh (v4hi, int)
7611
v2si __builtin_arm_tinsrw (v2si, int)
7612
long long __builtin_arm_tmia (long long, int, int)
7613
long long __builtin_arm_tmiabb (long long, int, int)
7614
long long __builtin_arm_tmiabt (long long, int, int)
7615
long long __builtin_arm_tmiaph (long long, int, int)
7616
long long __builtin_arm_tmiatb (long long, int, int)
7617
long long __builtin_arm_tmiatt (long long, int, int)
7618
int __builtin_arm_tmovmskb (v8qi)
7619
int __builtin_arm_tmovmskh (v4hi)
7620
int __builtin_arm_tmovmskw (v2si)
7621
long long __builtin_arm_waccb (v8qi)
7622
long long __builtin_arm_wacch (v4hi)
7623
long long __builtin_arm_waccw (v2si)
7624
v8qi __builtin_arm_waddb (v8qi, v8qi)
7625
v8qi __builtin_arm_waddbss (v8qi, v8qi)
7626
v8qi __builtin_arm_waddbus (v8qi, v8qi)
7627
v4hi __builtin_arm_waddh (v4hi, v4hi)
7628
v4hi __builtin_arm_waddhss (v4hi, v4hi)
7629
v4hi __builtin_arm_waddhus (v4hi, v4hi)
7630
v2si __builtin_arm_waddw (v2si, v2si)
7631
v2si __builtin_arm_waddwss (v2si, v2si)
7632
v2si __builtin_arm_waddwus (v2si, v2si)
7633
v8qi __builtin_arm_walign (v8qi, v8qi, int)
7634
long long __builtin_arm_wand(long long, long long)
7635
long long __builtin_arm_wandn (long long, long long)
7636
v8qi __builtin_arm_wavg2b (v8qi, v8qi)
7637
v8qi __builtin_arm_wavg2br (v8qi, v8qi)
7638
v4hi __builtin_arm_wavg2h (v4hi, v4hi)
7639
v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
7640
v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
7641
v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
7642
v2si __builtin_arm_wcmpeqw (v2si, v2si)
7643
v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
7644
v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
7645
v2si __builtin_arm_wcmpgtsw (v2si, v2si)
7646
v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
7647
v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
7648
v2si __builtin_arm_wcmpgtuw (v2si, v2si)
7649
long long __builtin_arm_wmacs (long long, v4hi, v4hi)
7650
long long __builtin_arm_wmacsz (v4hi, v4hi)
7651
long long __builtin_arm_wmacu (long long, v4hi, v4hi)
7652
long long __builtin_arm_wmacuz (v4hi, v4hi)
7653
v4hi __builtin_arm_wmadds (v4hi, v4hi)
7654
v4hi __builtin_arm_wmaddu (v4hi, v4hi)
7655
v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
7656
v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
7657
v2si __builtin_arm_wmaxsw (v2si, v2si)
7658
v8qi __builtin_arm_wmaxub (v8qi, v8qi)
7659
v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
7660
v2si __builtin_arm_wmaxuw (v2si, v2si)
7661
v8qi __builtin_arm_wminsb (v8qi, v8qi)
7662
v4hi __builtin_arm_wminsh (v4hi, v4hi)
7663
v2si __builtin_arm_wminsw (v2si, v2si)
7664
v8qi __builtin_arm_wminub (v8qi, v8qi)
7665
v4hi __builtin_arm_wminuh (v4hi, v4hi)
7666
v2si __builtin_arm_wminuw (v2si, v2si)
7667
v4hi __builtin_arm_wmulsm (v4hi, v4hi)
7668
v4hi __builtin_arm_wmulul (v4hi, v4hi)
7669
v4hi __builtin_arm_wmulum (v4hi, v4hi)
7670
long long __builtin_arm_wor (long long, long long)
7671
v2si __builtin_arm_wpackdss (long long, long long)
7672
v2si __builtin_arm_wpackdus (long long, long long)
7673
v8qi __builtin_arm_wpackhss (v4hi, v4hi)
7674
v8qi __builtin_arm_wpackhus (v4hi, v4hi)
7675
v4hi __builtin_arm_wpackwss (v2si, v2si)
7676
v4hi __builtin_arm_wpackwus (v2si, v2si)
7677
long long __builtin_arm_wrord (long long, long long)
7678
long long __builtin_arm_wrordi (long long, int)
7679
v4hi __builtin_arm_wrorh (v4hi, long long)
7680
v4hi __builtin_arm_wrorhi (v4hi, int)
7681
v2si __builtin_arm_wrorw (v2si, long long)
7682
v2si __builtin_arm_wrorwi (v2si, int)
7683
v2si __builtin_arm_wsadb (v8qi, v8qi)
7684
v2si __builtin_arm_wsadbz (v8qi, v8qi)
7685
v2si __builtin_arm_wsadh (v4hi, v4hi)
7686
v2si __builtin_arm_wsadhz (v4hi, v4hi)
7687
v4hi __builtin_arm_wshufh (v4hi, int)
7688
long long __builtin_arm_wslld (long long, long long)
7689
long long __builtin_arm_wslldi (long long, int)
7690
v4hi __builtin_arm_wsllh (v4hi, long long)
7691
v4hi __builtin_arm_wsllhi (v4hi, int)
7692
v2si __builtin_arm_wsllw (v2si, long long)
7693
v2si __builtin_arm_wsllwi (v2si, int)
7694
long long __builtin_arm_wsrad (long long, long long)
7695
long long __builtin_arm_wsradi (long long, int)
7696
v4hi __builtin_arm_wsrah (v4hi, long long)
7697
v4hi __builtin_arm_wsrahi (v4hi, int)
7698
v2si __builtin_arm_wsraw (v2si, long long)
7699
v2si __builtin_arm_wsrawi (v2si, int)
7700
long long __builtin_arm_wsrld (long long, long long)
7701
long long __builtin_arm_wsrldi (long long, int)
7702
v4hi __builtin_arm_wsrlh (v4hi, long long)
7703
v4hi __builtin_arm_wsrlhi (v4hi, int)
7704
v2si __builtin_arm_wsrlw (v2si, long long)
7705
v2si __builtin_arm_wsrlwi (v2si, int)
7706
v8qi __builtin_arm_wsubb (v8qi, v8qi)
7707
v8qi __builtin_arm_wsubbss (v8qi, v8qi)
7708
v8qi __builtin_arm_wsubbus (v8qi, v8qi)
7709
v4hi __builtin_arm_wsubh (v4hi, v4hi)
7710
v4hi __builtin_arm_wsubhss (v4hi, v4hi)
7711
v4hi __builtin_arm_wsubhus (v4hi, v4hi)
7712
v2si __builtin_arm_wsubw (v2si, v2si)
7713
v2si __builtin_arm_wsubwss (v2si, v2si)
7714
v2si __builtin_arm_wsubwus (v2si, v2si)
7715
v4hi __builtin_arm_wunpckehsb (v8qi)
7716
v2si __builtin_arm_wunpckehsh (v4hi)
7717
long long __builtin_arm_wunpckehsw (v2si)
7718
v4hi __builtin_arm_wunpckehub (v8qi)
7719
v2si __builtin_arm_wunpckehuh (v4hi)
7720
long long __builtin_arm_wunpckehuw (v2si)
7721
v4hi __builtin_arm_wunpckelsb (v8qi)
7722
v2si __builtin_arm_wunpckelsh (v4hi)
7723
long long __builtin_arm_wunpckelsw (v2si)
7724
v4hi __builtin_arm_wunpckelub (v8qi)
7725
v2si __builtin_arm_wunpckeluh (v4hi)
7726
long long __builtin_arm_wunpckeluw (v2si)
7727
v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
7728
v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
7729
v2si __builtin_arm_wunpckihw (v2si, v2si)
7730
v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
7731
v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
7732
v2si __builtin_arm_wunpckilw (v2si, v2si)
7733
long long __builtin_arm_wxor (long long, long long)
7734
long long __builtin_arm_wzero ()
7735
@end smallexample
7736
 
7737
@node ARM NEON Intrinsics
7738
@subsection ARM NEON Intrinsics
7739
 
7740
These built-in intrinsics for the ARM Advanced SIMD extension are available
7741
when the @option{-mfpu=neon} switch is used:
7742
 
7743
@include arm-neon-intrinsics.texi
7744
 
7745
@node Blackfin Built-in Functions
7746
@subsection Blackfin Built-in Functions
7747
 
7748
Currently, there are two Blackfin-specific built-in functions.  These are
7749
used for generating @code{CSYNC} and @code{SSYNC} machine insns without
7750
using inline assembly; by using these built-in functions the compiler can
7751
automatically add workarounds for hardware errata involving these
7752
instructions.  These functions are named as follows:
7753
 
7754
@smallexample
7755
void __builtin_bfin_csync (void)
7756
void __builtin_bfin_ssync (void)
7757
@end smallexample
7758
 
7759
@node FR-V Built-in Functions
7760
@subsection FR-V Built-in Functions
7761
 
7762
GCC provides many FR-V-specific built-in functions.  In general,
7763
these functions are intended to be compatible with those described
7764
by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
7765
Semiconductor}.  The two exceptions are @code{__MDUNPACKH} and
7766
@code{__MBTOHE}, the gcc forms of which pass 128-bit values by
7767
pointer rather than by value.
7768
 
7769
Most of the functions are named after specific FR-V instructions.
7770
Such functions are said to be ``directly mapped'' and are summarized
7771
here in tabular form.
7772
 
7773
@menu
7774
* Argument Types::
7775
* Directly-mapped Integer Functions::
7776
* Directly-mapped Media Functions::
7777
* Raw read/write Functions::
7778
* Other Built-in Functions::
7779
@end menu
7780
 
7781
@node Argument Types
7782
@subsubsection Argument Types
7783
 
7784
The arguments to the built-in functions can be divided into three groups:
7785
register numbers, compile-time constants and run-time values.  In order
7786
to make this classification clear at a glance, the arguments and return
7787
values are given the following pseudo types:
7788
 
7789
@multitable @columnfractions .20 .30 .15 .35
7790
@item Pseudo type @tab Real C type @tab Constant? @tab Description
7791
@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
7792
@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
7793
@item @code{sw1} @tab @code{int} @tab No @tab a signed word
7794
@item @code{uw2} @tab @code{unsigned long long} @tab No
7795
@tab an unsigned doubleword
7796
@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
7797
@item @code{const} @tab @code{int} @tab Yes @tab an integer constant
7798
@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
7799
@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
7800
@end multitable
7801
 
7802
These pseudo types are not defined by GCC, they are simply a notational
7803
convenience used in this manual.
7804
 
7805
Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
7806
and @code{sw2} are evaluated at run time.  They correspond to
7807
register operands in the underlying FR-V instructions.
7808
 
7809
@code{const} arguments represent immediate operands in the underlying
7810
FR-V instructions.  They must be compile-time constants.
7811
 
7812
@code{acc} arguments are evaluated at compile time and specify the number
7813
of an accumulator register.  For example, an @code{acc} argument of 2
7814
will select the ACC2 register.
7815
 
7816
@code{iacc} arguments are similar to @code{acc} arguments but specify the
7817
number of an IACC register.  See @pxref{Other Built-in Functions}
7818
for more details.
7819
 
7820
@node Directly-mapped Integer Functions
7821
@subsubsection Directly-mapped Integer Functions
7822
 
7823
The functions listed below map directly to FR-V I-type instructions.
7824
 
7825
@multitable @columnfractions .45 .32 .23
7826
@item Function prototype @tab Example usage @tab Assembly output
7827
@item @code{sw1 __ADDSS (sw1, sw1)}
7828
@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
7829
@tab @code{ADDSS @var{a},@var{b},@var{c}}
7830
@item @code{sw1 __SCAN (sw1, sw1)}
7831
@tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
7832
@tab @code{SCAN @var{a},@var{b},@var{c}}
7833
@item @code{sw1 __SCUTSS (sw1)}
7834
@tab @code{@var{b} = __SCUTSS (@var{a})}
7835
@tab @code{SCUTSS @var{a},@var{b}}
7836
@item @code{sw1 __SLASS (sw1, sw1)}
7837
@tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
7838
@tab @code{SLASS @var{a},@var{b},@var{c}}
7839
@item @code{void __SMASS (sw1, sw1)}
7840
@tab @code{__SMASS (@var{a}, @var{b})}
7841
@tab @code{SMASS @var{a},@var{b}}
7842
@item @code{void __SMSSS (sw1, sw1)}
7843
@tab @code{__SMSSS (@var{a}, @var{b})}
7844
@tab @code{SMSSS @var{a},@var{b}}
7845
@item @code{void __SMU (sw1, sw1)}
7846
@tab @code{__SMU (@var{a}, @var{b})}
7847
@tab @code{SMU @var{a},@var{b}}
7848
@item @code{sw2 __SMUL (sw1, sw1)}
7849
@tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
7850
@tab @code{SMUL @var{a},@var{b},@var{c}}
7851
@item @code{sw1 __SUBSS (sw1, sw1)}
7852
@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
7853
@tab @code{SUBSS @var{a},@var{b},@var{c}}
7854
@item @code{uw2 __UMUL (uw1, uw1)}
7855
@tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
7856
@tab @code{UMUL @var{a},@var{b},@var{c}}
7857
@end multitable
7858
 
7859
@node Directly-mapped Media Functions
7860
@subsubsection Directly-mapped Media Functions
7861
 
7862
The functions listed below map directly to FR-V M-type instructions.
7863
 
7864
@multitable @columnfractions .45 .32 .23
7865
@item Function prototype @tab Example usage @tab Assembly output
7866
@item @code{uw1 __MABSHS (sw1)}
7867
@tab @code{@var{b} = __MABSHS (@var{a})}
7868
@tab @code{MABSHS @var{a},@var{b}}
7869
@item @code{void __MADDACCS (acc, acc)}
7870
@tab @code{__MADDACCS (@var{b}, @var{a})}
7871
@tab @code{MADDACCS @var{a},@var{b}}
7872
@item @code{sw1 __MADDHSS (sw1, sw1)}
7873
@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
7874
@tab @code{MADDHSS @var{a},@var{b},@var{c}}
7875
@item @code{uw1 __MADDHUS (uw1, uw1)}
7876
@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
7877
@tab @code{MADDHUS @var{a},@var{b},@var{c}}
7878
@item @code{uw1 __MAND (uw1, uw1)}
7879
@tab @code{@var{c} = __MAND (@var{a}, @var{b})}
7880
@tab @code{MAND @var{a},@var{b},@var{c}}
7881
@item @code{void __MASACCS (acc, acc)}
7882
@tab @code{__MASACCS (@var{b}, @var{a})}
7883
@tab @code{MASACCS @var{a},@var{b}}
7884
@item @code{uw1 __MAVEH (uw1, uw1)}
7885
@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
7886
@tab @code{MAVEH @var{a},@var{b},@var{c}}
7887
@item @code{uw2 __MBTOH (uw1)}
7888
@tab @code{@var{b} = __MBTOH (@var{a})}
7889
@tab @code{MBTOH @var{a},@var{b}}
7890
@item @code{void __MBTOHE (uw1 *, uw1)}
7891
@tab @code{__MBTOHE (&@var{b}, @var{a})}
7892
@tab @code{MBTOHE @var{a},@var{b}}
7893
@item @code{void __MCLRACC (acc)}
7894
@tab @code{__MCLRACC (@var{a})}
7895
@tab @code{MCLRACC @var{a}}
7896
@item @code{void __MCLRACCA (void)}
7897
@tab @code{__MCLRACCA ()}
7898
@tab @code{MCLRACCA}
7899
@item @code{uw1 __Mcop1 (uw1, uw1)}
7900
@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
7901
@tab @code{Mcop1 @var{a},@var{b},@var{c}}
7902
@item @code{uw1 __Mcop2 (uw1, uw1)}
7903
@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
7904
@tab @code{Mcop2 @var{a},@var{b},@var{c}}
7905
@item @code{uw1 __MCPLHI (uw2, const)}
7906
@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
7907
@tab @code{MCPLHI @var{a},#@var{b},@var{c}}
7908
@item @code{uw1 __MCPLI (uw2, const)}
7909
@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
7910
@tab @code{MCPLI @var{a},#@var{b},@var{c}}
7911
@item @code{void __MCPXIS (acc, sw1, sw1)}
7912
@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
7913
@tab @code{MCPXIS @var{a},@var{b},@var{c}}
7914
@item @code{void __MCPXIU (acc, uw1, uw1)}
7915
@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
7916
@tab @code{MCPXIU @var{a},@var{b},@var{c}}
7917
@item @code{void __MCPXRS (acc, sw1, sw1)}
7918
@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
7919
@tab @code{MCPXRS @var{a},@var{b},@var{c}}
7920
@item @code{void __MCPXRU (acc, uw1, uw1)}
7921
@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
7922
@tab @code{MCPXRU @var{a},@var{b},@var{c}}
7923
@item @code{uw1 __MCUT (acc, uw1)}
7924
@tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
7925
@tab @code{MCUT @var{a},@var{b},@var{c}}
7926
@item @code{uw1 __MCUTSS (acc, sw1)}
7927
@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
7928
@tab @code{MCUTSS @var{a},@var{b},@var{c}}
7929
@item @code{void __MDADDACCS (acc, acc)}
7930
@tab @code{__MDADDACCS (@var{b}, @var{a})}
7931
@tab @code{MDADDACCS @var{a},@var{b}}
7932
@item @code{void __MDASACCS (acc, acc)}
7933
@tab @code{__MDASACCS (@var{b}, @var{a})}
7934
@tab @code{MDASACCS @var{a},@var{b}}
7935
@item @code{uw2 __MDCUTSSI (acc, const)}
7936
@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
7937
@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
7938
@item @code{uw2 __MDPACKH (uw2, uw2)}
7939
@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
7940
@tab @code{MDPACKH @var{a},@var{b},@var{c}}
7941
@item @code{uw2 __MDROTLI (uw2, const)}
7942
@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
7943
@tab @code{MDROTLI @var{a},#@var{b},@var{c}}
7944
@item @code{void __MDSUBACCS (acc, acc)}
7945
@tab @code{__MDSUBACCS (@var{b}, @var{a})}
7946
@tab @code{MDSUBACCS @var{a},@var{b}}
7947
@item @code{void __MDUNPACKH (uw1 *, uw2)}
7948
@tab @code{__MDUNPACKH (&@var{b}, @var{a})}
7949
@tab @code{MDUNPACKH @var{a},@var{b}}
7950
@item @code{uw2 __MEXPDHD (uw1, const)}
7951
@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
7952
@tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
7953
@item @code{uw1 __MEXPDHW (uw1, const)}
7954
@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
7955
@tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
7956
@item @code{uw1 __MHDSETH (uw1, const)}
7957
@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
7958
@tab @code{MHDSETH @var{a},#@var{b},@var{c}}
7959
@item @code{sw1 __MHDSETS (const)}
7960
@tab @code{@var{b} = __MHDSETS (@var{a})}
7961
@tab @code{MHDSETS #@var{a},@var{b}}
7962
@item @code{uw1 __MHSETHIH (uw1, const)}
7963
@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
7964
@tab @code{MHSETHIH #@var{a},@var{b}}
7965
@item @code{sw1 __MHSETHIS (sw1, const)}
7966
@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
7967
@tab @code{MHSETHIS #@var{a},@var{b}}
7968
@item @code{uw1 __MHSETLOH (uw1, const)}
7969
@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
7970
@tab @code{MHSETLOH #@var{a},@var{b}}
7971
@item @code{sw1 __MHSETLOS (sw1, const)}
7972
@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
7973
@tab @code{MHSETLOS #@var{a},@var{b}}
7974
@item @code{uw1 __MHTOB (uw2)}
7975
@tab @code{@var{b} = __MHTOB (@var{a})}
7976
@tab @code{MHTOB @var{a},@var{b}}
7977
@item @code{void __MMACHS (acc, sw1, sw1)}
7978
@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
7979
@tab @code{MMACHS @var{a},@var{b},@var{c}}
7980
@item @code{void __MMACHU (acc, uw1, uw1)}
7981
@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
7982
@tab @code{MMACHU @var{a},@var{b},@var{c}}
7983
@item @code{void __MMRDHS (acc, sw1, sw1)}
7984
@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
7985
@tab @code{MMRDHS @var{a},@var{b},@var{c}}
7986
@item @code{void __MMRDHU (acc, uw1, uw1)}
7987
@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
7988
@tab @code{MMRDHU @var{a},@var{b},@var{c}}
7989
@item @code{void __MMULHS (acc, sw1, sw1)}
7990
@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
7991
@tab @code{MMULHS @var{a},@var{b},@var{c}}
7992
@item @code{void __MMULHU (acc, uw1, uw1)}
7993
@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
7994
@tab @code{MMULHU @var{a},@var{b},@var{c}}
7995
@item @code{void __MMULXHS (acc, sw1, sw1)}
7996
@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
7997
@tab @code{MMULXHS @var{a},@var{b},@var{c}}
7998
@item @code{void __MMULXHU (acc, uw1, uw1)}
7999
@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
8000
@tab @code{MMULXHU @var{a},@var{b},@var{c}}
8001
@item @code{uw1 __MNOT (uw1)}
8002
@tab @code{@var{b} = __MNOT (@var{a})}
8003
@tab @code{MNOT @var{a},@var{b}}
8004
@item @code{uw1 __MOR (uw1, uw1)}
8005
@tab @code{@var{c} = __MOR (@var{a}, @var{b})}
8006
@tab @code{MOR @var{a},@var{b},@var{c}}
8007
@item @code{uw1 __MPACKH (uh, uh)}
8008
@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
8009
@tab @code{MPACKH @var{a},@var{b},@var{c}}
8010
@item @code{sw2 __MQADDHSS (sw2, sw2)}
8011
@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
8012
@tab @code{MQADDHSS @var{a},@var{b},@var{c}}
8013
@item @code{uw2 __MQADDHUS (uw2, uw2)}
8014
@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
8015
@tab @code{MQADDHUS @var{a},@var{b},@var{c}}
8016
@item @code{void __MQCPXIS (acc, sw2, sw2)}
8017
@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
8018
@tab @code{MQCPXIS @var{a},@var{b},@var{c}}
8019
@item @code{void __MQCPXIU (acc, uw2, uw2)}
8020
@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
8021
@tab @code{MQCPXIU @var{a},@var{b},@var{c}}
8022
@item @code{void __MQCPXRS (acc, sw2, sw2)}
8023
@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
8024
@tab @code{MQCPXRS @var{a},@var{b},@var{c}}
8025
@item @code{void __MQCPXRU (acc, uw2, uw2)}
8026
@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
8027
@tab @code{MQCPXRU @var{a},@var{b},@var{c}}
8028
@item @code{sw2 __MQLCLRHS (sw2, sw2)}
8029
@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
8030
@tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
8031
@item @code{sw2 __MQLMTHS (sw2, sw2)}
8032
@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
8033
@tab @code{MQLMTHS @var{a},@var{b},@var{c}}
8034
@item @code{void __MQMACHS (acc, sw2, sw2)}
8035
@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
8036
@tab @code{MQMACHS @var{a},@var{b},@var{c}}
8037
@item @code{void __MQMACHU (acc, uw2, uw2)}
8038
@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
8039
@tab @code{MQMACHU @var{a},@var{b},@var{c}}
8040
@item @code{void __MQMACXHS (acc, sw2, sw2)}
8041
@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
8042
@tab @code{MQMACXHS @var{a},@var{b},@var{c}}
8043
@item @code{void __MQMULHS (acc, sw2, sw2)}
8044
@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
8045
@tab @code{MQMULHS @var{a},@var{b},@var{c}}
8046
@item @code{void __MQMULHU (acc, uw2, uw2)}
8047
@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
8048
@tab @code{MQMULHU @var{a},@var{b},@var{c}}
8049
@item @code{void __MQMULXHS (acc, sw2, sw2)}
8050
@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
8051
@tab @code{MQMULXHS @var{a},@var{b},@var{c}}
8052
@item @code{void __MQMULXHU (acc, uw2, uw2)}
8053
@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
8054
@tab @code{MQMULXHU @var{a},@var{b},@var{c}}
8055
@item @code{sw2 __MQSATHS (sw2, sw2)}
8056
@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
8057
@tab @code{MQSATHS @var{a},@var{b},@var{c}}
8058
@item @code{uw2 __MQSLLHI (uw2, int)}
8059
@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
8060
@tab @code{MQSLLHI @var{a},@var{b},@var{c}}
8061
@item @code{sw2 __MQSRAHI (sw2, int)}
8062
@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
8063
@tab @code{MQSRAHI @var{a},@var{b},@var{c}}
8064
@item @code{sw2 __MQSUBHSS (sw2, sw2)}
8065
@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
8066
@tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
8067
@item @code{uw2 __MQSUBHUS (uw2, uw2)}
8068
@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
8069
@tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
8070
@item @code{void __MQXMACHS (acc, sw2, sw2)}
8071
@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
8072
@tab @code{MQXMACHS @var{a},@var{b},@var{c}}
8073
@item @code{void __MQXMACXHS (acc, sw2, sw2)}
8074
@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
8075
@tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
8076
@item @code{uw1 __MRDACC (acc)}
8077
@tab @code{@var{b} = __MRDACC (@var{a})}
8078
@tab @code{MRDACC @var{a},@var{b}}
8079
@item @code{uw1 __MRDACCG (acc)}
8080
@tab @code{@var{b} = __MRDACCG (@var{a})}
8081
@tab @code{MRDACCG @var{a},@var{b}}
8082
@item @code{uw1 __MROTLI (uw1, const)}
8083
@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
8084
@tab @code{MROTLI @var{a},#@var{b},@var{c}}
8085
@item @code{uw1 __MROTRI (uw1, const)}
8086
@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
8087
@tab @code{MROTRI @var{a},#@var{b},@var{c}}
8088
@item @code{sw1 __MSATHS (sw1, sw1)}
8089
@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
8090
@tab @code{MSATHS @var{a},@var{b},@var{c}}
8091
@item @code{uw1 __MSATHU (uw1, uw1)}
8092
@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
8093
@tab @code{MSATHU @var{a},@var{b},@var{c}}
8094
@item @code{uw1 __MSLLHI (uw1, const)}
8095
@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
8096
@tab @code{MSLLHI @var{a},#@var{b},@var{c}}
8097
@item @code{sw1 __MSRAHI (sw1, const)}
8098
@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
8099
@tab @code{MSRAHI @var{a},#@var{b},@var{c}}
8100
@item @code{uw1 __MSRLHI (uw1, const)}
8101
@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
8102
@tab @code{MSRLHI @var{a},#@var{b},@var{c}}
8103
@item @code{void __MSUBACCS (acc, acc)}
8104
@tab @code{__MSUBACCS (@var{b}, @var{a})}
8105
@tab @code{MSUBACCS @var{a},@var{b}}
8106
@item @code{sw1 __MSUBHSS (sw1, sw1)}
8107
@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
8108
@tab @code{MSUBHSS @var{a},@var{b},@var{c}}
8109
@item @code{uw1 __MSUBHUS (uw1, uw1)}
8110
@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
8111
@tab @code{MSUBHUS @var{a},@var{b},@var{c}}
8112
@item @code{void __MTRAP (void)}
8113
@tab @code{__MTRAP ()}
8114
@tab @code{MTRAP}
8115
@item @code{uw2 __MUNPACKH (uw1)}
8116
@tab @code{@var{b} = __MUNPACKH (@var{a})}
8117
@tab @code{MUNPACKH @var{a},@var{b}}
8118
@item @code{uw1 __MWCUT (uw2, uw1)}
8119
@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
8120
@tab @code{MWCUT @var{a},@var{b},@var{c}}
8121
@item @code{void __MWTACC (acc, uw1)}
8122
@tab @code{__MWTACC (@var{b}, @var{a})}
8123
@tab @code{MWTACC @var{a},@var{b}}
8124
@item @code{void __MWTACCG (acc, uw1)}
8125
@tab @code{__MWTACCG (@var{b}, @var{a})}
8126
@tab @code{MWTACCG @var{a},@var{b}}
8127
@item @code{uw1 __MXOR (uw1, uw1)}
8128
@tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
8129
@tab @code{MXOR @var{a},@var{b},@var{c}}
8130
@end multitable
8131
 
8132
@node Raw read/write Functions
8133
@subsubsection Raw read/write Functions
8134
 
8135
This sections describes built-in functions related to read and write
8136
instructions to access memory.  These functions generate
8137
@code{membar} instructions to flush the I/O load and stores where
8138
appropriate, as described in Fujitsu's manual described above.
8139
 
8140
@table @code
8141
 
8142
@item unsigned char __builtin_read8 (void *@var{data})
8143
@item unsigned short __builtin_read16 (void *@var{data})
8144
@item unsigned long __builtin_read32 (void *@var{data})
8145
@item unsigned long long __builtin_read64 (void *@var{data})
8146
 
8147
@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
8148
@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
8149
@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
8150
@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
8151
@end table
8152
 
8153
@node Other Built-in Functions
8154
@subsubsection Other Built-in Functions
8155
 
8156
This section describes built-in functions that are not named after
8157
a specific FR-V instruction.
8158
 
8159
@table @code
8160
@item sw2 __IACCreadll (iacc @var{reg})
8161
Return the full 64-bit value of IACC0@.  The @var{reg} argument is reserved
8162
for future expansion and must be 0.
8163
 
8164
@item sw1 __IACCreadl (iacc @var{reg})
8165
Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
8166
Other values of @var{reg} are rejected as invalid.
8167
 
8168
@item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
8169
Set the full 64-bit value of IACC0 to @var{x}.  The @var{reg} argument
8170
is reserved for future expansion and must be 0.
8171
 
8172
@item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
8173
Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
8174
is 1.  Other values of @var{reg} are rejected as invalid.
8175
 
8176
@item void __data_prefetch0 (const void *@var{x})
8177
Use the @code{dcpl} instruction to load the contents of address @var{x}
8178
into the data cache.
8179
 
8180
@item void __data_prefetch (const void *@var{x})
8181
Use the @code{nldub} instruction to load the contents of address @var{x}
8182
into the data cache.  The instruction will be issued in slot I1@.
8183
@end table
8184
 
8185
@node X86 Built-in Functions
8186
@subsection X86 Built-in Functions
8187
 
8188
These built-in functions are available for the i386 and x86-64 family
8189
of computers, depending on the command-line switches used.
8190
 
8191
Note that, if you specify command-line switches such as @option{-msse},
8192
the compiler could use the extended instruction sets even if the built-ins
8193
are not used explicitly in the program.  For this reason, applications
8194
which perform runtime CPU detection must compile separate files for each
8195
supported architecture, using the appropriate flags.  In particular,
8196
the file containing the CPU detection code should be compiled without
8197
these options.
8198
 
8199
The following machine modes are available for use with MMX built-in functions
8200
(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
8201
@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
8202
vector of eight 8-bit integers.  Some of the built-in functions operate on
8203
MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
8204
 
8205
If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
8206
of two 32-bit floating point values.
8207
 
8208
If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
8209
floating point values.  Some instructions use a vector of four 32-bit
8210
integers, these use @code{V4SI}.  Finally, some instructions operate on an
8211
entire vector register, interpreting it as a 128-bit integer, these use mode
8212
@code{TI}.
8213
 
8214
In 64-bit mode, the x86-64 family of processors uses additional built-in
8215
functions for efficient use of @code{TF} (@code{__float128}) 128-bit
8216
floating point and @code{TC} 128-bit complex floating point values.
8217
 
8218
The following floating point built-in functions are available in 64-bit
8219
mode.  All of them implement the function that is part of the name.
8220
 
8221
@smallexample
8222
__float128 __builtin_fabsq (__float128)
8223
__float128 __builtin_copysignq (__float128, __float128)
8224
@end smallexample
8225
 
8226
The following floating point built-in functions are made available in the
8227
64-bit mode.
8228
 
8229
@table @code
8230
@item __float128 __builtin_infq (void)
8231
Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
8232
@findex __builtin_infq
8233
 
8234
@item __float128 __builtin_huge_valq (void)
8235
Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
8236
@findex __builtin_huge_valq
8237
@end table
8238
 
8239
The following built-in functions are made available by @option{-mmmx}.
8240
All of them generate the machine instruction that is part of the name.
8241
 
8242
@smallexample
8243
v8qi __builtin_ia32_paddb (v8qi, v8qi)
8244
v4hi __builtin_ia32_paddw (v4hi, v4hi)
8245
v2si __builtin_ia32_paddd (v2si, v2si)
8246
v8qi __builtin_ia32_psubb (v8qi, v8qi)
8247
v4hi __builtin_ia32_psubw (v4hi, v4hi)
8248
v2si __builtin_ia32_psubd (v2si, v2si)
8249
v8qi __builtin_ia32_paddsb (v8qi, v8qi)
8250
v4hi __builtin_ia32_paddsw (v4hi, v4hi)
8251
v8qi __builtin_ia32_psubsb (v8qi, v8qi)
8252
v4hi __builtin_ia32_psubsw (v4hi, v4hi)
8253
v8qi __builtin_ia32_paddusb (v8qi, v8qi)
8254
v4hi __builtin_ia32_paddusw (v4hi, v4hi)
8255
v8qi __builtin_ia32_psubusb (v8qi, v8qi)
8256
v4hi __builtin_ia32_psubusw (v4hi, v4hi)
8257
v4hi __builtin_ia32_pmullw (v4hi, v4hi)
8258
v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
8259
di __builtin_ia32_pand (di, di)
8260
di __builtin_ia32_pandn (di,di)
8261
di __builtin_ia32_por (di, di)
8262
di __builtin_ia32_pxor (di, di)
8263
v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
8264
v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
8265
v2si __builtin_ia32_pcmpeqd (v2si, v2si)
8266
v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
8267
v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
8268
v2si __builtin_ia32_pcmpgtd (v2si, v2si)
8269
v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
8270
v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
8271
v2si __builtin_ia32_punpckhdq (v2si, v2si)
8272
v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
8273
v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
8274
v2si __builtin_ia32_punpckldq (v2si, v2si)
8275
v8qi __builtin_ia32_packsswb (v4hi, v4hi)
8276
v4hi __builtin_ia32_packssdw (v2si, v2si)
8277
v8qi __builtin_ia32_packuswb (v4hi, v4hi)
8278
 
8279
v4hi __builtin_ia32_psllw (v4hi, v4hi)
8280
v2si __builtin_ia32_pslld (v2si, v2si)
8281
v1di __builtin_ia32_psllq (v1di, v1di)
8282
v4hi __builtin_ia32_psrlw (v4hi, v4hi)
8283
v2si __builtin_ia32_psrld (v2si, v2si)
8284
v1di __builtin_ia32_psrlq (v1di, v1di)
8285
v4hi __builtin_ia32_psraw (v4hi, v4hi)
8286
v2si __builtin_ia32_psrad (v2si, v2si)
8287
v4hi __builtin_ia32_psllwi (v4hi, int)
8288
v2si __builtin_ia32_pslldi (v2si, int)
8289
v1di __builtin_ia32_psllqi (v1di, int)
8290
v4hi __builtin_ia32_psrlwi (v4hi, int)
8291
v2si __builtin_ia32_psrldi (v2si, int)
8292
v1di __builtin_ia32_psrlqi (v1di, int)
8293
v4hi __builtin_ia32_psrawi (v4hi, int)
8294
v2si __builtin_ia32_psradi (v2si, int)
8295
 
8296
@end smallexample
8297
 
8298
The following built-in functions are made available either with
8299
@option{-msse}, or with a combination of @option{-m3dnow} and
8300
@option{-march=athlon}.  All of them generate the machine
8301
instruction that is part of the name.
8302
 
8303
@smallexample
8304
v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
8305
v8qi __builtin_ia32_pavgb (v8qi, v8qi)
8306
v4hi __builtin_ia32_pavgw (v4hi, v4hi)
8307
v1di __builtin_ia32_psadbw (v8qi, v8qi)
8308
v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
8309
v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
8310
v8qi __builtin_ia32_pminub (v8qi, v8qi)
8311
v4hi __builtin_ia32_pminsw (v4hi, v4hi)
8312
int __builtin_ia32_pextrw (v4hi, int)
8313
v4hi __builtin_ia32_pinsrw (v4hi, int, int)
8314
int __builtin_ia32_pmovmskb (v8qi)
8315
void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
8316
void __builtin_ia32_movntq (di *, di)
8317
void __builtin_ia32_sfence (void)
8318
@end smallexample
8319
 
8320
The following built-in functions are available when @option{-msse} is used.
8321
All of them generate the machine instruction that is part of the name.
8322
 
8323
@smallexample
8324
int __builtin_ia32_comieq (v4sf, v4sf)
8325
int __builtin_ia32_comineq (v4sf, v4sf)
8326
int __builtin_ia32_comilt (v4sf, v4sf)
8327
int __builtin_ia32_comile (v4sf, v4sf)
8328
int __builtin_ia32_comigt (v4sf, v4sf)
8329
int __builtin_ia32_comige (v4sf, v4sf)
8330
int __builtin_ia32_ucomieq (v4sf, v4sf)
8331
int __builtin_ia32_ucomineq (v4sf, v4sf)
8332
int __builtin_ia32_ucomilt (v4sf, v4sf)
8333
int __builtin_ia32_ucomile (v4sf, v4sf)
8334
int __builtin_ia32_ucomigt (v4sf, v4sf)
8335
int __builtin_ia32_ucomige (v4sf, v4sf)
8336
v4sf __builtin_ia32_addps (v4sf, v4sf)
8337
v4sf __builtin_ia32_subps (v4sf, v4sf)
8338
v4sf __builtin_ia32_mulps (v4sf, v4sf)
8339
v4sf __builtin_ia32_divps (v4sf, v4sf)
8340
v4sf __builtin_ia32_addss (v4sf, v4sf)
8341
v4sf __builtin_ia32_subss (v4sf, v4sf)
8342
v4sf __builtin_ia32_mulss (v4sf, v4sf)
8343
v4sf __builtin_ia32_divss (v4sf, v4sf)
8344
v4si __builtin_ia32_cmpeqps (v4sf, v4sf)
8345
v4si __builtin_ia32_cmpltps (v4sf, v4sf)
8346
v4si __builtin_ia32_cmpleps (v4sf, v4sf)
8347
v4si __builtin_ia32_cmpgtps (v4sf, v4sf)
8348
v4si __builtin_ia32_cmpgeps (v4sf, v4sf)
8349
v4si __builtin_ia32_cmpunordps (v4sf, v4sf)
8350
v4si __builtin_ia32_cmpneqps (v4sf, v4sf)
8351
v4si __builtin_ia32_cmpnltps (v4sf, v4sf)
8352
v4si __builtin_ia32_cmpnleps (v4sf, v4sf)
8353
v4si __builtin_ia32_cmpngtps (v4sf, v4sf)
8354
v4si __builtin_ia32_cmpngeps (v4sf, v4sf)
8355
v4si __builtin_ia32_cmpordps (v4sf, v4sf)
8356
v4si __builtin_ia32_cmpeqss (v4sf, v4sf)
8357
v4si __builtin_ia32_cmpltss (v4sf, v4sf)
8358
v4si __builtin_ia32_cmpless (v4sf, v4sf)
8359
v4si __builtin_ia32_cmpunordss (v4sf, v4sf)
8360
v4si __builtin_ia32_cmpneqss (v4sf, v4sf)
8361
v4si __builtin_ia32_cmpnlts (v4sf, v4sf)
8362
v4si __builtin_ia32_cmpnless (v4sf, v4sf)
8363
v4si __builtin_ia32_cmpordss (v4sf, v4sf)
8364
v4sf __builtin_ia32_maxps (v4sf, v4sf)
8365
v4sf __builtin_ia32_maxss (v4sf, v4sf)
8366
v4sf __builtin_ia32_minps (v4sf, v4sf)
8367
v4sf __builtin_ia32_minss (v4sf, v4sf)
8368
v4sf __builtin_ia32_andps (v4sf, v4sf)
8369
v4sf __builtin_ia32_andnps (v4sf, v4sf)
8370
v4sf __builtin_ia32_orps (v4sf, v4sf)
8371
v4sf __builtin_ia32_xorps (v4sf, v4sf)
8372
v4sf __builtin_ia32_movss (v4sf, v4sf)
8373
v4sf __builtin_ia32_movhlps (v4sf, v4sf)
8374
v4sf __builtin_ia32_movlhps (v4sf, v4sf)
8375
v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
8376
v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
8377
v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
8378
v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
8379
v2si __builtin_ia32_cvtps2pi (v4sf)
8380
int __builtin_ia32_cvtss2si (v4sf)
8381
v2si __builtin_ia32_cvttps2pi (v4sf)
8382
int __builtin_ia32_cvttss2si (v4sf)
8383
v4sf __builtin_ia32_rcpps (v4sf)
8384
v4sf __builtin_ia32_rsqrtps (v4sf)
8385
v4sf __builtin_ia32_sqrtps (v4sf)
8386
v4sf __builtin_ia32_rcpss (v4sf)
8387
v4sf __builtin_ia32_rsqrtss (v4sf)
8388
v4sf __builtin_ia32_sqrtss (v4sf)
8389
v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
8390
void __builtin_ia32_movntps (float *, v4sf)
8391
int __builtin_ia32_movmskps (v4sf)
8392
@end smallexample
8393
 
8394
The following built-in functions are available when @option{-msse} is used.
8395
 
8396
@table @code
8397
@item v4sf __builtin_ia32_loadaps (float *)
8398
Generates the @code{movaps} machine instruction as a load from memory.
8399
@item void __builtin_ia32_storeaps (float *, v4sf)
8400
Generates the @code{movaps} machine instruction as a store to memory.
8401
@item v4sf __builtin_ia32_loadups (float *)
8402
Generates the @code{movups} machine instruction as a load from memory.
8403
@item void __builtin_ia32_storeups (float *, v4sf)
8404
Generates the @code{movups} machine instruction as a store to memory.
8405
@item v4sf __builtin_ia32_loadsss (float *)
8406
Generates the @code{movss} machine instruction as a load from memory.
8407
@item void __builtin_ia32_storess (float *, v4sf)
8408
Generates the @code{movss} machine instruction as a store to memory.
8409
@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
8410
Generates the @code{movhps} machine instruction as a load from memory.
8411
@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
8412
Generates the @code{movlps} machine instruction as a load from memory
8413
@item void __builtin_ia32_storehps (v2sf *, v4sf)
8414
Generates the @code{movhps} machine instruction as a store to memory.
8415
@item void __builtin_ia32_storelps (v2sf *, v4sf)
8416
Generates the @code{movlps} machine instruction as a store to memory.
8417
@end table
8418
 
8419
The following built-in functions are available when @option{-msse2} is used.
8420
All of them generate the machine instruction that is part of the name.
8421
 
8422
@smallexample
8423
int __builtin_ia32_comisdeq (v2df, v2df)
8424
int __builtin_ia32_comisdlt (v2df, v2df)
8425
int __builtin_ia32_comisdle (v2df, v2df)
8426
int __builtin_ia32_comisdgt (v2df, v2df)
8427
int __builtin_ia32_comisdge (v2df, v2df)
8428
int __builtin_ia32_comisdneq (v2df, v2df)
8429
int __builtin_ia32_ucomisdeq (v2df, v2df)
8430
int __builtin_ia32_ucomisdlt (v2df, v2df)
8431
int __builtin_ia32_ucomisdle (v2df, v2df)
8432
int __builtin_ia32_ucomisdgt (v2df, v2df)
8433
int __builtin_ia32_ucomisdge (v2df, v2df)
8434
int __builtin_ia32_ucomisdneq (v2df, v2df)
8435
v2df __builtin_ia32_cmpeqpd (v2df, v2df)
8436
v2df __builtin_ia32_cmpltpd (v2df, v2df)
8437
v2df __builtin_ia32_cmplepd (v2df, v2df)
8438
v2df __builtin_ia32_cmpgtpd (v2df, v2df)
8439
v2df __builtin_ia32_cmpgepd (v2df, v2df)
8440
v2df __builtin_ia32_cmpunordpd (v2df, v2df)
8441
v2df __builtin_ia32_cmpneqpd (v2df, v2df)
8442
v2df __builtin_ia32_cmpnltpd (v2df, v2df)
8443
v2df __builtin_ia32_cmpnlepd (v2df, v2df)
8444
v2df __builtin_ia32_cmpngtpd (v2df, v2df)
8445
v2df __builtin_ia32_cmpngepd (v2df, v2df)
8446
v2df __builtin_ia32_cmpordpd (v2df, v2df)
8447
v2df __builtin_ia32_cmpeqsd (v2df, v2df)
8448
v2df __builtin_ia32_cmpltsd (v2df, v2df)
8449
v2df __builtin_ia32_cmplesd (v2df, v2df)
8450
v2df __builtin_ia32_cmpunordsd (v2df, v2df)
8451
v2df __builtin_ia32_cmpneqsd (v2df, v2df)
8452
v2df __builtin_ia32_cmpnltsd (v2df, v2df)
8453
v2df __builtin_ia32_cmpnlesd (v2df, v2df)
8454
v2df __builtin_ia32_cmpordsd (v2df, v2df)
8455
v2di __builtin_ia32_paddq (v2di, v2di)
8456
v2di __builtin_ia32_psubq (v2di, v2di)
8457
v2df __builtin_ia32_addpd (v2df, v2df)
8458
v2df __builtin_ia32_subpd (v2df, v2df)
8459
v2df __builtin_ia32_mulpd (v2df, v2df)
8460
v2df __builtin_ia32_divpd (v2df, v2df)
8461
v2df __builtin_ia32_addsd (v2df, v2df)
8462
v2df __builtin_ia32_subsd (v2df, v2df)
8463
v2df __builtin_ia32_mulsd (v2df, v2df)
8464
v2df __builtin_ia32_divsd (v2df, v2df)
8465
v2df __builtin_ia32_minpd (v2df, v2df)
8466
v2df __builtin_ia32_maxpd (v2df, v2df)
8467
v2df __builtin_ia32_minsd (v2df, v2df)
8468
v2df __builtin_ia32_maxsd (v2df, v2df)
8469
v2df __builtin_ia32_andpd (v2df, v2df)
8470
v2df __builtin_ia32_andnpd (v2df, v2df)
8471
v2df __builtin_ia32_orpd (v2df, v2df)
8472
v2df __builtin_ia32_xorpd (v2df, v2df)
8473
v2df __builtin_ia32_movsd (v2df, v2df)
8474
v2df __builtin_ia32_unpckhpd (v2df, v2df)
8475
v2df __builtin_ia32_unpcklpd (v2df, v2df)
8476
v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
8477
v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
8478
v4si __builtin_ia32_paddd128 (v4si, v4si)
8479
v2di __builtin_ia32_paddq128 (v2di, v2di)
8480
v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
8481
v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
8482
v4si __builtin_ia32_psubd128 (v4si, v4si)
8483
v2di __builtin_ia32_psubq128 (v2di, v2di)
8484
v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
8485
v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
8486
v2di __builtin_ia32_pand128 (v2di, v2di)
8487
v2di __builtin_ia32_pandn128 (v2di, v2di)
8488
v2di __builtin_ia32_por128 (v2di, v2di)
8489
v2di __builtin_ia32_pxor128 (v2di, v2di)
8490
v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
8491
v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
8492
v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
8493
v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
8494
v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
8495
v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
8496
v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
8497
v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
8498
v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
8499
v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
8500
v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
8501
v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
8502
v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
8503
v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
8504
v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
8505
v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
8506
v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
8507
v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
8508
v4si __builtin_ia32_punpckldq128 (v4si, v4si)
8509
v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
8510
v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
8511
v8hi __builtin_ia32_packssdw128 (v4si, v4si)
8512
v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
8513
v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
8514
void __builtin_ia32_maskmovdqu (v16qi, v16qi)
8515
v2df __builtin_ia32_loadupd (double *)
8516
void __builtin_ia32_storeupd (double *, v2df)
8517
v2df __builtin_ia32_loadhpd (v2df, double const *)
8518
v2df __builtin_ia32_loadlpd (v2df, double const *)
8519
int __builtin_ia32_movmskpd (v2df)
8520
int __builtin_ia32_pmovmskb128 (v16qi)
8521
void __builtin_ia32_movnti (int *, int)
8522
void __builtin_ia32_movntpd (double *, v2df)
8523
void __builtin_ia32_movntdq (v2df *, v2df)
8524
v4si __builtin_ia32_pshufd (v4si, int)
8525
v8hi __builtin_ia32_pshuflw (v8hi, int)
8526
v8hi __builtin_ia32_pshufhw (v8hi, int)
8527
v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
8528
v2df __builtin_ia32_sqrtpd (v2df)
8529
v2df __builtin_ia32_sqrtsd (v2df)
8530
v2df __builtin_ia32_shufpd (v2df, v2df, int)
8531
v2df __builtin_ia32_cvtdq2pd (v4si)
8532
v4sf __builtin_ia32_cvtdq2ps (v4si)
8533
v4si __builtin_ia32_cvtpd2dq (v2df)
8534
v2si __builtin_ia32_cvtpd2pi (v2df)
8535
v4sf __builtin_ia32_cvtpd2ps (v2df)
8536
v4si __builtin_ia32_cvttpd2dq (v2df)
8537
v2si __builtin_ia32_cvttpd2pi (v2df)
8538
v2df __builtin_ia32_cvtpi2pd (v2si)
8539
int __builtin_ia32_cvtsd2si (v2df)
8540
int __builtin_ia32_cvttsd2si (v2df)
8541
long long __builtin_ia32_cvtsd2si64 (v2df)
8542
long long __builtin_ia32_cvttsd2si64 (v2df)
8543
v4si __builtin_ia32_cvtps2dq (v4sf)
8544
v2df __builtin_ia32_cvtps2pd (v4sf)
8545
v4si __builtin_ia32_cvttps2dq (v4sf)
8546
v2df __builtin_ia32_cvtsi2sd (v2df, int)
8547
v2df __builtin_ia32_cvtsi642sd (v2df, long long)
8548
v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
8549
v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
8550
void __builtin_ia32_clflush (const void *)
8551
void __builtin_ia32_lfence (void)
8552
void __builtin_ia32_mfence (void)
8553
v16qi __builtin_ia32_loaddqu (const char *)
8554
void __builtin_ia32_storedqu (char *, v16qi)
8555
v1di __builtin_ia32_pmuludq (v2si, v2si)
8556
v2di __builtin_ia32_pmuludq128 (v4si, v4si)
8557
v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
8558
v4si __builtin_ia32_pslld128 (v4si, v4si)
8559
v2di __builtin_ia32_psllq128 (v2di, v2di)
8560
v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
8561
v4si __builtin_ia32_psrld128 (v4si, v4si)
8562
v2di __builtin_ia32_psrlq128 (v2di, v2di)
8563
v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
8564
v4si __builtin_ia32_psrad128 (v4si, v4si)
8565
v2di __builtin_ia32_pslldqi128 (v2di, int)
8566
v8hi __builtin_ia32_psllwi128 (v8hi, int)
8567
v4si __builtin_ia32_pslldi128 (v4si, int)
8568
v2di __builtin_ia32_psllqi128 (v2di, int)
8569
v2di __builtin_ia32_psrldqi128 (v2di, int)
8570
v8hi __builtin_ia32_psrlwi128 (v8hi, int)
8571
v4si __builtin_ia32_psrldi128 (v4si, int)
8572
v2di __builtin_ia32_psrlqi128 (v2di, int)
8573
v8hi __builtin_ia32_psrawi128 (v8hi, int)
8574
v4si __builtin_ia32_psradi128 (v4si, int)
8575
v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
8576
v2di __builtin_ia32_movq128 (v2di)
8577
@end smallexample
8578
 
8579
The following built-in functions are available when @option{-msse3} is used.
8580
All of them generate the machine instruction that is part of the name.
8581
 
8582
@smallexample
8583
v2df __builtin_ia32_addsubpd (v2df, v2df)
8584
v4sf __builtin_ia32_addsubps (v4sf, v4sf)
8585
v2df __builtin_ia32_haddpd (v2df, v2df)
8586
v4sf __builtin_ia32_haddps (v4sf, v4sf)
8587
v2df __builtin_ia32_hsubpd (v2df, v2df)
8588
v4sf __builtin_ia32_hsubps (v4sf, v4sf)
8589
v16qi __builtin_ia32_lddqu (char const *)
8590
void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
8591
v2df __builtin_ia32_movddup (v2df)
8592
v4sf __builtin_ia32_movshdup (v4sf)
8593
v4sf __builtin_ia32_movsldup (v4sf)
8594
void __builtin_ia32_mwait (unsigned int, unsigned int)
8595
@end smallexample
8596
 
8597
The following built-in functions are available when @option{-msse3} is used.
8598
 
8599
@table @code
8600
@item v2df __builtin_ia32_loadddup (double const *)
8601
Generates the @code{movddup} machine instruction as a load from memory.
8602
@end table
8603
 
8604
The following built-in functions are available when @option{-mssse3} is used.
8605
All of them generate the machine instruction that is part of the name
8606
with MMX registers.
8607
 
8608
@smallexample
8609
v2si __builtin_ia32_phaddd (v2si, v2si)
8610
v4hi __builtin_ia32_phaddw (v4hi, v4hi)
8611
v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
8612
v2si __builtin_ia32_phsubd (v2si, v2si)
8613
v4hi __builtin_ia32_phsubw (v4hi, v4hi)
8614
v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
8615
v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
8616
v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
8617
v8qi __builtin_ia32_pshufb (v8qi, v8qi)
8618
v8qi __builtin_ia32_psignb (v8qi, v8qi)
8619
v2si __builtin_ia32_psignd (v2si, v2si)
8620
v4hi __builtin_ia32_psignw (v4hi, v4hi)
8621
v1di __builtin_ia32_palignr (v1di, v1di, int)
8622
v8qi __builtin_ia32_pabsb (v8qi)
8623
v2si __builtin_ia32_pabsd (v2si)
8624
v4hi __builtin_ia32_pabsw (v4hi)
8625
@end smallexample
8626
 
8627
The following built-in functions are available when @option{-mssse3} is used.
8628
All of them generate the machine instruction that is part of the name
8629
with SSE registers.
8630
 
8631
@smallexample
8632
v4si __builtin_ia32_phaddd128 (v4si, v4si)
8633
v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
8634
v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
8635
v4si __builtin_ia32_phsubd128 (v4si, v4si)
8636
v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
8637
v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
8638
v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
8639
v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
8640
v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
8641
v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
8642
v4si __builtin_ia32_psignd128 (v4si, v4si)
8643
v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
8644
v2di __builtin_ia32_palignr128 (v2di, v2di, int)
8645
v16qi __builtin_ia32_pabsb128 (v16qi)
8646
v4si __builtin_ia32_pabsd128 (v4si)
8647
v8hi __builtin_ia32_pabsw128 (v8hi)
8648
@end smallexample
8649
 
8650
The following built-in functions are available when @option{-msse4.1} is
8651
used.  All of them generate the machine instruction that is part of the
8652
name.
8653
 
8654
@smallexample
8655
v2df __builtin_ia32_blendpd (v2df, v2df, const int)
8656
v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
8657
v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
8658
v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
8659
v2df __builtin_ia32_dppd (v2df, v2df, const int)
8660
v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
8661
v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
8662
v2di __builtin_ia32_movntdqa (v2di *);
8663
v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
8664
v8hi __builtin_ia32_packusdw128 (v4si, v4si)
8665
v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
8666
v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
8667
v2di __builtin_ia32_pcmpeqq (v2di, v2di)
8668
v8hi __builtin_ia32_phminposuw128 (v8hi)
8669
v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
8670
v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
8671
v4si __builtin_ia32_pmaxud128 (v4si, v4si)
8672
v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
8673
v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
8674
v4si __builtin_ia32_pminsd128 (v4si, v4si)
8675
v4si __builtin_ia32_pminud128 (v4si, v4si)
8676
v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
8677
v4si __builtin_ia32_pmovsxbd128 (v16qi)
8678
v2di __builtin_ia32_pmovsxbq128 (v16qi)
8679
v8hi __builtin_ia32_pmovsxbw128 (v16qi)
8680
v2di __builtin_ia32_pmovsxdq128 (v4si)
8681
v4si __builtin_ia32_pmovsxwd128 (v8hi)
8682
v2di __builtin_ia32_pmovsxwq128 (v8hi)
8683
v4si __builtin_ia32_pmovzxbd128 (v16qi)
8684
v2di __builtin_ia32_pmovzxbq128 (v16qi)
8685
v8hi __builtin_ia32_pmovzxbw128 (v16qi)
8686
v2di __builtin_ia32_pmovzxdq128 (v4si)
8687
v4si __builtin_ia32_pmovzxwd128 (v8hi)
8688
v2di __builtin_ia32_pmovzxwq128 (v8hi)
8689
v2di __builtin_ia32_pmuldq128 (v4si, v4si)
8690
v4si __builtin_ia32_pmulld128 (v4si, v4si)
8691
int __builtin_ia32_ptestc128 (v2di, v2di)
8692
int __builtin_ia32_ptestnzc128 (v2di, v2di)
8693
int __builtin_ia32_ptestz128 (v2di, v2di)
8694
v2df __builtin_ia32_roundpd (v2df, const int)
8695
v4sf __builtin_ia32_roundps (v4sf, const int)
8696
v2df __builtin_ia32_roundsd (v2df, v2df, const int)
8697
v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
8698
@end smallexample
8699
 
8700
The following built-in functions are available when @option{-msse4.1} is
8701
used.
8702
 
8703
@table @code
8704
@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
8705
Generates the @code{insertps} machine instruction.
8706
@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
8707
Generates the @code{pextrb} machine instruction.
8708
@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
8709
Generates the @code{pinsrb} machine instruction.
8710
@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
8711
Generates the @code{pinsrd} machine instruction.
8712
@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
8713
Generates the @code{pinsrq} machine instruction in 64bit mode.
8714
@end table
8715
 
8716
The following built-in functions are changed to generate new SSE4.1
8717
instructions when @option{-msse4.1} is used.
8718
 
8719
@table @code
8720
@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
8721
Generates the @code{extractps} machine instruction.
8722
@item int __builtin_ia32_vec_ext_v4si (v4si, const int)
8723
Generates the @code{pextrd} machine instruction.
8724
@item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
8725
Generates the @code{pextrq} machine instruction in 64bit mode.
8726
@end table
8727
 
8728
The following built-in functions are available when @option{-msse4.2} is
8729
used.  All of them generate the machine instruction that is part of the
8730
name.
8731
 
8732
@smallexample
8733
v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
8734
int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
8735
int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
8736
int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
8737
int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
8738
int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
8739
int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
8740
v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
8741
int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
8742
int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
8743
int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
8744
int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
8745
int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
8746
int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
8747
v2di __builtin_ia32_pcmpgtq (v2di, v2di)
8748
@end smallexample
8749
 
8750
The following built-in functions are available when @option{-msse4.2} is
8751
used.
8752
 
8753
@table @code
8754
@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
8755
Generates the @code{crc32b} machine instruction.
8756
@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
8757
Generates the @code{crc32w} machine instruction.
8758
@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
8759
Generates the @code{crc32l} machine instruction.
8760
@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
8761
Generates the @code{crc32q} machine instruction.
8762
@end table
8763
 
8764
The following built-in functions are changed to generate new SSE4.2
8765
instructions when @option{-msse4.2} is used.
8766
 
8767
@table @code
8768
@item int __builtin_popcount (unsigned int)
8769
Generates the @code{popcntl} machine instruction.
8770
@item int __builtin_popcountl (unsigned long)
8771
Generates the @code{popcntl} or @code{popcntq} machine instruction,
8772
depending on the size of @code{unsigned long}.
8773
@item int __builtin_popcountll (unsigned long long)
8774
Generates the @code{popcntq} machine instruction.
8775
@end table
8776
 
8777
The following built-in functions are available when @option{-mavx} is
8778
used. All of them generate the machine instruction that is part of the
8779
name.
8780
 
8781
@smallexample
8782
v4df __builtin_ia32_addpd256 (v4df,v4df)
8783
v8sf __builtin_ia32_addps256 (v8sf,v8sf)
8784
v4df __builtin_ia32_addsubpd256 (v4df,v4df)
8785
v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
8786
v4df __builtin_ia32_andnpd256 (v4df,v4df)
8787
v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
8788
v4df __builtin_ia32_andpd256 (v4df,v4df)
8789
v8sf __builtin_ia32_andps256 (v8sf,v8sf)
8790
v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
8791
v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
8792
v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
8793
v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
8794
v2df __builtin_ia32_cmppd (v2df,v2df,int)
8795
v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
8796
v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
8797
v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
8798
v2df __builtin_ia32_cmpsd (v2df,v2df,int)
8799
v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
8800
v4df __builtin_ia32_cvtdq2pd256 (v4si)
8801
v8sf __builtin_ia32_cvtdq2ps256 (v8si)
8802
v4si __builtin_ia32_cvtpd2dq256 (v4df)
8803
v4sf __builtin_ia32_cvtpd2ps256 (v4df)
8804
v8si __builtin_ia32_cvtps2dq256 (v8sf)
8805
v4df __builtin_ia32_cvtps2pd256 (v4sf)
8806
v4si __builtin_ia32_cvttpd2dq256 (v4df)
8807
v8si __builtin_ia32_cvttps2dq256 (v8sf)
8808
v4df __builtin_ia32_divpd256 (v4df,v4df)
8809
v8sf __builtin_ia32_divps256 (v8sf,v8sf)
8810
v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
8811
v4df __builtin_ia32_haddpd256 (v4df,v4df)
8812
v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
8813
v4df __builtin_ia32_hsubpd256 (v4df,v4df)
8814
v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
8815
v32qi __builtin_ia32_lddqu256 (pcchar)
8816
v32qi __builtin_ia32_loaddqu256 (pcchar)
8817
v4df __builtin_ia32_loadupd256 (pcdouble)
8818
v8sf __builtin_ia32_loadups256 (pcfloat)
8819
v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
8820
v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
8821
v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
8822
v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
8823
void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
8824
void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
8825
void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
8826
void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
8827
v4df __builtin_ia32_maxpd256 (v4df,v4df)
8828
v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
8829
v4df __builtin_ia32_minpd256 (v4df,v4df)
8830
v8sf __builtin_ia32_minps256 (v8sf,v8sf)
8831
v4df __builtin_ia32_movddup256 (v4df)
8832
int __builtin_ia32_movmskpd256 (v4df)
8833
int __builtin_ia32_movmskps256 (v8sf)
8834
v8sf __builtin_ia32_movshdup256 (v8sf)
8835
v8sf __builtin_ia32_movsldup256 (v8sf)
8836
v4df __builtin_ia32_mulpd256 (v4df,v4df)
8837
v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
8838
v4df __builtin_ia32_orpd256 (v4df,v4df)
8839
v8sf __builtin_ia32_orps256 (v8sf,v8sf)
8840
v2df __builtin_ia32_pd_pd256 (v4df)
8841
v4df __builtin_ia32_pd256_pd (v2df)
8842
v4sf __builtin_ia32_ps_ps256 (v8sf)
8843
v8sf __builtin_ia32_ps256_ps (v4sf)
8844
int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
8845
int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
8846
int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
8847
v8sf __builtin_ia32_rcpps256 (v8sf)
8848
v4df __builtin_ia32_roundpd256 (v4df,int)
8849
v8sf __builtin_ia32_roundps256 (v8sf,int)
8850
v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
8851
v8sf __builtin_ia32_rsqrtps256 (v8sf)
8852
v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
8853
v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
8854
v4si __builtin_ia32_si_si256 (v8si)
8855
v8si __builtin_ia32_si256_si (v4si)
8856
v4df __builtin_ia32_sqrtpd256 (v4df)
8857
v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
8858
v8sf __builtin_ia32_sqrtps256 (v8sf)
8859
void __builtin_ia32_storedqu256 (pchar,v32qi)
8860
void __builtin_ia32_storeupd256 (pdouble,v4df)
8861
void __builtin_ia32_storeups256 (pfloat,v8sf)
8862
v4df __builtin_ia32_subpd256 (v4df,v4df)
8863
v8sf __builtin_ia32_subps256 (v8sf,v8sf)
8864
v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
8865
v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
8866
v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
8867
v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
8868
v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
8869
v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
8870
v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
8871
v4sf __builtin_ia32_vbroadcastss (pcfloat)
8872
v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
8873
v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
8874
v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
8875
v4si __builtin_ia32_vextractf128_si256 (v8si,int)
8876
v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
8877
v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
8878
v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
8879
v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
8880
v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
8881
v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
8882
v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
8883
v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
8884
v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
8885
v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
8886
v2df __builtin_ia32_vpermilpd (v2df,int)
8887
v4df __builtin_ia32_vpermilpd256 (v4df,int)
8888
v4sf __builtin_ia32_vpermilps (v4sf,int)
8889
v8sf __builtin_ia32_vpermilps256 (v8sf,int)
8890
v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
8891
v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
8892
v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
8893
v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
8894
int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
8895
int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
8896
int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
8897
int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
8898
int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
8899
int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
8900
int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
8901
int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
8902
int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
8903
int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
8904
int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
8905
int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
8906
void __builtin_ia32_vzeroall (void)
8907
void __builtin_ia32_vzeroupper (void)
8908
v4df __builtin_ia32_xorpd256 (v4df,v4df)
8909
v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
8910
@end smallexample
8911
 
8912
The following built-in functions are available when @option{-maes} is
8913
used.  All of them generate the machine instruction that is part of the
8914
name.
8915
 
8916
@smallexample
8917
v2di __builtin_ia32_aesenc128 (v2di, v2di)
8918
v2di __builtin_ia32_aesenclast128 (v2di, v2di)
8919
v2di __builtin_ia32_aesdec128 (v2di, v2di)
8920
v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
8921
v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
8922
v2di __builtin_ia32_aesimc128 (v2di)
8923
@end smallexample
8924
 
8925
The following built-in function is available when @option{-mpclmul} is
8926
used.
8927
 
8928
@table @code
8929
@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
8930
Generates the @code{pclmulqdq} machine instruction.
8931
@end table
8932
 
8933
The following built-in functions are available when @option{-msse4a} is used.
8934
All of them generate the machine instruction that is part of the name.
8935
 
8936
@smallexample
8937
void __builtin_ia32_movntsd (double *, v2df)
8938
void __builtin_ia32_movntss (float *, v4sf)
8939
v2di __builtin_ia32_extrq  (v2di, v16qi)
8940
v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
8941
v2di __builtin_ia32_insertq (v2di, v2di)
8942
v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
8943
@end smallexample
8944
 
8945
The following built-in functions are available when @option{-mxop} is used.
8946
@smallexample
8947
v2df __builtin_ia32_vfrczpd (v2df)
8948
v4sf __builtin_ia32_vfrczps (v4sf)
8949
v2df __builtin_ia32_vfrczsd (v2df, v2df)
8950
v4sf __builtin_ia32_vfrczss (v4sf, v4sf)
8951
v4df __builtin_ia32_vfrczpd256 (v4df)
8952
v8sf __builtin_ia32_vfrczps256 (v8sf)
8953
v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
8954
v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
8955
v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
8956
v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
8957
v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
8958
v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
8959
v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
8960
v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
8961
v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
8962
v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
8963
v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
8964
v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
8965
v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
8966
v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
8967
v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
8968
v4si __builtin_ia32_vpcomeqd (v4si, v4si)
8969
v2di __builtin_ia32_vpcomeqq (v2di, v2di)
8970
v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
8971
v4si __builtin_ia32_vpcomequd (v4si, v4si)
8972
v2di __builtin_ia32_vpcomequq (v2di, v2di)
8973
v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
8974
v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
8975
v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
8976
v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
8977
v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
8978
v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
8979
v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
8980
v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
8981
v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
8982
v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
8983
v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
8984
v4si __builtin_ia32_vpcomged (v4si, v4si)
8985
v2di __builtin_ia32_vpcomgeq (v2di, v2di)
8986
v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
8987
v4si __builtin_ia32_vpcomgeud (v4si, v4si)
8988
v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
8989
v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
8990
v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
8991
v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
8992
v4si __builtin_ia32_vpcomgtd (v4si, v4si)
8993
v2di __builtin_ia32_vpcomgtq (v2di, v2di)
8994
v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
8995
v4si __builtin_ia32_vpcomgtud (v4si, v4si)
8996
v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
8997
v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
8998
v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
8999
v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
9000
v4si __builtin_ia32_vpcomled (v4si, v4si)
9001
v2di __builtin_ia32_vpcomleq (v2di, v2di)
9002
v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
9003
v4si __builtin_ia32_vpcomleud (v4si, v4si)
9004
v2di __builtin_ia32_vpcomleuq (v2di, v2di)
9005
v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
9006
v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
9007
v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
9008
v4si __builtin_ia32_vpcomltd (v4si, v4si)
9009
v2di __builtin_ia32_vpcomltq (v2di, v2di)
9010
v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
9011
v4si __builtin_ia32_vpcomltud (v4si, v4si)
9012
v2di __builtin_ia32_vpcomltuq (v2di, v2di)
9013
v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
9014
v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
9015
v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
9016
v4si __builtin_ia32_vpcomned (v4si, v4si)
9017
v2di __builtin_ia32_vpcomneq (v2di, v2di)
9018
v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
9019
v4si __builtin_ia32_vpcomneud (v4si, v4si)
9020
v2di __builtin_ia32_vpcomneuq (v2di, v2di)
9021
v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
9022
v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
9023
v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
9024
v4si __builtin_ia32_vpcomtrued (v4si, v4si)
9025
v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
9026
v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
9027
v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
9028
v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
9029
v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
9030
v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
9031
v4si __builtin_ia32_vphaddbd (v16qi)
9032
v2di __builtin_ia32_vphaddbq (v16qi)
9033
v8hi __builtin_ia32_vphaddbw (v16qi)
9034
v2di __builtin_ia32_vphadddq (v4si)
9035
v4si __builtin_ia32_vphaddubd (v16qi)
9036
v2di __builtin_ia32_vphaddubq (v16qi)
9037
v8hi __builtin_ia32_vphaddubw (v16qi)
9038
v2di __builtin_ia32_vphaddudq (v4si)
9039
v4si __builtin_ia32_vphadduwd (v8hi)
9040
v2di __builtin_ia32_vphadduwq (v8hi)
9041
v4si __builtin_ia32_vphaddwd (v8hi)
9042
v2di __builtin_ia32_vphaddwq (v8hi)
9043
v8hi __builtin_ia32_vphsubbw (v16qi)
9044
v2di __builtin_ia32_vphsubdq (v4si)
9045
v4si __builtin_ia32_vphsubwd (v8hi)
9046
v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
9047
v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
9048
v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
9049
v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
9050
v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
9051
v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
9052
v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
9053
v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
9054
v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
9055
v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
9056
v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
9057
v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
9058
v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
9059
v16qi __builtin_ia32_vprotb (v16qi, v16qi)
9060
v4si __builtin_ia32_vprotd (v4si, v4si)
9061
v2di __builtin_ia32_vprotq (v2di, v2di)
9062
v8hi __builtin_ia32_vprotw (v8hi, v8hi)
9063
v16qi __builtin_ia32_vpshab (v16qi, v16qi)
9064
v4si __builtin_ia32_vpshad (v4si, v4si)
9065
v2di __builtin_ia32_vpshaq (v2di, v2di)
9066
v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
9067
v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
9068
v4si __builtin_ia32_vpshld (v4si, v4si)
9069
v2di __builtin_ia32_vpshlq (v2di, v2di)
9070
v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
9071
@end smallexample
9072
 
9073
The following built-in functions are available when @option{-mfma4} is used.
9074
All of them generate the machine instruction that is part of the name
9075
with MMX registers.
9076
 
9077
@smallexample
9078
v2df __builtin_ia32_fmaddpd (v2df, v2df, v2df)
9079
v4sf __builtin_ia32_fmaddps (v4sf, v4sf, v4sf)
9080
v2df __builtin_ia32_fmaddsd (v2df, v2df, v2df)
9081
v4sf __builtin_ia32_fmaddss (v4sf, v4sf, v4sf)
9082
v2df __builtin_ia32_fmsubpd (v2df, v2df, v2df)
9083
v4sf __builtin_ia32_fmsubps (v4sf, v4sf, v4sf)
9084
v2df __builtin_ia32_fmsubsd (v2df, v2df, v2df)
9085
v4sf __builtin_ia32_fmsubss (v4sf, v4sf, v4sf)
9086
v2df __builtin_ia32_fnmaddpd (v2df, v2df, v2df)
9087
v4sf __builtin_ia32_fnmaddps (v4sf, v4sf, v4sf)
9088
v2df __builtin_ia32_fnmaddsd (v2df, v2df, v2df)
9089
v4sf __builtin_ia32_fnmaddss (v4sf, v4sf, v4sf)
9090
v2df __builtin_ia32_fnmsubpd (v2df, v2df, v2df)
9091
v4sf __builtin_ia32_fnmsubps (v4sf, v4sf, v4sf)
9092
v2df __builtin_ia32_fnmsubsd (v2df, v2df, v2df)
9093
v4sf __builtin_ia32_fnmsubss (v4sf, v4sf, v4sf)
9094
v2df __builtin_ia32_fmaddsubpd  (v2df, v2df, v2df)
9095
v4sf __builtin_ia32_fmaddsubps  (v4sf, v4sf, v4sf)
9096
v2df __builtin_ia32_fmsubaddpd  (v2df, v2df, v2df)
9097
v4sf __builtin_ia32_fmsubaddps  (v4sf, v4sf, v4sf)
9098
v4df __builtin_ia32_fmaddpd256 (v4df, v4df, v4df)
9099
v8sf __builtin_ia32_fmaddps256 (v8sf, v8sf, v8sf)
9100
v4df __builtin_ia32_fmsubpd256 (v4df, v4df, v4df)
9101
v8sf __builtin_ia32_fmsubps256 (v8sf, v8sf, v8sf)
9102
v4df __builtin_ia32_fnmaddpd256 (v4df, v4df, v4df)
9103
v8sf __builtin_ia32_fnmaddps256 (v8sf, v8sf, v8sf)
9104
v4df __builtin_ia32_fnmsubpd256 (v4df, v4df, v4df)
9105
v8sf __builtin_ia32_fnmsubps256 (v8sf, v8sf, v8sf)
9106
v4df __builtin_ia32_fmaddsubpd256 (v4df, v4df, v4df)
9107
v8sf __builtin_ia32_fmaddsubps256 (v8sf, v8sf, v8sf)
9108
v4df __builtin_ia32_fmsubaddpd256 (v4df, v4df, v4df)
9109
v8sf __builtin_ia32_fmsubaddps256 (v8sf, v8sf, v8sf)
9110
 
9111
@end smallexample
9112
 
9113
The following built-in functions are available when @option{-mlwp} is used.
9114
 
9115
@smallexample
9116
void __builtin_ia32_llwpcb16 (void *);
9117
void __builtin_ia32_llwpcb32 (void *);
9118
void __builtin_ia32_llwpcb64 (void *);
9119
void * __builtin_ia32_llwpcb16 (void);
9120
void * __builtin_ia32_llwpcb32 (void);
9121
void * __builtin_ia32_llwpcb64 (void);
9122
void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
9123
void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
9124
void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
9125
unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
9126
unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
9127
unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
9128
@end smallexample
9129
 
9130
The following built-in functions are available when @option{-m3dnow} is used.
9131
All of them generate the machine instruction that is part of the name.
9132
 
9133
@smallexample
9134
void __builtin_ia32_femms (void)
9135
v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
9136
v2si __builtin_ia32_pf2id (v2sf)
9137
v2sf __builtin_ia32_pfacc (v2sf, v2sf)
9138
v2sf __builtin_ia32_pfadd (v2sf, v2sf)
9139
v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
9140
v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
9141
v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
9142
v2sf __builtin_ia32_pfmax (v2sf, v2sf)
9143
v2sf __builtin_ia32_pfmin (v2sf, v2sf)
9144
v2sf __builtin_ia32_pfmul (v2sf, v2sf)
9145
v2sf __builtin_ia32_pfrcp (v2sf)
9146
v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
9147
v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
9148
v2sf __builtin_ia32_pfrsqrt (v2sf)
9149
v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf)
9150
v2sf __builtin_ia32_pfsub (v2sf, v2sf)
9151
v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
9152
v2sf __builtin_ia32_pi2fd (v2si)
9153
v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
9154
@end smallexample
9155
 
9156
The following built-in functions are available when both @option{-m3dnow}
9157
and @option{-march=athlon} are used.  All of them generate the machine
9158
instruction that is part of the name.
9159
 
9160
@smallexample
9161
v2si __builtin_ia32_pf2iw (v2sf)
9162
v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
9163
v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
9164
v2sf __builtin_ia32_pi2fw (v2si)
9165
v2sf __builtin_ia32_pswapdsf (v2sf)
9166
v2si __builtin_ia32_pswapdsi (v2si)
9167
@end smallexample
9168
 
9169
@node MIPS DSP Built-in Functions
9170
@subsection MIPS DSP Built-in Functions
9171
 
9172
The MIPS DSP Application-Specific Extension (ASE) includes new
9173
instructions that are designed to improve the performance of DSP and
9174
media applications.  It provides instructions that operate on packed
9175
8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
9176
 
9177
GCC supports MIPS DSP operations using both the generic
9178
vector extensions (@pxref{Vector Extensions}) and a collection of
9179
MIPS-specific built-in functions.  Both kinds of support are
9180
enabled by the @option{-mdsp} command-line option.
9181
 
9182
Revision 2 of the ASE was introduced in the second half of 2006.
9183
This revision adds extra instructions to the original ASE, but is
9184
otherwise backwards-compatible with it.  You can select revision 2
9185
using the command-line option @option{-mdspr2}; this option implies
9186
@option{-mdsp}.
9187
 
9188
The SCOUNT and POS bits of the DSP control register are global.  The
9189
WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
9190
POS bits.  During optimization, the compiler will not delete these
9191
instructions and it will not delete calls to functions containing
9192
these instructions.
9193
 
9194
At present, GCC only provides support for operations on 32-bit
9195
vectors.  The vector type associated with 8-bit integer data is
9196
usually called @code{v4i8}, the vector type associated with Q7
9197
is usually called @code{v4q7}, the vector type associated with 16-bit
9198
integer data is usually called @code{v2i16}, and the vector type
9199
associated with Q15 is usually called @code{v2q15}.  They can be
9200
defined in C as follows:
9201
 
9202
@smallexample
9203
typedef signed char v4i8 __attribute__ ((vector_size(4)));
9204
typedef signed char v4q7 __attribute__ ((vector_size(4)));
9205
typedef short v2i16 __attribute__ ((vector_size(4)));
9206
typedef short v2q15 __attribute__ ((vector_size(4)));
9207
@end smallexample
9208
 
9209
@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
9210
initialized in the same way as aggregates.  For example:
9211
 
9212
@smallexample
9213
v4i8 a = @{1, 2, 3, 4@};
9214
v4i8 b;
9215
b = (v4i8) @{5, 6, 7, 8@};
9216
 
9217
v2q15 c = @{0x0fcb, 0x3a75@};
9218
v2q15 d;
9219
d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
9220
@end smallexample
9221
 
9222
@emph{Note:} The CPU's endianness determines the order in which values
9223
are packed.  On little-endian targets, the first value is the least
9224
significant and the last value is the most significant.  The opposite
9225
order applies to big-endian targets.  For example, the code above will
9226
set the lowest byte of @code{a} to @code{1} on little-endian targets
9227
and @code{4} on big-endian targets.
9228
 
9229
@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
9230
representation.  As shown in this example, the integer representation
9231
of a Q7 value can be obtained by multiplying the fractional value by
9232
@code{0x1.0p7}.  The equivalent for Q15 values is to multiply by
9233
@code{0x1.0p15}.  The equivalent for Q31 values is to multiply by
9234
@code{0x1.0p31}.
9235
 
9236
The table below lists the @code{v4i8} and @code{v2q15} operations for which
9237
hardware support exists.  @code{a} and @code{b} are @code{v4i8} values,
9238
and @code{c} and @code{d} are @code{v2q15} values.
9239
 
9240
@multitable @columnfractions .50 .50
9241
@item C code @tab MIPS instruction
9242
@item @code{a + b} @tab @code{addu.qb}
9243
@item @code{c + d} @tab @code{addq.ph}
9244
@item @code{a - b} @tab @code{subu.qb}
9245
@item @code{c - d} @tab @code{subq.ph}
9246
@end multitable
9247
 
9248
The table below lists the @code{v2i16} operation for which
9249
hardware support exists for the DSP ASE REV 2.  @code{e} and @code{f} are
9250
@code{v2i16} values.
9251
 
9252
@multitable @columnfractions .50 .50
9253
@item C code @tab MIPS instruction
9254
@item @code{e * f} @tab @code{mul.ph}
9255
@end multitable
9256
 
9257
It is easier to describe the DSP built-in functions if we first define
9258
the following types:
9259
 
9260
@smallexample
9261
typedef int q31;
9262
typedef int i32;
9263
typedef unsigned int ui32;
9264
typedef long long a64;
9265
@end smallexample
9266
 
9267
@code{q31} and @code{i32} are actually the same as @code{int}, but we
9268
use @code{q31} to indicate a Q31 fractional value and @code{i32} to
9269
indicate a 32-bit integer value.  Similarly, @code{a64} is the same as
9270
@code{long long}, but we use @code{a64} to indicate values that will
9271
be placed in one of the four DSP accumulators (@code{$ac0},
9272
@code{$ac1}, @code{$ac2} or @code{$ac3}).
9273
 
9274
Also, some built-in functions prefer or require immediate numbers as
9275
parameters, because the corresponding DSP instructions accept both immediate
9276
numbers and register operands, or accept immediate numbers only.  The
9277
immediate parameters are listed as follows.
9278
 
9279
@smallexample
9280
imm0_3: 0 to 3.
9281
imm0_7: 0 to 7.
9282
imm0_15: 0 to 15.
9283
imm0_31: 0 to 31.
9284
imm0_63: 0 to 63.
9285
imm0_255: 0 to 255.
9286
imm_n32_31: -32 to 31.
9287
imm_n512_511: -512 to 511.
9288
@end smallexample
9289
 
9290
The following built-in functions map directly to a particular MIPS DSP
9291
instruction.  Please refer to the architecture specification
9292
for details on what each instruction does.
9293
 
9294
@smallexample
9295
v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
9296
v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
9297
q31 __builtin_mips_addq_s_w (q31, q31)
9298
v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
9299
v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
9300
v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
9301
v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
9302
q31 __builtin_mips_subq_s_w (q31, q31)
9303
v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
9304
v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
9305
i32 __builtin_mips_addsc (i32, i32)
9306
i32 __builtin_mips_addwc (i32, i32)
9307
i32 __builtin_mips_modsub (i32, i32)
9308
i32 __builtin_mips_raddu_w_qb (v4i8)
9309
v2q15 __builtin_mips_absq_s_ph (v2q15)
9310
q31 __builtin_mips_absq_s_w (q31)
9311
v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
9312
v2q15 __builtin_mips_precrq_ph_w (q31, q31)
9313
v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
9314
v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
9315
q31 __builtin_mips_preceq_w_phl (v2q15)
9316
q31 __builtin_mips_preceq_w_phr (v2q15)
9317
v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
9318
v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
9319
v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
9320
v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
9321
v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
9322
v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
9323
v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
9324
v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
9325
v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
9326
v4i8 __builtin_mips_shll_qb (v4i8, i32)
9327
v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
9328
v2q15 __builtin_mips_shll_ph (v2q15, i32)
9329
v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
9330
v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
9331
q31 __builtin_mips_shll_s_w (q31, imm0_31)
9332
q31 __builtin_mips_shll_s_w (q31, i32)
9333
v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
9334
v4i8 __builtin_mips_shrl_qb (v4i8, i32)
9335
v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
9336
v2q15 __builtin_mips_shra_ph (v2q15, i32)
9337
v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
9338
v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
9339
q31 __builtin_mips_shra_r_w (q31, imm0_31)
9340
q31 __builtin_mips_shra_r_w (q31, i32)
9341
v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
9342
v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
9343
v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
9344
q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
9345
q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
9346
a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
9347
a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
9348
a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
9349
a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
9350
a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
9351
a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
9352
a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
9353
a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
9354
a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
9355
a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
9356
a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
9357
a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
9358
a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
9359
i32 __builtin_mips_bitrev (i32)
9360
i32 __builtin_mips_insv (i32, i32)
9361
v4i8 __builtin_mips_repl_qb (imm0_255)
9362
v4i8 __builtin_mips_repl_qb (i32)
9363
v2q15 __builtin_mips_repl_ph (imm_n512_511)
9364
v2q15 __builtin_mips_repl_ph (i32)
9365
void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
9366
void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
9367
void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
9368
i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
9369
i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
9370
i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
9371
void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
9372
void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
9373
void __builtin_mips_cmp_le_ph (v2q15, v2q15)
9374
v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
9375
v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
9376
v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
9377
i32 __builtin_mips_extr_w (a64, imm0_31)
9378
i32 __builtin_mips_extr_w (a64, i32)
9379
i32 __builtin_mips_extr_r_w (a64, imm0_31)
9380
i32 __builtin_mips_extr_s_h (a64, i32)
9381
i32 __builtin_mips_extr_rs_w (a64, imm0_31)
9382
i32 __builtin_mips_extr_rs_w (a64, i32)
9383
i32 __builtin_mips_extr_s_h (a64, imm0_31)
9384
i32 __builtin_mips_extr_r_w (a64, i32)
9385
i32 __builtin_mips_extp (a64, imm0_31)
9386
i32 __builtin_mips_extp (a64, i32)
9387
i32 __builtin_mips_extpdp (a64, imm0_31)
9388
i32 __builtin_mips_extpdp (a64, i32)
9389
a64 __builtin_mips_shilo (a64, imm_n32_31)
9390
a64 __builtin_mips_shilo (a64, i32)
9391
a64 __builtin_mips_mthlip (a64, i32)
9392
void __builtin_mips_wrdsp (i32, imm0_63)
9393
i32 __builtin_mips_rddsp (imm0_63)
9394
i32 __builtin_mips_lbux (void *, i32)
9395
i32 __builtin_mips_lhx (void *, i32)
9396
i32 __builtin_mips_lwx (void *, i32)
9397
i32 __builtin_mips_bposge32 (void)
9398
@end smallexample
9399
 
9400
The following built-in functions map directly to a particular MIPS DSP REV 2
9401
instruction.  Please refer to the architecture specification
9402
for details on what each instruction does.
9403
 
9404
@smallexample
9405
v4q7 __builtin_mips_absq_s_qb (v4q7);
9406
v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
9407
v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
9408
v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
9409
v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
9410
i32 __builtin_mips_append (i32, i32, imm0_31);
9411
i32 __builtin_mips_balign (i32, i32, imm0_3);
9412
i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
9413
i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
9414
i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
9415
a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
9416
a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
9417
a64 __builtin_mips_madd (a64, i32, i32);
9418
a64 __builtin_mips_maddu (a64, ui32, ui32);
9419
a64 __builtin_mips_msub (a64, i32, i32);
9420
a64 __builtin_mips_msubu (a64, ui32, ui32);
9421
v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
9422
v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
9423
q31 __builtin_mips_mulq_rs_w (q31, q31);
9424
v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
9425
q31 __builtin_mips_mulq_s_w (q31, q31);
9426
a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
9427
a64 __builtin_mips_mult (i32, i32);
9428
a64 __builtin_mips_multu (ui32, ui32);
9429
v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
9430
v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
9431
v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
9432
i32 __builtin_mips_prepend (i32, i32, imm0_31);
9433
v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
9434
v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
9435
v4i8 __builtin_mips_shra_qb (v4i8, i32);
9436
v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
9437
v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
9438
v2i16 __builtin_mips_shrl_ph (v2i16, i32);
9439
v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
9440
v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
9441
v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
9442
v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
9443
v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
9444
v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
9445
q31 __builtin_mips_addqh_w (q31, q31);
9446
q31 __builtin_mips_addqh_r_w (q31, q31);
9447
v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
9448
v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
9449
q31 __builtin_mips_subqh_w (q31, q31);
9450
q31 __builtin_mips_subqh_r_w (q31, q31);
9451
a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
9452
a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
9453
a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
9454
a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
9455
a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
9456
a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
9457
@end smallexample
9458
 
9459
 
9460
@node MIPS Paired-Single Support
9461
@subsection MIPS Paired-Single Support
9462
 
9463
The MIPS64 architecture includes a number of instructions that
9464
operate on pairs of single-precision floating-point values.
9465
Each pair is packed into a 64-bit floating-point register,
9466
with one element being designated the ``upper half'' and
9467
the other being designated the ``lower half''.
9468
 
9469
GCC supports paired-single operations using both the generic
9470
vector extensions (@pxref{Vector Extensions}) and a collection of
9471
MIPS-specific built-in functions.  Both kinds of support are
9472
enabled by the @option{-mpaired-single} command-line option.
9473
 
9474
The vector type associated with paired-single values is usually
9475
called @code{v2sf}.  It can be defined in C as follows:
9476
 
9477
@smallexample
9478
typedef float v2sf __attribute__ ((vector_size (8)));
9479
@end smallexample
9480
 
9481
@code{v2sf} values are initialized in the same way as aggregates.
9482
For example:
9483
 
9484
@smallexample
9485
v2sf a = @{1.5, 9.1@};
9486
v2sf b;
9487
float e, f;
9488
b = (v2sf) @{e, f@};
9489
@end smallexample
9490
 
9491
@emph{Note:} The CPU's endianness determines which value is stored in
9492
the upper half of a register and which value is stored in the lower half.
9493
On little-endian targets, the first value is the lower one and the second
9494
value is the upper one.  The opposite order applies to big-endian targets.
9495
For example, the code above will set the lower half of @code{a} to
9496
@code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
9497
 
9498
@node MIPS Loongson Built-in Functions
9499
@subsection MIPS Loongson Built-in Functions
9500
 
9501
GCC provides intrinsics to access the SIMD instructions provided by the
9502
ST Microelectronics Loongson-2E and -2F processors.  These intrinsics,
9503
available after inclusion of the @code{loongson.h} header file,
9504
operate on the following 64-bit vector types:
9505
 
9506
@itemize
9507
@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
9508
@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
9509
@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
9510
@item @code{int8x8_t}, a vector of eight signed 8-bit integers;
9511
@item @code{int16x4_t}, a vector of four signed 16-bit integers;
9512
@item @code{int32x2_t}, a vector of two signed 32-bit integers.
9513
@end itemize
9514
 
9515
The intrinsics provided are listed below; each is named after the
9516
machine instruction to which it corresponds, with suffixes added as
9517
appropriate to distinguish intrinsics that expand to the same machine
9518
instruction yet have different argument types.  Refer to the architecture
9519
documentation for a description of the functionality of each
9520
instruction.
9521
 
9522
@smallexample
9523
int16x4_t packsswh (int32x2_t s, int32x2_t t);
9524
int8x8_t packsshb (int16x4_t s, int16x4_t t);
9525
uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
9526
uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
9527
uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
9528
uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
9529
int32x2_t paddw_s (int32x2_t s, int32x2_t t);
9530
int16x4_t paddh_s (int16x4_t s, int16x4_t t);
9531
int8x8_t paddb_s (int8x8_t s, int8x8_t t);
9532
uint64_t paddd_u (uint64_t s, uint64_t t);
9533
int64_t paddd_s (int64_t s, int64_t t);
9534
int16x4_t paddsh (int16x4_t s, int16x4_t t);
9535
int8x8_t paddsb (int8x8_t s, int8x8_t t);
9536
uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
9537
uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
9538
uint64_t pandn_ud (uint64_t s, uint64_t t);
9539
uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
9540
uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
9541
uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
9542
int64_t pandn_sd (int64_t s, int64_t t);
9543
int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
9544
int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
9545
int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
9546
uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
9547
uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
9548
uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
9549
uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
9550
uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
9551
int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
9552
int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
9553
int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
9554
uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
9555
uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
9556
uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
9557
int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
9558
int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
9559
int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
9560
uint16x4_t pextrh_u (uint16x4_t s, int field);
9561
int16x4_t pextrh_s (int16x4_t s, int field);
9562
uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
9563
uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
9564
uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
9565
uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
9566
int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
9567
int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
9568
int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
9569
int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
9570
int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
9571
int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
9572
uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
9573
int16x4_t pminsh (int16x4_t s, int16x4_t t);
9574
uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
9575
uint8x8_t pmovmskb_u (uint8x8_t s);
9576
int8x8_t pmovmskb_s (int8x8_t s);
9577
uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
9578
int16x4_t pmulhh (int16x4_t s, int16x4_t t);
9579
int16x4_t pmullh (int16x4_t s, int16x4_t t);
9580
int64_t pmuluw (uint32x2_t s, uint32x2_t t);
9581
uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
9582
uint16x4_t biadd (uint8x8_t s);
9583
uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
9584
uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
9585
int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
9586
uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
9587
int16x4_t psllh_s (int16x4_t s, uint8_t amount);
9588
uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
9589
int32x2_t psllw_s (int32x2_t s, uint8_t amount);
9590
uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
9591
int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
9592
uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
9593
int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
9594
uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
9595
int16x4_t psrah_s (int16x4_t s, uint8_t amount);
9596
uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
9597
int32x2_t psraw_s (int32x2_t s, uint8_t amount);
9598
uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
9599
uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
9600
uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
9601
int32x2_t psubw_s (int32x2_t s, int32x2_t t);
9602
int16x4_t psubh_s (int16x4_t s, int16x4_t t);
9603
int8x8_t psubb_s (int8x8_t s, int8x8_t t);
9604
uint64_t psubd_u (uint64_t s, uint64_t t);
9605
int64_t psubd_s (int64_t s, int64_t t);
9606
int16x4_t psubsh (int16x4_t s, int16x4_t t);
9607
int8x8_t psubsb (int8x8_t s, int8x8_t t);
9608
uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
9609
uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
9610
uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
9611
uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
9612
uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
9613
int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
9614
int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
9615
int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
9616
uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
9617
uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
9618
uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
9619
int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
9620
int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
9621
int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
9622
@end smallexample
9623
 
9624
@menu
9625
* Paired-Single Arithmetic::
9626
* Paired-Single Built-in Functions::
9627
* MIPS-3D Built-in Functions::
9628
@end menu
9629
 
9630
@node Paired-Single Arithmetic
9631
@subsubsection Paired-Single Arithmetic
9632
 
9633
The table below lists the @code{v2sf} operations for which hardware
9634
support exists.  @code{a}, @code{b} and @code{c} are @code{v2sf}
9635
values and @code{x} is an integral value.
9636
 
9637
@multitable @columnfractions .50 .50
9638
@item C code @tab MIPS instruction
9639
@item @code{a + b} @tab @code{add.ps}
9640
@item @code{a - b} @tab @code{sub.ps}
9641
@item @code{-a} @tab @code{neg.ps}
9642
@item @code{a * b} @tab @code{mul.ps}
9643
@item @code{a * b + c} @tab @code{madd.ps}
9644
@item @code{a * b - c} @tab @code{msub.ps}
9645
@item @code{-(a * b + c)} @tab @code{nmadd.ps}
9646
@item @code{-(a * b - c)} @tab @code{nmsub.ps}
9647
@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
9648
@end multitable
9649
 
9650
Note that the multiply-accumulate instructions can be disabled
9651
using the command-line option @code{-mno-fused-madd}.
9652
 
9653
@node Paired-Single Built-in Functions
9654
@subsubsection Paired-Single Built-in Functions
9655
 
9656
The following paired-single functions map directly to a particular
9657
MIPS instruction.  Please refer to the architecture specification
9658
for details on what each instruction does.
9659
 
9660
@table @code
9661
@item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
9662
Pair lower lower (@code{pll.ps}).
9663
 
9664
@item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
9665
Pair upper lower (@code{pul.ps}).
9666
 
9667
@item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
9668
Pair lower upper (@code{plu.ps}).
9669
 
9670
@item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
9671
Pair upper upper (@code{puu.ps}).
9672
 
9673
@item v2sf __builtin_mips_cvt_ps_s (float, float)
9674
Convert pair to paired single (@code{cvt.ps.s}).
9675
 
9676
@item float __builtin_mips_cvt_s_pl (v2sf)
9677
Convert pair lower to single (@code{cvt.s.pl}).
9678
 
9679
@item float __builtin_mips_cvt_s_pu (v2sf)
9680
Convert pair upper to single (@code{cvt.s.pu}).
9681
 
9682
@item v2sf __builtin_mips_abs_ps (v2sf)
9683
Absolute value (@code{abs.ps}).
9684
 
9685
@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
9686
Align variable (@code{alnv.ps}).
9687
 
9688
@emph{Note:} The value of the third parameter must be 0 or 4
9689
modulo 8, otherwise the result will be unpredictable.  Please read the
9690
instruction description for details.
9691
@end table
9692
 
9693
The following multi-instruction functions are also available.
9694
In each case, @var{cond} can be any of the 16 floating-point conditions:
9695
@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
9696
@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
9697
@code{lt}, @code{nge}, @code{le} or @code{ngt}.
9698
 
9699
@table @code
9700
@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9701
@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9702
Conditional move based on floating point comparison (@code{c.@var{cond}.ps},
9703
@code{movt.ps}/@code{movf.ps}).
9704
 
9705
The @code{movt} functions return the value @var{x} computed by:
9706
 
9707
@smallexample
9708
c.@var{cond}.ps @var{cc},@var{a},@var{b}
9709
mov.ps @var{x},@var{c}
9710
movt.ps @var{x},@var{d},@var{cc}
9711
@end smallexample
9712
 
9713
The @code{movf} functions are similar but use @code{movf.ps} instead
9714
of @code{movt.ps}.
9715
 
9716
@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9717
@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9718
Comparison of two paired-single values (@code{c.@var{cond}.ps},
9719
@code{bc1t}/@code{bc1f}).
9720
 
9721
These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
9722
and return either the upper or lower half of the result.  For example:
9723
 
9724
@smallexample
9725
v2sf a, b;
9726
if (__builtin_mips_upper_c_eq_ps (a, b))
9727
  upper_halves_are_equal ();
9728
else
9729
  upper_halves_are_unequal ();
9730
 
9731
if (__builtin_mips_lower_c_eq_ps (a, b))
9732
  lower_halves_are_equal ();
9733
else
9734
  lower_halves_are_unequal ();
9735
@end smallexample
9736
@end table
9737
 
9738
@node MIPS-3D Built-in Functions
9739
@subsubsection MIPS-3D Built-in Functions
9740
 
9741
The MIPS-3D Application-Specific Extension (ASE) includes additional
9742
paired-single instructions that are designed to improve the performance
9743
of 3D graphics operations.  Support for these instructions is controlled
9744
by the @option{-mips3d} command-line option.
9745
 
9746
The functions listed below map directly to a particular MIPS-3D
9747
instruction.  Please refer to the architecture specification for
9748
more details on what each instruction does.
9749
 
9750
@table @code
9751
@item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
9752
Reduction add (@code{addr.ps}).
9753
 
9754
@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
9755
Reduction multiply (@code{mulr.ps}).
9756
 
9757
@item v2sf __builtin_mips_cvt_pw_ps (v2sf)
9758
Convert paired single to paired word (@code{cvt.pw.ps}).
9759
 
9760
@item v2sf __builtin_mips_cvt_ps_pw (v2sf)
9761
Convert paired word to paired single (@code{cvt.ps.pw}).
9762
 
9763
@item float __builtin_mips_recip1_s (float)
9764
@itemx double __builtin_mips_recip1_d (double)
9765
@itemx v2sf __builtin_mips_recip1_ps (v2sf)
9766
Reduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
9767
 
9768
@item float __builtin_mips_recip2_s (float, float)
9769
@itemx double __builtin_mips_recip2_d (double, double)
9770
@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
9771
Reduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
9772
 
9773
@item float __builtin_mips_rsqrt1_s (float)
9774
@itemx double __builtin_mips_rsqrt1_d (double)
9775
@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
9776
Reduced precision reciprocal square root (sequence step 1)
9777
(@code{rsqrt1.@var{fmt}}).
9778
 
9779
@item float __builtin_mips_rsqrt2_s (float, float)
9780
@itemx double __builtin_mips_rsqrt2_d (double, double)
9781
@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
9782
Reduced precision reciprocal square root (sequence step 2)
9783
(@code{rsqrt2.@var{fmt}}).
9784
@end table
9785
 
9786
The following multi-instruction functions are also available.
9787
In each case, @var{cond} can be any of the 16 floating-point conditions:
9788
@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
9789
@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
9790
@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
9791
 
9792
@table @code
9793
@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
9794
@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
9795
Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
9796
@code{bc1t}/@code{bc1f}).
9797
 
9798
These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
9799
or @code{cabs.@var{cond}.d} and return the result as a boolean value.
9800
For example:
9801
 
9802
@smallexample
9803
float a, b;
9804
if (__builtin_mips_cabs_eq_s (a, b))
9805
  true ();
9806
else
9807
  false ();
9808
@end smallexample
9809
 
9810
@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9811
@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9812
Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
9813
@code{bc1t}/@code{bc1f}).
9814
 
9815
These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
9816
and return either the upper or lower half of the result.  For example:
9817
 
9818
@smallexample
9819
v2sf a, b;
9820
if (__builtin_mips_upper_cabs_eq_ps (a, b))
9821
  upper_halves_are_equal ();
9822
else
9823
  upper_halves_are_unequal ();
9824
 
9825
if (__builtin_mips_lower_cabs_eq_ps (a, b))
9826
  lower_halves_are_equal ();
9827
else
9828
  lower_halves_are_unequal ();
9829
@end smallexample
9830
 
9831
@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9832
@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9833
Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
9834
@code{movt.ps}/@code{movf.ps}).
9835
 
9836
The @code{movt} functions return the value @var{x} computed by:
9837
 
9838
@smallexample
9839
cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
9840
mov.ps @var{x},@var{c}
9841
movt.ps @var{x},@var{d},@var{cc}
9842
@end smallexample
9843
 
9844
The @code{movf} functions are similar but use @code{movf.ps} instead
9845
of @code{movt.ps}.
9846
 
9847
@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9848
@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9849
@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9850
@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
9851
Comparison of two paired-single values
9852
(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
9853
@code{bc1any2t}/@code{bc1any2f}).
9854
 
9855
These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
9856
or @code{cabs.@var{cond}.ps}.  The @code{any} forms return true if either
9857
result is true and the @code{all} forms return true if both results are true.
9858
For example:
9859
 
9860
@smallexample
9861
v2sf a, b;
9862
if (__builtin_mips_any_c_eq_ps (a, b))
9863
  one_is_true ();
9864
else
9865
  both_are_false ();
9866
 
9867
if (__builtin_mips_all_c_eq_ps (a, b))
9868
  both_are_true ();
9869
else
9870
  one_is_false ();
9871
@end smallexample
9872
 
9873
@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9874
@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9875
@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9876
@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
9877
Comparison of four paired-single values
9878
(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
9879
@code{bc1any4t}/@code{bc1any4f}).
9880
 
9881
These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
9882
to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
9883
The @code{any} forms return true if any of the four results are true
9884
and the @code{all} forms return true if all four results are true.
9885
For example:
9886
 
9887
@smallexample
9888
v2sf a, b, c, d;
9889
if (__builtin_mips_any_c_eq_4s (a, b, c, d))
9890
  some_are_true ();
9891
else
9892
  all_are_false ();
9893
 
9894
if (__builtin_mips_all_c_eq_4s (a, b, c, d))
9895
  all_are_true ();
9896
else
9897
  some_are_false ();
9898
@end smallexample
9899
@end table
9900
 
9901
@node picoChip Built-in Functions
9902
@subsection picoChip Built-in Functions
9903
 
9904
GCC provides an interface to selected machine instructions from the
9905
picoChip instruction set.
9906
 
9907
@table @code
9908
@item int __builtin_sbc (int @var{value})
9909
Sign bit count.  Return the number of consecutive bits in @var{value}
9910
which have the same value as the sign-bit.  The result is the number of
9911
leading sign bits minus one, giving the number of redundant sign bits in
9912
@var{value}.
9913
 
9914
@item int __builtin_byteswap (int @var{value})
9915
Byte swap.  Return the result of swapping the upper and lower bytes of
9916
@var{value}.
9917
 
9918
@item int __builtin_brev (int @var{value})
9919
Bit reversal.  Return the result of reversing the bits in
9920
@var{value}.  Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
9921
and so on.
9922
 
9923
@item int __builtin_adds (int @var{x}, int @var{y})
9924
Saturating addition.  Return the result of adding @var{x} and @var{y},
9925
storing the value 32767 if the result overflows.
9926
 
9927
@item int __builtin_subs (int @var{x}, int @var{y})
9928
Saturating subtraction.  Return the result of subtracting @var{y} from
9929
@var{x}, storing the value @minus{}32768 if the result overflows.
9930
 
9931
@item void __builtin_halt (void)
9932
Halt.  The processor will stop execution.  This built-in is useful for
9933
implementing assertions.
9934
 
9935
@end table
9936
 
9937
@node Other MIPS Built-in Functions
9938
@subsection Other MIPS Built-in Functions
9939
 
9940
GCC provides other MIPS-specific built-in functions:
9941
 
9942
@table @code
9943
@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
9944
Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
9945
GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
9946
when this function is available.
9947
@end table
9948
 
9949
@node PowerPC AltiVec/VSX Built-in Functions
9950
@subsection PowerPC AltiVec Built-in Functions
9951
 
9952
GCC provides an interface for the PowerPC family of processors to access
9953
the AltiVec operations described in Motorola's AltiVec Programming
9954
Interface Manual.  The interface is made available by including
9955
@code{<altivec.h>} and using @option{-maltivec} and
9956
@option{-mabi=altivec}.  The interface supports the following vector
9957
types.
9958
 
9959
@smallexample
9960
vector unsigned char
9961
vector signed char
9962
vector bool char
9963
 
9964
vector unsigned short
9965
vector signed short
9966
vector bool short
9967
vector pixel
9968
 
9969
vector unsigned int
9970
vector signed int
9971
vector bool int
9972
vector float
9973
@end smallexample
9974
 
9975
If @option{-mvsx} is used the following additional vector types are
9976
implemented.
9977
 
9978
@smallexample
9979
vector unsigned long
9980
vector signed long
9981
vector double
9982
@end smallexample
9983
 
9984
The long types are only implemented for 64-bit code generation, and
9985
the long type is only used in the floating point/integer conversion
9986
instructions.
9987
 
9988
GCC's implementation of the high-level language interface available from
9989
C and C++ code differs from Motorola's documentation in several ways.
9990
 
9991
@itemize @bullet
9992
 
9993
@item
9994
A vector constant is a list of constant expressions within curly braces.
9995
 
9996
@item
9997
A vector initializer requires no cast if the vector constant is of the
9998
same type as the variable it is initializing.
9999
 
10000
@item
10001
If @code{signed} or @code{unsigned} is omitted, the signedness of the
10002
vector type is the default signedness of the base type.  The default
10003
varies depending on the operating system, so a portable program should
10004
always specify the signedness.
10005
 
10006
@item
10007
Compiling with @option{-maltivec} adds keywords @code{__vector},
10008
@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
10009
@code{bool}.  When compiling ISO C, the context-sensitive substitution
10010
of the keywords @code{vector}, @code{pixel} and @code{bool} is
10011
disabled.  To use them, you must include @code{<altivec.h>} instead.
10012
 
10013
@item
10014
GCC allows using a @code{typedef} name as the type specifier for a
10015
vector type.
10016
 
10017
@item
10018
For C, overloaded functions are implemented with macros so the following
10019
does not work:
10020
 
10021
@smallexample
10022
  vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
10023
@end smallexample
10024
 
10025
Since @code{vec_add} is a macro, the vector constant in the example
10026
is treated as four separate arguments.  Wrap the entire argument in
10027
parentheses for this to work.
10028
@end itemize
10029
 
10030
@emph{Note:} Only the @code{<altivec.h>} interface is supported.
10031
Internally, GCC uses built-in functions to achieve the functionality in
10032
the aforementioned header file, but they are not supported and are
10033
subject to change without notice.
10034
 
10035
The following interfaces are supported for the generic and specific
10036
AltiVec operations and the AltiVec predicates.  In cases where there
10037
is a direct mapping between generic and specific operations, only the
10038
generic names are shown here, although the specific operations can also
10039
be used.
10040
 
10041
Arguments that are documented as @code{const int} require literal
10042
integral values within the range required for that operation.
10043
 
10044
@smallexample
10045
vector signed char vec_abs (vector signed char);
10046
vector signed short vec_abs (vector signed short);
10047
vector signed int vec_abs (vector signed int);
10048
vector float vec_abs (vector float);
10049
 
10050
vector signed char vec_abss (vector signed char);
10051
vector signed short vec_abss (vector signed short);
10052
vector signed int vec_abss (vector signed int);
10053
 
10054
vector signed char vec_add (vector bool char, vector signed char);
10055
vector signed char vec_add (vector signed char, vector bool char);
10056
vector signed char vec_add (vector signed char, vector signed char);
10057
vector unsigned char vec_add (vector bool char, vector unsigned char);
10058
vector unsigned char vec_add (vector unsigned char, vector bool char);
10059
vector unsigned char vec_add (vector unsigned char,
10060
                              vector unsigned char);
10061
vector signed short vec_add (vector bool short, vector signed short);
10062
vector signed short vec_add (vector signed short, vector bool short);
10063
vector signed short vec_add (vector signed short, vector signed short);
10064
vector unsigned short vec_add (vector bool short,
10065
                               vector unsigned short);
10066
vector unsigned short vec_add (vector unsigned short,
10067
                               vector bool short);
10068
vector unsigned short vec_add (vector unsigned short,
10069
                               vector unsigned short);
10070
vector signed int vec_add (vector bool int, vector signed int);
10071
vector signed int vec_add (vector signed int, vector bool int);
10072
vector signed int vec_add (vector signed int, vector signed int);
10073
vector unsigned int vec_add (vector bool int, vector unsigned int);
10074
vector unsigned int vec_add (vector unsigned int, vector bool int);
10075
vector unsigned int vec_add (vector unsigned int, vector unsigned int);
10076
vector float vec_add (vector float, vector float);
10077
 
10078
vector float vec_vaddfp (vector float, vector float);
10079
 
10080
vector signed int vec_vadduwm (vector bool int, vector signed int);
10081
vector signed int vec_vadduwm (vector signed int, vector bool int);
10082
vector signed int vec_vadduwm (vector signed int, vector signed int);
10083
vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
10084
vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
10085
vector unsigned int vec_vadduwm (vector unsigned int,
10086
                                 vector unsigned int);
10087
 
10088
vector signed short vec_vadduhm (vector bool short,
10089
                                 vector signed short);
10090
vector signed short vec_vadduhm (vector signed short,
10091
                                 vector bool short);
10092
vector signed short vec_vadduhm (vector signed short,
10093
                                 vector signed short);
10094
vector unsigned short vec_vadduhm (vector bool short,
10095
                                   vector unsigned short);
10096
vector unsigned short vec_vadduhm (vector unsigned short,
10097
                                   vector bool short);
10098
vector unsigned short vec_vadduhm (vector unsigned short,
10099
                                   vector unsigned short);
10100
 
10101
vector signed char vec_vaddubm (vector bool char, vector signed char);
10102
vector signed char vec_vaddubm (vector signed char, vector bool char);
10103
vector signed char vec_vaddubm (vector signed char, vector signed char);
10104
vector unsigned char vec_vaddubm (vector bool char,
10105
                                  vector unsigned char);
10106
vector unsigned char vec_vaddubm (vector unsigned char,
10107
                                  vector bool char);
10108
vector unsigned char vec_vaddubm (vector unsigned char,
10109
                                  vector unsigned char);
10110
 
10111
vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
10112
 
10113
vector unsigned char vec_adds (vector bool char, vector unsigned char);
10114
vector unsigned char vec_adds (vector unsigned char, vector bool char);
10115
vector unsigned char vec_adds (vector unsigned char,
10116
                               vector unsigned char);
10117
vector signed char vec_adds (vector bool char, vector signed char);
10118
vector signed char vec_adds (vector signed char, vector bool char);
10119
vector signed char vec_adds (vector signed char, vector signed char);
10120
vector unsigned short vec_adds (vector bool short,
10121
                                vector unsigned short);
10122
vector unsigned short vec_adds (vector unsigned short,
10123
                                vector bool short);
10124
vector unsigned short vec_adds (vector unsigned short,
10125
                                vector unsigned short);
10126
vector signed short vec_adds (vector bool short, vector signed short);
10127
vector signed short vec_adds (vector signed short, vector bool short);
10128
vector signed short vec_adds (vector signed short, vector signed short);
10129
vector unsigned int vec_adds (vector bool int, vector unsigned int);
10130
vector unsigned int vec_adds (vector unsigned int, vector bool int);
10131
vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
10132
vector signed int vec_adds (vector bool int, vector signed int);
10133
vector signed int vec_adds (vector signed int, vector bool int);
10134
vector signed int vec_adds (vector signed int, vector signed int);
10135
 
10136
vector signed int vec_vaddsws (vector bool int, vector signed int);
10137
vector signed int vec_vaddsws (vector signed int, vector bool int);
10138
vector signed int vec_vaddsws (vector signed int, vector signed int);
10139
 
10140
vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
10141
vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
10142
vector unsigned int vec_vadduws (vector unsigned int,
10143
                                 vector unsigned int);
10144
 
10145
vector signed short vec_vaddshs (vector bool short,
10146
                                 vector signed short);
10147
vector signed short vec_vaddshs (vector signed short,
10148
                                 vector bool short);
10149
vector signed short vec_vaddshs (vector signed short,
10150
                                 vector signed short);
10151
 
10152
vector unsigned short vec_vadduhs (vector bool short,
10153
                                   vector unsigned short);
10154
vector unsigned short vec_vadduhs (vector unsigned short,
10155
                                   vector bool short);
10156
vector unsigned short vec_vadduhs (vector unsigned short,
10157
                                   vector unsigned short);
10158
 
10159
vector signed char vec_vaddsbs (vector bool char, vector signed char);
10160
vector signed char vec_vaddsbs (vector signed char, vector bool char);
10161
vector signed char vec_vaddsbs (vector signed char, vector signed char);
10162
 
10163
vector unsigned char vec_vaddubs (vector bool char,
10164
                                  vector unsigned char);
10165
vector unsigned char vec_vaddubs (vector unsigned char,
10166
                                  vector bool char);
10167
vector unsigned char vec_vaddubs (vector unsigned char,
10168
                                  vector unsigned char);
10169
 
10170
vector float vec_and (vector float, vector float);
10171
vector float vec_and (vector float, vector bool int);
10172
vector float vec_and (vector bool int, vector float);
10173
vector bool int vec_and (vector bool int, vector bool int);
10174
vector signed int vec_and (vector bool int, vector signed int);
10175
vector signed int vec_and (vector signed int, vector bool int);
10176
vector signed int vec_and (vector signed int, vector signed int);
10177
vector unsigned int vec_and (vector bool int, vector unsigned int);
10178
vector unsigned int vec_and (vector unsigned int, vector bool int);
10179
vector unsigned int vec_and (vector unsigned int, vector unsigned int);
10180
vector bool short vec_and (vector bool short, vector bool short);
10181
vector signed short vec_and (vector bool short, vector signed short);
10182
vector signed short vec_and (vector signed short, vector bool short);
10183
vector signed short vec_and (vector signed short, vector signed short);
10184
vector unsigned short vec_and (vector bool short,
10185
                               vector unsigned short);
10186
vector unsigned short vec_and (vector unsigned short,
10187
                               vector bool short);
10188
vector unsigned short vec_and (vector unsigned short,
10189
                               vector unsigned short);
10190
vector signed char vec_and (vector bool char, vector signed char);
10191
vector bool char vec_and (vector bool char, vector bool char);
10192
vector signed char vec_and (vector signed char, vector bool char);
10193
vector signed char vec_and (vector signed char, vector signed char);
10194
vector unsigned char vec_and (vector bool char, vector unsigned char);
10195
vector unsigned char vec_and (vector unsigned char, vector bool char);
10196
vector unsigned char vec_and (vector unsigned char,
10197
                              vector unsigned char);
10198
 
10199
vector float vec_andc (vector float, vector float);
10200
vector float vec_andc (vector float, vector bool int);
10201
vector float vec_andc (vector bool int, vector float);
10202
vector bool int vec_andc (vector bool int, vector bool int);
10203
vector signed int vec_andc (vector bool int, vector signed int);
10204
vector signed int vec_andc (vector signed int, vector bool int);
10205
vector signed int vec_andc (vector signed int, vector signed int);
10206
vector unsigned int vec_andc (vector bool int, vector unsigned int);
10207
vector unsigned int vec_andc (vector unsigned int, vector bool int);
10208
vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
10209
vector bool short vec_andc (vector bool short, vector bool short);
10210
vector signed short vec_andc (vector bool short, vector signed short);
10211
vector signed short vec_andc (vector signed short, vector bool short);
10212
vector signed short vec_andc (vector signed short, vector signed short);
10213
vector unsigned short vec_andc (vector bool short,
10214
                                vector unsigned short);
10215
vector unsigned short vec_andc (vector unsigned short,
10216
                                vector bool short);
10217
vector unsigned short vec_andc (vector unsigned short,
10218
                                vector unsigned short);
10219
vector signed char vec_andc (vector bool char, vector signed char);
10220
vector bool char vec_andc (vector bool char, vector bool char);
10221
vector signed char vec_andc (vector signed char, vector bool char);
10222
vector signed char vec_andc (vector signed char, vector signed char);
10223
vector unsigned char vec_andc (vector bool char, vector unsigned char);
10224
vector unsigned char vec_andc (vector unsigned char, vector bool char);
10225
vector unsigned char vec_andc (vector unsigned char,
10226
                               vector unsigned char);
10227
 
10228
vector unsigned char vec_avg (vector unsigned char,
10229
                              vector unsigned char);
10230
vector signed char vec_avg (vector signed char, vector signed char);
10231
vector unsigned short vec_avg (vector unsigned short,
10232
                               vector unsigned short);
10233
vector signed short vec_avg (vector signed short, vector signed short);
10234
vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
10235
vector signed int vec_avg (vector signed int, vector signed int);
10236
 
10237
vector signed int vec_vavgsw (vector signed int, vector signed int);
10238
 
10239
vector unsigned int vec_vavguw (vector unsigned int,
10240
                                vector unsigned int);
10241
 
10242
vector signed short vec_vavgsh (vector signed short,
10243
                                vector signed short);
10244
 
10245
vector unsigned short vec_vavguh (vector unsigned short,
10246
                                  vector unsigned short);
10247
 
10248
vector signed char vec_vavgsb (vector signed char, vector signed char);
10249
 
10250
vector unsigned char vec_vavgub (vector unsigned char,
10251
                                 vector unsigned char);
10252
 
10253
vector float vec_copysign (vector float);
10254
 
10255
vector float vec_ceil (vector float);
10256
 
10257
vector signed int vec_cmpb (vector float, vector float);
10258
 
10259
vector bool char vec_cmpeq (vector signed char, vector signed char);
10260
vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
10261
vector bool short vec_cmpeq (vector signed short, vector signed short);
10262
vector bool short vec_cmpeq (vector unsigned short,
10263
                             vector unsigned short);
10264
vector bool int vec_cmpeq (vector signed int, vector signed int);
10265
vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
10266
vector bool int vec_cmpeq (vector float, vector float);
10267
 
10268
vector bool int vec_vcmpeqfp (vector float, vector float);
10269
 
10270
vector bool int vec_vcmpequw (vector signed int, vector signed int);
10271
vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
10272
 
10273
vector bool short vec_vcmpequh (vector signed short,
10274
                                vector signed short);
10275
vector bool short vec_vcmpequh (vector unsigned short,
10276
                                vector unsigned short);
10277
 
10278
vector bool char vec_vcmpequb (vector signed char, vector signed char);
10279
vector bool char vec_vcmpequb (vector unsigned char,
10280
                               vector unsigned char);
10281
 
10282
vector bool int vec_cmpge (vector float, vector float);
10283
 
10284
vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
10285
vector bool char vec_cmpgt (vector signed char, vector signed char);
10286
vector bool short vec_cmpgt (vector unsigned short,
10287
                             vector unsigned short);
10288
vector bool short vec_cmpgt (vector signed short, vector signed short);
10289
vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
10290
vector bool int vec_cmpgt (vector signed int, vector signed int);
10291
vector bool int vec_cmpgt (vector float, vector float);
10292
 
10293
vector bool int vec_vcmpgtfp (vector float, vector float);
10294
 
10295
vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
10296
 
10297
vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
10298
 
10299
vector bool short vec_vcmpgtsh (vector signed short,
10300
                                vector signed short);
10301
 
10302
vector bool short vec_vcmpgtuh (vector unsigned short,
10303
                                vector unsigned short);
10304
 
10305
vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
10306
 
10307
vector bool char vec_vcmpgtub (vector unsigned char,
10308
                               vector unsigned char);
10309
 
10310
vector bool int vec_cmple (vector float, vector float);
10311
 
10312
vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
10313
vector bool char vec_cmplt (vector signed char, vector signed char);
10314
vector bool short vec_cmplt (vector unsigned short,
10315
                             vector unsigned short);
10316
vector bool short vec_cmplt (vector signed short, vector signed short);
10317
vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
10318
vector bool int vec_cmplt (vector signed int, vector signed int);
10319
vector bool int vec_cmplt (vector float, vector float);
10320
 
10321
vector float vec_ctf (vector unsigned int, const int);
10322
vector float vec_ctf (vector signed int, const int);
10323
 
10324
vector float vec_vcfsx (vector signed int, const int);
10325
 
10326
vector float vec_vcfux (vector unsigned int, const int);
10327
 
10328
vector signed int vec_cts (vector float, const int);
10329
 
10330
vector unsigned int vec_ctu (vector float, const int);
10331
 
10332
void vec_dss (const int);
10333
 
10334
void vec_dssall (void);
10335
 
10336
void vec_dst (const vector unsigned char *, int, const int);
10337
void vec_dst (const vector signed char *, int, const int);
10338
void vec_dst (const vector bool char *, int, const int);
10339
void vec_dst (const vector unsigned short *, int, const int);
10340
void vec_dst (const vector signed short *, int, const int);
10341
void vec_dst (const vector bool short *, int, const int);
10342
void vec_dst (const vector pixel *, int, const int);
10343
void vec_dst (const vector unsigned int *, int, const int);
10344
void vec_dst (const vector signed int *, int, const int);
10345
void vec_dst (const vector bool int *, int, const int);
10346
void vec_dst (const vector float *, int, const int);
10347
void vec_dst (const unsigned char *, int, const int);
10348
void vec_dst (const signed char *, int, const int);
10349
void vec_dst (const unsigned short *, int, const int);
10350
void vec_dst (const short *, int, const int);
10351
void vec_dst (const unsigned int *, int, const int);
10352
void vec_dst (const int *, int, const int);
10353
void vec_dst (const unsigned long *, int, const int);
10354
void vec_dst (const long *, int, const int);
10355
void vec_dst (const float *, int, const int);
10356
 
10357
void vec_dstst (const vector unsigned char *, int, const int);
10358
void vec_dstst (const vector signed char *, int, const int);
10359
void vec_dstst (const vector bool char *, int, const int);
10360
void vec_dstst (const vector unsigned short *, int, const int);
10361
void vec_dstst (const vector signed short *, int, const int);
10362
void vec_dstst (const vector bool short *, int, const int);
10363
void vec_dstst (const vector pixel *, int, const int);
10364
void vec_dstst (const vector unsigned int *, int, const int);
10365
void vec_dstst (const vector signed int *, int, const int);
10366
void vec_dstst (const vector bool int *, int, const int);
10367
void vec_dstst (const vector float *, int, const int);
10368
void vec_dstst (const unsigned char *, int, const int);
10369
void vec_dstst (const signed char *, int, const int);
10370
void vec_dstst (const unsigned short *, int, const int);
10371
void vec_dstst (const short *, int, const int);
10372
void vec_dstst (const unsigned int *, int, const int);
10373
void vec_dstst (const int *, int, const int);
10374
void vec_dstst (const unsigned long *, int, const int);
10375
void vec_dstst (const long *, int, const int);
10376
void vec_dstst (const float *, int, const int);
10377
 
10378
void vec_dststt (const vector unsigned char *, int, const int);
10379
void vec_dststt (const vector signed char *, int, const int);
10380
void vec_dststt (const vector bool char *, int, const int);
10381
void vec_dststt (const vector unsigned short *, int, const int);
10382
void vec_dststt (const vector signed short *, int, const int);
10383
void vec_dststt (const vector bool short *, int, const int);
10384
void vec_dststt (const vector pixel *, int, const int);
10385
void vec_dststt (const vector unsigned int *, int, const int);
10386
void vec_dststt (const vector signed int *, int, const int);
10387
void vec_dststt (const vector bool int *, int, const int);
10388
void vec_dststt (const vector float *, int, const int);
10389
void vec_dststt (const unsigned char *, int, const int);
10390
void vec_dststt (const signed char *, int, const int);
10391
void vec_dststt (const unsigned short *, int, const int);
10392
void vec_dststt (const short *, int, const int);
10393
void vec_dststt (const unsigned int *, int, const int);
10394
void vec_dststt (const int *, int, const int);
10395
void vec_dststt (const unsigned long *, int, const int);
10396
void vec_dststt (const long *, int, const int);
10397
void vec_dststt (const float *, int, const int);
10398
 
10399
void vec_dstt (const vector unsigned char *, int, const int);
10400
void vec_dstt (const vector signed char *, int, const int);
10401
void vec_dstt (const vector bool char *, int, const int);
10402
void vec_dstt (const vector unsigned short *, int, const int);
10403
void vec_dstt (const vector signed short *, int, const int);
10404
void vec_dstt (const vector bool short *, int, const int);
10405
void vec_dstt (const vector pixel *, int, const int);
10406
void vec_dstt (const vector unsigned int *, int, const int);
10407
void vec_dstt (const vector signed int *, int, const int);
10408
void vec_dstt (const vector bool int *, int, const int);
10409
void vec_dstt (const vector float *, int, const int);
10410
void vec_dstt (const unsigned char *, int, const int);
10411
void vec_dstt (const signed char *, int, const int);
10412
void vec_dstt (const unsigned short *, int, const int);
10413
void vec_dstt (const short *, int, const int);
10414
void vec_dstt (const unsigned int *, int, const int);
10415
void vec_dstt (const int *, int, const int);
10416
void vec_dstt (const unsigned long *, int, const int);
10417
void vec_dstt (const long *, int, const int);
10418
void vec_dstt (const float *, int, const int);
10419
 
10420
vector float vec_expte (vector float);
10421
 
10422
vector float vec_floor (vector float);
10423
 
10424
vector float vec_ld (int, const vector float *);
10425
vector float vec_ld (int, const float *);
10426
vector bool int vec_ld (int, const vector bool int *);
10427
vector signed int vec_ld (int, const vector signed int *);
10428
vector signed int vec_ld (int, const int *);
10429
vector signed int vec_ld (int, const long *);
10430
vector unsigned int vec_ld (int, const vector unsigned int *);
10431
vector unsigned int vec_ld (int, const unsigned int *);
10432
vector unsigned int vec_ld (int, const unsigned long *);
10433
vector bool short vec_ld (int, const vector bool short *);
10434
vector pixel vec_ld (int, const vector pixel *);
10435
vector signed short vec_ld (int, const vector signed short *);
10436
vector signed short vec_ld (int, const short *);
10437
vector unsigned short vec_ld (int, const vector unsigned short *);
10438
vector unsigned short vec_ld (int, const unsigned short *);
10439
vector bool char vec_ld (int, const vector bool char *);
10440
vector signed char vec_ld (int, const vector signed char *);
10441
vector signed char vec_ld (int, const signed char *);
10442
vector unsigned char vec_ld (int, const vector unsigned char *);
10443
vector unsigned char vec_ld (int, const unsigned char *);
10444
 
10445
vector signed char vec_lde (int, const signed char *);
10446
vector unsigned char vec_lde (int, const unsigned char *);
10447
vector signed short vec_lde (int, const short *);
10448
vector unsigned short vec_lde (int, const unsigned short *);
10449
vector float vec_lde (int, const float *);
10450
vector signed int vec_lde (int, const int *);
10451
vector unsigned int vec_lde (int, const unsigned int *);
10452
vector signed int vec_lde (int, const long *);
10453
vector unsigned int vec_lde (int, const unsigned long *);
10454
 
10455
vector float vec_lvewx (int, float *);
10456
vector signed int vec_lvewx (int, int *);
10457
vector unsigned int vec_lvewx (int, unsigned int *);
10458
vector signed int vec_lvewx (int, long *);
10459
vector unsigned int vec_lvewx (int, unsigned long *);
10460
 
10461
vector signed short vec_lvehx (int, short *);
10462
vector unsigned short vec_lvehx (int, unsigned short *);
10463
 
10464
vector signed char vec_lvebx (int, char *);
10465
vector unsigned char vec_lvebx (int, unsigned char *);
10466
 
10467
vector float vec_ldl (int, const vector float *);
10468
vector float vec_ldl (int, const float *);
10469
vector bool int vec_ldl (int, const vector bool int *);
10470
vector signed int vec_ldl (int, const vector signed int *);
10471
vector signed int vec_ldl (int, const int *);
10472
vector signed int vec_ldl (int, const long *);
10473
vector unsigned int vec_ldl (int, const vector unsigned int *);
10474
vector unsigned int vec_ldl (int, const unsigned int *);
10475
vector unsigned int vec_ldl (int, const unsigned long *);
10476
vector bool short vec_ldl (int, const vector bool short *);
10477
vector pixel vec_ldl (int, const vector pixel *);
10478
vector signed short vec_ldl (int, const vector signed short *);
10479
vector signed short vec_ldl (int, const short *);
10480
vector unsigned short vec_ldl (int, const vector unsigned short *);
10481
vector unsigned short vec_ldl (int, const unsigned short *);
10482
vector bool char vec_ldl (int, const vector bool char *);
10483
vector signed char vec_ldl (int, const vector signed char *);
10484
vector signed char vec_ldl (int, const signed char *);
10485
vector unsigned char vec_ldl (int, const vector unsigned char *);
10486
vector unsigned char vec_ldl (int, const unsigned char *);
10487
 
10488
vector float vec_loge (vector float);
10489
 
10490
vector unsigned char vec_lvsl (int, const volatile unsigned char *);
10491
vector unsigned char vec_lvsl (int, const volatile signed char *);
10492
vector unsigned char vec_lvsl (int, const volatile unsigned short *);
10493
vector unsigned char vec_lvsl (int, const volatile short *);
10494
vector unsigned char vec_lvsl (int, const volatile unsigned int *);
10495
vector unsigned char vec_lvsl (int, const volatile int *);
10496
vector unsigned char vec_lvsl (int, const volatile unsigned long *);
10497
vector unsigned char vec_lvsl (int, const volatile long *);
10498
vector unsigned char vec_lvsl (int, const volatile float *);
10499
 
10500
vector unsigned char vec_lvsr (int, const volatile unsigned char *);
10501
vector unsigned char vec_lvsr (int, const volatile signed char *);
10502
vector unsigned char vec_lvsr (int, const volatile unsigned short *);
10503
vector unsigned char vec_lvsr (int, const volatile short *);
10504
vector unsigned char vec_lvsr (int, const volatile unsigned int *);
10505
vector unsigned char vec_lvsr (int, const volatile int *);
10506
vector unsigned char vec_lvsr (int, const volatile unsigned long *);
10507
vector unsigned char vec_lvsr (int, const volatile long *);
10508
vector unsigned char vec_lvsr (int, const volatile float *);
10509
 
10510
vector float vec_madd (vector float, vector float, vector float);
10511
 
10512
vector signed short vec_madds (vector signed short,
10513
                               vector signed short,
10514
                               vector signed short);
10515
 
10516
vector unsigned char vec_max (vector bool char, vector unsigned char);
10517
vector unsigned char vec_max (vector unsigned char, vector bool char);
10518
vector unsigned char vec_max (vector unsigned char,
10519
                              vector unsigned char);
10520
vector signed char vec_max (vector bool char, vector signed char);
10521
vector signed char vec_max (vector signed char, vector bool char);
10522
vector signed char vec_max (vector signed char, vector signed char);
10523
vector unsigned short vec_max (vector bool short,
10524
                               vector unsigned short);
10525
vector unsigned short vec_max (vector unsigned short,
10526
                               vector bool short);
10527
vector unsigned short vec_max (vector unsigned short,
10528
                               vector unsigned short);
10529
vector signed short vec_max (vector bool short, vector signed short);
10530
vector signed short vec_max (vector signed short, vector bool short);
10531
vector signed short vec_max (vector signed short, vector signed short);
10532
vector unsigned int vec_max (vector bool int, vector unsigned int);
10533
vector unsigned int vec_max (vector unsigned int, vector bool int);
10534
vector unsigned int vec_max (vector unsigned int, vector unsigned int);
10535
vector signed int vec_max (vector bool int, vector signed int);
10536
vector signed int vec_max (vector signed int, vector bool int);
10537
vector signed int vec_max (vector signed int, vector signed int);
10538
vector float vec_max (vector float, vector float);
10539
 
10540
vector float vec_vmaxfp (vector float, vector float);
10541
 
10542
vector signed int vec_vmaxsw (vector bool int, vector signed int);
10543
vector signed int vec_vmaxsw (vector signed int, vector bool int);
10544
vector signed int vec_vmaxsw (vector signed int, vector signed int);
10545
 
10546
vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
10547
vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
10548
vector unsigned int vec_vmaxuw (vector unsigned int,
10549
                                vector unsigned int);
10550
 
10551
vector signed short vec_vmaxsh (vector bool short, vector signed short);
10552
vector signed short vec_vmaxsh (vector signed short, vector bool short);
10553
vector signed short vec_vmaxsh (vector signed short,
10554
                                vector signed short);
10555
 
10556
vector unsigned short vec_vmaxuh (vector bool short,
10557
                                  vector unsigned short);
10558
vector unsigned short vec_vmaxuh (vector unsigned short,
10559
                                  vector bool short);
10560
vector unsigned short vec_vmaxuh (vector unsigned short,
10561
                                  vector unsigned short);
10562
 
10563
vector signed char vec_vmaxsb (vector bool char, vector signed char);
10564
vector signed char vec_vmaxsb (vector signed char, vector bool char);
10565
vector signed char vec_vmaxsb (vector signed char, vector signed char);
10566
 
10567
vector unsigned char vec_vmaxub (vector bool char,
10568
                                 vector unsigned char);
10569
vector unsigned char vec_vmaxub (vector unsigned char,
10570
                                 vector bool char);
10571
vector unsigned char vec_vmaxub (vector unsigned char,
10572
                                 vector unsigned char);
10573
 
10574
vector bool char vec_mergeh (vector bool char, vector bool char);
10575
vector signed char vec_mergeh (vector signed char, vector signed char);
10576
vector unsigned char vec_mergeh (vector unsigned char,
10577
                                 vector unsigned char);
10578
vector bool short vec_mergeh (vector bool short, vector bool short);
10579
vector pixel vec_mergeh (vector pixel, vector pixel);
10580
vector signed short vec_mergeh (vector signed short,
10581
                                vector signed short);
10582
vector unsigned short vec_mergeh (vector unsigned short,
10583
                                  vector unsigned short);
10584
vector float vec_mergeh (vector float, vector float);
10585
vector bool int vec_mergeh (vector bool int, vector bool int);
10586
vector signed int vec_mergeh (vector signed int, vector signed int);
10587
vector unsigned int vec_mergeh (vector unsigned int,
10588
                                vector unsigned int);
10589
 
10590
vector float vec_vmrghw (vector float, vector float);
10591
vector bool int vec_vmrghw (vector bool int, vector bool int);
10592
vector signed int vec_vmrghw (vector signed int, vector signed int);
10593
vector unsigned int vec_vmrghw (vector unsigned int,
10594
                                vector unsigned int);
10595
 
10596
vector bool short vec_vmrghh (vector bool short, vector bool short);
10597
vector signed short vec_vmrghh (vector signed short,
10598
                                vector signed short);
10599
vector unsigned short vec_vmrghh (vector unsigned short,
10600
                                  vector unsigned short);
10601
vector pixel vec_vmrghh (vector pixel, vector pixel);
10602
 
10603
vector bool char vec_vmrghb (vector bool char, vector bool char);
10604
vector signed char vec_vmrghb (vector signed char, vector signed char);
10605
vector unsigned char vec_vmrghb (vector unsigned char,
10606
                                 vector unsigned char);
10607
 
10608
vector bool char vec_mergel (vector bool char, vector bool char);
10609
vector signed char vec_mergel (vector signed char, vector signed char);
10610
vector unsigned char vec_mergel (vector unsigned char,
10611
                                 vector unsigned char);
10612
vector bool short vec_mergel (vector bool short, vector bool short);
10613
vector pixel vec_mergel (vector pixel, vector pixel);
10614
vector signed short vec_mergel (vector signed short,
10615
                                vector signed short);
10616
vector unsigned short vec_mergel (vector unsigned short,
10617
                                  vector unsigned short);
10618
vector float vec_mergel (vector float, vector float);
10619
vector bool int vec_mergel (vector bool int, vector bool int);
10620
vector signed int vec_mergel (vector signed int, vector signed int);
10621
vector unsigned int vec_mergel (vector unsigned int,
10622
                                vector unsigned int);
10623
 
10624
vector float vec_vmrglw (vector float, vector float);
10625
vector signed int vec_vmrglw (vector signed int, vector signed int);
10626
vector unsigned int vec_vmrglw (vector unsigned int,
10627
                                vector unsigned int);
10628
vector bool int vec_vmrglw (vector bool int, vector bool int);
10629
 
10630
vector bool short vec_vmrglh (vector bool short, vector bool short);
10631
vector signed short vec_vmrglh (vector signed short,
10632
                                vector signed short);
10633
vector unsigned short vec_vmrglh (vector unsigned short,
10634
                                  vector unsigned short);
10635
vector pixel vec_vmrglh (vector pixel, vector pixel);
10636
 
10637
vector bool char vec_vmrglb (vector bool char, vector bool char);
10638
vector signed char vec_vmrglb (vector signed char, vector signed char);
10639
vector unsigned char vec_vmrglb (vector unsigned char,
10640
                                 vector unsigned char);
10641
 
10642
vector unsigned short vec_mfvscr (void);
10643
 
10644
vector unsigned char vec_min (vector bool char, vector unsigned char);
10645
vector unsigned char vec_min (vector unsigned char, vector bool char);
10646
vector unsigned char vec_min (vector unsigned char,
10647
                              vector unsigned char);
10648
vector signed char vec_min (vector bool char, vector signed char);
10649
vector signed char vec_min (vector signed char, vector bool char);
10650
vector signed char vec_min (vector signed char, vector signed char);
10651
vector unsigned short vec_min (vector bool short,
10652
                               vector unsigned short);
10653
vector unsigned short vec_min (vector unsigned short,
10654
                               vector bool short);
10655
vector unsigned short vec_min (vector unsigned short,
10656
                               vector unsigned short);
10657
vector signed short vec_min (vector bool short, vector signed short);
10658
vector signed short vec_min (vector signed short, vector bool short);
10659
vector signed short vec_min (vector signed short, vector signed short);
10660
vector unsigned int vec_min (vector bool int, vector unsigned int);
10661
vector unsigned int vec_min (vector unsigned int, vector bool int);
10662
vector unsigned int vec_min (vector unsigned int, vector unsigned int);
10663
vector signed int vec_min (vector bool int, vector signed int);
10664
vector signed int vec_min (vector signed int, vector bool int);
10665
vector signed int vec_min (vector signed int, vector signed int);
10666
vector float vec_min (vector float, vector float);
10667
 
10668
vector float vec_vminfp (vector float, vector float);
10669
 
10670
vector signed int vec_vminsw (vector bool int, vector signed int);
10671
vector signed int vec_vminsw (vector signed int, vector bool int);
10672
vector signed int vec_vminsw (vector signed int, vector signed int);
10673
 
10674
vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
10675
vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
10676
vector unsigned int vec_vminuw (vector unsigned int,
10677
                                vector unsigned int);
10678
 
10679
vector signed short vec_vminsh (vector bool short, vector signed short);
10680
vector signed short vec_vminsh (vector signed short, vector bool short);
10681
vector signed short vec_vminsh (vector signed short,
10682
                                vector signed short);
10683
 
10684
vector unsigned short vec_vminuh (vector bool short,
10685
                                  vector unsigned short);
10686
vector unsigned short vec_vminuh (vector unsigned short,
10687
                                  vector bool short);
10688
vector unsigned short vec_vminuh (vector unsigned short,
10689
                                  vector unsigned short);
10690
 
10691
vector signed char vec_vminsb (vector bool char, vector signed char);
10692
vector signed char vec_vminsb (vector signed char, vector bool char);
10693
vector signed char vec_vminsb (vector signed char, vector signed char);
10694
 
10695
vector unsigned char vec_vminub (vector bool char,
10696
                                 vector unsigned char);
10697
vector unsigned char vec_vminub (vector unsigned char,
10698
                                 vector bool char);
10699
vector unsigned char vec_vminub (vector unsigned char,
10700
                                 vector unsigned char);
10701
 
10702
vector signed short vec_mladd (vector signed short,
10703
                               vector signed short,
10704
                               vector signed short);
10705
vector signed short vec_mladd (vector signed short,
10706
                               vector unsigned short,
10707
                               vector unsigned short);
10708
vector signed short vec_mladd (vector unsigned short,
10709
                               vector signed short,
10710
                               vector signed short);
10711
vector unsigned short vec_mladd (vector unsigned short,
10712
                                 vector unsigned short,
10713
                                 vector unsigned short);
10714
 
10715
vector signed short vec_mradds (vector signed short,
10716
                                vector signed short,
10717
                                vector signed short);
10718
 
10719
vector unsigned int vec_msum (vector unsigned char,
10720
                              vector unsigned char,
10721
                              vector unsigned int);
10722
vector signed int vec_msum (vector signed char,
10723
                            vector unsigned char,
10724
                            vector signed int);
10725
vector unsigned int vec_msum (vector unsigned short,
10726
                              vector unsigned short,
10727
                              vector unsigned int);
10728
vector signed int vec_msum (vector signed short,
10729
                            vector signed short,
10730
                            vector signed int);
10731
 
10732
vector signed int vec_vmsumshm (vector signed short,
10733
                                vector signed short,
10734
                                vector signed int);
10735
 
10736
vector unsigned int vec_vmsumuhm (vector unsigned short,
10737
                                  vector unsigned short,
10738
                                  vector unsigned int);
10739
 
10740
vector signed int vec_vmsummbm (vector signed char,
10741
                                vector unsigned char,
10742
                                vector signed int);
10743
 
10744
vector unsigned int vec_vmsumubm (vector unsigned char,
10745
                                  vector unsigned char,
10746
                                  vector unsigned int);
10747
 
10748
vector unsigned int vec_msums (vector unsigned short,
10749
                               vector unsigned short,
10750
                               vector unsigned int);
10751
vector signed int vec_msums (vector signed short,
10752
                             vector signed short,
10753
                             vector signed int);
10754
 
10755
vector signed int vec_vmsumshs (vector signed short,
10756
                                vector signed short,
10757
                                vector signed int);
10758
 
10759
vector unsigned int vec_vmsumuhs (vector unsigned short,
10760
                                  vector unsigned short,
10761
                                  vector unsigned int);
10762
 
10763
void vec_mtvscr (vector signed int);
10764
void vec_mtvscr (vector unsigned int);
10765
void vec_mtvscr (vector bool int);
10766
void vec_mtvscr (vector signed short);
10767
void vec_mtvscr (vector unsigned short);
10768
void vec_mtvscr (vector bool short);
10769
void vec_mtvscr (vector pixel);
10770
void vec_mtvscr (vector signed char);
10771
void vec_mtvscr (vector unsigned char);
10772
void vec_mtvscr (vector bool char);
10773
 
10774
vector unsigned short vec_mule (vector unsigned char,
10775
                                vector unsigned char);
10776
vector signed short vec_mule (vector signed char,
10777
                              vector signed char);
10778
vector unsigned int vec_mule (vector unsigned short,
10779
                              vector unsigned short);
10780
vector signed int vec_mule (vector signed short, vector signed short);
10781
 
10782
vector signed int vec_vmulesh (vector signed short,
10783
                               vector signed short);
10784
 
10785
vector unsigned int vec_vmuleuh (vector unsigned short,
10786
                                 vector unsigned short);
10787
 
10788
vector signed short vec_vmulesb (vector signed char,
10789
                                 vector signed char);
10790
 
10791
vector unsigned short vec_vmuleub (vector unsigned char,
10792
                                  vector unsigned char);
10793
 
10794
vector unsigned short vec_mulo (vector unsigned char,
10795
                                vector unsigned char);
10796
vector signed short vec_mulo (vector signed char, vector signed char);
10797
vector unsigned int vec_mulo (vector unsigned short,
10798
                              vector unsigned short);
10799
vector signed int vec_mulo (vector signed short, vector signed short);
10800
 
10801
vector signed int vec_vmulosh (vector signed short,
10802
                               vector signed short);
10803
 
10804
vector unsigned int vec_vmulouh (vector unsigned short,
10805
                                 vector unsigned short);
10806
 
10807
vector signed short vec_vmulosb (vector signed char,
10808
                                 vector signed char);
10809
 
10810
vector unsigned short vec_vmuloub (vector unsigned char,
10811
                                   vector unsigned char);
10812
 
10813
vector float vec_nmsub (vector float, vector float, vector float);
10814
 
10815
vector float vec_nor (vector float, vector float);
10816
vector signed int vec_nor (vector signed int, vector signed int);
10817
vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
10818
vector bool int vec_nor (vector bool int, vector bool int);
10819
vector signed short vec_nor (vector signed short, vector signed short);
10820
vector unsigned short vec_nor (vector unsigned short,
10821
                               vector unsigned short);
10822
vector bool short vec_nor (vector bool short, vector bool short);
10823
vector signed char vec_nor (vector signed char, vector signed char);
10824
vector unsigned char vec_nor (vector unsigned char,
10825
                              vector unsigned char);
10826
vector bool char vec_nor (vector bool char, vector bool char);
10827
 
10828
vector float vec_or (vector float, vector float);
10829
vector float vec_or (vector float, vector bool int);
10830
vector float vec_or (vector bool int, vector float);
10831
vector bool int vec_or (vector bool int, vector bool int);
10832
vector signed int vec_or (vector bool int, vector signed int);
10833
vector signed int vec_or (vector signed int, vector bool int);
10834
vector signed int vec_or (vector signed int, vector signed int);
10835
vector unsigned int vec_or (vector bool int, vector unsigned int);
10836
vector unsigned int vec_or (vector unsigned int, vector bool int);
10837
vector unsigned int vec_or (vector unsigned int, vector unsigned int);
10838
vector bool short vec_or (vector bool short, vector bool short);
10839
vector signed short vec_or (vector bool short, vector signed short);
10840
vector signed short vec_or (vector signed short, vector bool short);
10841
vector signed short vec_or (vector signed short, vector signed short);
10842
vector unsigned short vec_or (vector bool short, vector unsigned short);
10843
vector unsigned short vec_or (vector unsigned short, vector bool short);
10844
vector unsigned short vec_or (vector unsigned short,
10845
                              vector unsigned short);
10846
vector signed char vec_or (vector bool char, vector signed char);
10847
vector bool char vec_or (vector bool char, vector bool char);
10848
vector signed char vec_or (vector signed char, vector bool char);
10849
vector signed char vec_or (vector signed char, vector signed char);
10850
vector unsigned char vec_or (vector bool char, vector unsigned char);
10851
vector unsigned char vec_or (vector unsigned char, vector bool char);
10852
vector unsigned char vec_or (vector unsigned char,
10853
                             vector unsigned char);
10854
 
10855
vector signed char vec_pack (vector signed short, vector signed short);
10856
vector unsigned char vec_pack (vector unsigned short,
10857
                               vector unsigned short);
10858
vector bool char vec_pack (vector bool short, vector bool short);
10859
vector signed short vec_pack (vector signed int, vector signed int);
10860
vector unsigned short vec_pack (vector unsigned int,
10861
                                vector unsigned int);
10862
vector bool short vec_pack (vector bool int, vector bool int);
10863
 
10864
vector bool short vec_vpkuwum (vector bool int, vector bool int);
10865
vector signed short vec_vpkuwum (vector signed int, vector signed int);
10866
vector unsigned short vec_vpkuwum (vector unsigned int,
10867
                                   vector unsigned int);
10868
 
10869
vector bool char vec_vpkuhum (vector bool short, vector bool short);
10870
vector signed char vec_vpkuhum (vector signed short,
10871
                                vector signed short);
10872
vector unsigned char vec_vpkuhum (vector unsigned short,
10873
                                  vector unsigned short);
10874
 
10875
vector pixel vec_packpx (vector unsigned int, vector unsigned int);
10876
 
10877
vector unsigned char vec_packs (vector unsigned short,
10878
                                vector unsigned short);
10879
vector signed char vec_packs (vector signed short, vector signed short);
10880
vector unsigned short vec_packs (vector unsigned int,
10881
                                 vector unsigned int);
10882
vector signed short vec_packs (vector signed int, vector signed int);
10883
 
10884
vector signed short vec_vpkswss (vector signed int, vector signed int);
10885
 
10886
vector unsigned short vec_vpkuwus (vector unsigned int,
10887
                                   vector unsigned int);
10888
 
10889
vector signed char vec_vpkshss (vector signed short,
10890
                                vector signed short);
10891
 
10892
vector unsigned char vec_vpkuhus (vector unsigned short,
10893
                                  vector unsigned short);
10894
 
10895
vector unsigned char vec_packsu (vector unsigned short,
10896
                                 vector unsigned short);
10897
vector unsigned char vec_packsu (vector signed short,
10898
                                 vector signed short);
10899
vector unsigned short vec_packsu (vector unsigned int,
10900
                                  vector unsigned int);
10901
vector unsigned short vec_packsu (vector signed int, vector signed int);
10902
 
10903
vector unsigned short vec_vpkswus (vector signed int,
10904
                                   vector signed int);
10905
 
10906
vector unsigned char vec_vpkshus (vector signed short,
10907
                                  vector signed short);
10908
 
10909
vector float vec_perm (vector float,
10910
                       vector float,
10911
                       vector unsigned char);
10912
vector signed int vec_perm (vector signed int,
10913
                            vector signed int,
10914
                            vector unsigned char);
10915
vector unsigned int vec_perm (vector unsigned int,
10916
                              vector unsigned int,
10917
                              vector unsigned char);
10918
vector bool int vec_perm (vector bool int,
10919
                          vector bool int,
10920
                          vector unsigned char);
10921
vector signed short vec_perm (vector signed short,
10922
                              vector signed short,
10923
                              vector unsigned char);
10924
vector unsigned short vec_perm (vector unsigned short,
10925
                                vector unsigned short,
10926
                                vector unsigned char);
10927
vector bool short vec_perm (vector bool short,
10928
                            vector bool short,
10929
                            vector unsigned char);
10930
vector pixel vec_perm (vector pixel,
10931
                       vector pixel,
10932
                       vector unsigned char);
10933
vector signed char vec_perm (vector signed char,
10934
                             vector signed char,
10935
                             vector unsigned char);
10936
vector unsigned char vec_perm (vector unsigned char,
10937
                               vector unsigned char,
10938
                               vector unsigned char);
10939
vector bool char vec_perm (vector bool char,
10940
                           vector bool char,
10941
                           vector unsigned char);
10942
 
10943
vector float vec_re (vector float);
10944
 
10945
vector signed char vec_rl (vector signed char,
10946
                           vector unsigned char);
10947
vector unsigned char vec_rl (vector unsigned char,
10948
                             vector unsigned char);
10949
vector signed short vec_rl (vector signed short, vector unsigned short);
10950
vector unsigned short vec_rl (vector unsigned short,
10951
                              vector unsigned short);
10952
vector signed int vec_rl (vector signed int, vector unsigned int);
10953
vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
10954
 
10955
vector signed int vec_vrlw (vector signed int, vector unsigned int);
10956
vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
10957
 
10958
vector signed short vec_vrlh (vector signed short,
10959
                              vector unsigned short);
10960
vector unsigned short vec_vrlh (vector unsigned short,
10961
                                vector unsigned short);
10962
 
10963
vector signed char vec_vrlb (vector signed char, vector unsigned char);
10964
vector unsigned char vec_vrlb (vector unsigned char,
10965
                               vector unsigned char);
10966
 
10967
vector float vec_round (vector float);
10968
 
10969
vector float vec_rsqrte (vector float);
10970
 
10971
vector float vec_sel (vector float, vector float, vector bool int);
10972
vector float vec_sel (vector float, vector float, vector unsigned int);
10973
vector signed int vec_sel (vector signed int,
10974
                           vector signed int,
10975
                           vector bool int);
10976
vector signed int vec_sel (vector signed int,
10977
                           vector signed int,
10978
                           vector unsigned int);
10979
vector unsigned int vec_sel (vector unsigned int,
10980
                             vector unsigned int,
10981
                             vector bool int);
10982
vector unsigned int vec_sel (vector unsigned int,
10983
                             vector unsigned int,
10984
                             vector unsigned int);
10985
vector bool int vec_sel (vector bool int,
10986
                         vector bool int,
10987
                         vector bool int);
10988
vector bool int vec_sel (vector bool int,
10989
                         vector bool int,
10990
                         vector unsigned int);
10991
vector signed short vec_sel (vector signed short,
10992
                             vector signed short,
10993
                             vector bool short);
10994
vector signed short vec_sel (vector signed short,
10995
                             vector signed short,
10996
                             vector unsigned short);
10997
vector unsigned short vec_sel (vector unsigned short,
10998
                               vector unsigned short,
10999
                               vector bool short);
11000
vector unsigned short vec_sel (vector unsigned short,
11001
                               vector unsigned short,
11002
                               vector unsigned short);
11003
vector bool short vec_sel (vector bool short,
11004
                           vector bool short,
11005
                           vector bool short);
11006
vector bool short vec_sel (vector bool short,
11007
                           vector bool short,
11008
                           vector unsigned short);
11009
vector signed char vec_sel (vector signed char,
11010
                            vector signed char,
11011
                            vector bool char);
11012
vector signed char vec_sel (vector signed char,
11013
                            vector signed char,
11014
                            vector unsigned char);
11015
vector unsigned char vec_sel (vector unsigned char,
11016
                              vector unsigned char,
11017
                              vector bool char);
11018
vector unsigned char vec_sel (vector unsigned char,
11019
                              vector unsigned char,
11020
                              vector unsigned char);
11021
vector bool char vec_sel (vector bool char,
11022
                          vector bool char,
11023
                          vector bool char);
11024
vector bool char vec_sel (vector bool char,
11025
                          vector bool char,
11026
                          vector unsigned char);
11027
 
11028
vector signed char vec_sl (vector signed char,
11029
                           vector unsigned char);
11030
vector unsigned char vec_sl (vector unsigned char,
11031
                             vector unsigned char);
11032
vector signed short vec_sl (vector signed short, vector unsigned short);
11033
vector unsigned short vec_sl (vector unsigned short,
11034
                              vector unsigned short);
11035
vector signed int vec_sl (vector signed int, vector unsigned int);
11036
vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
11037
 
11038
vector signed int vec_vslw (vector signed int, vector unsigned int);
11039
vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
11040
 
11041
vector signed short vec_vslh (vector signed short,
11042
                              vector unsigned short);
11043
vector unsigned short vec_vslh (vector unsigned short,
11044
                                vector unsigned short);
11045
 
11046
vector signed char vec_vslb (vector signed char, vector unsigned char);
11047
vector unsigned char vec_vslb (vector unsigned char,
11048
                               vector unsigned char);
11049
 
11050
vector float vec_sld (vector float, vector float, const int);
11051
vector signed int vec_sld (vector signed int,
11052
                           vector signed int,
11053
                           const int);
11054
vector unsigned int vec_sld (vector unsigned int,
11055
                             vector unsigned int,
11056
                             const int);
11057
vector bool int vec_sld (vector bool int,
11058
                         vector bool int,
11059
                         const int);
11060
vector signed short vec_sld (vector signed short,
11061
                             vector signed short,
11062
                             const int);
11063
vector unsigned short vec_sld (vector unsigned short,
11064
                               vector unsigned short,
11065
                               const int);
11066
vector bool short vec_sld (vector bool short,
11067
                           vector bool short,
11068
                           const int);
11069
vector pixel vec_sld (vector pixel,
11070
                      vector pixel,
11071
                      const int);
11072
vector signed char vec_sld (vector signed char,
11073
                            vector signed char,
11074
                            const int);
11075
vector unsigned char vec_sld (vector unsigned char,
11076
                              vector unsigned char,
11077
                              const int);
11078
vector bool char vec_sld (vector bool char,
11079
                          vector bool char,
11080
                          const int);
11081
 
11082
vector signed int vec_sll (vector signed int,
11083
                           vector unsigned int);
11084
vector signed int vec_sll (vector signed int,
11085
                           vector unsigned short);
11086
vector signed int vec_sll (vector signed int,
11087
                           vector unsigned char);
11088
vector unsigned int vec_sll (vector unsigned int,
11089
                             vector unsigned int);
11090
vector unsigned int vec_sll (vector unsigned int,
11091
                             vector unsigned short);
11092
vector unsigned int vec_sll (vector unsigned int,
11093
                             vector unsigned char);
11094
vector bool int vec_sll (vector bool int,
11095
                         vector unsigned int);
11096
vector bool int vec_sll (vector bool int,
11097
                         vector unsigned short);
11098
vector bool int vec_sll (vector bool int,
11099
                         vector unsigned char);
11100
vector signed short vec_sll (vector signed short,
11101
                             vector unsigned int);
11102
vector signed short vec_sll (vector signed short,
11103
                             vector unsigned short);
11104
vector signed short vec_sll (vector signed short,
11105
                             vector unsigned char);
11106
vector unsigned short vec_sll (vector unsigned short,
11107
                               vector unsigned int);
11108
vector unsigned short vec_sll (vector unsigned short,
11109
                               vector unsigned short);
11110
vector unsigned short vec_sll (vector unsigned short,
11111
                               vector unsigned char);
11112
vector bool short vec_sll (vector bool short, vector unsigned int);
11113
vector bool short vec_sll (vector bool short, vector unsigned short);
11114
vector bool short vec_sll (vector bool short, vector unsigned char);
11115
vector pixel vec_sll (vector pixel, vector unsigned int);
11116
vector pixel vec_sll (vector pixel, vector unsigned short);
11117
vector pixel vec_sll (vector pixel, vector unsigned char);
11118
vector signed char vec_sll (vector signed char, vector unsigned int);
11119
vector signed char vec_sll (vector signed char, vector unsigned short);
11120
vector signed char vec_sll (vector signed char, vector unsigned char);
11121
vector unsigned char vec_sll (vector unsigned char,
11122
                              vector unsigned int);
11123
vector unsigned char vec_sll (vector unsigned char,
11124
                              vector unsigned short);
11125
vector unsigned char vec_sll (vector unsigned char,
11126
                              vector unsigned char);
11127
vector bool char vec_sll (vector bool char, vector unsigned int);
11128
vector bool char vec_sll (vector bool char, vector unsigned short);
11129
vector bool char vec_sll (vector bool char, vector unsigned char);
11130
 
11131
vector float vec_slo (vector float, vector signed char);
11132
vector float vec_slo (vector float, vector unsigned char);
11133
vector signed int vec_slo (vector signed int, vector signed char);
11134
vector signed int vec_slo (vector signed int, vector unsigned char);
11135
vector unsigned int vec_slo (vector unsigned int, vector signed char);
11136
vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
11137
vector signed short vec_slo (vector signed short, vector signed char);
11138
vector signed short vec_slo (vector signed short, vector unsigned char);
11139
vector unsigned short vec_slo (vector unsigned short,
11140
                               vector signed char);
11141
vector unsigned short vec_slo (vector unsigned short,
11142
                               vector unsigned char);
11143
vector pixel vec_slo (vector pixel, vector signed char);
11144
vector pixel vec_slo (vector pixel, vector unsigned char);
11145
vector signed char vec_slo (vector signed char, vector signed char);
11146
vector signed char vec_slo (vector signed char, vector unsigned char);
11147
vector unsigned char vec_slo (vector unsigned char, vector signed char);
11148
vector unsigned char vec_slo (vector unsigned char,
11149
                              vector unsigned char);
11150
 
11151
vector signed char vec_splat (vector signed char, const int);
11152
vector unsigned char vec_splat (vector unsigned char, const int);
11153
vector bool char vec_splat (vector bool char, const int);
11154
vector signed short vec_splat (vector signed short, const int);
11155
vector unsigned short vec_splat (vector unsigned short, const int);
11156
vector bool short vec_splat (vector bool short, const int);
11157
vector pixel vec_splat (vector pixel, const int);
11158
vector float vec_splat (vector float, const int);
11159
vector signed int vec_splat (vector signed int, const int);
11160
vector unsigned int vec_splat (vector unsigned int, const int);
11161
vector bool int vec_splat (vector bool int, const int);
11162
 
11163
vector float vec_vspltw (vector float, const int);
11164
vector signed int vec_vspltw (vector signed int, const int);
11165
vector unsigned int vec_vspltw (vector unsigned int, const int);
11166
vector bool int vec_vspltw (vector bool int, const int);
11167
 
11168
vector bool short vec_vsplth (vector bool short, const int);
11169
vector signed short vec_vsplth (vector signed short, const int);
11170
vector unsigned short vec_vsplth (vector unsigned short, const int);
11171
vector pixel vec_vsplth (vector pixel, const int);
11172
 
11173
vector signed char vec_vspltb (vector signed char, const int);
11174
vector unsigned char vec_vspltb (vector unsigned char, const int);
11175
vector bool char vec_vspltb (vector bool char, const int);
11176
 
11177
vector signed char vec_splat_s8 (const int);
11178
 
11179
vector signed short vec_splat_s16 (const int);
11180
 
11181
vector signed int vec_splat_s32 (const int);
11182
 
11183
vector unsigned char vec_splat_u8 (const int);
11184
 
11185
vector unsigned short vec_splat_u16 (const int);
11186
 
11187
vector unsigned int vec_splat_u32 (const int);
11188
 
11189
vector signed char vec_sr (vector signed char, vector unsigned char);
11190
vector unsigned char vec_sr (vector unsigned char,
11191
                             vector unsigned char);
11192
vector signed short vec_sr (vector signed short,
11193
                            vector unsigned short);
11194
vector unsigned short vec_sr (vector unsigned short,
11195
                              vector unsigned short);
11196
vector signed int vec_sr (vector signed int, vector unsigned int);
11197
vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
11198
 
11199
vector signed int vec_vsrw (vector signed int, vector unsigned int);
11200
vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
11201
 
11202
vector signed short vec_vsrh (vector signed short,
11203
                              vector unsigned short);
11204
vector unsigned short vec_vsrh (vector unsigned short,
11205
                                vector unsigned short);
11206
 
11207
vector signed char vec_vsrb (vector signed char, vector unsigned char);
11208
vector unsigned char vec_vsrb (vector unsigned char,
11209
                               vector unsigned char);
11210
 
11211
vector signed char vec_sra (vector signed char, vector unsigned char);
11212
vector unsigned char vec_sra (vector unsigned char,
11213
                              vector unsigned char);
11214
vector signed short vec_sra (vector signed short,
11215
                             vector unsigned short);
11216
vector unsigned short vec_sra (vector unsigned short,
11217
                               vector unsigned short);
11218
vector signed int vec_sra (vector signed int, vector unsigned int);
11219
vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
11220
 
11221
vector signed int vec_vsraw (vector signed int, vector unsigned int);
11222
vector unsigned int vec_vsraw (vector unsigned int,
11223
                               vector unsigned int);
11224
 
11225
vector signed short vec_vsrah (vector signed short,
11226
                               vector unsigned short);
11227
vector unsigned short vec_vsrah (vector unsigned short,
11228
                                 vector unsigned short);
11229
 
11230
vector signed char vec_vsrab (vector signed char, vector unsigned char);
11231
vector unsigned char vec_vsrab (vector unsigned char,
11232
                                vector unsigned char);
11233
 
11234
vector signed int vec_srl (vector signed int, vector unsigned int);
11235
vector signed int vec_srl (vector signed int, vector unsigned short);
11236
vector signed int vec_srl (vector signed int, vector unsigned char);
11237
vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
11238
vector unsigned int vec_srl (vector unsigned int,
11239
                             vector unsigned short);
11240
vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
11241
vector bool int vec_srl (vector bool int, vector unsigned int);
11242
vector bool int vec_srl (vector bool int, vector unsigned short);
11243
vector bool int vec_srl (vector bool int, vector unsigned char);
11244
vector signed short vec_srl (vector signed short, vector unsigned int);
11245
vector signed short vec_srl (vector signed short,
11246
                             vector unsigned short);
11247
vector signed short vec_srl (vector signed short, vector unsigned char);
11248
vector unsigned short vec_srl (vector unsigned short,
11249
                               vector unsigned int);
11250
vector unsigned short vec_srl (vector unsigned short,
11251
                               vector unsigned short);
11252
vector unsigned short vec_srl (vector unsigned short,
11253
                               vector unsigned char);
11254
vector bool short vec_srl (vector bool short, vector unsigned int);
11255
vector bool short vec_srl (vector bool short, vector unsigned short);
11256
vector bool short vec_srl (vector bool short, vector unsigned char);
11257
vector pixel vec_srl (vector pixel, vector unsigned int);
11258
vector pixel vec_srl (vector pixel, vector unsigned short);
11259
vector pixel vec_srl (vector pixel, vector unsigned char);
11260
vector signed char vec_srl (vector signed char, vector unsigned int);
11261
vector signed char vec_srl (vector signed char, vector unsigned short);
11262
vector signed char vec_srl (vector signed char, vector unsigned char);
11263
vector unsigned char vec_srl (vector unsigned char,
11264
                              vector unsigned int);
11265
vector unsigned char vec_srl (vector unsigned char,
11266
                              vector unsigned short);
11267
vector unsigned char vec_srl (vector unsigned char,
11268
                              vector unsigned char);
11269
vector bool char vec_srl (vector bool char, vector unsigned int);
11270
vector bool char vec_srl (vector bool char, vector unsigned short);
11271
vector bool char vec_srl (vector bool char, vector unsigned char);
11272
 
11273
vector float vec_sro (vector float, vector signed char);
11274
vector float vec_sro (vector float, vector unsigned char);
11275
vector signed int vec_sro (vector signed int, vector signed char);
11276
vector signed int vec_sro (vector signed int, vector unsigned char);
11277
vector unsigned int vec_sro (vector unsigned int, vector signed char);
11278
vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
11279
vector signed short vec_sro (vector signed short, vector signed char);
11280
vector signed short vec_sro (vector signed short, vector unsigned char);
11281
vector unsigned short vec_sro (vector unsigned short,
11282
                               vector signed char);
11283
vector unsigned short vec_sro (vector unsigned short,
11284
                               vector unsigned char);
11285
vector pixel vec_sro (vector pixel, vector signed char);
11286
vector pixel vec_sro (vector pixel, vector unsigned char);
11287
vector signed char vec_sro (vector signed char, vector signed char);
11288
vector signed char vec_sro (vector signed char, vector unsigned char);
11289
vector unsigned char vec_sro (vector unsigned char, vector signed char);
11290
vector unsigned char vec_sro (vector unsigned char,
11291
                              vector unsigned char);
11292
 
11293
void vec_st (vector float, int, vector float *);
11294
void vec_st (vector float, int, float *);
11295
void vec_st (vector signed int, int, vector signed int *);
11296
void vec_st (vector signed int, int, int *);
11297
void vec_st (vector unsigned int, int, vector unsigned int *);
11298
void vec_st (vector unsigned int, int, unsigned int *);
11299
void vec_st (vector bool int, int, vector bool int *);
11300
void vec_st (vector bool int, int, unsigned int *);
11301
void vec_st (vector bool int, int, int *);
11302
void vec_st (vector signed short, int, vector signed short *);
11303
void vec_st (vector signed short, int, short *);
11304
void vec_st (vector unsigned short, int, vector unsigned short *);
11305
void vec_st (vector unsigned short, int, unsigned short *);
11306
void vec_st (vector bool short, int, vector bool short *);
11307
void vec_st (vector bool short, int, unsigned short *);
11308
void vec_st (vector pixel, int, vector pixel *);
11309
void vec_st (vector pixel, int, unsigned short *);
11310
void vec_st (vector pixel, int, short *);
11311
void vec_st (vector bool short, int, short *);
11312
void vec_st (vector signed char, int, vector signed char *);
11313
void vec_st (vector signed char, int, signed char *);
11314
void vec_st (vector unsigned char, int, vector unsigned char *);
11315
void vec_st (vector unsigned char, int, unsigned char *);
11316
void vec_st (vector bool char, int, vector bool char *);
11317
void vec_st (vector bool char, int, unsigned char *);
11318
void vec_st (vector bool char, int, signed char *);
11319
 
11320
void vec_ste (vector signed char, int, signed char *);
11321
void vec_ste (vector unsigned char, int, unsigned char *);
11322
void vec_ste (vector bool char, int, signed char *);
11323
void vec_ste (vector bool char, int, unsigned char *);
11324
void vec_ste (vector signed short, int, short *);
11325
void vec_ste (vector unsigned short, int, unsigned short *);
11326
void vec_ste (vector bool short, int, short *);
11327
void vec_ste (vector bool short, int, unsigned short *);
11328
void vec_ste (vector pixel, int, short *);
11329
void vec_ste (vector pixel, int, unsigned short *);
11330
void vec_ste (vector float, int, float *);
11331
void vec_ste (vector signed int, int, int *);
11332
void vec_ste (vector unsigned int, int, unsigned int *);
11333
void vec_ste (vector bool int, int, int *);
11334
void vec_ste (vector bool int, int, unsigned int *);
11335
 
11336
void vec_stvewx (vector float, int, float *);
11337
void vec_stvewx (vector signed int, int, int *);
11338
void vec_stvewx (vector unsigned int, int, unsigned int *);
11339
void vec_stvewx (vector bool int, int, int *);
11340
void vec_stvewx (vector bool int, int, unsigned int *);
11341
 
11342
void vec_stvehx (vector signed short, int, short *);
11343
void vec_stvehx (vector unsigned short, int, unsigned short *);
11344
void vec_stvehx (vector bool short, int, short *);
11345
void vec_stvehx (vector bool short, int, unsigned short *);
11346
void vec_stvehx (vector pixel, int, short *);
11347
void vec_stvehx (vector pixel, int, unsigned short *);
11348
 
11349
void vec_stvebx (vector signed char, int, signed char *);
11350
void vec_stvebx (vector unsigned char, int, unsigned char *);
11351
void vec_stvebx (vector bool char, int, signed char *);
11352
void vec_stvebx (vector bool char, int, unsigned char *);
11353
 
11354
void vec_stl (vector float, int, vector float *);
11355
void vec_stl (vector float, int, float *);
11356
void vec_stl (vector signed int, int, vector signed int *);
11357
void vec_stl (vector signed int, int, int *);
11358
void vec_stl (vector unsigned int, int, vector unsigned int *);
11359
void vec_stl (vector unsigned int, int, unsigned int *);
11360
void vec_stl (vector bool int, int, vector bool int *);
11361
void vec_stl (vector bool int, int, unsigned int *);
11362
void vec_stl (vector bool int, int, int *);
11363
void vec_stl (vector signed short, int, vector signed short *);
11364
void vec_stl (vector signed short, int, short *);
11365
void vec_stl (vector unsigned short, int, vector unsigned short *);
11366
void vec_stl (vector unsigned short, int, unsigned short *);
11367
void vec_stl (vector bool short, int, vector bool short *);
11368
void vec_stl (vector bool short, int, unsigned short *);
11369
void vec_stl (vector bool short, int, short *);
11370
void vec_stl (vector pixel, int, vector pixel *);
11371
void vec_stl (vector pixel, int, unsigned short *);
11372
void vec_stl (vector pixel, int, short *);
11373
void vec_stl (vector signed char, int, vector signed char *);
11374
void vec_stl (vector signed char, int, signed char *);
11375
void vec_stl (vector unsigned char, int, vector unsigned char *);
11376
void vec_stl (vector unsigned char, int, unsigned char *);
11377
void vec_stl (vector bool char, int, vector bool char *);
11378
void vec_stl (vector bool char, int, unsigned char *);
11379
void vec_stl (vector bool char, int, signed char *);
11380
 
11381
vector signed char vec_sub (vector bool char, vector signed char);
11382
vector signed char vec_sub (vector signed char, vector bool char);
11383
vector signed char vec_sub (vector signed char, vector signed char);
11384
vector unsigned char vec_sub (vector bool char, vector unsigned char);
11385
vector unsigned char vec_sub (vector unsigned char, vector bool char);
11386
vector unsigned char vec_sub (vector unsigned char,
11387
                              vector unsigned char);
11388
vector signed short vec_sub (vector bool short, vector signed short);
11389
vector signed short vec_sub (vector signed short, vector bool short);
11390
vector signed short vec_sub (vector signed short, vector signed short);
11391
vector unsigned short vec_sub (vector bool short,
11392
                               vector unsigned short);
11393
vector unsigned short vec_sub (vector unsigned short,
11394
                               vector bool short);
11395
vector unsigned short vec_sub (vector unsigned short,
11396
                               vector unsigned short);
11397
vector signed int vec_sub (vector bool int, vector signed int);
11398
vector signed int vec_sub (vector signed int, vector bool int);
11399
vector signed int vec_sub (vector signed int, vector signed int);
11400
vector unsigned int vec_sub (vector bool int, vector unsigned int);
11401
vector unsigned int vec_sub (vector unsigned int, vector bool int);
11402
vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
11403
vector float vec_sub (vector float, vector float);
11404
 
11405
vector float vec_vsubfp (vector float, vector float);
11406
 
11407
vector signed int vec_vsubuwm (vector bool int, vector signed int);
11408
vector signed int vec_vsubuwm (vector signed int, vector bool int);
11409
vector signed int vec_vsubuwm (vector signed int, vector signed int);
11410
vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
11411
vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
11412
vector unsigned int vec_vsubuwm (vector unsigned int,
11413
                                 vector unsigned int);
11414
 
11415
vector signed short vec_vsubuhm (vector bool short,
11416
                                 vector signed short);
11417
vector signed short vec_vsubuhm (vector signed short,
11418
                                 vector bool short);
11419
vector signed short vec_vsubuhm (vector signed short,
11420
                                 vector signed short);
11421
vector unsigned short vec_vsubuhm (vector bool short,
11422
                                   vector unsigned short);
11423
vector unsigned short vec_vsubuhm (vector unsigned short,
11424
                                   vector bool short);
11425
vector unsigned short vec_vsubuhm (vector unsigned short,
11426
                                   vector unsigned short);
11427
 
11428
vector signed char vec_vsububm (vector bool char, vector signed char);
11429
vector signed char vec_vsububm (vector signed char, vector bool char);
11430
vector signed char vec_vsububm (vector signed char, vector signed char);
11431
vector unsigned char vec_vsububm (vector bool char,
11432
                                  vector unsigned char);
11433
vector unsigned char vec_vsububm (vector unsigned char,
11434
                                  vector bool char);
11435
vector unsigned char vec_vsububm (vector unsigned char,
11436
                                  vector unsigned char);
11437
 
11438
vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
11439
 
11440
vector unsigned char vec_subs (vector bool char, vector unsigned char);
11441
vector unsigned char vec_subs (vector unsigned char, vector bool char);
11442
vector unsigned char vec_subs (vector unsigned char,
11443
                               vector unsigned char);
11444
vector signed char vec_subs (vector bool char, vector signed char);
11445
vector signed char vec_subs (vector signed char, vector bool char);
11446
vector signed char vec_subs (vector signed char, vector signed char);
11447
vector unsigned short vec_subs (vector bool short,
11448
                                vector unsigned short);
11449
vector unsigned short vec_subs (vector unsigned short,
11450
                                vector bool short);
11451
vector unsigned short vec_subs (vector unsigned short,
11452
                                vector unsigned short);
11453
vector signed short vec_subs (vector bool short, vector signed short);
11454
vector signed short vec_subs (vector signed short, vector bool short);
11455
vector signed short vec_subs (vector signed short, vector signed short);
11456
vector unsigned int vec_subs (vector bool int, vector unsigned int);
11457
vector unsigned int vec_subs (vector unsigned int, vector bool int);
11458
vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
11459
vector signed int vec_subs (vector bool int, vector signed int);
11460
vector signed int vec_subs (vector signed int, vector bool int);
11461
vector signed int vec_subs (vector signed int, vector signed int);
11462
 
11463
vector signed int vec_vsubsws (vector bool int, vector signed int);
11464
vector signed int vec_vsubsws (vector signed int, vector bool int);
11465
vector signed int vec_vsubsws (vector signed int, vector signed int);
11466
 
11467
vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
11468
vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
11469
vector unsigned int vec_vsubuws (vector unsigned int,
11470
                                 vector unsigned int);
11471
 
11472
vector signed short vec_vsubshs (vector bool short,
11473
                                 vector signed short);
11474
vector signed short vec_vsubshs (vector signed short,
11475
                                 vector bool short);
11476
vector signed short vec_vsubshs (vector signed short,
11477
                                 vector signed short);
11478
 
11479
vector unsigned short vec_vsubuhs (vector bool short,
11480
                                   vector unsigned short);
11481
vector unsigned short vec_vsubuhs (vector unsigned short,
11482
                                   vector bool short);
11483
vector unsigned short vec_vsubuhs (vector unsigned short,
11484
                                   vector unsigned short);
11485
 
11486
vector signed char vec_vsubsbs (vector bool char, vector signed char);
11487
vector signed char vec_vsubsbs (vector signed char, vector bool char);
11488
vector signed char vec_vsubsbs (vector signed char, vector signed char);
11489
 
11490
vector unsigned char vec_vsububs (vector bool char,
11491
                                  vector unsigned char);
11492
vector unsigned char vec_vsububs (vector unsigned char,
11493
                                  vector bool char);
11494
vector unsigned char vec_vsububs (vector unsigned char,
11495
                                  vector unsigned char);
11496
 
11497
vector unsigned int vec_sum4s (vector unsigned char,
11498
                               vector unsigned int);
11499
vector signed int vec_sum4s (vector signed char, vector signed int);
11500
vector signed int vec_sum4s (vector signed short, vector signed int);
11501
 
11502
vector signed int vec_vsum4shs (vector signed short, vector signed int);
11503
 
11504
vector signed int vec_vsum4sbs (vector signed char, vector signed int);
11505
 
11506
vector unsigned int vec_vsum4ubs (vector unsigned char,
11507
                                  vector unsigned int);
11508
 
11509
vector signed int vec_sum2s (vector signed int, vector signed int);
11510
 
11511
vector signed int vec_sums (vector signed int, vector signed int);
11512
 
11513
vector float vec_trunc (vector float);
11514
 
11515
vector signed short vec_unpackh (vector signed char);
11516
vector bool short vec_unpackh (vector bool char);
11517
vector signed int vec_unpackh (vector signed short);
11518
vector bool int vec_unpackh (vector bool short);
11519
vector unsigned int vec_unpackh (vector pixel);
11520
 
11521
vector bool int vec_vupkhsh (vector bool short);
11522
vector signed int vec_vupkhsh (vector signed short);
11523
 
11524
vector unsigned int vec_vupkhpx (vector pixel);
11525
 
11526
vector bool short vec_vupkhsb (vector bool char);
11527
vector signed short vec_vupkhsb (vector signed char);
11528
 
11529
vector signed short vec_unpackl (vector signed char);
11530
vector bool short vec_unpackl (vector bool char);
11531
vector unsigned int vec_unpackl (vector pixel);
11532
vector signed int vec_unpackl (vector signed short);
11533
vector bool int vec_unpackl (vector bool short);
11534
 
11535
vector unsigned int vec_vupklpx (vector pixel);
11536
 
11537
vector bool int vec_vupklsh (vector bool short);
11538
vector signed int vec_vupklsh (vector signed short);
11539
 
11540
vector bool short vec_vupklsb (vector bool char);
11541
vector signed short vec_vupklsb (vector signed char);
11542
 
11543
vector float vec_xor (vector float, vector float);
11544
vector float vec_xor (vector float, vector bool int);
11545
vector float vec_xor (vector bool int, vector float);
11546
vector bool int vec_xor (vector bool int, vector bool int);
11547
vector signed int vec_xor (vector bool int, vector signed int);
11548
vector signed int vec_xor (vector signed int, vector bool int);
11549
vector signed int vec_xor (vector signed int, vector signed int);
11550
vector unsigned int vec_xor (vector bool int, vector unsigned int);
11551
vector unsigned int vec_xor (vector unsigned int, vector bool int);
11552
vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
11553
vector bool short vec_xor (vector bool short, vector bool short);
11554
vector signed short vec_xor (vector bool short, vector signed short);
11555
vector signed short vec_xor (vector signed short, vector bool short);
11556
vector signed short vec_xor (vector signed short, vector signed short);
11557
vector unsigned short vec_xor (vector bool short,
11558
                               vector unsigned short);
11559
vector unsigned short vec_xor (vector unsigned short,
11560
                               vector bool short);
11561
vector unsigned short vec_xor (vector unsigned short,
11562
                               vector unsigned short);
11563
vector signed char vec_xor (vector bool char, vector signed char);
11564
vector bool char vec_xor (vector bool char, vector bool char);
11565
vector signed char vec_xor (vector signed char, vector bool char);
11566
vector signed char vec_xor (vector signed char, vector signed char);
11567
vector unsigned char vec_xor (vector bool char, vector unsigned char);
11568
vector unsigned char vec_xor (vector unsigned char, vector bool char);
11569
vector unsigned char vec_xor (vector unsigned char,
11570
                              vector unsigned char);
11571
 
11572
int vec_all_eq (vector signed char, vector bool char);
11573
int vec_all_eq (vector signed char, vector signed char);
11574
int vec_all_eq (vector unsigned char, vector bool char);
11575
int vec_all_eq (vector unsigned char, vector unsigned char);
11576
int vec_all_eq (vector bool char, vector bool char);
11577
int vec_all_eq (vector bool char, vector unsigned char);
11578
int vec_all_eq (vector bool char, vector signed char);
11579
int vec_all_eq (vector signed short, vector bool short);
11580
int vec_all_eq (vector signed short, vector signed short);
11581
int vec_all_eq (vector unsigned short, vector bool short);
11582
int vec_all_eq (vector unsigned short, vector unsigned short);
11583
int vec_all_eq (vector bool short, vector bool short);
11584
int vec_all_eq (vector bool short, vector unsigned short);
11585
int vec_all_eq (vector bool short, vector signed short);
11586
int vec_all_eq (vector pixel, vector pixel);
11587
int vec_all_eq (vector signed int, vector bool int);
11588
int vec_all_eq (vector signed int, vector signed int);
11589
int vec_all_eq (vector unsigned int, vector bool int);
11590
int vec_all_eq (vector unsigned int, vector unsigned int);
11591
int vec_all_eq (vector bool int, vector bool int);
11592
int vec_all_eq (vector bool int, vector unsigned int);
11593
int vec_all_eq (vector bool int, vector signed int);
11594
int vec_all_eq (vector float, vector float);
11595
 
11596
int vec_all_ge (vector bool char, vector unsigned char);
11597
int vec_all_ge (vector unsigned char, vector bool char);
11598
int vec_all_ge (vector unsigned char, vector unsigned char);
11599
int vec_all_ge (vector bool char, vector signed char);
11600
int vec_all_ge (vector signed char, vector bool char);
11601
int vec_all_ge (vector signed char, vector signed char);
11602
int vec_all_ge (vector bool short, vector unsigned short);
11603
int vec_all_ge (vector unsigned short, vector bool short);
11604
int vec_all_ge (vector unsigned short, vector unsigned short);
11605
int vec_all_ge (vector signed short, vector signed short);
11606
int vec_all_ge (vector bool short, vector signed short);
11607
int vec_all_ge (vector signed short, vector bool short);
11608
int vec_all_ge (vector bool int, vector unsigned int);
11609
int vec_all_ge (vector unsigned int, vector bool int);
11610
int vec_all_ge (vector unsigned int, vector unsigned int);
11611
int vec_all_ge (vector bool int, vector signed int);
11612
int vec_all_ge (vector signed int, vector bool int);
11613
int vec_all_ge (vector signed int, vector signed int);
11614
int vec_all_ge (vector float, vector float);
11615
 
11616
int vec_all_gt (vector bool char, vector unsigned char);
11617
int vec_all_gt (vector unsigned char, vector bool char);
11618
int vec_all_gt (vector unsigned char, vector unsigned char);
11619
int vec_all_gt (vector bool char, vector signed char);
11620
int vec_all_gt (vector signed char, vector bool char);
11621
int vec_all_gt (vector signed char, vector signed char);
11622
int vec_all_gt (vector bool short, vector unsigned short);
11623
int vec_all_gt (vector unsigned short, vector bool short);
11624
int vec_all_gt (vector unsigned short, vector unsigned short);
11625
int vec_all_gt (vector bool short, vector signed short);
11626
int vec_all_gt (vector signed short, vector bool short);
11627
int vec_all_gt (vector signed short, vector signed short);
11628
int vec_all_gt (vector bool int, vector unsigned int);
11629
int vec_all_gt (vector unsigned int, vector bool int);
11630
int vec_all_gt (vector unsigned int, vector unsigned int);
11631
int vec_all_gt (vector bool int, vector signed int);
11632
int vec_all_gt (vector signed int, vector bool int);
11633
int vec_all_gt (vector signed int, vector signed int);
11634
int vec_all_gt (vector float, vector float);
11635
 
11636
int vec_all_in (vector float, vector float);
11637
 
11638
int vec_all_le (vector bool char, vector unsigned char);
11639
int vec_all_le (vector unsigned char, vector bool char);
11640
int vec_all_le (vector unsigned char, vector unsigned char);
11641
int vec_all_le (vector bool char, vector signed char);
11642
int vec_all_le (vector signed char, vector bool char);
11643
int vec_all_le (vector signed char, vector signed char);
11644
int vec_all_le (vector bool short, vector unsigned short);
11645
int vec_all_le (vector unsigned short, vector bool short);
11646
int vec_all_le (vector unsigned short, vector unsigned short);
11647
int vec_all_le (vector bool short, vector signed short);
11648
int vec_all_le (vector signed short, vector bool short);
11649
int vec_all_le (vector signed short, vector signed short);
11650
int vec_all_le (vector bool int, vector unsigned int);
11651
int vec_all_le (vector unsigned int, vector bool int);
11652
int vec_all_le (vector unsigned int, vector unsigned int);
11653
int vec_all_le (vector bool int, vector signed int);
11654
int vec_all_le (vector signed int, vector bool int);
11655
int vec_all_le (vector signed int, vector signed int);
11656
int vec_all_le (vector float, vector float);
11657
 
11658
int vec_all_lt (vector bool char, vector unsigned char);
11659
int vec_all_lt (vector unsigned char, vector bool char);
11660
int vec_all_lt (vector unsigned char, vector unsigned char);
11661
int vec_all_lt (vector bool char, vector signed char);
11662
int vec_all_lt (vector signed char, vector bool char);
11663
int vec_all_lt (vector signed char, vector signed char);
11664
int vec_all_lt (vector bool short, vector unsigned short);
11665
int vec_all_lt (vector unsigned short, vector bool short);
11666
int vec_all_lt (vector unsigned short, vector unsigned short);
11667
int vec_all_lt (vector bool short, vector signed short);
11668
int vec_all_lt (vector signed short, vector bool short);
11669
int vec_all_lt (vector signed short, vector signed short);
11670
int vec_all_lt (vector bool int, vector unsigned int);
11671
int vec_all_lt (vector unsigned int, vector bool int);
11672
int vec_all_lt (vector unsigned int, vector unsigned int);
11673
int vec_all_lt (vector bool int, vector signed int);
11674
int vec_all_lt (vector signed int, vector bool int);
11675
int vec_all_lt (vector signed int, vector signed int);
11676
int vec_all_lt (vector float, vector float);
11677
 
11678
int vec_all_nan (vector float);
11679
 
11680
int vec_all_ne (vector signed char, vector bool char);
11681
int vec_all_ne (vector signed char, vector signed char);
11682
int vec_all_ne (vector unsigned char, vector bool char);
11683
int vec_all_ne (vector unsigned char, vector unsigned char);
11684
int vec_all_ne (vector bool char, vector bool char);
11685
int vec_all_ne (vector bool char, vector unsigned char);
11686
int vec_all_ne (vector bool char, vector signed char);
11687
int vec_all_ne (vector signed short, vector bool short);
11688
int vec_all_ne (vector signed short, vector signed short);
11689
int vec_all_ne (vector unsigned short, vector bool short);
11690
int vec_all_ne (vector unsigned short, vector unsigned short);
11691
int vec_all_ne (vector bool short, vector bool short);
11692
int vec_all_ne (vector bool short, vector unsigned short);
11693
int vec_all_ne (vector bool short, vector signed short);
11694
int vec_all_ne (vector pixel, vector pixel);
11695
int vec_all_ne (vector signed int, vector bool int);
11696
int vec_all_ne (vector signed int, vector signed int);
11697
int vec_all_ne (vector unsigned int, vector bool int);
11698
int vec_all_ne (vector unsigned int, vector unsigned int);
11699
int vec_all_ne (vector bool int, vector bool int);
11700
int vec_all_ne (vector bool int, vector unsigned int);
11701
int vec_all_ne (vector bool int, vector signed int);
11702
int vec_all_ne (vector float, vector float);
11703
 
11704
int vec_all_nge (vector float, vector float);
11705
 
11706
int vec_all_ngt (vector float, vector float);
11707
 
11708
int vec_all_nle (vector float, vector float);
11709
 
11710
int vec_all_nlt (vector float, vector float);
11711
 
11712
int vec_all_numeric (vector float);
11713
 
11714
int vec_any_eq (vector signed char, vector bool char);
11715
int vec_any_eq (vector signed char, vector signed char);
11716
int vec_any_eq (vector unsigned char, vector bool char);
11717
int vec_any_eq (vector unsigned char, vector unsigned char);
11718
int vec_any_eq (vector bool char, vector bool char);
11719
int vec_any_eq (vector bool char, vector unsigned char);
11720
int vec_any_eq (vector bool char, vector signed char);
11721
int vec_any_eq (vector signed short, vector bool short);
11722
int vec_any_eq (vector signed short, vector signed short);
11723
int vec_any_eq (vector unsigned short, vector bool short);
11724
int vec_any_eq (vector unsigned short, vector unsigned short);
11725
int vec_any_eq (vector bool short, vector bool short);
11726
int vec_any_eq (vector bool short, vector unsigned short);
11727
int vec_any_eq (vector bool short, vector signed short);
11728
int vec_any_eq (vector pixel, vector pixel);
11729
int vec_any_eq (vector signed int, vector bool int);
11730
int vec_any_eq (vector signed int, vector signed int);
11731
int vec_any_eq (vector unsigned int, vector bool int);
11732
int vec_any_eq (vector unsigned int, vector unsigned int);
11733
int vec_any_eq (vector bool int, vector bool int);
11734
int vec_any_eq (vector bool int, vector unsigned int);
11735
int vec_any_eq (vector bool int, vector signed int);
11736
int vec_any_eq (vector float, vector float);
11737
 
11738
int vec_any_ge (vector signed char, vector bool char);
11739
int vec_any_ge (vector unsigned char, vector bool char);
11740
int vec_any_ge (vector unsigned char, vector unsigned char);
11741
int vec_any_ge (vector signed char, vector signed char);
11742
int vec_any_ge (vector bool char, vector unsigned char);
11743
int vec_any_ge (vector bool char, vector signed char);
11744
int vec_any_ge (vector unsigned short, vector bool short);
11745
int vec_any_ge (vector unsigned short, vector unsigned short);
11746
int vec_any_ge (vector signed short, vector signed short);
11747
int vec_any_ge (vector signed short, vector bool short);
11748
int vec_any_ge (vector bool short, vector unsigned short);
11749
int vec_any_ge (vector bool short, vector signed short);
11750
int vec_any_ge (vector signed int, vector bool int);
11751
int vec_any_ge (vector unsigned int, vector bool int);
11752
int vec_any_ge (vector unsigned int, vector unsigned int);
11753
int vec_any_ge (vector signed int, vector signed int);
11754
int vec_any_ge (vector bool int, vector unsigned int);
11755
int vec_any_ge (vector bool int, vector signed int);
11756
int vec_any_ge (vector float, vector float);
11757
 
11758
int vec_any_gt (vector bool char, vector unsigned char);
11759
int vec_any_gt (vector unsigned char, vector bool char);
11760
int vec_any_gt (vector unsigned char, vector unsigned char);
11761
int vec_any_gt (vector bool char, vector signed char);
11762
int vec_any_gt (vector signed char, vector bool char);
11763
int vec_any_gt (vector signed char, vector signed char);
11764
int vec_any_gt (vector bool short, vector unsigned short);
11765
int vec_any_gt (vector unsigned short, vector bool short);
11766
int vec_any_gt (vector unsigned short, vector unsigned short);
11767
int vec_any_gt (vector bool short, vector signed short);
11768
int vec_any_gt (vector signed short, vector bool short);
11769
int vec_any_gt (vector signed short, vector signed short);
11770
int vec_any_gt (vector bool int, vector unsigned int);
11771
int vec_any_gt (vector unsigned int, vector bool int);
11772
int vec_any_gt (vector unsigned int, vector unsigned int);
11773
int vec_any_gt (vector bool int, vector signed int);
11774
int vec_any_gt (vector signed int, vector bool int);
11775
int vec_any_gt (vector signed int, vector signed int);
11776
int vec_any_gt (vector float, vector float);
11777
 
11778
int vec_any_le (vector bool char, vector unsigned char);
11779
int vec_any_le (vector unsigned char, vector bool char);
11780
int vec_any_le (vector unsigned char, vector unsigned char);
11781
int vec_any_le (vector bool char, vector signed char);
11782
int vec_any_le (vector signed char, vector bool char);
11783
int vec_any_le (vector signed char, vector signed char);
11784
int vec_any_le (vector bool short, vector unsigned short);
11785
int vec_any_le (vector unsigned short, vector bool short);
11786
int vec_any_le (vector unsigned short, vector unsigned short);
11787
int vec_any_le (vector bool short, vector signed short);
11788
int vec_any_le (vector signed short, vector bool short);
11789
int vec_any_le (vector signed short, vector signed short);
11790
int vec_any_le (vector bool int, vector unsigned int);
11791
int vec_any_le (vector unsigned int, vector bool int);
11792
int vec_any_le (vector unsigned int, vector unsigned int);
11793
int vec_any_le (vector bool int, vector signed int);
11794
int vec_any_le (vector signed int, vector bool int);
11795
int vec_any_le (vector signed int, vector signed int);
11796
int vec_any_le (vector float, vector float);
11797
 
11798
int vec_any_lt (vector bool char, vector unsigned char);
11799
int vec_any_lt (vector unsigned char, vector bool char);
11800
int vec_any_lt (vector unsigned char, vector unsigned char);
11801
int vec_any_lt (vector bool char, vector signed char);
11802
int vec_any_lt (vector signed char, vector bool char);
11803
int vec_any_lt (vector signed char, vector signed char);
11804
int vec_any_lt (vector bool short, vector unsigned short);
11805
int vec_any_lt (vector unsigned short, vector bool short);
11806
int vec_any_lt (vector unsigned short, vector unsigned short);
11807
int vec_any_lt (vector bool short, vector signed short);
11808
int vec_any_lt (vector signed short, vector bool short);
11809
int vec_any_lt (vector signed short, vector signed short);
11810
int vec_any_lt (vector bool int, vector unsigned int);
11811
int vec_any_lt (vector unsigned int, vector bool int);
11812
int vec_any_lt (vector unsigned int, vector unsigned int);
11813
int vec_any_lt (vector bool int, vector signed int);
11814
int vec_any_lt (vector signed int, vector bool int);
11815
int vec_any_lt (vector signed int, vector signed int);
11816
int vec_any_lt (vector float, vector float);
11817
 
11818
int vec_any_nan (vector float);
11819
 
11820
int vec_any_ne (vector signed char, vector bool char);
11821
int vec_any_ne (vector signed char, vector signed char);
11822
int vec_any_ne (vector unsigned char, vector bool char);
11823
int vec_any_ne (vector unsigned char, vector unsigned char);
11824
int vec_any_ne (vector bool char, vector bool char);
11825
int vec_any_ne (vector bool char, vector unsigned char);
11826
int vec_any_ne (vector bool char, vector signed char);
11827
int vec_any_ne (vector signed short, vector bool short);
11828
int vec_any_ne (vector signed short, vector signed short);
11829
int vec_any_ne (vector unsigned short, vector bool short);
11830
int vec_any_ne (vector unsigned short, vector unsigned short);
11831
int vec_any_ne (vector bool short, vector bool short);
11832
int vec_any_ne (vector bool short, vector unsigned short);
11833
int vec_any_ne (vector bool short, vector signed short);
11834
int vec_any_ne (vector pixel, vector pixel);
11835
int vec_any_ne (vector signed int, vector bool int);
11836
int vec_any_ne (vector signed int, vector signed int);
11837
int vec_any_ne (vector unsigned int, vector bool int);
11838
int vec_any_ne (vector unsigned int, vector unsigned int);
11839
int vec_any_ne (vector bool int, vector bool int);
11840
int vec_any_ne (vector bool int, vector unsigned int);
11841
int vec_any_ne (vector bool int, vector signed int);
11842
int vec_any_ne (vector float, vector float);
11843
 
11844
int vec_any_nge (vector float, vector float);
11845
 
11846
int vec_any_ngt (vector float, vector float);
11847
 
11848
int vec_any_nle (vector float, vector float);
11849
 
11850
int vec_any_nlt (vector float, vector float);
11851
 
11852
int vec_any_numeric (vector float);
11853
 
11854
int vec_any_out (vector float, vector float);
11855
@end smallexample
11856
 
11857
If the vector/scalar (VSX) instruction set is available, the following
11858
additional functions are available:
11859
 
11860
@smallexample
11861
vector double vec_abs (vector double);
11862
vector double vec_add (vector double, vector double);
11863
vector double vec_and (vector double, vector double);
11864
vector double vec_and (vector double, vector bool long);
11865
vector double vec_and (vector bool long, vector double);
11866
vector double vec_andc (vector double, vector double);
11867
vector double vec_andc (vector double, vector bool long);
11868
vector double vec_andc (vector bool long, vector double);
11869
vector double vec_ceil (vector double);
11870
vector bool long vec_cmpeq (vector double, vector double);
11871
vector bool long vec_cmpge (vector double, vector double);
11872
vector bool long vec_cmpgt (vector double, vector double);
11873
vector bool long vec_cmple (vector double, vector double);
11874
vector bool long vec_cmplt (vector double, vector double);
11875
vector float vec_div (vector float, vector float);
11876
vector double vec_div (vector double, vector double);
11877
vector double vec_floor (vector double);
11878
vector double vec_madd (vector double, vector double, vector double);
11879
vector double vec_max (vector double, vector double);
11880
vector double vec_min (vector double, vector double);
11881
vector float vec_msub (vector float, vector float, vector float);
11882
vector double vec_msub (vector double, vector double, vector double);
11883
vector float vec_mul (vector float, vector float);
11884
vector double vec_mul (vector double, vector double);
11885
vector float vec_nearbyint (vector float);
11886
vector double vec_nearbyint (vector double);
11887
vector float vec_nmadd (vector float, vector float, vector float);
11888
vector double vec_nmadd (vector double, vector double, vector double);
11889
vector double vec_nmsub (vector double, vector double, vector double);
11890
vector double vec_nor (vector double, vector double);
11891
vector double vec_or (vector double, vector double);
11892
vector double vec_or (vector double, vector bool long);
11893
vector double vec_or (vector bool long, vector double);
11894
vector double vec_perm (vector double,
11895
                        vector double,
11896
                        vector unsigned char);
11897
vector float vec_rint (vector float);
11898
vector double vec_rint (vector double);
11899
vector double vec_sel (vector double, vector double, vector bool long);
11900
vector double vec_sel (vector double, vector double, vector unsigned long);
11901
vector double vec_sub (vector double, vector double);
11902
vector float vec_sqrt (vector float);
11903
vector double vec_sqrt (vector double);
11904
vector double vec_trunc (vector double);
11905
vector double vec_xor (vector double, vector double);
11906
vector double vec_xor (vector double, vector bool long);
11907
vector double vec_xor (vector bool long, vector double);
11908
int vec_all_eq (vector double, vector double);
11909
int vec_all_ge (vector double, vector double);
11910
int vec_all_gt (vector double, vector double);
11911
int vec_all_le (vector double, vector double);
11912
int vec_all_lt (vector double, vector double);
11913
int vec_all_nan (vector double);
11914
int vec_all_ne (vector double, vector double);
11915
int vec_all_nge (vector double, vector double);
11916
int vec_all_ngt (vector double, vector double);
11917
int vec_all_nle (vector double, vector double);
11918
int vec_all_nlt (vector double, vector double);
11919
int vec_all_numeric (vector double);
11920
int vec_any_eq (vector double, vector double);
11921
int vec_any_ge (vector double, vector double);
11922
int vec_any_gt (vector double, vector double);
11923
int vec_any_le (vector double, vector double);
11924
int vec_any_lt (vector double, vector double);
11925
int vec_any_nan (vector double);
11926
int vec_any_ne (vector double, vector double);
11927
int vec_any_nge (vector double, vector double);
11928
int vec_any_ngt (vector double, vector double);
11929
int vec_any_nle (vector double, vector double);
11930
int vec_any_nlt (vector double, vector double);
11931
int vec_any_numeric (vector double);
11932
@end smallexample
11933
 
11934
GCC provides a few other builtins on Powerpc to access certain instructions:
11935
@smallexample
11936
float __builtin_recipdivf (float, float);
11937
float __builtin_rsqrtf (float);
11938
double __builtin_recipdiv (double, double);
11939
long __builtin_bpermd (long, long);
11940
int __builtin_bswap16 (int);
11941
@end smallexample
11942
 
11943
@node RX Built-in Functions
11944
@subsection RX Built-in Functions
11945
GCC supports some of the RX instructions which cannot be expressed in
11946
the C programming language via the use of built-in functions.  The
11947
following functions are supported:
11948
 
11949
@deftypefn {Built-in Function}  void __builtin_rx_brk (void)
11950
Generates the @code{brk} machine instruction.
11951
@end deftypefn
11952
 
11953
@deftypefn {Built-in Function}  void __builtin_rx_clrpsw (int)
11954
Generates the @code{clrpsw} machine instruction to clear the specified
11955
bit in the processor status word.
11956
@end deftypefn
11957
 
11958
@deftypefn {Built-in Function}  void __builtin_rx_int (int)
11959
Generates the @code{int} machine instruction to generate an interrupt
11960
with the specified value.
11961
@end deftypefn
11962
 
11963
@deftypefn {Built-in Function}  void __builtin_rx_machi (int, int)
11964
Generates the @code{machi} machine instruction to add the result of
11965
multiplying the top 16-bits of the two arguments into the
11966
accumulator.
11967
@end deftypefn
11968
 
11969
@deftypefn {Built-in Function}  void __builtin_rx_maclo (int, int)
11970
Generates the @code{maclo} machine instruction to add the result of
11971
multiplying the bottom 16-bits of the two arguments into the
11972
accumulator.
11973
@end deftypefn
11974
 
11975
@deftypefn {Built-in Function}  void __builtin_rx_mulhi (int, int)
11976
Generates the @code{mulhi} machine instruction to place the result of
11977
multiplying the top 16-bits of the two arguments into the
11978
accumulator.
11979
@end deftypefn
11980
 
11981
@deftypefn {Built-in Function}  void __builtin_rx_mullo (int, int)
11982
Generates the @code{mullo} machine instruction to place the result of
11983
multiplying the bottom 16-bits of the two arguments into the
11984
accumulator.
11985
@end deftypefn
11986
 
11987
@deftypefn {Built-in Function}  int  __builtin_rx_mvfachi (void)
11988
Generates the @code{mvfachi} machine instruction to read the top
11989
32-bits of the accumulator.
11990
@end deftypefn
11991
 
11992
@deftypefn {Built-in Function}  int  __builtin_rx_mvfacmi (void)
11993
Generates the @code{mvfacmi} machine instruction to read the middle
11994
32-bits of the accumulator.
11995
@end deftypefn
11996
 
11997
@deftypefn {Built-in Function}  int __builtin_rx_mvfc (int)
11998
Generates the @code{mvfc} machine instruction which reads the control
11999
register specified in its argument and returns its value.
12000
@end deftypefn
12001
 
12002
@deftypefn {Built-in Function}  void __builtin_rx_mvtachi (int)
12003
Generates the @code{mvtachi} machine instruction to set the top
12004
32-bits of the accumulator.
12005
@end deftypefn
12006
 
12007
@deftypefn {Built-in Function}  void __builtin_rx_mvtaclo (int)
12008
Generates the @code{mvtaclo} machine instruction to set the bottom
12009
32-bits of the accumulator.
12010
@end deftypefn
12011
 
12012
@deftypefn {Built-in Function}  void __builtin_rx_mvtc (int reg, int val)
12013
Generates the @code{mvtc} machine instruction which sets control
12014
register number @code{reg} to @code{val}.
12015
@end deftypefn
12016
 
12017
@deftypefn {Built-in Function}  void __builtin_rx_mvtipl (int)
12018
Generates the @code{mvtipl} machine instruction set the interrupt
12019
priority level.
12020
@end deftypefn
12021
 
12022
@deftypefn {Built-in Function}  void __builtin_rx_racw (int)
12023
Generates the @code{racw} machine instruction to round the accumulator
12024
according to the specified mode.
12025
@end deftypefn
12026
 
12027
@deftypefn {Built-in Function}  int __builtin_rx_revw (int)
12028
Generates the @code{revw} machine instruction which swaps the bytes in
12029
the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
12030
and also bits 16--23 occupy bits 24--31 and vice versa.
12031
@end deftypefn
12032
 
12033
@deftypefn {Built-in Function}  void __builtin_rx_rmpa (void)
12034
Generates the @code{rmpa} machine instruction which initiates a
12035
repeated multiply and accumulate sequence.
12036
@end deftypefn
12037
 
12038
@deftypefn {Built-in Function}  void __builtin_rx_round (float)
12039
Generates the @code{round} machine instruction which returns the
12040
floating point argument rounded according to the current rounding mode
12041
set in the floating point status word register.
12042
@end deftypefn
12043
 
12044
@deftypefn {Built-in Function}  int __builtin_rx_sat (int)
12045
Generates the @code{sat} machine instruction which returns the
12046
saturated value of the argument.
12047
@end deftypefn
12048
 
12049
@deftypefn {Built-in Function}  void __builtin_rx_setpsw (int)
12050
Generates the @code{setpsw} machine instruction to set the specified
12051
bit in the processor status word.
12052
@end deftypefn
12053
 
12054
@deftypefn {Built-in Function}  void __builtin_rx_wait (void)
12055
Generates the @code{wait} machine instruction.
12056
@end deftypefn
12057
 
12058
@node SPARC VIS Built-in Functions
12059
@subsection SPARC VIS Built-in Functions
12060
 
12061
GCC supports SIMD operations on the SPARC using both the generic vector
12062
extensions (@pxref{Vector Extensions}) as well as built-in functions for
12063
the SPARC Visual Instruction Set (VIS).  When you use the @option{-mvis}
12064
switch, the VIS extension is exposed as the following built-in functions:
12065
 
12066
@smallexample
12067
typedef int v2si __attribute__ ((vector_size (8)));
12068
typedef short v4hi __attribute__ ((vector_size (8)));
12069
typedef short v2hi __attribute__ ((vector_size (4)));
12070
typedef char v8qi __attribute__ ((vector_size (8)));
12071
typedef char v4qi __attribute__ ((vector_size (4)));
12072
 
12073
void * __builtin_vis_alignaddr (void *, long);
12074
int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
12075
v2si __builtin_vis_faligndatav2si (v2si, v2si);
12076
v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
12077
v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
12078
 
12079
v4hi __builtin_vis_fexpand (v4qi);
12080
 
12081
v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
12082
v4hi __builtin_vis_fmul8x16au (v4qi, v4hi);
12083
v4hi __builtin_vis_fmul8x16al (v4qi, v4hi);
12084
v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
12085
v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
12086
v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
12087
v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
12088
 
12089
v4qi __builtin_vis_fpack16 (v4hi);
12090
v8qi __builtin_vis_fpack32 (v2si, v2si);
12091
v2hi __builtin_vis_fpackfix (v2si);
12092
v8qi __builtin_vis_fpmerge (v4qi, v4qi);
12093
 
12094
int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
12095
@end smallexample
12096
 
12097
@node SPU Built-in Functions
12098
@subsection SPU Built-in Functions
12099
 
12100
GCC provides extensions for the SPU processor as described in the
12101
Sony/Toshiba/IBM SPU Language Extensions Specification, which can be
12102
found at @uref{http://cell.scei.co.jp/} or
12103
@uref{http://www.ibm.com/developerworks/power/cell/}.  GCC's
12104
implementation differs in several ways.
12105
 
12106
@itemize @bullet
12107
 
12108
@item
12109
The optional extension of specifying vector constants in parentheses is
12110
not supported.
12111
 
12112
@item
12113
A vector initializer requires no cast if the vector constant is of the
12114
same type as the variable it is initializing.
12115
 
12116
@item
12117
If @code{signed} or @code{unsigned} is omitted, the signedness of the
12118
vector type is the default signedness of the base type.  The default
12119
varies depending on the operating system, so a portable program should
12120
always specify the signedness.
12121
 
12122
@item
12123
By default, the keyword @code{__vector} is added. The macro
12124
@code{vector} is defined in @code{<spu_intrinsics.h>} and can be
12125
undefined.
12126
 
12127
@item
12128
GCC allows using a @code{typedef} name as the type specifier for a
12129
vector type.
12130
 
12131
@item
12132
For C, overloaded functions are implemented with macros so the following
12133
does not work:
12134
 
12135
@smallexample
12136
  spu_add ((vector signed int)@{1, 2, 3, 4@}, foo);
12137
@end smallexample
12138
 
12139
Since @code{spu_add} is a macro, the vector constant in the example
12140
is treated as four separate arguments.  Wrap the entire argument in
12141
parentheses for this to work.
12142
 
12143
@item
12144
The extended version of @code{__builtin_expect} is not supported.
12145
 
12146
@end itemize
12147
 
12148
@emph{Note:} Only the interface described in the aforementioned
12149
specification is supported. Internally, GCC uses built-in functions to
12150
implement the required functionality, but these are not supported and
12151
are subject to change without notice.
12152
 
12153
@node Target Format Checks
12154
@section Format Checks Specific to Particular Target Machines
12155
 
12156
For some target machines, GCC supports additional options to the
12157
format attribute
12158
(@pxref{Function Attributes,,Declaring Attributes of Functions}).
12159
 
12160
@menu
12161
* Solaris Format Checks::
12162
@end menu
12163
 
12164
@node Solaris Format Checks
12165
@subsection Solaris Format Checks
12166
 
12167
Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
12168
check.  @code{cmn_err} accepts a subset of the standard @code{printf}
12169
conversions, and the two-argument @code{%b} conversion for displaying
12170
bit-fields.  See the Solaris man page for @code{cmn_err} for more information.
12171
 
12172
@node Pragmas
12173
@section Pragmas Accepted by GCC
12174
@cindex pragmas
12175
@cindex #pragma
12176
 
12177
GCC supports several types of pragmas, primarily in order to compile
12178
code originally written for other compilers.  Note that in general
12179
we do not recommend the use of pragmas; @xref{Function Attributes},
12180
for further explanation.
12181
 
12182
@menu
12183
* ARM Pragmas::
12184
* M32C Pragmas::
12185
* MeP Pragmas::
12186
* RS/6000 and PowerPC Pragmas::
12187
* Darwin Pragmas::
12188
* Solaris Pragmas::
12189
* Symbol-Renaming Pragmas::
12190
* Structure-Packing Pragmas::
12191
* Weak Pragmas::
12192
* Diagnostic Pragmas::
12193
* Visibility Pragmas::
12194
* Push/Pop Macro Pragmas::
12195
* Function Specific Option Pragmas::
12196
@end menu
12197
 
12198
@node ARM Pragmas
12199
@subsection ARM Pragmas
12200
 
12201
The ARM target defines pragmas for controlling the default addition of
12202
@code{long_call} and @code{short_call} attributes to functions.
12203
@xref{Function Attributes}, for information about the effects of these
12204
attributes.
12205
 
12206
@table @code
12207
@item long_calls
12208
@cindex pragma, long_calls
12209
Set all subsequent functions to have the @code{long_call} attribute.
12210
 
12211
@item no_long_calls
12212
@cindex pragma, no_long_calls
12213
Set all subsequent functions to have the @code{short_call} attribute.
12214
 
12215
@item long_calls_off
12216
@cindex pragma, long_calls_off
12217
Do not affect the @code{long_call} or @code{short_call} attributes of
12218
subsequent functions.
12219
@end table
12220
 
12221
@node M32C Pragmas
12222
@subsection M32C Pragmas
12223
 
12224
@table @code
12225
@item memregs @var{number}
12226
@cindex pragma, memregs
12227
Overrides the command line option @code{-memregs=} for the current
12228
file.  Use with care!  This pragma must be before any function in the
12229
file, and mixing different memregs values in different objects may
12230
make them incompatible.  This pragma is useful when a
12231
performance-critical function uses a memreg for temporary values,
12232
as it may allow you to reduce the number of memregs used.
12233
 
12234
@end table
12235
 
12236
@node MeP Pragmas
12237
@subsection MeP Pragmas
12238
 
12239
@table @code
12240
 
12241
@item custom io_volatile (on|off)
12242
@cindex pragma, custom io_volatile
12243
Overrides the command line option @code{-mio-volatile} for the current
12244
file.  Note that for compatibility with future GCC releases, this
12245
option should only be used once before any @code{io} variables in each
12246
file.
12247
 
12248
@item GCC coprocessor available @var{registers}
12249
@cindex pragma, coprocessor available
12250
Specifies which coprocessor registers are available to the register
12251
allocator.  @var{registers} may be a single register, register range
12252
separated by ellipses, or comma-separated list of those.  Example:
12253
 
12254
@example
12255
#pragma GCC coprocessor available $c0...$c10, $c28
12256
@end example
12257
 
12258
@item GCC coprocessor call_saved @var{registers}
12259
@cindex pragma, coprocessor call_saved
12260
Specifies which coprocessor registers are to be saved and restored by
12261
any function using them.  @var{registers} may be a single register,
12262
register range separated by ellipses, or comma-separated list of
12263
those.  Example:
12264
 
12265
@example
12266
#pragma GCC coprocessor call_saved $c4...$c6, $c31
12267
@end example
12268
 
12269
@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
12270
@cindex pragma, coprocessor subclass
12271
Creates and defines a register class.  These register classes can be
12272
used by inline @code{asm} constructs.  @var{registers} may be a single
12273
register, register range separated by ellipses, or comma-separated
12274
list of those.  Example:
12275
 
12276
@example
12277
#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
12278
 
12279
asm ("cpfoo %0" : "=B" (x));
12280
@end example
12281
 
12282
@item GCC disinterrupt @var{name} , @var{name} @dots{}
12283
@cindex pragma, disinterrupt
12284
For the named functions, the compiler adds code to disable interrupts
12285
for the duration of those functions.  Any functions so named, which
12286
are not encountered in the source, cause a warning that the pragma was
12287
not used.  Examples:
12288
 
12289
@example
12290
#pragma disinterrupt foo
12291
#pragma disinterrupt bar, grill
12292
int foo () @{ @dots{} @}
12293
@end example
12294
 
12295
@item GCC call @var{name} , @var{name} @dots{}
12296
@cindex pragma, call
12297
For the named functions, the compiler always uses a register-indirect
12298
call model when calling the named functions.  Examples:
12299
 
12300
@example
12301
extern int foo ();
12302
#pragma call foo
12303
@end example
12304
 
12305
@end table
12306
 
12307
@node RS/6000 and PowerPC Pragmas
12308
@subsection RS/6000 and PowerPC Pragmas
12309
 
12310
The RS/6000 and PowerPC targets define one pragma for controlling
12311
whether or not the @code{longcall} attribute is added to function
12312
declarations by default.  This pragma overrides the @option{-mlongcall}
12313
option, but not the @code{longcall} and @code{shortcall} attributes.
12314
@xref{RS/6000 and PowerPC Options}, for more information about when long
12315
calls are and are not necessary.
12316
 
12317
@table @code
12318
@item longcall (1)
12319
@cindex pragma, longcall
12320
Apply the @code{longcall} attribute to all subsequent function
12321
declarations.
12322
 
12323
@item longcall (0)
12324
Do not apply the @code{longcall} attribute to subsequent function
12325
declarations.
12326
@end table
12327
 
12328
@c Describe h8300 pragmas here.
12329
@c Describe sh pragmas here.
12330
@c Describe v850 pragmas here.
12331
 
12332
@node Darwin Pragmas
12333
@subsection Darwin Pragmas
12334
 
12335
The following pragmas are available for all architectures running the
12336
Darwin operating system.  These are useful for compatibility with other
12337
Mac OS compilers.
12338
 
12339
@table @code
12340
@item mark @var{tokens}@dots{}
12341
@cindex pragma, mark
12342
This pragma is accepted, but has no effect.
12343
 
12344
@item options align=@var{alignment}
12345
@cindex pragma, options align
12346
This pragma sets the alignment of fields in structures.  The values of
12347
@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
12348
@code{power}, to emulate PowerPC alignment.  Uses of this pragma nest
12349
properly; to restore the previous setting, use @code{reset} for the
12350
@var{alignment}.
12351
 
12352
@item segment @var{tokens}@dots{}
12353
@cindex pragma, segment
12354
This pragma is accepted, but has no effect.
12355
 
12356
@item unused (@var{var} [, @var{var}]@dots{})
12357
@cindex pragma, unused
12358
This pragma declares variables to be possibly unused.  GCC will not
12359
produce warnings for the listed variables.  The effect is similar to
12360
that of the @code{unused} attribute, except that this pragma may appear
12361
anywhere within the variables' scopes.
12362
@end table
12363
 
12364
@node Solaris Pragmas
12365
@subsection Solaris Pragmas
12366
 
12367
The Solaris target supports @code{#pragma redefine_extname}
12368
(@pxref{Symbol-Renaming Pragmas}).  It also supports additional
12369
@code{#pragma} directives for compatibility with the system compiler.
12370
 
12371
@table @code
12372
@item align @var{alignment} (@var{variable} [, @var{variable}]...)
12373
@cindex pragma, align
12374
 
12375
Increase the minimum alignment of each @var{variable} to @var{alignment}.
12376
This is the same as GCC's @code{aligned} attribute @pxref{Variable
12377
Attributes}).  Macro expansion occurs on the arguments to this pragma
12378
when compiling C and Objective-C@.  It does not currently occur when
12379
compiling C++, but this is a bug which may be fixed in a future
12380
release.
12381
 
12382
@item fini (@var{function} [, @var{function}]...)
12383
@cindex pragma, fini
12384
 
12385
This pragma causes each listed @var{function} to be called after
12386
main, or during shared module unloading, by adding a call to the
12387
@code{.fini} section.
12388
 
12389
@item init (@var{function} [, @var{function}]...)
12390
@cindex pragma, init
12391
 
12392
This pragma causes each listed @var{function} to be called during
12393
initialization (before @code{main}) or during shared module loading, by
12394
adding a call to the @code{.init} section.
12395
 
12396
@end table
12397
 
12398
@node Symbol-Renaming Pragmas
12399
@subsection Symbol-Renaming Pragmas
12400
 
12401
For compatibility with the Solaris and Tru64 UNIX system headers, GCC
12402
supports two @code{#pragma} directives which change the name used in
12403
assembly for a given declaration.  @code{#pragma extern_prefix} is only
12404
available on platforms whose system headers need it. To get this effect
12405
on all platforms supported by GCC, use the asm labels extension (@pxref{Asm
12406
Labels}).
12407
 
12408
@table @code
12409
@item redefine_extname @var{oldname} @var{newname}
12410
@cindex pragma, redefine_extname
12411
 
12412
This pragma gives the C function @var{oldname} the assembly symbol
12413
@var{newname}.  The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
12414
will be defined if this pragma is available (currently on all platforms).
12415
 
12416
@item extern_prefix @var{string}
12417
@cindex pragma, extern_prefix
12418
 
12419
This pragma causes all subsequent external function and variable
12420
declarations to have @var{string} prepended to their assembly symbols.
12421
This effect may be terminated with another @code{extern_prefix} pragma
12422
whose argument is an empty string.  The preprocessor macro
12423
@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is
12424
available (currently only on Tru64 UNIX)@.
12425
@end table
12426
 
12427
These pragmas and the asm labels extension interact in a complicated
12428
manner.  Here are some corner cases you may want to be aware of.
12429
 
12430
@enumerate
12431
@item Both pragmas silently apply only to declarations with external
12432
linkage.  Asm labels do not have this restriction.
12433
 
12434
@item In C++, both pragmas silently apply only to declarations with
12435
``C'' linkage.  Again, asm labels do not have this restriction.
12436
 
12437
@item If any of the three ways of changing the assembly name of a
12438
declaration is applied to a declaration whose assembly name has
12439
already been determined (either by a previous use of one of these
12440
features, or because the compiler needed the assembly name in order to
12441
generate code), and the new name is different, a warning issues and
12442
the name does not change.
12443
 
12444
@item The @var{oldname} used by @code{#pragma redefine_extname} is
12445
always the C-language name.
12446
 
12447
@item If @code{#pragma extern_prefix} is in effect, and a declaration
12448
occurs with an asm label attached, the prefix is silently ignored for
12449
that declaration.
12450
 
12451
@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname}
12452
apply to the same declaration, whichever triggered first wins, and a
12453
warning issues if they contradict each other.  (We would like to have
12454
@code{#pragma redefine_extname} always win, for consistency with asm
12455
labels, but if @code{#pragma extern_prefix} triggers first we have no
12456
way of knowing that that happened.)
12457
@end enumerate
12458
 
12459
@node Structure-Packing Pragmas
12460
@subsection Structure-Packing Pragmas
12461
 
12462
For compatibility with Microsoft Windows compilers, GCC supports a
12463
set of @code{#pragma} directives which change the maximum alignment of
12464
members of structures (other than zero-width bitfields), unions, and
12465
classes subsequently defined. The @var{n} value below always is required
12466
to be a small power of two and specifies the new alignment in bytes.
12467
 
12468
@enumerate
12469
@item @code{#pragma pack(@var{n})} simply sets the new alignment.
12470
@item @code{#pragma pack()} sets the alignment to the one that was in
12471
effect when compilation started (see also command line option
12472
@option{-fpack-struct[=<n>]} @pxref{Code Gen Options}).
12473
@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
12474
setting on an internal stack and then optionally sets the new alignment.
12475
@item @code{#pragma pack(pop)} restores the alignment setting to the one
12476
saved at the top of the internal stack (and removes that stack entry).
12477
Note that @code{#pragma pack([@var{n}])} does not influence this internal
12478
stack; thus it is possible to have @code{#pragma pack(push)} followed by
12479
multiple @code{#pragma pack(@var{n})} instances and finalized by a single
12480
@code{#pragma pack(pop)}.
12481
@end enumerate
12482
 
12483
Some targets, e.g.@: i386 and powerpc, support the @code{ms_struct}
12484
@code{#pragma} which lays out a structure as the documented
12485
@code{__attribute__ ((ms_struct))}.
12486
@enumerate
12487
@item @code{#pragma ms_struct on} turns on the layout for structures
12488
declared.
12489
@item @code{#pragma ms_struct off} turns off the layout for structures
12490
declared.
12491
@item @code{#pragma ms_struct reset} goes back to the default layout.
12492
@end enumerate
12493
 
12494
@node Weak Pragmas
12495
@subsection Weak Pragmas
12496
 
12497
For compatibility with SVR4, GCC supports a set of @code{#pragma}
12498
directives for declaring symbols to be weak, and defining weak
12499
aliases.
12500
 
12501
@table @code
12502
@item #pragma weak @var{symbol}
12503
@cindex pragma, weak
12504
This pragma declares @var{symbol} to be weak, as if the declaration
12505
had the attribute of the same name.  The pragma may appear before
12506
or after the declaration of @var{symbol}, but must appear before
12507
either its first use or its definition.  It is not an error for
12508
@var{symbol} to never be defined at all.
12509
 
12510
@item #pragma weak @var{symbol1} = @var{symbol2}
12511
This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
12512
It is an error if @var{symbol2} is not defined in the current
12513
translation unit.
12514
@end table
12515
 
12516
@node Diagnostic Pragmas
12517
@subsection Diagnostic Pragmas
12518
 
12519
GCC allows the user to selectively enable or disable certain types of
12520
diagnostics, and change the kind of the diagnostic.  For example, a
12521
project's policy might require that all sources compile with
12522
@option{-Werror} but certain files might have exceptions allowing
12523
specific types of warnings.  Or, a project might selectively enable
12524
diagnostics and treat them as errors depending on which preprocessor
12525
macros are defined.
12526
 
12527
@table @code
12528
@item #pragma GCC diagnostic @var{kind} @var{option}
12529
@cindex pragma, diagnostic
12530
 
12531
Modifies the disposition of a diagnostic.  Note that not all
12532
diagnostics are modifiable; at the moment only warnings (normally
12533
controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
12534
Use @option{-fdiagnostics-show-option} to determine which diagnostics
12535
are controllable and which option controls them.
12536
 
12537
@var{kind} is @samp{error} to treat this diagnostic as an error,
12538
@samp{warning} to treat it like a warning (even if @option{-Werror} is
12539
in effect), or @samp{ignored} if the diagnostic is to be ignored.
12540
@var{option} is a double quoted string which matches the command line
12541
option.
12542
 
12543
@example
12544
#pragma GCC diagnostic warning "-Wformat"
12545
#pragma GCC diagnostic error "-Wformat"
12546
#pragma GCC diagnostic ignored "-Wformat"
12547
@end example
12548
 
12549
Note that these pragmas override any command line options.  Also,
12550
while it is syntactically valid to put these pragmas anywhere in your
12551
sources, the only supported location for them is before any data or
12552
functions are defined.  Doing otherwise may result in unpredictable
12553
results depending on how the optimizer manages your sources.  If the
12554
same option is listed multiple times, the last one specified is the
12555
one that is in effect.  This pragma is not intended to be a general
12556
purpose replacement for command line options, but for implementing
12557
strict control over project policies.
12558
 
12559
@end table
12560
 
12561
GCC also offers a simple mechanism for printing messages during
12562
compilation.
12563
 
12564
@table @code
12565
@item #pragma message @var{string}
12566
@cindex pragma, diagnostic
12567
 
12568
Prints @var{string} as a compiler message on compilation.  The message
12569
is informational only, and is neither a compilation warning nor an error.
12570
 
12571
@smallexample
12572
#pragma message "Compiling " __FILE__ "..."
12573
@end smallexample
12574
 
12575
@var{string} may be parenthesized, and is printed with location
12576
information.  For example,
12577
 
12578
@smallexample
12579
#define DO_PRAGMA(x) _Pragma (#x)
12580
#define TODO(x) DO_PRAGMA(message ("TODO - " #x))
12581
 
12582
TODO(Remember to fix this)
12583
@end smallexample
12584
 
12585
prints @samp{/tmp/file.c:4: note: #pragma message:
12586
TODO - Remember to fix this}.
12587
 
12588
@end table
12589
 
12590
@node Visibility Pragmas
12591
@subsection Visibility Pragmas
12592
 
12593
@table @code
12594
@item #pragma GCC visibility push(@var{visibility})
12595
@itemx #pragma GCC visibility pop
12596
@cindex pragma, visibility
12597
 
12598
This pragma allows the user to set the visibility for multiple
12599
declarations without having to give each a visibility attribute
12600
@xref{Function Attributes}, for more information about visibility and
12601
the attribute syntax.
12602
 
12603
In C++, @samp{#pragma GCC visibility} affects only namespace-scope
12604
declarations.  Class members and template specializations are not
12605
affected; if you want to override the visibility for a particular
12606
member or instantiation, you must use an attribute.
12607
 
12608
@end table
12609
 
12610
 
12611
@node Push/Pop Macro Pragmas
12612
@subsection Push/Pop Macro Pragmas
12613
 
12614
For compatibility with Microsoft Windows compilers, GCC supports
12615
@samp{#pragma push_macro(@var{"macro_name"})}
12616
and @samp{#pragma pop_macro(@var{"macro_name"})}.
12617
 
12618
@table @code
12619
@item #pragma push_macro(@var{"macro_name"})
12620
@cindex pragma, push_macro
12621
This pragma saves the value of the macro named as @var{macro_name} to
12622
the top of the stack for this macro.
12623
 
12624
@item #pragma pop_macro(@var{"macro_name"})
12625
@cindex pragma, pop_macro
12626
This pragma sets the value of the macro named as @var{macro_name} to
12627
the value on top of the stack for this macro. If the stack for
12628
@var{macro_name} is empty, the value of the macro remains unchanged.
12629
@end table
12630
 
12631
For example:
12632
 
12633
@smallexample
12634
#define X  1
12635
#pragma push_macro("X")
12636
#undef X
12637
#define X -1
12638
#pragma pop_macro("X")
12639
int x [X];
12640
@end smallexample
12641
 
12642
In this example, the definition of X as 1 is saved by @code{#pragma
12643
push_macro} and restored by @code{#pragma pop_macro}.
12644
 
12645
@node Function Specific Option Pragmas
12646
@subsection Function Specific Option Pragmas
12647
 
12648
@table @code
12649
@item #pragma GCC target (@var{"string"}...)
12650
@cindex pragma GCC target
12651
 
12652
This pragma allows you to set target specific options for functions
12653
defined later in the source file.  One or more strings can be
12654
specified.  Each function that is defined after this point will be as
12655
if @code{attribute((target("STRING")))} was specified for that
12656
function.  The parenthesis around the options is optional.
12657
@xref{Function Attributes}, for more information about the
12658
@code{target} attribute and the attribute syntax.
12659
 
12660
The @samp{#pragma GCC target} pragma is not implemented in GCC
12661
versions earlier than 4.4, and is currently only implemented for the
12662
386 and x86_64 backends.
12663
@end table
12664
 
12665
@table @code
12666
@item #pragma GCC optimize (@var{"string"}...)
12667
@cindex pragma GCC optimize
12668
 
12669
This pragma allows you to set global optimization options for functions
12670
defined later in the source file.  One or more strings can be
12671
specified.  Each function that is defined after this point will be as
12672
if @code{attribute((optimize("STRING")))} was specified for that
12673
function.  The parenthesis around the options is optional.
12674
@xref{Function Attributes}, for more information about the
12675
@code{optimize} attribute and the attribute syntax.
12676
 
12677
The @samp{#pragma GCC optimize} pragma is not implemented in GCC
12678
versions earlier than 4.4.
12679
@end table
12680
 
12681
@table @code
12682
@item #pragma GCC push_options
12683
@itemx #pragma GCC pop_options
12684
@cindex pragma GCC push_options
12685
@cindex pragma GCC pop_options
12686
 
12687
These pragmas maintain a stack of the current target and optimization
12688
options.  It is intended for include files where you temporarily want
12689
to switch to using a different @samp{#pragma GCC target} or
12690
@samp{#pragma GCC optimize} and then to pop back to the previous
12691
options.
12692
 
12693
The @samp{#pragma GCC push_options} and @samp{#pragma GCC pop_options}
12694
pragmas are not implemented in GCC versions earlier than 4.4.
12695
@end table
12696
 
12697
@table @code
12698
@item #pragma GCC reset_options
12699
@cindex pragma GCC reset_options
12700
 
12701
This pragma clears the current @code{#pragma GCC target} and
12702
@code{#pragma GCC optimize} to use the default switches as specified
12703
on the command line.
12704
 
12705
The @samp{#pragma GCC reset_options} pragma is not implemented in GCC
12706
versions earlier than 4.4.
12707
@end table
12708
 
12709
@node Unnamed Fields
12710
@section Unnamed struct/union fields within structs/unions
12711
@cindex struct
12712
@cindex union
12713
 
12714
For compatibility with other compilers, GCC allows you to define
12715
a structure or union that contains, as fields, structures and unions
12716
without names.  For example:
12717
 
12718
@smallexample
12719
struct @{
12720
  int a;
12721
  union @{
12722
    int b;
12723
    float c;
12724
  @};
12725
  int d;
12726
@} foo;
12727
@end smallexample
12728
 
12729
In this example, the user would be able to access members of the unnamed
12730
union with code like @samp{foo.b}.  Note that only unnamed structs and
12731
unions are allowed, you may not have, for example, an unnamed
12732
@code{int}.
12733
 
12734
You must never create such structures that cause ambiguous field definitions.
12735
For example, this structure:
12736
 
12737
@smallexample
12738
struct @{
12739
  int a;
12740
  struct @{
12741
    int a;
12742
  @};
12743
@} foo;
12744
@end smallexample
12745
 
12746
It is ambiguous which @code{a} is being referred to with @samp{foo.a}.
12747
Such constructs are not supported and must be avoided.  In the future,
12748
such constructs may be detected and treated as compilation errors.
12749
 
12750
@opindex fms-extensions
12751
Unless @option{-fms-extensions} is used, the unnamed field must be a
12752
structure or union definition without a tag (for example, @samp{struct
12753
@{ int a; @};}).  If @option{-fms-extensions} is used, the field may
12754
also be a definition with a tag such as @samp{struct foo @{ int a;
12755
@};}, a reference to a previously defined structure or union such as
12756
@samp{struct foo;}, or a reference to a @code{typedef} name for a
12757
previously defined structure or union type.
12758
 
12759
@node Thread-Local
12760
@section Thread-Local Storage
12761
@cindex Thread-Local Storage
12762
@cindex @acronym{TLS}
12763
@cindex __thread
12764
 
12765
Thread-local storage (@acronym{TLS}) is a mechanism by which variables
12766
are allocated such that there is one instance of the variable per extant
12767
thread.  The run-time model GCC uses to implement this originates
12768
in the IA-64 processor-specific ABI, but has since been migrated
12769
to other processors as well.  It requires significant support from
12770
the linker (@command{ld}), dynamic linker (@command{ld.so}), and
12771
system libraries (@file{libc.so} and @file{libpthread.so}), so it
12772
is not available everywhere.
12773
 
12774
At the user level, the extension is visible with a new storage
12775
class keyword: @code{__thread}.  For example:
12776
 
12777
@smallexample
12778
__thread int i;
12779
extern __thread struct state s;
12780
static __thread char *p;
12781
@end smallexample
12782
 
12783
The @code{__thread} specifier may be used alone, with the @code{extern}
12784
or @code{static} specifiers, but with no other storage class specifier.
12785
When used with @code{extern} or @code{static}, @code{__thread} must appear
12786
immediately after the other storage class specifier.
12787
 
12788
The @code{__thread} specifier may be applied to any global, file-scoped
12789
static, function-scoped static, or static data member of a class.  It may
12790
not be applied to block-scoped automatic or non-static data member.
12791
 
12792
When the address-of operator is applied to a thread-local variable, it is
12793
evaluated at run-time and returns the address of the current thread's
12794
instance of that variable.  An address so obtained may be used by any
12795
thread.  When a thread terminates, any pointers to thread-local variables
12796
in that thread become invalid.
12797
 
12798
No static initialization may refer to the address of a thread-local variable.
12799
 
12800
In C++, if an initializer is present for a thread-local variable, it must
12801
be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
12802
standard.
12803
 
12804
See @uref{http://people.redhat.com/drepper/tls.pdf,
12805
ELF Handling For Thread-Local Storage} for a detailed explanation of
12806
the four thread-local storage addressing models, and how the run-time
12807
is expected to function.
12808
 
12809
@menu
12810
* C99 Thread-Local Edits::
12811
* C++98 Thread-Local Edits::
12812
@end menu
12813
 
12814
@node C99 Thread-Local Edits
12815
@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
12816
 
12817
The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
12818
that document the exact semantics of the language extension.
12819
 
12820
@itemize @bullet
12821
@item
12822
@cite{5.1.2  Execution environments}
12823
 
12824
Add new text after paragraph 1
12825
 
12826
@quotation
12827
Within either execution environment, a @dfn{thread} is a flow of
12828
control within a program.  It is implementation defined whether
12829
or not there may be more than one thread associated with a program.
12830
It is implementation defined how threads beyond the first are
12831
created, the name and type of the function called at thread
12832
startup, and how threads may be terminated.  However, objects
12833
with thread storage duration shall be initialized before thread
12834
startup.
12835
@end quotation
12836
 
12837
@item
12838
@cite{6.2.4  Storage durations of objects}
12839
 
12840
Add new text before paragraph 3
12841
 
12842
@quotation
12843
An object whose identifier is declared with the storage-class
12844
specifier @w{@code{__thread}} has @dfn{thread storage duration}.
12845
Its lifetime is the entire execution of the thread, and its
12846
stored value is initialized only once, prior to thread startup.
12847
@end quotation
12848
 
12849
@item
12850
@cite{6.4.1  Keywords}
12851
 
12852
Add @code{__thread}.
12853
 
12854
@item
12855
@cite{6.7.1  Storage-class specifiers}
12856
 
12857
Add @code{__thread} to the list of storage class specifiers in
12858
paragraph 1.
12859
 
12860
Change paragraph 2 to
12861
 
12862
@quotation
12863
With the exception of @code{__thread}, at most one storage-class
12864
specifier may be given [@dots{}].  The @code{__thread} specifier may
12865
be used alone, or immediately following @code{extern} or
12866
@code{static}.
12867
@end quotation
12868
 
12869
Add new text after paragraph 6
12870
 
12871
@quotation
12872
The declaration of an identifier for a variable that has
12873
block scope that specifies @code{__thread} shall also
12874
specify either @code{extern} or @code{static}.
12875
 
12876
The @code{__thread} specifier shall be used only with
12877
variables.
12878
@end quotation
12879
@end itemize
12880
 
12881
@node C++98 Thread-Local Edits
12882
@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
12883
 
12884
The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
12885
that document the exact semantics of the language extension.
12886
 
12887
@itemize @bullet
12888
@item
12889
@b{[intro.execution]}
12890
 
12891
New text after paragraph 4
12892
 
12893
@quotation
12894
A @dfn{thread} is a flow of control within the abstract machine.
12895
It is implementation defined whether or not there may be more than
12896
one thread.
12897
@end quotation
12898
 
12899
New text after paragraph 7
12900
 
12901
@quotation
12902
It is unspecified whether additional action must be taken to
12903
ensure when and whether side effects are visible to other threads.
12904
@end quotation
12905
 
12906
@item
12907
@b{[lex.key]}
12908
 
12909
Add @code{__thread}.
12910
 
12911
@item
12912
@b{[basic.start.main]}
12913
 
12914
Add after paragraph 5
12915
 
12916
@quotation
12917
The thread that begins execution at the @code{main} function is called
12918
the @dfn{main thread}.  It is implementation defined how functions
12919
beginning threads other than the main thread are designated or typed.
12920
A function so designated, as well as the @code{main} function, is called
12921
a @dfn{thread startup function}.  It is implementation defined what
12922
happens if a thread startup function returns.  It is implementation
12923
defined what happens to other threads when any thread calls @code{exit}.
12924
@end quotation
12925
 
12926
@item
12927
@b{[basic.start.init]}
12928
 
12929
Add after paragraph 4
12930
 
12931
@quotation
12932
The storage for an object of thread storage duration shall be
12933
statically initialized before the first statement of the thread startup
12934
function.  An object of thread storage duration shall not require
12935
dynamic initialization.
12936
@end quotation
12937
 
12938
@item
12939
@b{[basic.start.term]}
12940
 
12941
Add after paragraph 3
12942
 
12943
@quotation
12944
The type of an object with thread storage duration shall not have a
12945
non-trivial destructor, nor shall it be an array type whose elements
12946
(directly or indirectly) have non-trivial destructors.
12947
@end quotation
12948
 
12949
@item
12950
@b{[basic.stc]}
12951
 
12952
Add ``thread storage duration'' to the list in paragraph 1.
12953
 
12954
Change paragraph 2
12955
 
12956
@quotation
12957
Thread, static, and automatic storage durations are associated with
12958
objects introduced by declarations [@dots{}].
12959
@end quotation
12960
 
12961
Add @code{__thread} to the list of specifiers in paragraph 3.
12962
 
12963
@item
12964
@b{[basic.stc.thread]}
12965
 
12966
New section before @b{[basic.stc.static]}
12967
 
12968
@quotation
12969
The keyword @code{__thread} applied to a non-local object gives the
12970
object thread storage duration.
12971
 
12972
A local variable or class data member declared both @code{static}
12973
and @code{__thread} gives the variable or member thread storage
12974
duration.
12975
@end quotation
12976
 
12977
@item
12978
@b{[basic.stc.static]}
12979
 
12980
Change paragraph 1
12981
 
12982
@quotation
12983
All objects which have neither thread storage duration, dynamic
12984
storage duration nor are local [@dots{}].
12985
@end quotation
12986
 
12987
@item
12988
@b{[dcl.stc]}
12989
 
12990
Add @code{__thread} to the list in paragraph 1.
12991
 
12992
Change paragraph 1
12993
 
12994
@quotation
12995
With the exception of @code{__thread}, at most one
12996
@var{storage-class-specifier} shall appear in a given
12997
@var{decl-specifier-seq}.  The @code{__thread} specifier may
12998
be used alone, or immediately following the @code{extern} or
12999
@code{static} specifiers.  [@dots{}]
13000
@end quotation
13001
 
13002
Add after paragraph 5
13003
 
13004
@quotation
13005
The @code{__thread} specifier can be applied only to the names of objects
13006
and to anonymous unions.
13007
@end quotation
13008
 
13009
@item
13010
@b{[class.mem]}
13011
 
13012
Add after paragraph 6
13013
 
13014
@quotation
13015
Non-@code{static} members shall not be @code{__thread}.
13016
@end quotation
13017
@end itemize
13018
 
13019
@node Binary constants
13020
@section Binary constants using the @samp{0b} prefix
13021
@cindex Binary constants using the @samp{0b} prefix
13022
 
13023
Integer constants can be written as binary constants, consisting of a
13024
sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
13025
@samp{0B}.  This is particularly useful in environments that operate a
13026
lot on the bit-level (like microcontrollers).
13027
 
13028
The following statements are identical:
13029
 
13030
@smallexample
13031
i =       42;
13032
i =     0x2a;
13033
i =      052;
13034
i = 0b101010;
13035
@end smallexample
13036
 
13037
The type of these constants follows the same rules as for octal or
13038
hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
13039
can be applied.
13040
 
13041
@node C++ Extensions
13042
@chapter Extensions to the C++ Language
13043
@cindex extensions, C++ language
13044
@cindex C++ language extensions
13045
 
13046
The GNU compiler provides these extensions to the C++ language (and you
13047
can also use most of the C language extensions in your C++ programs).  If you
13048
want to write code that checks whether these features are available, you can
13049
test for the GNU compiler the same way as for C programs: check for a
13050
predefined macro @code{__GNUC__}.  You can also use @code{__GNUG__} to
13051
test specifically for GNU C++ (@pxref{Common Predefined Macros,,
13052
Predefined Macros,cpp,The GNU C Preprocessor}).
13053
 
13054
@menu
13055
* Volatiles::           What constitutes an access to a volatile object.
13056
* Restricted Pointers:: C99 restricted pointers and references.
13057
* Vague Linkage::       Where G++ puts inlines, vtables and such.
13058
* C++ Interface::       You can use a single C++ header file for both
13059
                        declarations and definitions.
13060
* Template Instantiation:: Methods for ensuring that exactly one copy of
13061
                        each needed template instantiation is emitted.
13062
* Bound member functions:: You can extract a function pointer to the
13063
                        method denoted by a @samp{->*} or @samp{.*} expression.
13064
* C++ Attributes::      Variable, function, and type attributes for C++ only.
13065
* Namespace Association:: Strong using-directives for namespace association.
13066
* Type Traits::         Compiler support for type traits
13067
* Java Exceptions::     Tweaking exception handling to work with Java.
13068
* Deprecated Features:: Things will disappear from g++.
13069
* Backwards Compatibility:: Compatibilities with earlier definitions of C++.
13070
@end menu
13071
 
13072
@node Volatiles
13073
@section When is a Volatile Object Accessed?
13074
@cindex accessing volatiles
13075
@cindex volatile read
13076
@cindex volatile write
13077
@cindex volatile access
13078
 
13079
Both the C and C++ standard have the concept of volatile objects.  These
13080
are normally accessed by pointers and used for accessing hardware.  The
13081
standards encourage compilers to refrain from optimizations concerning
13082
accesses to volatile objects.  The C standard leaves it implementation
13083
defined  as to what constitutes a volatile access.  The C++ standard omits
13084
to specify this, except to say that C++ should behave in a similar manner
13085
to C with respect to volatiles, where possible.  The minimum either
13086
standard specifies is that at a sequence point all previous accesses to
13087
volatile objects have stabilized and no subsequent accesses have
13088
occurred.  Thus an implementation is free to reorder and combine
13089
volatile accesses which occur between sequence points, but cannot do so
13090
for accesses across a sequence point.  The use of volatiles does not
13091
allow you to violate the restriction on updating objects multiple times
13092
within a sequence point.
13093
 
13094
@xref{Qualifiers implementation, , Volatile qualifier and the C compiler}.
13095
 
13096
The behavior differs slightly between C and C++ in the non-obvious cases:
13097
 
13098
@smallexample
13099
volatile int *src = @var{somevalue};
13100
*src;
13101
@end smallexample
13102
 
13103
With C, such expressions are rvalues, and GCC interprets this either as a
13104
read of the volatile object being pointed to or only as request to evaluate
13105
the side-effects.  The C++ standard specifies that such expressions do not
13106
undergo lvalue to rvalue conversion, and that the type of the dereferenced
13107
object may be incomplete.  The C++ standard does not specify explicitly
13108
that it is this lvalue to rvalue conversion which may be responsible for
13109
causing an access.  However, there is reason to believe that it is,
13110
because otherwise certain simple expressions become undefined.  However,
13111
because it would surprise most programmers, G++ treats dereferencing a
13112
pointer to volatile object of complete type when the value is unused as
13113
GCC would do for an equivalent type in C@.  When the object has incomplete
13114
type, G++ issues a warning; if you wish to force an error, you must
13115
force a conversion to rvalue with, for instance, a static cast.
13116
 
13117
When using a reference to volatile, G++ does not treat equivalent
13118
expressions as accesses to volatiles, but instead issues a warning that
13119
no volatile is accessed.  The rationale for this is that otherwise it
13120
becomes difficult to determine where volatile access occur, and not
13121
possible to ignore the return value from functions returning volatile
13122
references.  Again, if you wish to force a read, cast the reference to
13123
an rvalue.
13124
 
13125
@node Restricted Pointers
13126
@section Restricting Pointer Aliasing
13127
@cindex restricted pointers
13128
@cindex restricted references
13129
@cindex restricted this pointer
13130
 
13131
As with the C front end, G++ understands the C99 feature of restricted pointers,
13132
specified with the @code{__restrict__}, or @code{__restrict} type
13133
qualifier.  Because you cannot compile C++ by specifying the @option{-std=c99}
13134
language flag, @code{restrict} is not a keyword in C++.
13135
 
13136
In addition to allowing restricted pointers, you can specify restricted
13137
references, which indicate that the reference is not aliased in the local
13138
context.
13139
 
13140
@smallexample
13141
void fn (int *__restrict__ rptr, int &__restrict__ rref)
13142
@{
13143
  /* @r{@dots{}} */
13144
@}
13145
@end smallexample
13146
 
13147
@noindent
13148
In the body of @code{fn}, @var{rptr} points to an unaliased integer and
13149
@var{rref} refers to a (different) unaliased integer.
13150
 
13151
You may also specify whether a member function's @var{this} pointer is
13152
unaliased by using @code{__restrict__} as a member function qualifier.
13153
 
13154
@smallexample
13155
void T::fn () __restrict__
13156
@{
13157
  /* @r{@dots{}} */
13158
@}
13159
@end smallexample
13160
 
13161
@noindent
13162
Within the body of @code{T::fn}, @var{this} will have the effective
13163
definition @code{T *__restrict__ const this}.  Notice that the
13164
interpretation of a @code{__restrict__} member function qualifier is
13165
different to that of @code{const} or @code{volatile} qualifier, in that it
13166
is applied to the pointer rather than the object.  This is consistent with
13167
other compilers which implement restricted pointers.
13168
 
13169
As with all outermost parameter qualifiers, @code{__restrict__} is
13170
ignored in function definition matching.  This means you only need to
13171
specify @code{__restrict__} in a function definition, rather than
13172
in a function prototype as well.
13173
 
13174
@node Vague Linkage
13175
@section Vague Linkage
13176
@cindex vague linkage
13177
 
13178
There are several constructs in C++ which require space in the object
13179
file but are not clearly tied to a single translation unit.  We say that
13180
these constructs have ``vague linkage''.  Typically such constructs are
13181
emitted wherever they are needed, though sometimes we can be more
13182
clever.
13183
 
13184
@table @asis
13185
@item Inline Functions
13186
Inline functions are typically defined in a header file which can be
13187
included in many different compilations.  Hopefully they can usually be
13188
inlined, but sometimes an out-of-line copy is necessary, if the address
13189
of the function is taken or if inlining fails.  In general, we emit an
13190
out-of-line copy in all translation units where one is needed.  As an
13191
exception, we only emit inline virtual functions with the vtable, since
13192
it will always require a copy.
13193
 
13194
Local static variables and string constants used in an inline function
13195
are also considered to have vague linkage, since they must be shared
13196
between all inlined and out-of-line instances of the function.
13197
 
13198
@item VTables
13199
@cindex vtable
13200
C++ virtual functions are implemented in most compilers using a lookup
13201
table, known as a vtable.  The vtable contains pointers to the virtual
13202
functions provided by a class, and each object of the class contains a
13203
pointer to its vtable (or vtables, in some multiple-inheritance
13204
situations).  If the class declares any non-inline, non-pure virtual
13205
functions, the first one is chosen as the ``key method'' for the class,
13206
and the vtable is only emitted in the translation unit where the key
13207
method is defined.
13208
 
13209
@emph{Note:} If the chosen key method is later defined as inline, the
13210
vtable will still be emitted in every translation unit which defines it.
13211
Make sure that any inline virtuals are declared inline in the class
13212
body, even if they are not defined there.
13213
 
13214
@item type_info objects
13215
@cindex type_info
13216
@cindex RTTI
13217
C++ requires information about types to be written out in order to
13218
implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
13219
For polymorphic classes (classes with virtual functions), the type_info
13220
object is written out along with the vtable so that @samp{dynamic_cast}
13221
can determine the dynamic type of a class object at runtime.  For all
13222
other types, we write out the type_info object when it is used: when
13223
applying @samp{typeid} to an expression, throwing an object, or
13224
referring to a type in a catch clause or exception specification.
13225
 
13226
@item Template Instantiations
13227
Most everything in this section also applies to template instantiations,
13228
but there are other options as well.
13229
@xref{Template Instantiation,,Where's the Template?}.
13230
 
13231
@end table
13232
 
13233
When used with GNU ld version 2.8 or later on an ELF system such as
13234
GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
13235
these constructs will be discarded at link time.  This is known as
13236
COMDAT support.
13237
 
13238
On targets that don't support COMDAT, but do support weak symbols, GCC
13239
will use them.  This way one copy will override all the others, but
13240
the unused copies will still take up space in the executable.
13241
 
13242
For targets which do not support either COMDAT or weak symbols,
13243
most entities with vague linkage will be emitted as local symbols to
13244
avoid duplicate definition errors from the linker.  This will not happen
13245
for local statics in inlines, however, as having multiple copies will
13246
almost certainly break things.
13247
 
13248
@xref{C++ Interface,,Declarations and Definitions in One Header}, for
13249
another way to control placement of these constructs.
13250
 
13251
@node C++ Interface
13252
@section #pragma interface and implementation
13253
 
13254
@cindex interface and implementation headers, C++
13255
@cindex C++ interface and implementation headers
13256
@cindex pragmas, interface and implementation
13257
 
13258
@code{#pragma interface} and @code{#pragma implementation} provide the
13259
user with a way of explicitly directing the compiler to emit entities
13260
with vague linkage (and debugging information) in a particular
13261
translation unit.
13262
 
13263
@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in
13264
most cases, because of COMDAT support and the ``key method'' heuristic
13265
mentioned in @ref{Vague Linkage}.  Using them can actually cause your
13266
program to grow due to unnecessary out-of-line copies of inline
13267
functions.  Currently (3.4) the only benefit of these
13268
@code{#pragma}s is reduced duplication of debugging information, and
13269
that should be addressed soon on DWARF 2 targets with the use of
13270
COMDAT groups.
13271
 
13272
@table @code
13273
@item #pragma interface
13274
@itemx #pragma interface "@var{subdir}/@var{objects}.h"
13275
@kindex #pragma interface
13276
Use this directive in @emph{header files} that define object classes, to save
13277
space in most of the object files that use those classes.  Normally,
13278
local copies of certain information (backup copies of inline member
13279
functions, debugging information, and the internal tables that implement
13280
virtual functions) must be kept in each object file that includes class
13281
definitions.  You can use this pragma to avoid such duplication.  When a
13282
header file containing @samp{#pragma interface} is included in a
13283
compilation, this auxiliary information will not be generated (unless
13284
the main input source file itself uses @samp{#pragma implementation}).
13285
Instead, the object files will contain references to be resolved at link
13286
time.
13287
 
13288
The second form of this directive is useful for the case where you have
13289
multiple headers with the same name in different directories.  If you
13290
use this form, you must specify the same string to @samp{#pragma
13291
implementation}.
13292
 
13293
@item #pragma implementation
13294
@itemx #pragma implementation "@var{objects}.h"
13295
@kindex #pragma implementation
13296
Use this pragma in a @emph{main input file}, when you want full output from
13297
included header files to be generated (and made globally visible).  The
13298
included header file, in turn, should use @samp{#pragma interface}.
13299
Backup copies of inline member functions, debugging information, and the
13300
internal tables used to implement virtual functions are all generated in
13301
implementation files.
13302
 
13303
@cindex implied @code{#pragma implementation}
13304
@cindex @code{#pragma implementation}, implied
13305
@cindex naming convention, implementation headers
13306
If you use @samp{#pragma implementation} with no argument, it applies to
13307
an include file with the same basename@footnote{A file's @dfn{basename}
13308
was the name stripped of all leading path information and of trailing
13309
suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
13310
file.  For example, in @file{allclass.cc}, giving just
13311
@samp{#pragma implementation}
13312
by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
13313
 
13314
In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as
13315
an implementation file whenever you would include it from
13316
@file{allclass.cc} even if you never specified @samp{#pragma
13317
implementation}.  This was deemed to be more trouble than it was worth,
13318
however, and disabled.
13319
 
13320
Use the string argument if you want a single implementation file to
13321
include code from multiple header files.  (You must also use
13322
@samp{#include} to include the header file; @samp{#pragma
13323
implementation} only specifies how to use the file---it doesn't actually
13324
include it.)
13325
 
13326
There is no way to split up the contents of a single header file into
13327
multiple implementation files.
13328
@end table
13329
 
13330
@cindex inlining and C++ pragmas
13331
@cindex C++ pragmas, effect on inlining
13332
@cindex pragmas in C++, effect on inlining
13333
@samp{#pragma implementation} and @samp{#pragma interface} also have an
13334
effect on function inlining.
13335
 
13336
If you define a class in a header file marked with @samp{#pragma
13337
interface}, the effect on an inline function defined in that class is
13338
similar to an explicit @code{extern} declaration---the compiler emits
13339
no code at all to define an independent version of the function.  Its
13340
definition is used only for inlining with its callers.
13341
 
13342
@opindex fno-implement-inlines
13343
Conversely, when you include the same header file in a main source file
13344
that declares it as @samp{#pragma implementation}, the compiler emits
13345
code for the function itself; this defines a version of the function
13346
that can be found via pointers (or by callers compiled without
13347
inlining).  If all calls to the function can be inlined, you can avoid
13348
emitting the function by compiling with @option{-fno-implement-inlines}.
13349
If any calls were not inlined, you will get linker errors.
13350
 
13351
@node Template Instantiation
13352
@section Where's the Template?
13353
@cindex template instantiation
13354
 
13355
C++ templates are the first language feature to require more
13356
intelligence from the environment than one usually finds on a UNIX
13357
system.  Somehow the compiler and linker have to make sure that each
13358
template instance occurs exactly once in the executable if it is needed,
13359
and not at all otherwise.  There are two basic approaches to this
13360
problem, which are referred to as the Borland model and the Cfront model.
13361
 
13362
@table @asis
13363
@item Borland model
13364
Borland C++ solved the template instantiation problem by adding the code
13365
equivalent of common blocks to their linker; the compiler emits template
13366
instances in each translation unit that uses them, and the linker
13367
collapses them together.  The advantage of this model is that the linker
13368
only has to consider the object files themselves; there is no external
13369
complexity to worry about.  This disadvantage is that compilation time
13370
is increased because the template code is being compiled repeatedly.
13371
Code written for this model tends to include definitions of all
13372
templates in the header file, since they must be seen to be
13373
instantiated.
13374
 
13375
@item Cfront model
13376
The AT&T C++ translator, Cfront, solved the template instantiation
13377
problem by creating the notion of a template repository, an
13378
automatically maintained place where template instances are stored.  A
13379
more modern version of the repository works as follows: As individual
13380
object files are built, the compiler places any template definitions and
13381
instantiations encountered in the repository.  At link time, the link
13382
wrapper adds in the objects in the repository and compiles any needed
13383
instances that were not previously emitted.  The advantages of this
13384
model are more optimal compilation speed and the ability to use the
13385
system linker; to implement the Borland model a compiler vendor also
13386
needs to replace the linker.  The disadvantages are vastly increased
13387
complexity, and thus potential for error; for some code this can be
13388
just as transparent, but in practice it can been very difficult to build
13389
multiple programs in one directory and one program in multiple
13390
directories.  Code written for this model tends to separate definitions
13391
of non-inline member templates into a separate file, which should be
13392
compiled separately.
13393
@end table
13394
 
13395
When used with GNU ld version 2.8 or later on an ELF system such as
13396
GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the
13397
Borland model.  On other systems, G++ implements neither automatic
13398
model.
13399
 
13400
A future version of G++ will support a hybrid model whereby the compiler
13401
will emit any instantiations for which the template definition is
13402
included in the compile, and store template definitions and
13403
instantiation context information into the object file for the rest.
13404
The link wrapper will extract that information as necessary and invoke
13405
the compiler to produce the remaining instantiations.  The linker will
13406
then combine duplicate instantiations.
13407
 
13408
In the mean time, you have the following options for dealing with
13409
template instantiations:
13410
 
13411
@enumerate
13412
@item
13413
@opindex frepo
13414
Compile your template-using code with @option{-frepo}.  The compiler will
13415
generate files with the extension @samp{.rpo} listing all of the
13416
template instantiations used in the corresponding object files which
13417
could be instantiated there; the link wrapper, @samp{collect2}, will
13418
then update the @samp{.rpo} files to tell the compiler where to place
13419
those instantiations and rebuild any affected object files.  The
13420
link-time overhead is negligible after the first pass, as the compiler
13421
will continue to place the instantiations in the same files.
13422
 
13423
This is your best option for application code written for the Borland
13424
model, as it will just work.  Code written for the Cfront model will
13425
need to be modified so that the template definitions are available at
13426
one or more points of instantiation; usually this is as simple as adding
13427
@code{#include <tmethods.cc>} to the end of each template header.
13428
 
13429
For library code, if you want the library to provide all of the template
13430
instantiations it needs, just try to link all of its object files
13431
together; the link will fail, but cause the instantiations to be
13432
generated as a side effect.  Be warned, however, that this may cause
13433
conflicts if multiple libraries try to provide the same instantiations.
13434
For greater control, use explicit instantiation as described in the next
13435
option.
13436
 
13437
@item
13438
@opindex fno-implicit-templates
13439
Compile your code with @option{-fno-implicit-templates} to disable the
13440
implicit generation of template instances, and explicitly instantiate
13441
all the ones you use.  This approach requires more knowledge of exactly
13442
which instances you need than do the others, but it's less
13443
mysterious and allows greater control.  You can scatter the explicit
13444
instantiations throughout your program, perhaps putting them in the
13445
translation units where the instances are used or the translation units
13446
that define the templates themselves; you can put all of the explicit
13447
instantiations you need into one big file; or you can create small files
13448
like
13449
 
13450
@smallexample
13451
#include "Foo.h"
13452
#include "Foo.cc"
13453
 
13454
template class Foo<int>;
13455
template ostream& operator <<
13456
                (ostream&, const Foo<int>&);
13457
@end smallexample
13458
 
13459
for each of the instances you need, and create a template instantiation
13460
library from those.
13461
 
13462
If you are using Cfront-model code, you can probably get away with not
13463
using @option{-fno-implicit-templates} when compiling files that don't
13464
@samp{#include} the member template definitions.
13465
 
13466
If you use one big file to do the instantiations, you may want to
13467
compile it without @option{-fno-implicit-templates} so you get all of the
13468
instances required by your explicit instantiations (but not by any
13469
other files) without having to specify them as well.
13470
 
13471
G++ has extended the template instantiation syntax given in the ISO
13472
standard to allow forward declaration of explicit instantiations
13473
(with @code{extern}), instantiation of the compiler support data for a
13474
template class (i.e.@: the vtable) without instantiating any of its
13475
members (with @code{inline}), and instantiation of only the static data
13476
members of a template class, without the support data or member
13477
functions (with (@code{static}):
13478
 
13479
@smallexample
13480
extern template int max (int, int);
13481
inline template class Foo<int>;
13482
static template class Foo<int>;
13483
@end smallexample
13484
 
13485
@item
13486
Do nothing.  Pretend G++ does implement automatic instantiation
13487
management.  Code written for the Borland model will work fine, but
13488
each translation unit will contain instances of each of the templates it
13489
uses.  In a large program, this can lead to an unacceptable amount of code
13490
duplication.
13491
@end enumerate
13492
 
13493
@node Bound member functions
13494
@section Extracting the function pointer from a bound pointer to member function
13495
@cindex pmf
13496
@cindex pointer to member function
13497
@cindex bound pointer to member function
13498
 
13499
In C++, pointer to member functions (PMFs) are implemented using a wide
13500
pointer of sorts to handle all the possible call mechanisms; the PMF
13501
needs to store information about how to adjust the @samp{this} pointer,
13502
and if the function pointed to is virtual, where to find the vtable, and
13503
where in the vtable to look for the member function.  If you are using
13504
PMFs in an inner loop, you should really reconsider that decision.  If
13505
that is not an option, you can extract the pointer to the function that
13506
would be called for a given object/PMF pair and call it directly inside
13507
the inner loop, to save a bit of time.
13508
 
13509
Note that you will still be paying the penalty for the call through a
13510
function pointer; on most modern architectures, such a call defeats the
13511
branch prediction features of the CPU@.  This is also true of normal
13512
virtual function calls.
13513
 
13514
The syntax for this extension is
13515
 
13516
@smallexample
13517
extern A a;
13518
extern int (A::*fp)();
13519
typedef int (*fptr)(A *);
13520
 
13521
fptr p = (fptr)(a.*fp);
13522
@end smallexample
13523
 
13524
For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
13525
no object is needed to obtain the address of the function.  They can be
13526
converted to function pointers directly:
13527
 
13528
@smallexample
13529
fptr p1 = (fptr)(&A::foo);
13530
@end smallexample
13531
 
13532
@opindex Wno-pmf-conversions
13533
You must specify @option{-Wno-pmf-conversions} to use this extension.
13534
 
13535
@node C++ Attributes
13536
@section C++-Specific Variable, Function, and Type Attributes
13537
 
13538
Some attributes only make sense for C++ programs.
13539
 
13540
@table @code
13541
@item init_priority (@var{priority})
13542
@cindex init_priority attribute
13543
 
13544
 
13545
In Standard C++, objects defined at namespace scope are guaranteed to be
13546
initialized in an order in strict accordance with that of their definitions
13547
@emph{in a given translation unit}.  No guarantee is made for initializations
13548
across translation units.  However, GNU C++ allows users to control the
13549
order of initialization of objects defined at namespace scope with the
13550
@code{init_priority} attribute by specifying a relative @var{priority},
13551
a constant integral expression currently bounded between 101 and 65535
13552
inclusive.  Lower numbers indicate a higher priority.
13553
 
13554
In the following example, @code{A} would normally be created before
13555
@code{B}, but the @code{init_priority} attribute has reversed that order:
13556
 
13557
@smallexample
13558
Some_Class  A  __attribute__ ((init_priority (2000)));
13559
Some_Class  B  __attribute__ ((init_priority (543)));
13560
@end smallexample
13561
 
13562
@noindent
13563
Note that the particular values of @var{priority} do not matter; only their
13564
relative ordering.
13565
 
13566
@item java_interface
13567
@cindex java_interface attribute
13568
 
13569
This type attribute informs C++ that the class is a Java interface.  It may
13570
only be applied to classes declared within an @code{extern "Java"} block.
13571
Calls to methods declared in this interface will be dispatched using GCJ's
13572
interface table mechanism, instead of regular virtual table dispatch.
13573
 
13574
@end table
13575
 
13576
See also @ref{Namespace Association}.
13577
 
13578
@node Namespace Association
13579
@section Namespace Association
13580
 
13581
@strong{Caution:} The semantics of this extension are not fully
13582
defined.  Users should refrain from using this extension as its
13583
semantics may change subtly over time.  It is possible that this
13584
extension will be removed in future versions of G++.
13585
 
13586
A using-directive with @code{__attribute ((strong))} is stronger
13587
than a normal using-directive in two ways:
13588
 
13589
@itemize @bullet
13590
@item
13591
Templates from the used namespace can be specialized and explicitly
13592
instantiated as though they were members of the using namespace.
13593
 
13594
@item
13595
The using namespace is considered an associated namespace of all
13596
templates in the used namespace for purposes of argument-dependent
13597
name lookup.
13598
@end itemize
13599
 
13600
The used namespace must be nested within the using namespace so that
13601
normal unqualified lookup works properly.
13602
 
13603
This is useful for composing a namespace transparently from
13604
implementation namespaces.  For example:
13605
 
13606
@smallexample
13607
namespace std @{
13608
  namespace debug @{
13609
    template <class T> struct A @{ @};
13610
  @}
13611
  using namespace debug __attribute ((__strong__));
13612
  template <> struct A<int> @{ @};   // @r{ok to specialize}
13613
 
13614
  template <class T> void f (A<T>);
13615
@}
13616
 
13617
int main()
13618
@{
13619
  f (std::A<float>());             // @r{lookup finds} std::f
13620
  f (std::A<int>());
13621
@}
13622
@end smallexample
13623
 
13624
@node Type Traits
13625
@section Type Traits
13626
 
13627
The C++ front-end implements syntactic extensions that allow to
13628
determine at compile time various characteristics of a type (or of a
13629
pair of types).
13630
 
13631
@table @code
13632
@item __has_nothrow_assign (type)
13633
If @code{type} is const qualified or is a reference type then the trait is
13634
false.  Otherwise if @code{__has_trivial_assign (type)} is true then the trait
13635
is true, else if @code{type} is a cv class or union type with copy assignment
13636
operators that are known not to throw an exception then the trait is true,
13637
else it is false.  Requires: @code{type} shall be a complete type, an array
13638
type of unknown bound, or is a @code{void} type.
13639
 
13640
@item __has_nothrow_copy (type)
13641
If @code{__has_trivial_copy (type)} is true then the trait is true, else if
13642
@code{type} is a cv class or union type with copy constructors that
13643
are known not to throw an exception then the trait is true, else it is false.
13644
Requires: @code{type} shall be a complete type, an array type of
13645
unknown bound, or is a @code{void} type.
13646
 
13647
@item __has_nothrow_constructor (type)
13648
If @code{__has_trivial_constructor (type)} is true then the trait is
13649
true, else if @code{type} is a cv class or union type (or array
13650
thereof) with a default constructor that is known not to throw an
13651
exception then the trait is true, else it is false.  Requires:
13652
@code{type} shall be a complete type, an array type of unknown bound,
13653
or is a @code{void} type.
13654
 
13655
@item __has_trivial_assign (type)
13656
If @code{type} is const qualified or is a reference type then the trait is
13657
false.  Otherwise if @code{__is_pod (type)} is true then the trait is
13658
true, else if @code{type} is a cv class or union type with a trivial
13659
copy assignment ([class.copy]) then the trait is true, else it is
13660
false.  Requires: @code{type} shall be a complete type, an array type
13661
of unknown bound, or is a @code{void} type.
13662
 
13663
@item __has_trivial_copy (type)
13664
If @code{__is_pod (type)} is true or @code{type} is a reference type
13665
then the trait is true, else if @code{type} is a cv class or union type
13666
with a trivial copy constructor ([class.copy]) then the trait
13667
is true, else it is false.  Requires: @code{type} shall be a complete
13668
type, an array type of unknown bound, or is a @code{void} type.
13669
 
13670
@item __has_trivial_constructor (type)
13671
If @code{__is_pod (type)} is true then the trait is true, else if
13672
@code{type} is a cv class or union type (or array thereof) with a
13673
trivial default constructor ([class.ctor]) then the trait is true,
13674
else it is false.  Requires: @code{type} shall be a complete type, an
13675
array type of unknown bound, or is a @code{void} type.
13676
 
13677
@item __has_trivial_destructor (type)
13678
If @code{__is_pod (type)} is true or @code{type} is a reference type then
13679
the trait is true, else if @code{type} is a cv class or union type (or
13680
array thereof) with a trivial destructor ([class.dtor]) then the trait
13681
is true, else it is false.  Requires: @code{type} shall be a complete
13682
type, an array type of unknown bound, or is a @code{void} type.
13683
 
13684
@item __has_virtual_destructor (type)
13685
If @code{type} is a class type with a virtual destructor
13686
([class.dtor]) then the trait is true, else it is false.  Requires:
13687
@code{type}  shall be a complete type, an array type of unknown bound,
13688
or is a @code{void} type.
13689
 
13690
@item __is_abstract (type)
13691
If @code{type} is an abstract class ([class.abstract]) then the trait
13692
is true, else it is false.  Requires: @code{type} shall be a complete
13693
type, an array type of unknown bound, or is a @code{void} type.
13694
 
13695
@item __is_base_of (base_type, derived_type)
13696
If @code{base_type} is a base class of @code{derived_type}
13697
([class.derived]) then the trait is true, otherwise it is false.
13698
Top-level cv qualifications of @code{base_type} and
13699
@code{derived_type} are ignored.  For the purposes of this trait, a
13700
class type is considered is own base.  Requires: if @code{__is_class
13701
(base_type)} and @code{__is_class (derived_type)} are true and
13702
@code{base_type} and @code{derived_type} are not the same type
13703
(disregarding cv-qualifiers), @code{derived_type} shall be a complete
13704
type.  Diagnostic is produced if this requirement is not met.
13705
 
13706
@item __is_class (type)
13707
If @code{type} is a cv class type, and not a union type
13708
([basic.compound]) the trait is true, else it is false.
13709
 
13710
@item __is_empty (type)
13711
If @code{__is_class (type)} is false then the trait is false.
13712
Otherwise @code{type} is considered empty if and only if: @code{type}
13713
has no non-static data members, or all non-static data members, if
13714
any, are bit-fields of length 0, and @code{type} has no virtual
13715
members, and @code{type} has no virtual base classes, and @code{type}
13716
has no base classes @code{base_type} for which
13717
@code{__is_empty (base_type)} is false.  Requires: @code{type} shall
13718
be a complete type, an array type of unknown bound, or is a
13719
@code{void} type.
13720
 
13721
@item __is_enum (type)
13722
If @code{type} is a cv enumeration type ([basic.compound]) the trait is
13723
true, else it is false.
13724
 
13725
@item __is_pod (type)
13726
If @code{type} is a cv POD type ([basic.types]) then the trait is true,
13727
else it is false.  Requires: @code{type} shall be a complete type,
13728
an array type of unknown bound, or is a @code{void} type.
13729
 
13730
@item __is_polymorphic (type)
13731
If @code{type} is a polymorphic class ([class.virtual]) then the trait
13732
is true, else it is false.  Requires: @code{type} shall be a complete
13733
type, an array type of unknown bound, or is a @code{void} type.
13734
 
13735
@item __is_union (type)
13736
If @code{type} is a cv union type ([basic.compound]) the trait is
13737
true, else it is false.
13738
 
13739
@end table
13740
 
13741
@node Java Exceptions
13742
@section Java Exceptions
13743
 
13744
The Java language uses a slightly different exception handling model
13745
from C++.  Normally, GNU C++ will automatically detect when you are
13746
writing C++ code that uses Java exceptions, and handle them
13747
appropriately.  However, if C++ code only needs to execute destructors
13748
when Java exceptions are thrown through it, GCC will guess incorrectly.
13749
Sample problematic code is:
13750
 
13751
@smallexample
13752
  struct S @{ ~S(); @};
13753
  extern void bar();    // @r{is written in Java, and may throw exceptions}
13754
  void foo()
13755
  @{
13756
    S s;
13757
    bar();
13758
  @}
13759
@end smallexample
13760
 
13761
@noindent
13762
The usual effect of an incorrect guess is a link failure, complaining of
13763
a missing routine called @samp{__gxx_personality_v0}.
13764
 
13765
You can inform the compiler that Java exceptions are to be used in a
13766
translation unit, irrespective of what it might think, by writing
13767
@samp{@w{#pragma GCC java_exceptions}} at the head of the file.  This
13768
@samp{#pragma} must appear before any functions that throw or catch
13769
exceptions, or run destructors when exceptions are thrown through them.
13770
 
13771
You cannot mix Java and C++ exceptions in the same translation unit.  It
13772
is believed to be safe to throw a C++ exception from one file through
13773
another file compiled for the Java exception model, or vice versa, but
13774
there may be bugs in this area.
13775
 
13776
@node Deprecated Features
13777
@section Deprecated Features
13778
 
13779
In the past, the GNU C++ compiler was extended to experiment with new
13780
features, at a time when the C++ language was still evolving.  Now that
13781
the C++ standard is complete, some of those features are superseded by
13782
superior alternatives.  Using the old features might cause a warning in
13783
some cases that the feature will be dropped in the future.  In other
13784
cases, the feature might be gone already.
13785
 
13786
While the list below is not exhaustive, it documents some of the options
13787
that are now deprecated:
13788
 
13789
@table @code
13790
@item -fexternal-templates
13791
@itemx -falt-external-templates
13792
These are two of the many ways for G++ to implement template
13793
instantiation.  @xref{Template Instantiation}.  The C++ standard clearly
13794
defines how template definitions have to be organized across
13795
implementation units.  G++ has an implicit instantiation mechanism that
13796
should work just fine for standard-conforming code.
13797
 
13798
@item -fstrict-prototype
13799
@itemx -fno-strict-prototype
13800
Previously it was possible to use an empty prototype parameter list to
13801
indicate an unspecified number of parameters (like C), rather than no
13802
parameters, as C++ demands.  This feature has been removed, except where
13803
it is required for backwards compatibility.   @xref{Backwards Compatibility}.
13804
@end table
13805
 
13806
G++ allows a virtual function returning @samp{void *} to be overridden
13807
by one returning a different pointer type.  This extension to the
13808
covariant return type rules is now deprecated and will be removed from a
13809
future version.
13810
 
13811
The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and
13812
their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated
13813
and are now removed from G++.  Code using these operators should be
13814
modified to use @code{std::min} and @code{std::max} instead.
13815
 
13816
The named return value extension has been deprecated, and is now
13817
removed from G++.
13818
 
13819
The use of initializer lists with new expressions has been deprecated,
13820
and is now removed from G++.
13821
 
13822
Floating and complex non-type template parameters have been deprecated,
13823
and are now removed from G++.
13824
 
13825
The implicit typename extension has been deprecated and is now
13826
removed from G++.
13827
 
13828
The use of default arguments in function pointers, function typedefs
13829
and other places where they are not permitted by the standard is
13830
deprecated and will be removed from a future version of G++.
13831
 
13832
G++ allows floating-point literals to appear in integral constant expressions,
13833
e.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} }
13834
This extension is deprecated and will be removed from a future version.
13835
 
13836
G++ allows static data members of const floating-point type to be declared
13837
with an initializer in a class definition. The standard only allows
13838
initializers for static members of const integral types and const
13839
enumeration types so this extension has been deprecated and will be removed
13840
from a future version.
13841
 
13842
@node Backwards Compatibility
13843
@section Backwards Compatibility
13844
@cindex Backwards Compatibility
13845
@cindex ARM [Annotated C++ Reference Manual]
13846
 
13847
Now that there is a definitive ISO standard C++, G++ has a specification
13848
to adhere to.  The C++ language evolved over time, and features that
13849
used to be acceptable in previous drafts of the standard, such as the ARM
13850
[Annotated C++ Reference Manual], are no longer accepted.  In order to allow
13851
compilation of C++ written to such drafts, G++ contains some backwards
13852
compatibilities.  @emph{All such backwards compatibility features are
13853
liable to disappear in future versions of G++.} They should be considered
13854
deprecated.   @xref{Deprecated Features}.
13855
 
13856
@table @code
13857
@item For scope
13858
If a variable is declared at for scope, it used to remain in scope until
13859
the end of the scope which contained the for statement (rather than just
13860
within the for scope).  G++ retains this, but issues a warning, if such a
13861
variable is accessed outside the for scope.
13862
 
13863
@item Implicit C language
13864
Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
13865
scope to set the language.  On such systems, all header files are
13866
implicitly scoped inside a C language scope.  Also, an empty prototype
13867
@code{()} will be treated as an unspecified number of arguments, rather
13868
than no arguments, as C++ demands.
13869
@end table

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.