This is
/es/build/frv-050408/1/frv550-uclinux/X-tools-build/gcc/doc/gcc.info,
produced by makeinfo version 4.0 from
/es/build/frv-050408/1/frv550-uclinux/sources/tools-src/gcc/doc/gcc.texi.

START-INFO-DIR-ENTRY
* usegcc: (usegcc).			Using the GNU C compiler.
END-INFO-DIR-ENTRY

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gcc: (gcc).                  The GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the use of the GNU compilers.

   Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

File: gcc.info,  Node: Preprocessing directives implementation,  Next: Library functions implementation,  Prev: Qualifiers implementation,  Up: C Implementation

Preprocessing directives
========================

   * `How sequences in both forms of header names are mapped to headers
     or external source file names (6.4.7).'

   * `Whether the value of a character constant in a constant expression
     that controls conditional inclusion matches the value of the same
     character constant in the execution character set (6.10.1).'

   * `Whether the value of a single-character character constant in a
     constant expression that controls conditional inclusion may have a
     negative value (6.10.1).'

   * `The places that are searched for an included `<>' delimited
     header, and how the places are specified or the header is
     identified (6.10.2).'

   * `How the named source file is searched for in an included `""'
     delimited header (6.10.2).'

   * `The method by which preprocessing tokens (possibly resulting from
     macro expansion) in a `#include' directive are combined into a
     header name (6.10.2).'

   * `The nesting limit for `#include' processing (6.10.2).'

     GCC imposes a limit of 200 nested `#include's.

   * `Whether the `#' operator inserts a `\' character before the `\'
     character that begins a universal character name in a character
     constant or string literal (6.10.3.2).'

   * `The behavior on each recognized non-`STDC #pragma' directive
     (6.10.6).'

   * `The definitions for `__DATE__' and `__TIME__' when respectively,
     the date and time of translation are not available (6.10.8).'

     If the date and time are not available, `__DATE__' expands to
     `"??? ?? ????"' and `__TIME__' expands to `"??:??:??"'.



File: gcc.info,  Node: Library functions implementation,  Next: Architecture implementation,  Prev: Preprocessing directives implementation,  Up: C Implementation

Library functions
=================

   The behavior of these points are dependent on the implementation of
the C library, and are not defined by GCC itself.


File: gcc.info,  Node: Architecture implementation,  Next: Locale-specific behavior implementation,  Prev: Library functions implementation,  Up: C Implementation

Architecture
============

   * `The values or expressions assigned to the macros specified in the
     headers `<float.h>', `<limits.h>', and `<stdint.h>' (5.2.4.2,
     7.18.2, 7.18.3).'

   * `The number, order, and encoding of bytes in any object (when not
     explicitly specified in this International Standard) (6.2.6.1).'

   * `The value of the result of the sizeof operator (6.5.3.4).'



File: gcc.info,  Node: Locale-specific behavior implementation,  Prev: Architecture implementation,  Up: C Implementation

Locale-specific behavior
========================

   The behavior of these points are dependent on the implementation of
the C library, and are not defined by GCC itself.


File: gcc.info,  Node: C Extensions,  Next: C++ Extensions,  Prev: C Implementation,  Up: Top

Extensions to the C Language Family
***********************************

   GNU C provides several language features not found in ISO standard C.
(The `-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
`__GNUC__', which is always defined under GCC.

   These extensions are available in C and Objective-C.  Most of them
are also available in C++.  *Note Extensions to the C++ Language: C++
Extensions, for extensions that apply _only_ to C++.

   Some features that are in ISO C99 but not C89 or C++ are also, as
extensions, accepted by GCC in C89 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::              `typeof': referring to the type of an expression.
* Lvalues::             Using `?:', `,' and casts in lvalues.
* Conditionals::        Omitting the middle operand of a `?:' expression.
* Long Long::		Double-word integers---`long long int'.
* Complex::             Data types for complex numbers.
* Hex Floats::          Hexadecimal floating-point constants.
* 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 `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.
* Interrupt Functions:: Compiling functions for interrupt calls
* C++ Comments::        C++ comments are recognized.
* Dollar Signs::        Dollar sign is allowed in identifiers.
* Character Escapes::   `\e' stands for the character <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::  `__const__', `__asm__', etc., for header files.
* Incomplete Enums::    `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.
* Other Builtins::      Other built-in functions.
* Redefining Typedefs:: Allow typedefs to be redefined.
* Target Builtins::     Built-in functions specific to particular targets.
* Pragmas::             Pragmas accepted by GCC.
* Unnamed Fields::      Unnamed struct/union fields within structs/unions.
* Thread-Local::        Per-thread variables.


File: gcc.info,  Node: Statement Exprs,  Next: Local Labels,  Up: C Extensions

Statements and Declarations in Expressions
==========================================

   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:

     ({ int y = foo (); int z;
        if (y > 0) z = y;
        else z = - y;
        z; })

is a valid (though slightly more complex than necessary) expression for
the absolute value of `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 `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:

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

But this definition computes either A or B twice, with bad results if
the operand has side effects.  In GNU C, if you know the type of the
operands (here let's assume `int'), you can define the macro safely as
follows:

     #define maxint(a,b) \
       ({int _a = (a), _b = (b); _a > _b ? _a : _b; })

   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 `typeof' (*note 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 `A' is a class, then

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

will construct a temporary `A' object to hold the result of the
statement expression, and that will be used to invoke `Foo'.  Therefore
the `this' pointer observed by `Foo' will not be the address of `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,

     #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 ());
     }

will have different places where temporaries are destroyed.  For the
`macro' case, the temporary `X' will be destroyed just after the
initialization of `b'.  In the `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.)


File: gcc.info,  Node: Local Labels,  Next: Labels as Values,  Prev: Statement Exprs,  Up: C Extensions

Locally Declared Labels
=======================

   GCC allows you to declare "local labels" in any nested block scope.
A local label is just like an ordinary label, but you can only
reference it (with a `goto' statement, or by taking its address) within
the block in which it was declared.

   A local label declaration looks like this:

     __label__ LABEL;

or

     __label__ LABEL1, LABEL2, /* ... */;

   Local label declarations must come at the beginning of the block,
before any ordinary declarations or statements.

   The label declaration defines the label _name_, but does not define
the label itself.  You must do this in the usual way, with `LABEL:',
within the statements of the statement expression.

   The local label feature is useful for complex macros.  If a macro
contains nested loops, a `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:

     #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)

   This could also be written using a statement-expression:

     #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;                                          \
     })

   Local label declarations also make the labels they declare visible to
nested functions, if there are any.  *Note Nested Functions::, for
details.


File: gcc.info,  Node: Labels as Values,  Next: Nested Functions,  Prev: Local Labels,  Up: C Extensions

Labels as Values
================

   You can get the address of a label defined in the current function
(or a containing function) with the unary operator `&&'.  The value has
type `void *'.  This value is a constant and can be used wherever a
constant of that type is valid.  For example:

     void *ptr;
     /* ... */
     ptr = &&foo;

   To use these values, you need to be able to jump to one.  This is
done with the computed goto statement(1), `goto *EXP;'.  For example,

     goto *ptr;

Any expression of type `void *' is allowed.

   One way of using these constants is in initializing a static array
that will serve as a jump table:

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

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

     goto *array[i];

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
`switch' statement.  The `switch' statement is cleaner, so use that
rather than an array unless the problem does not fit a `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

     static const int array[] = { &&foo - &&foo, &&bar - &&foo,
                                  &&hack - &&foo };
     goto *(&&foo + array[i]);

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.

   ---------- Footnotes ----------

   (1) 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.


File: gcc.info,  Node: Nested Functions,  Next: Constructing Calls,  Prev: Labels as Values,  Up: C Extensions

Nested Functions
================

   A "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 `square', and call it twice:

     foo (double a, double b)
     {
       double square (double z) { return z * z; }
     
       return square (a) + square (b);
     }

   The nested function can access all the variables of the containing
function that are visible at the point of its definition.  This is
called "lexical scoping".  For example, here we show a nested function
which uses an inherited variable named `offset':

     bar (int *array, int offset, int size)
     {
       int access (int *array, int index)
         { return array[index + offset]; }
       int i;
       /* ... */
       for (i = 0; i < size; i++)
         /* ... */ access (array, i) /* ... */
     }

   Nested function definitions are permitted within functions in the
places where variable definitions are allowed; that is, in any block,
before the first statement 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:

     hack (int *array, int size)
     {
       void store (int index, int value)
         { array[index] = value; }
     
       intermediate (store, size);
     }

   Here, the function `intermediate' receives the address of `store' as
an argument.  If `intermediate' calls `store', the arguments given to
`store' are used to store into `array'.  But this technique works only
so long as the containing function (`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 "trampolines".  A paper describing them is available as

`http://people.debian.org/~aaronl/Usenix88-lexic.pdf'.

   A nested function can jump to a label inherited from a containing
function, provided the label was explicitly declared in the containing
function (*note Local Labels::).  Such a jump returns instantly to the
containing function, exiting the nested function which did the `goto'
and any intermediate functions as well.  Here is an example:

     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;
       /* ... */
       for (i = 0; i < size; i++)
         /* ... */ access (array, i) /* ... */
       /* ... */
       return 0;
     
      /* Control comes here from `access'
         if it detects an error.  */
      failure:
       return -1;
     }

   A nested function always has internal linkage.  Declaring one with
`extern' is erroneous.  If you need to declare the nested function
before its definition, use `auto' (which is otherwise meaningless for
function declarations).

     bar (int *array, int offset, int size)
     {
       __label__ failure;
       auto int access (int *, int);
       /* ... */
       int access (int *array, int index)
         {
           if (index > size)
             goto failure;
           return array[index + offset];
         }
       /* ... */
     }


File: gcc.info,  Node: Constructing Calls,  Next: Typeof,  Prev: Nested Functions,  Up: C Extensions

Constructing Function 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).

 - 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.

 - Built-in Function: void * __builtin_apply (void (*FUNCTION)(), void
          *ARGUMENTS, size_t SIZE)
     This built-in function invokes FUNCTION with a copy of the
     parameters described by ARGUMENTS and SIZE.

     The value of ARGUMENTS should be the value returned by
     `__builtin_apply_args'.  The argument 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 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 SIZE.  The
     value is used by `__builtin_apply' to compute the amount of data
     that should be pushed on the stack and copied from the incoming
     argument area.

 - Built-in Function: void __builtin_return (void *RESULT)
     This built-in function returns the value described by RESULT from
     the containing function.  You should specify, for RESULT, a value
     returned by `__builtin_apply'.


File: gcc.info,  Node: Typeof,  Next: Lvalues,  Prev: Constructing Calls,  Up: C Extensions

Referring to a Type with `typeof'
=================================

   Another way to refer to the type of an expression is with `typeof'.
The syntax of using of this keyword looks like `sizeof', but the
construct acts semantically like a type name defined with `typedef'.

   There are two ways of writing the argument to `typeof': with an
expression or with a type.  Here is an example with an expression:

     typeof (x[0](1))

This assumes that `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:

     typeof (int *)

Here the type described is that of pointers to `int'.

   If you are writing a header file that must work when included in ISO
C programs, write `__typeof__' instead of `typeof'.  *Note Alternate
Keywords::.

   A `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 `sizeof' or `typeof'.

   `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:

     #define max(a,b) \
       ({ typeof (a) _a = (a); \
           typeof (b) _b = (b); \
         _a > _b ? _a : _b; })

   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 `a' and `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.

Some more examples of the use of `typeof':

   * This declares `y' with the type of what `x' points to.

          typeof (*x) y;

   * This declares `y' as an array of such values.

          typeof (*x) y[4];

   * This declares `y' as an array of pointers to characters:

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

     It is equivalent to the following traditional C declaration:

          char *y[4];

     To see the meaning of the declaration using `typeof', and why it
     might be a useful way to write, let's rewrite it with these macros:

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

     Now the declaration can be rewritten this way:

          array (pointer (char), 4) y;

     Thus, `array (pointer (char), 4)' is the type of arrays of 4
     pointers to `char'.

   _Compatibility Note:_ In addition to `typeof', GCC 2 supported a
more limited extension which permitted one to write

     typedef T = EXPR;

with the effect of declaring T to have the type of the expression 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 `typeof':

     typedef typeof(EXPR) T;

This will work with all versions of GCC.


File: gcc.info,  Node: Lvalues,  Next: Conditionals,  Prev: Typeof,  Up: C Extensions

Generalized Lvalues
===================

   Compound expressions, conditional expressions and casts are allowed
as lvalues provided their operands are lvalues.  This means that you
can take their addresses or store values into them.  All these
extensions are deprecated.

   Standard C++ allows compound expressions and conditional expressions
as lvalues, and permits casts to reference type, so use of this
extension is not supported for C++ code.

   For example, a compound expression can be assigned, provided the last
expression in the sequence is an lvalue.  These two expressions are
equivalent:

     (a, b) += 5
     a, (b += 5)

   Similarly, the address of the compound expression can be taken.
These two expressions are equivalent:

     &(a, b)
     a, &b

   A conditional expression is a valid lvalue if its type is not void
and the true and false branches are both valid lvalues.  For example,
these two expressions are equivalent:

     (a ? b : c) = 5
     (a ? b = 5 : (c = 5))

   A cast is a valid lvalue if its operand is an lvalue.  This extension
is deprecated.  A simple assignment whose left-hand side is a cast
works by converting the right-hand side first to the specified type,
then to the type of the inner left-hand side expression.  After this is
stored, the value is converted back to the specified type to become the
value of the assignment.  Thus, if `a' has type `char *', the following
two expressions are equivalent:

     (int)a = 5
     (int)(a = (char *)(int)5)

   An assignment-with-arithmetic operation such as `+=' applied to a
cast performs the arithmetic using the type resulting from the cast,
and then continues as in the previous case.  Therefore, these two
expressions are equivalent:

     (int)a += 5
     (int)(a = (char *)(int) ((int)a + 5))

   You cannot take the address of an lvalue cast, because the use of its
address would not work out coherently.  Suppose that `&(int)f' were
permitted, where `f' has type `float'.  Then the following statement
would try to store an integer bit-pattern where a floating point number
belongs:

     *&(int)f = 1;

   This is quite different from what `(int)f = 1' would do--that would
convert 1 to floating point and store it.  Rather than cause this
inconsistency, we think it is better to prohibit use of `&' on a cast.

   If you really do want an `int *' pointer with the address of `f',
you can simply write `(int *)&f'.


File: gcc.info,  Node: Conditionals,  Next: Long Long,  Prev: Lvalues,  Up: C Extensions

Conditionals with Omitted Operands
==================================

   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

     x ? : y

has the value of `x' if that is nonzero; otherwise, the value of `y'.

   This example is perfectly equivalent to

     x ? x : y

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.


File: gcc.info,  Node: Long Long,  Next: Complex,  Prev: Conditionals,  Up: C Extensions

Double-Word Integers
====================

   ISO C99 supports data types for integers that are at least 64 bits
wide, and as an extension GCC supports them in C89 mode and in C++.
Simply write `long long int' for a signed integer, or `unsigned long
long int' for an unsigned integer.  To make an integer constant of type
`long long int', add the suffix `LL' to the integer.  To make an
integer constant of type `unsigned long long int', add the suffix `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 `long long' types for function
arguments, unless you declare function prototypes.  If a function
expects type `int' for its argument, and you pass a value of type `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 `long long int' and you pass `int'.  The best way
to avoid such problems is to use prototypes.


File: gcc.info,  Node: Complex,  Next: Hex Floats,  Prev: Long Long,  Up: C Extensions

Complex Numbers
===============

   ISO C99 supports complex floating data types, and as an extension GCC
supports them in C89 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 `_Complex'.  As an extension, the older GNU keyword
`__complex__' is also supported.

   For example, `_Complex double x;' declares `x' as a variable whose
real part and imaginary part are both of type `double'.  `_Complex
short int y;' declares `y' to have real and imaginary parts of type
`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 `i' or
`j' (either one; they are equivalent).  For example, `2.5fi' has type
`_Complex float' and `3i' has type `_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
`<complex.h>' and use the macros `I' or `_Complex_I' instead.

   To extract the real part of a complex-valued expression EXP, write
`__real__ EXP'.  Likewise, use `__imag__' to extract the imaginary
part.  This is a GNU extension; for values of floating type, you should
use the ISO C99 functions `crealf', `creal', `creall', `cimagf',
`cimag' and `cimagl', declared in `<complex.h>' and also provided as
built-in functions by GCC.

   The operator `~' 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 `conjf', `conj' and `conjl',
declared in `<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 `foo', the two
fictitious variables are named `foo$real' and `foo$imag'.  You can
examine and set these two fictitious variables with your debugger.


File: gcc.info,  Node: Hex Floats,  Next: Zero Length,  Prev: Complex,  Up: C Extensions

Hex Floats
==========

   ISO C99 supports floating-point numbers written not only in the usual
decimal notation, such as `1.55e1', but also numbers such as `0x1.fp3'
written in hexadecimal format.  As a GNU extension, GCC supports this
in C89 mode (except in some cases when strictly conforming) and in C++.
In that format the `0x' hex introducer and the `p' or `P' exponent
field are mandatory.  The exponent is a decimal number that indicates
the power of 2 by which the significant part will be multiplied.  Thus
`0x1.f' is 1 15/16, `p3' multiplies it by 8, and the value of `0x1.fp3'
is the same as `1.55e1'.

   Unlike for floating-point numbers in the decimal notation the
exponent is always required in the hexadecimal notation.  Otherwise the
compiler would not be able to resolve the ambiguity of, e.g., `0x1.f'.
This could mean `1.0f' or `1.9375' since `f' is also the extension for
floating-point constants of type `float'.


File: gcc.info,  Node: Zero Length,  Next: Variable Length,  Prev: Hex Floats,  Up: C Extensions

Arrays of Length Zero
=====================

   Zero-length arrays are allowed in GNU C.  They are very useful as the
last element of a structure which is really a header for a
variable-length object:

     struct line {
       int length;
       char contents[0];
     };
     
     struct line *thisline = (struct line *)
       malloc (sizeof (struct line) + this_length);
     thisline->length = this_length;

   In ISO C90, you would have to give `contents' a length of 1, which
means either you waste space or complicate the argument to `malloc'.

   In ISO C99, you would use a "flexible array member", which is
slightly different in syntax and semantics:

   * Flexible array members are written as `contents[]' without the `0'.

   * Flexible array members have incomplete type, and so the `sizeof'
     operator may not be applied.  As a quirk of the original
     implementation of zero-length arrays, `sizeof' evaluates to zero.

   * Flexible array members may only appear as the last member of a
     `struct' that is otherwise non-empty.

   * A structure containing a flexible array member, or a union
     containing such a structure (possibly recursively), may not be a
     member of a structure or an element of an array.  (However, these
     uses are permitted by GCC as extensions.)

   GCC versions before 3.0 allowed zero-length arrays to be statically
initialized, as if they were flexible arrays.  In addition to those
cases that were useful, it also allowed initializations in situations
that would corrupt later data.  Non-empty initialization of zero-length
arrays is now treated like any case where there are more initializer
elements than the array holds, in that a suitable warning about "excess
elements in array" is given, and the excess elements (all of them, in
this case) are ignored.

   Instead GCC allows static initialization of flexible array members.
This is equivalent to defining a new structure containing the original
structure followed by an array of sufficient size to contain the data.
I.e. in the following, `f1' is constructed as if it were declared like
`f2'.

     struct f1 {
       int x; int y[];
     } f1 = { 1, { 2, 3, 4 } };
     
     struct f2 {
       struct f1 f1; int data[3];
     } f2 = { { 1 }, { 2, 3, 4 } };

The convenience of this extension is that `f1' has the desired type,
eliminating the need to consistently refer to `f2.f1'.

   This has symmetry with normal static arrays, in that an array of
unknown size is also written with `[]'.

   Of course, this extension only makes sense if the extra data comes at
the end of a top-level object, as otherwise we would be overwriting
data at subsequent offsets.  To avoid undue complication and confusion
with initialization of deeply nested arrays, we simply disallow any
non-empty initialization except when the structure is the top-level
object.  For example:

     struct foo { int x; int y[]; };
     struct bar { struct foo z; };
     
     struct foo a = { 1, { 2, 3, 4 } };        // Valid.
     struct bar b = { { 1, { 2, 3, 4 } } };    // Invalid.
     struct bar c = { { 1, { } } };            // Valid.
     struct foo d[1] = { { 1 { 2, 3, 4 } } };  // Invalid.


File: gcc.info,  Node: Empty Structures,  Next: Variadic Macros,  Prev: Variable Length,  Up: C Extensions

Structures With No Members
==========================

   GCC permits a C structure to have no members:

     struct empty {
     };

   The structure will have size zero.  In C++, empty structures are part
of the language.  G++ treats empty structures as if they had a single
member of type `char'.


File: gcc.info,  Node: Variable Length,  Next: Empty Structures,  Prev: Zero Length,  Up: C Extensions

Arrays of Variable Length
=========================

   Variable-length automatic arrays are allowed in ISO C99, and as an
extension GCC accepts them in C89 mode and in C++.  (However, GCC's
implementation of variable-length arrays does not yet conform in detail
to the ISO C99 standard.)  These arrays are declared like any other
automatic arrays, but with a length that is not a constant expression.
The storage is allocated at the point of declaration and deallocated
when the brace-level is exited.  For example:

     FILE *
     concat_fopen (char *s1, char *s2, char *mode)
     {
       char str[strlen (s1) + strlen (s2) + 1];
       strcpy (str, s1);
       strcat (str, s2);
       return fopen (str, mode);
     }

   Jumping or breaking out of the scope of the array name deallocates
the storage.  Jumping into the scope is not allowed; you get an error
message for it.

   You can use the function `alloca' to get an effect much like
variable-length arrays.  The function `alloca' is available in many
other C implementations (but not in all).  On the other hand,
variable-length arrays are more elegant.

   There are other differences between these two methods.  Space
allocated with `alloca' exists until the containing _function_ returns.
The space for a variable-length array is deallocated as soon as the
array name's scope ends.  (If you use both variable-length arrays and
`alloca' in the same function, deallocation of a variable-length array
will also deallocate anything more recently allocated with `alloca'.)

   You can also use variable-length arrays as arguments to functions:

     struct entry
     tester (int len, char data[len][len])
     {
       /* ... */
     }

   The length of an array is computed once when the storage is allocated
and is remembered for the scope of the array in case you access it with
`sizeof'.

   If you want to pass the array first and the length afterward, you can
use a forward declaration in the parameter list--another GNU extension.

     struct entry
     tester (int len; char data[len][len], int len)
     {
       /* ... */
     }

   The `int len' before the semicolon is a "parameter forward
declaration", and it serves the purpose of making the name `len' known
when the declaration of `data' is parsed.

   You can write any number of such parameter forward declarations in
the parameter list.  They can be separated by commas or semicolons, but
the last one must end with a semicolon, which is followed by the "real"
parameter declarations.  Each forward declaration must match a "real"
declaration in parameter name and data type.  ISO C99 does not support
parameter forward declarations.


File: gcc.info,  Node: Variadic Macros,  Next: Escaped Newlines,  Prev: Empty Structures,  Up: C Extensions

Macros with a Variable Number of Arguments.
===========================================

   In the ISO C standard of 1999, a macro can be declared to accept a
variable number of arguments much as a function can.  The syntax for
defining the macro is similar to that of a function.  Here is an
example:

     #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)

   Here `...' is a "variable argument".  In the invocation of such a
macro, it represents the zero or more tokens until the closing
parenthesis that ends the invocation, including any commas.  This set of
tokens replaces the identifier `__VA_ARGS__' in the macro body wherever
it appears.  See the CPP manual for more information.

   GCC has long supported variadic macros, and used a different syntax
that allowed you to give a name to the variable arguments just like any
other argument.  Here is an example:

     #define debug(format, args...) fprintf (stderr, format, args)

   This is in all ways equivalent to the ISO C example above, but
arguably more readable and descriptive.

   GNU CPP has two further variadic macro extensions, and permits them
to be used with either of the above forms of macro definition.

   In standard C, you are not allowed to leave the variable argument out
entirely; but you are allowed to pass an empty argument.  For example,
this invocation is invalid in ISO C, because there is no comma after
the string:

     debug ("A message")

   GNU CPP permits you to completely omit the variable arguments in this
way.  In the above examples, the compiler would complain, though since
the expansion of the macro still has the extra comma after the format
string.

   To help solve this problem, CPP behaves specially for variable
arguments used with the token paste operator, `##'.  If instead you
write

     #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)

   and if the variable arguments are omitted or empty, the `##'
operator causes the preprocessor to remove the comma before it.  If you
do provide some variable arguments in your macro invocation, GNU CPP
does not complain about the paste operation and instead places the
variable arguments after the comma.  Just like any other pasted macro
argument, these arguments are not macro expanded.


File: gcc.info,  Node: Escaped Newlines,  Next: Subscripting,  Prev: Variadic Macros,  Up: C Extensions

Slightly Looser Rules for Escaped Newlines
==========================================

   Recently, the preprocessor has relaxed its treatment of escaped
newlines.  Previously, the newline had to immediately follow a
backslash.  The current implementation allows whitespace in the form of
spaces, horizontal and vertical tabs, and form feeds between the
backslash and the subsequent newline.  The preprocessor issues a
warning, but treats it as a valid escaped newline and combines the two
lines to form a single logical line.  This works within comments and
tokens, as well as between tokens.  Comments are _not_ treated as
whitespace for the purposes of this relaxation, since they have not yet
been replaced with spaces.


File: gcc.info,  Node: Subscripting,  Next: Pointer Arith,  Prev: Escaped Newlines,  Up: C Extensions

Non-Lvalue Arrays May Have Subscripts
=====================================

   In ISO C99, arrays that are not lvalues still decay to pointers, and
may be subscripted, although they may not be modified or used after the
next sequence point and the unary `&' operator may not be applied to
them.  As an extension, GCC allows such arrays to be subscripted in C89
mode, though otherwise they do not decay to pointers outside C99 mode.
For example, this is valid in GNU C though not valid in C89:

     struct foo {int a[4];};
     
     struct foo f();
     
     bar (int index)
     {
       return f().a[index];
     }


File: gcc.info,  Node: Pointer Arith,  Next: Initializers,  Prev: Subscripting,  Up: C Extensions

Arithmetic on `void'- and Function-Pointers
===========================================

   In GNU C, addition and subtraction operations are supported on
pointers to `void' and on pointers to functions.  This is done by
treating the size of a `void' or of a function as 1.

   A consequence of this is that `sizeof' is also allowed on `void' and
on function types, and returns 1.

   The option `-Wpointer-arith' requests a warning if these extensions
are used.


File: gcc.info,  Node: Initializers,  Next: Compound Literals,  Prev: Pointer Arith,  Up: C Extensions

Non-Constant Initializers
=========================

   As in standard C++ and ISO C99, the elements of an aggregate
initializer for an automatic variable are not required to be constant
expressions in GNU C.  Here is an example of an initializer with
run-time varying elements:

     foo (float f, float g)
     {
       float beat_freqs[2] = { f-g, f+g };
       /* ... */
     }


File: gcc.info,  Node: Compound Literals,  Next: Designated Inits,  Prev: Initializers,  Up: C Extensions

Compound Literals
=================

   ISO C99 supports compound literals.  A compound literal looks like a
cast containing an initializer.  Its value is an object of the type
specified in the cast, containing the elements specified in the
initializer; it is an lvalue.  As an extension, GCC supports compound
literals in C89 mode and in C++.

   Usually, the specified type is a structure.  Assume that `struct
foo' and `structure' are declared as shown:

     struct foo {int a; char b[2];} structure;

Here is an example of constructing a `struct foo' with a compound
literal:

     structure = ((struct foo) {x + y, 'a', 0});

This is equivalent to writing the following:

     {
       struct foo temp = {x + y, 'a', 0};
       structure = temp;
     }

   You can also construct an array.  If all the elements of the
compound literal are (made up of) simple constant expressions, suitable
for use in initializers of objects of static storage duration, then the
compound literal can be coerced to a pointer to its first element and
used in such an initializer, as shown here:

     char **foo = (char *[]) { "x", "y", "z" };

   Compound literals for scalar types and union types are is also
allowed, but then the compound literal is equivalent to a cast.

   As a GNU extension, GCC allows initialization of objects with static
storage duration by compound literals (which is not possible in ISO
C99, because the initializer is not a constant).  It is handled as if
the object was initialized only with the bracket enclosed list if
compound literal's and object types match.  The initializer list of the
compound literal must be constant.  If the object being initialized has
array type of unknown size, the size is determined by compound literal
size.

     static struct foo x = (struct foo) {1, 'a', 'b'};
     static int y[] = (int []) {1, 2, 3};
     static int z[] = (int [3]) {1};

The above lines are equivalent to the following:
     static struct foo x = {1, 'a', 'b'};
     static int y[] = {1, 2, 3};
     static int z[] = {1, 0, 0};

