Subversion Repositories openrisc_2011-10-31

@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,

@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010

@c Free Software Foundation, Inc.

@c This is part of the GCC manual.

@c For copying conditions, see the file gcc.texi.

@node C Extensions

@chapter Extensions to the C Language Family

@cindex extensions, C language

@cindex C language extensions

@opindex pedantic

GNU C provides several language features not found in ISO standard C@.

(The @option{-pedantic} option directs GCC to print a warning message if

any of these features is used.)  To test for the availability of these

features in conditional compilation, check for a predefined macro

@code{__GNUC__}, which is always defined under GCC@.

These extensions are available in C and Objective-C@.  Most of them are

also available in C++.  @xref{C++ Extensions,,Extensions to the

C++ Language}, for extensions that apply @emph{only} to C++.

Some features that are in ISO C99 but not C90 or C++ are also, as

extensions, accepted by GCC in C90 mode and in C++.

@menu

* Statement Exprs::     Putting statements and declarations inside expressions.

* Local Labels::        Labels local to a block.

* Labels as Values::    Getting pointers to labels, and computed gotos.

* Nested Functions::    As in Algol and Pascal, lexical scoping of functions.

* Constructing Calls::  Dispatching a call to another function.

* Typeof::              @code{typeof}: referring to the type of an expression.

* Conditionals::        Omitting the middle operand of a @samp{?:} expression.

* Long Long::           Double-word integers---@code{long long int}.

* Complex::             Data types for complex numbers.

* Floating Types::      Additional Floating Types.

* Half-Precision::      Half-Precision Floating Point.

* Decimal Float::       Decimal Floating Types.

* Hex Floats::          Hexadecimal floating-point constants.

* Fixed-Point::         Fixed-Point Types.

* Named Address Spaces::Named address spaces.

* Zero Length::         Zero-length arrays.

* Variable Length::     Arrays whose length is computed at run time.

* Empty Structures::    Structures with no members.

* Variadic Macros::     Macros with a variable number of arguments.

* Escaped Newlines::    Slightly looser rules for escaped newlines.

* Subscripting::        Any array can be subscripted, even if not an lvalue.

* Pointer Arith::       Arithmetic on @code{void}-pointers and function pointers.

* Initializers::        Non-constant initializers.

* Compound Literals::   Compound literals give structures, unions

                        or arrays as values.

* Designated Inits::    Labeling elements of initializers.

* Cast to Union::       Casting to union type from any member of the union.

* Case Ranges::         `case 1 ... 9' and such.

* Mixed Declarations::  Mixing declarations and code.

* Function Attributes:: Declaring that functions have no side effects,

                        or that they can never return.

* Attribute Syntax::    Formal syntax for attributes.

* Function Prototypes:: Prototype declarations and old-style definitions.

* C++ Comments::        C++ comments are recognized.

* Dollar Signs::        Dollar sign is allowed in identifiers.

* Character Escapes::   @samp{\e} stands for the character @key{ESC}.

* Variable Attributes:: Specifying attributes of variables.

* Type Attributes::     Specifying attributes of types.

* Alignment::           Inquiring about the alignment of a type or variable.

* Inline::              Defining inline functions (as fast as macros).

* Extended Asm::        Assembler instructions with C expressions as operands.

                        (With them you can define ``built-in'' functions.)

* Constraints::         Constraints for asm operands

* Asm Labels::          Specifying the assembler name to use for a C symbol.

* Explicit Reg Vars::   Defining variables residing in specified registers.

* Alternate Keywords::  @code{__const__}, @code{__asm__}, etc., for header files.

* Incomplete Enums::    @code{enum foo;}, with details to follow.

* Function Names::      Printable strings which are the name of the current

                        function.

* Return Address::      Getting the return or frame address of a function.

* Vector Extensions::   Using vector instructions through built-in functions.

* Offsetof::            Special syntax for implementing @code{offsetof}.

* Atomic Builtins::     Built-in functions for atomic memory access.

* Object Size Checking:: Built-in functions for limited buffer overflow

                        checking.

* Other Builtins::      Other built-in functions.

* Target Builtins::     Built-in functions specific to particular targets.

* Target Format Checks:: Format checks specific to particular targets.

* Pragmas::             Pragmas accepted by GCC.

* Unnamed Fields::      Unnamed struct/union fields within structs/unions.

* Thread-Local::        Per-thread variables.

* Binary constants::    Binary constants using the @samp{0b} prefix.

@end menu

@node Statement Exprs

@section Statements and Declarations in Expressions

@cindex statements inside expressions

@cindex declarations inside expressions

@cindex expressions containing statements

@cindex macros, statements in expressions

@c the above section title wrapped and causes an underfull hbox.. i

@c changed it from "within" to "in". --mew 4feb93

A compound statement enclosed in parentheses may appear as an expression

in GNU C@.  This allows you to use loops, switches, and local variables

within an expression.

Recall that a compound statement is a sequence of statements surrounded

by braces; in this construct, parentheses go around the braces.  For

example:

@smallexample

(@{ int y = foo (); int z;

   if (y > 0) z = y;

   else z = - y;

   z; @})

@end smallexample

@noindent

is a valid (though slightly more complex than necessary) expression

for the absolute value of @code{foo ()}.

The last thing in the compound statement should be an expression

followed by a semicolon; the value of this subexpression serves as the

value of the entire construct.  (If you use some other kind of statement

last within the braces, the construct has type @code{void}, and thus

effectively no value.)

This feature is especially useful in making macro definitions ``safe'' (so

that they evaluate each operand exactly once).  For example, the

``maximum'' function is commonly defined as a macro in standard C as

follows:

@smallexample

#define max(a,b) ((a) > (b) ? (a) : (b))

@end smallexample

@noindent

@cindex side effects, macro argument

But this definition computes either @var{a} or @var{b} twice, with bad

results if the operand has side effects.  In GNU C, if you know the

type of the operands (here taken as @code{int}), you can define

the macro safely as follows:

@smallexample

#define maxint(a,b) \

  (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})

@end smallexample

Embedded statements are not allowed in constant expressions, such as

the value of an enumeration constant, the width of a bit-field, or

the initial value of a static variable.

If you don't know the type of the operand, you can still do this, but you

must use @code{typeof} (@pxref{Typeof}).

In G++, the result value of a statement expression undergoes array and

function pointer decay, and is returned by value to the enclosing

expression.  For instance, if @code{A} is a class, then

@smallexample

        A a;

        (@{a;@}).Foo ()

@end smallexample

@noindent

will construct a temporary @code{A} object to hold the result of the

statement expression, and that will be used to invoke @code{Foo}.

Therefore the @code{this} pointer observed by @code{Foo} will not be the

address of @code{a}.

Any temporaries created within a statement within a statement expression

will be destroyed at the statement's end.  This makes statement

expressions inside macros slightly different from function calls.  In

the latter case temporaries introduced during argument evaluation will

be destroyed at the end of the statement that includes the function

call.  In the statement expression case they will be destroyed during

the statement expression.  For instance,

@smallexample

#define macro(a)  (@{__typeof__(a) b = (a); b + 3; @})

template<typename T> T function(T a) @{ T b = a; return b + 3; @}

void foo ()

@{

  macro (X ());

  function (X ());

@}

@end smallexample

@noindent

will have different places where temporaries are destroyed.  For the

@code{macro} case, the temporary @code{X} will be destroyed just after

the initialization of @code{b}.  In the @code{function} case that

temporary will be destroyed when the function returns.

These considerations mean that it is probably a bad idea to use

statement-expressions of this form in header files that are designed to

work with C++.  (Note that some versions of the GNU C Library contained

header files using statement-expression that lead to precisely this

bug.)

Jumping into a statement expression with @code{goto} or using a

@code{switch} statement outside the statement expression with a

@code{case} or @code{default} label inside the statement expression is

not permitted.  Jumping into a statement expression with a computed

@code{goto} (@pxref{Labels as Values}) yields undefined behavior.

Jumping out of a statement expression is permitted, but if the

statement expression is part of a larger expression then it is

unspecified which other subexpressions of that expression have been

evaluated except where the language definition requires certain

subexpressions to be evaluated before or after the statement

expression.  In any case, as with a function call the evaluation of a

statement expression is not interleaved with the evaluation of other

parts of the containing expression.  For example,

@smallexample

  foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();

@end smallexample

@noindent

will call @code{foo} and @code{bar1} and will not call @code{baz} but

may or may not call @code{bar2}.  If @code{bar2} is called, it will be

called after @code{foo} and before @code{bar1}

@node Local Labels

@section Locally Declared Labels

@cindex local labels

@cindex macros, local labels

GCC allows you to declare @dfn{local labels} in any nested block

scope.  A local label is just like an ordinary label, but you can

only reference it (with a @code{goto} statement, or by taking its

address) within the block in which it was declared.

A local label declaration looks like this:

@smallexample

__label__ @var{label};

@end smallexample

@noindent

or

@smallexample

__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;

@end smallexample

Local label declarations must come at the beginning of the block,

before any ordinary declarations or statements.

The label declaration defines the label @emph{name}, but does not define

the label itself.  You must do this in the usual way, with

@code{@var{label}:}, within the statements of the statement expression.

The local label feature is useful for complex macros.  If a macro

contains nested loops, a @code{goto} can be useful for breaking out of

them.  However, an ordinary label whose scope is the whole function

cannot be used: if the macro can be expanded several times in one

function, the label will be multiply defined in that function.  A

local label avoids this problem.  For example:

@smallexample

#define SEARCH(value, array, target)              \

do @{                                              \

  __label__ found;                                \

  typeof (target) _SEARCH_target = (target);      \

  typeof (*(array)) *_SEARCH_array = (array);     \

  int i, j;                                       \

  int value;                                      \

  for (i = 0; i < max; i++)                       \

    for (j = 0; j < max; j++)                     \

      if (_SEARCH_array[i][j] == _SEARCH_target)  \

        @{ (value) = i; goto found; @}              \

  (value) = -1;                                   \

 found:;                                          \

@} while (0)

@end smallexample

This could also be written using a statement-expression:

@smallexample

#define SEARCH(array, target)                     \

(@{                                                \

  __label__ found;                                \

  typeof (target) _SEARCH_target = (target);      \

  typeof (*(array)) *_SEARCH_array = (array);     \

  int i, j;                                       \

  int value;                                      \

  for (i = 0; i < max; i++)                       \

    for (j = 0; j < max; j++)                     \

      if (_SEARCH_array[i][j] == _SEARCH_target)  \

        @{ value = i; goto found; @}                \

  value = -1;                                     \

 found:                                           \

  value;                                          \

@})

@end smallexample

Local label declarations also make the labels they declare visible to

nested functions, if there are any.  @xref{Nested Functions}, for details.

@node Labels as Values

@section Labels as Values

@cindex labels as values

@cindex computed gotos

@cindex goto with computed label

@cindex address of a label

You can get the address of a label defined in the current function

(or a containing function) with the unary operator @samp{&&}.  The

value has type @code{void *}.  This value is a constant and can be used

wherever a constant of that type is valid.  For example:

@smallexample

void *ptr;

/* @r{@dots{}} */

ptr = &&foo;

@end smallexample

To use these values, you need to be able to jump to one.  This is done

with the computed goto statement@footnote{The analogous feature in

Fortran is called an assigned goto, but that name seems inappropriate in

C, where one can do more than simply store label addresses in label

variables.}, @code{goto *@var{exp};}.  For example,

@smallexample

goto *ptr;

@end smallexample

@noindent

Any expression of type @code{void *} is allowed.

One way of using these constants is in initializing a static array that

will serve as a jump table:

@smallexample

static void *array[] = @{ &&foo, &&bar, &&hack @};

@end smallexample

Then you can select a label with indexing, like this:

@smallexample

goto *array[i];

@end smallexample

@noindent

Note that this does not check whether the subscript is in bounds---array

indexing in C never does that.

Such an array of label values serves a purpose much like that of the

@code{switch} statement.  The @code{switch} statement is cleaner, so

use that rather than an array unless the problem does not fit a

@code{switch} statement very well.

Another use of label values is in an interpreter for threaded code.

The labels within the interpreter function can be stored in the

threaded code for super-fast dispatching.

You may not use this mechanism to jump to code in a different function.

If you do that, totally unpredictable things will happen.  The best way to

avoid this is to store the label address only in automatic variables and

never pass it as an argument.

An alternate way to write the above example is

@smallexample

static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,

                             &&hack - &&foo @};

goto *(&&foo + array[i]);

@end smallexample

@noindent

This is more friendly to code living in shared libraries, as it reduces

the number of dynamic relocations that are needed, and by consequence,

allows the data to be read-only.

The @code{&&foo} expressions for the same label might have different

values if the containing function is inlined or cloned.  If a program

relies on them being always the same,

@code{__attribute__((__noinline__,__noclone__))} should be used to

prevent inlining and cloning.  If @code{&&foo} is used in a static

variable initializer, inlining and cloning is forbidden.

@node Nested Functions

@section Nested Functions

@cindex nested functions

@cindex downward funargs

@cindex thunks

A @dfn{nested function} is a function defined inside another function.

(Nested functions are not supported for GNU C++.)  The nested function's

name is local to the block where it is defined.  For example, here we

define a nested function named @code{square}, and call it twice:

@smallexample

@group

foo (double a, double b)

@{

  double square (double z) @{ return z * z; @}

  return square (a) + square (b);

@}

@end group

@end smallexample

The nested function can access all the variables of the containing

function that are visible at the point of its definition.  This is

called @dfn{lexical scoping}.  For example, here we show a nested

function which uses an inherited variable named @code{offset}:

@smallexample

@group

bar (int *array, int offset, int size)

@{

  int access (int *array, int index)

    @{ return array[index + offset]; @}

  int i;

  /* @r{@dots{}} */

  for (i = 0; i < size; i++)

    /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */

@}

@end group

@end smallexample

Nested function definitions are permitted within functions in the places

where variable definitions are allowed; that is, in any block, mixed

with the other declarations and statements in the block.

It is possible to call the nested function from outside the scope of its

name by storing its address or passing the address to another function:

@smallexample

hack (int *array, int size)

@{

  void store (int index, int value)

    @{ array[index] = value; @}

  intermediate (store, size);

@}

@end smallexample

Here, the function @code{intermediate} receives the address of

@code{store} as an argument.  If @code{intermediate} calls @code{store},

the arguments given to @code{store} are used to store into @code{array}.

But this technique works only so long as the containing function

(@code{hack}, in this example) does not exit.

If you try to call the nested function through its address after the

containing function has exited, all hell will break loose.  If you try

to call it after a containing scope level has exited, and if it refers

to some of the variables that are no longer in scope, you may be lucky,

but it's not wise to take the risk.  If, however, the nested function

does not refer to anything that has gone out of scope, you should be

safe.

GCC implements taking the address of a nested function using a technique

called @dfn{trampolines}.  This technique was described in

@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX

C++ Conference Proceedings, October 17-21, 1988).

A nested function can jump to a label inherited from a containing

function, provided the label was explicitly declared in the containing

function (@pxref{Local Labels}).  Such a jump returns instantly to the

containing function, exiting the nested function which did the

@code{goto} and any intermediate functions as well.  Here is an example:

@smallexample

@group

bar (int *array, int offset, int size)

@{

  __label__ failure;

  int access (int *array, int index)

    @{

      if (index > size)

        goto failure;

      return array[index + offset];

    @}

  int i;

  /* @r{@dots{}} */

  for (i = 0; i < size; i++)

    /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */

  /* @r{@dots{}} */

  return 0;

 /* @r{Control comes here from @code{access}

    if it detects an error.}  */

 failure:

  return -1;

@}

@end group

@end smallexample

A nested function always has no linkage.  Declaring one with

@code{extern} or @code{static} is erroneous.  If you need to declare the nested function

before its definition, use @code{auto} (which is otherwise meaningless

for function declarations).

@smallexample

bar (int *array, int offset, int size)

@{

  __label__ failure;

  auto int access (int *, int);

  /* @r{@dots{}} */

  int access (int *array, int index)

    @{

      if (index > size)

        goto failure;

      return array[index + offset];

    @}

  /* @r{@dots{}} */

@}

@end smallexample

@node Constructing Calls

@section Constructing Function Calls

@cindex constructing calls

@cindex forwarding calls

Using the built-in functions described below, you can record

the arguments a function received, and call another function

with the same arguments, without knowing the number or types

of the arguments.

You can also record the return value of that function call,

and later return that value, without knowing what data type

the function tried to return (as long as your caller expects

that data type).

However, these built-in functions may interact badly with some

sophisticated features or other extensions of the language.  It

is, therefore, not recommended to use them outside very simple

functions acting as mere forwarders for their arguments.

@deftypefn {Built-in Function} {void *} __builtin_apply_args ()

This built-in function returns a pointer to data

describing how to perform a call with the same arguments as were passed

to the current function.

The function saves the arg pointer register, structure value address,

and all registers that might be used to pass arguments to a function

into a block of memory allocated on the stack.  Then it returns the

address of that block.

@end deftypefn

@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})

This built-in function invokes @var{function}

with a copy of the parameters described by @var{arguments}

and @var{size}.

The value of @var{arguments} should be the value returned by

@code{__builtin_apply_args}.  The argument @var{size} specifies the size

of the stack argument data, in bytes.

This function returns a pointer to data describing

how to return whatever value was returned by @var{function}.  The data

is saved in a block of memory allocated on the stack.

It is not always simple to compute the proper value for @var{size}.  The

value is used by @code{__builtin_apply} to compute the amount of data

that should be pushed on the stack and copied from the incoming argument

area.

@end deftypefn

@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})

This built-in function returns the value described by @var{result} from

the containing function.  You should specify, for @var{result}, a value

returned by @code{__builtin_apply}.

@end deftypefn

@deftypefn {Built-in Function} __builtin_va_arg_pack ()

This built-in function represents all anonymous arguments of an inline

function.  It can be used only in inline functions which will be always

inlined, never compiled as a separate function, such as those using

@code{__attribute__ ((__always_inline__))} or

@code{__attribute__ ((__gnu_inline__))} extern inline functions.

It must be only passed as last argument to some other function

with variable arguments.  This is useful for writing small wrapper

inlines for variable argument functions, when using preprocessor

macros is undesirable.  For example:

@smallexample

extern int myprintf (FILE *f, const char *format, ...);

extern inline __attribute__ ((__gnu_inline__)) int

myprintf (FILE *f, const char *format, ...)

@{

  int r = fprintf (f, "myprintf: ");

  if (r < 0)

    return r;

  int s = fprintf (f, format, __builtin_va_arg_pack ());

  if (s < 0)

    return s;

  return r + s;

@}

@end smallexample

@end deftypefn

@deftypefn {Built-in Function} __builtin_va_arg_pack_len ()

This built-in function returns the number of anonymous arguments of

an inline function.  It can be used only in inline functions which

will be always inlined, never compiled as a separate function, such

as those using @code{__attribute__ ((__always_inline__))} or

@code{__attribute__ ((__gnu_inline__))} extern inline functions.

For example following will do link or runtime checking of open

arguments for optimized code:

@smallexample

#ifdef __OPTIMIZE__

extern inline __attribute__((__gnu_inline__)) int

myopen (const char *path, int oflag, ...)

@{

  if (__builtin_va_arg_pack_len () > 1)

    warn_open_too_many_arguments ();

  if (__builtin_constant_p (oflag))

    @{

      if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)

        @{

          warn_open_missing_mode ();

          return __open_2 (path, oflag);

        @}

      return open (path, oflag, __builtin_va_arg_pack ());

    @}

  if (__builtin_va_arg_pack_len () < 1)

    return __open_2 (path, oflag);

  return open (path, oflag, __builtin_va_arg_pack ());

@}

#endif

@end smallexample

@end deftypefn

@node Typeof

@section Referring to a Type with @code{typeof}

@findex typeof

@findex sizeof

@cindex macros, types of arguments

Another way to refer to the type of an expression is with @code{typeof}.

The syntax of using of this keyword looks like @code{sizeof}, but the

construct acts semantically like a type name defined with @code{typedef}.

There are two ways of writing the argument to @code{typeof}: with an

expression or with a type.  Here is an example with an expression:

@smallexample

typeof (x[0](1))

@end smallexample

@noindent

This assumes that @code{x} is an array of pointers to functions;

the type described is that of the values of the functions.

Here is an example with a typename as the argument:

@smallexample

typeof (int *)

@end smallexample

@noindent

Here the type described is that of pointers to @code{int}.

If you are writing a header file that must work when included in ISO C

programs, write @code{__typeof__} instead of @code{typeof}.

@xref{Alternate Keywords}.

A @code{typeof}-construct can be used anywhere a typedef name could be

used.  For example, you can use it in a declaration, in a cast, or inside

of @code{sizeof} or @code{typeof}.

The operand of @code{typeof} is evaluated for its side effects if and

only if it is an expression of variably modified type or the name of

such a type.

@code{typeof} is often useful in conjunction with the

statements-within-expressions feature.  Here is how the two together can

be used to define a safe ``maximum'' macro that operates on any

arithmetic type and evaluates each of its arguments exactly once:

@smallexample

#define max(a,b) \

  (@{ typeof (a) _a = (a); \

      typeof (b) _b = (b); \

    _a > _b ? _a : _b; @})

@end smallexample

@cindex underscores in variables in macros

@cindex @samp{_} in variables in macros

@cindex local variables in macros

@cindex variables, local, in macros

@cindex macros, local variables in

The reason for using names that start with underscores for the local

variables is to avoid conflicts with variable names that occur within the

expressions that are substituted for @code{a} and @code{b}.  Eventually we

hope to design a new form of declaration syntax that allows you to declare

variables whose scopes start only after their initializers; this will be a

more reliable way to prevent such conflicts.

@noindent

Some more examples of the use of @code{typeof}:

@itemize @bullet

@item

This declares @code{y} with the type of what @code{x} points to.

@smallexample

typeof (*x) y;

@end smallexample

@item

This declares @code{y} as an array of such values.

@smallexample

typeof (*x) y[4];

@end smallexample

@item

This declares @code{y} as an array of pointers to characters:

@smallexample

typeof (typeof (char *)[4]) y;

@end smallexample

@noindent

It is equivalent to the following traditional C declaration:

@smallexample

char *y[4];

@end smallexample

To see the meaning of the declaration using @code{typeof}, and why it

might be a useful way to write, rewrite it with these macros:

@smallexample

#define pointer(T)  typeof(T *)

#define array(T, N) typeof(T [N])

@end smallexample

@noindent

Now the declaration can be rewritten this way:

@smallexample

array (pointer (char), 4) y;

@end smallexample

@noindent

Thus, @code{array (pointer (char), 4)} is the type of arrays of 4

pointers to @code{char}.

@end itemize

@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported

a more limited extension which permitted one to write

@smallexample

typedef @var{T} = @var{expr};

@end smallexample

@noindent

with the effect of declaring @var{T} to have the type of the expression

@var{expr}.  This extension does not work with GCC 3 (versions between

3.0 and 3.2 will crash; 3.2.1 and later give an error).  Code which

relies on it should be rewritten to use @code{typeof}:

@smallexample

typedef typeof(@var{expr}) @var{T};

@end smallexample

@noindent

This will work with all versions of GCC@.

@node Conditionals

@section Conditionals with Omitted Operands

@cindex conditional expressions, extensions

@cindex omitted middle-operands

@cindex middle-operands, omitted

@cindex extensions, @code{?:}

@cindex @code{?:} extensions

The middle operand in a conditional expression may be omitted.  Then

if the first operand is nonzero, its value is the value of the conditional

expression.

Therefore, the expression

@smallexample

x ? : y

@end smallexample

@noindent

has the value of @code{x} if that is nonzero; otherwise, the value of

@code{y}.

This example is perfectly equivalent to

@smallexample

x ? x : y

@end smallexample

@cindex side effect in ?:

@cindex ?: side effect

@noindent

In this simple case, the ability to omit the middle operand is not

especially useful.  When it becomes useful is when the first operand does,

or may (if it is a macro argument), contain a side effect.  Then repeating

the operand in the middle would perform the side effect twice.  Omitting

the middle operand uses the value already computed without the undesirable

effects of recomputing it.

@node Long Long

@section Double-Word Integers

@cindex @code{long long} data types

@cindex double-word arithmetic

@cindex multiprecision arithmetic

@cindex @code{LL} integer suffix

@cindex @code{ULL} integer suffix

ISO C99 supports data types for integers that are at least 64 bits wide,

and as an extension GCC supports them in C90 mode and in C++.

Simply write @code{long long int} for a signed integer, or

@code{unsigned long long int} for an unsigned integer.  To make an

integer constant of type @code{long long int}, add the suffix @samp{LL}

to the integer.  To make an integer constant of type @code{unsigned long

long int}, add the suffix @samp{ULL} to the integer.

You can use these types in arithmetic like any other integer types.

Addition, subtraction, and bitwise boolean operations on these types

are open-coded on all types of machines.  Multiplication is open-coded

if the machine supports fullword-to-doubleword a widening multiply

instruction.  Division and shifts are open-coded only on machines that

provide special support.  The operations that are not open-coded use

special library routines that come with GCC@.

There may be pitfalls when you use @code{long long} types for function

arguments, unless you declare function prototypes.  If a function

expects type @code{int} for its argument, and you pass a value of type

@code{long long int}, confusion will result because the caller and the

subroutine will disagree about the number of bytes for the argument.

Likewise, if the function expects @code{long long int} and you pass

@code{int}.  The best way to avoid such problems is to use prototypes.

@node Complex

@section Complex Numbers

@cindex complex numbers

@cindex @code{_Complex} keyword

@cindex @code{__complex__} keyword

ISO C99 supports complex floating data types, and as an extension GCC

supports them in C90 mode and in C++, and supports complex integer data

types which are not part of ISO C99.  You can declare complex types

using the keyword @code{_Complex}.  As an extension, the older GNU

keyword @code{__complex__} is also supported.

For example, @samp{_Complex double x;} declares @code{x} as a

variable whose real part and imaginary part are both of type

@code{double}.  @samp{_Complex short int y;} declares @code{y} to

have real and imaginary parts of type @code{short int}; this is not

likely to be useful, but it shows that the set of complex types is

complete.

To write a constant with a complex data type, use the suffix @samp{i} or

@samp{j} (either one; they are equivalent).  For example, @code{2.5fi}

has type @code{_Complex float} and @code{3i} has type

@code{_Complex int}.  Such a constant always has a pure imaginary

value, but you can form any complex value you like by adding one to a

real constant.  This is a GNU extension; if you have an ISO C99

conforming C library (such as GNU libc), and want to construct complex

constants of floating type, you should include @code{<complex.h>} and

use the macros @code{I} or @code{_Complex_I} instead.

@cindex @code{__real__} keyword

@cindex @code{__imag__} keyword

To extract the real part of a complex-valued expression @var{exp}, write

@code{__real__ @var{exp}}.  Likewise, use @code{__imag__} to

extract the imaginary part.  This is a GNU extension; for values of

floating type, you should use the ISO C99 functions @code{crealf},

@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and

@code{cimagl}, declared in @code{<complex.h>} and also provided as

built-in functions by GCC@.

@cindex complex conjugation

The operator @samp{~} performs complex conjugation when used on a value

with a complex type.  This is a GNU extension; for values of

floating type, you should use the ISO C99 functions @code{conjf},

@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also

provided as built-in functions by GCC@.

GCC can allocate complex automatic variables in a noncontiguous

fashion; it's even possible for the real part to be in a register while

the imaginary part is on the stack (or vice-versa).  Only the DWARF2

debug info format can represent this, so use of DWARF2 is recommended.

If you are using the stabs debug info format, GCC describes a noncontiguous

complex variable as if it were two separate variables of noncomplex type.

If the variable's actual name is @code{foo}, the two fictitious

variables are named @code{foo$real} and @code{foo$imag}.  You can

examine and set these two fictitious variables with your debugger.

@node Floating Types

@section Additional Floating Types

@cindex additional floating types

@cindex @code{__float80} data type

@cindex @code{__float128} data type

@cindex @code{w} floating point suffix

@cindex @code{q} floating point suffix

@cindex @code{W} floating point suffix

@cindex @code{Q} floating point suffix

As an extension, the GNU C compiler supports additional floating

types, @code{__float80} and @code{__float128} to support 80bit

(@code{XFmode}) and 128 bit (@code{TFmode}) floating types.

Support for additional types includes the arithmetic operators:

add, subtract, multiply, divide; unary arithmetic operators;

relational operators; equality operators; and conversions to and from

integer and other floating types.  Use a suffix @samp{w} or @samp{W}

in a literal constant of type @code{__float80} and @samp{q} or @samp{Q}

for @code{_float128}.  You can declare complex types using the

corresponding internal complex type, @code{XCmode} for @code{__float80}

type and @code{TCmode} for @code{__float128} type:

@smallexample

typedef _Complex float __attribute__((mode(TC))) _Complex128;

typedef _Complex float __attribute__((mode(XC))) _Complex80;

@end smallexample

Not all targets support additional floating point types.  @code{__float80}

and @code{__float128} types are supported on i386, x86_64 and ia64 targets.

@node Half-Precision

@section Half-Precision Floating Point

@cindex half-precision floating point

@cindex @code{__fp16} data type

On ARM targets, GCC supports half-precision (16-bit) floating point via

the @code{__fp16} type.  You must enable this type explicitly

with the @option{-mfp16-format} command-line option in order to use it.

ARM supports two incompatible representations for half-precision

floating-point values.  You must choose one of the representations and

use it consistently in your program.

Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.

This format can represent normalized values in the range of @math{2^{-14}} to 65504.