This is ../../gcc-3.4/gcc/doc/gcc.info, produced by makeinfo version
4.2 from ../../gcc-3.4/gcc/doc/gcc.texi.

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: Characters implementation,  Next: Integers implementation,  Prev: Identifiers implementation,  Up: C Implementation

Characters
==========

   * `The number of bits in a byte (3.6).'

   * `The values of the members of the execution character set (5.2.1).'

   * `The unique value of the member of the execution character set
     produced for each of the standard alphabetic escape sequences
     (5.2.2).'

   * `The value of a `char' object into which has been stored any
     character other than a member of the basic execution character set
     (6.2.5).'

   * `Which of `signed char' or `unsigned char' has the same range,
     representation, and behavior as "plain" `char' (6.2.5, 6.3.1.1).'

   * `The mapping of members of the source character set (in character
     constants and string literals) to members of the execution
     character set (6.4.4.4, 5.1.1.2).'

   * `The value of an integer character constant containing more than
     one character or containing a character or escape sequence that
     does not map to a single-byte execution character (6.4.4.4).'

   * `The value of a wide character constant containing more than one
     multibyte character, or containing a multibyte character or escape
     sequence not represented in the extended execution character set
     (6.4.4.4).'

   * `The current locale used to convert a wide character constant
     consisting of a single multibyte character that maps to a member
     of the extended execution character set into a corresponding wide
     character code (6.4.4.4).'

   * `The current locale used to convert a wide string literal into
     corresponding wide character codes (6.4.5).'

   * `The value of a string literal containing a multibyte character or
     escape sequence not represented in the execution character set
     (6.4.5).'


File: gcc.info,  Node: Integers implementation,  Next: Floating point implementation,  Prev: Characters implementation,  Up: C Implementation

Integers
========

   * `Any extended integer types that exist in the implementation
     (6.2.5).'

   * `Whether signed integer types are represented using sign and
     magnitude, two's complement, or one's complement, and whether the
     extraordinary value is a trap representation or an ordinary value
     (6.2.6.2).'

     GCC supports only two's complement integer types, and all bit
     patterns are ordinary values.

   * `The rank of any extended integer type relative to another extended
     integer type with the same precision (6.3.1.1).'

   * `The result of, or the signal raised by, converting an integer to a
     signed integer type when the value cannot be represented in an
     object of that type (6.3.1.3).'

   * `The results of some bitwise operations on signed integers (6.5).'


File: gcc.info,  Node: Floating point implementation,  Next: Arrays and pointers implementation,  Prev: Integers implementation,  Up: C Implementation

Floating point
==============

   * `The accuracy of the floating-point operations and of the library
     functions in `<math.h>' and `<complex.h>' that return
     floating-point results (5.2.4.2.2).'

   * `The rounding behaviors characterized by non-standard values of
     `FLT_ROUNDS'  (5.2.4.2.2).'

   * `The evaluation methods characterized by non-standard negative
     values of `FLT_EVAL_METHOD' (5.2.4.2.2).'

   * `The direction of rounding when an integer is converted to a
     floating-point number that cannot exactly represent the original
     value (6.3.1.4).'

   * `The direction of rounding when a floating-point number is
     converted to a narrower floating-point number (6.3.1.5).'

   * `How the nearest representable value or the larger or smaller
     representable value immediately adjacent to the nearest
     representable value is chosen for certain floating constants
     (6.4.4.2).'

   * `Whether and how floating expressions are contracted when not
     disallowed by the `FP_CONTRACT' pragma (6.5).'

   * `The default state for the `FENV_ACCESS' pragma (7.6.1).'

   * `Additional floating-point exceptions, rounding modes,
     environments, and classifications, and their macro names (7.6,
     7.12).'

   * `The default state for the `FP_CONTRACT' pragma (7.12.2).'

   * `Whether the "inexact" floating-point exception can be raised when
     the rounded result actually does equal the mathematical result in
     an IEC 60559 conformant implementation (F.9).'

   * `Whether the "underflow" (and "inexact") floating-point exception
     can be raised when a result is tiny but not inexact in an IEC
     60559 conformant implementation (F.9).'



File: gcc.info,  Node: Arrays and pointers implementation,  Next: Hints implementation,  Prev: Floating point implementation,  Up: C Implementation

Arrays and pointers
===================

   * `The result of converting a pointer to an integer or vice versa
     (6.3.2.3).'

     A cast from pointer to integer discards most-significant bits if
     the pointer representation is larger than the integer type,
     sign-extends(1) if the pointer representation is smaller than the
     integer type, otherwise the bits are unchanged.

     A cast from integer to pointer discards most-significant bits if
     the pointer representation is smaller than the integer type,
     extends according to the signedness of the integer type if the
     pointer representation is larger than the integer type, otherwise
     the bits are unchanged.

     When casting from pointer to integer and back again, the resulting
     pointer must reference the same object as the original pointer,
     otherwise the behavior is undefined.  That is, one may not use
     integer arithmetic to avoid the undefined behavior of pointer
     arithmetic as proscribed in 6.5.6/8.

   * `The size of the result of subtracting two pointers to elements of
     the same array (6.5.6).'


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

   (1) Future versions of GCC may zero-extend, or use a target-defined
`ptr_extend' pattern.  Do not rely on sign extension.


File: gcc.info,  Node: Hints implementation,  Next: Structures unions enumerations and bit-fields implementation,  Prev: Arrays and pointers implementation,  Up: C Implementation

Hints
=====

   * `The extent to which suggestions made by using the `register'
     storage-class specifier are effective (6.7.1).'

     The `register' specifier affects code generation only in these
     ways:

        * When used as part of the register variable extension, see
          *Note Explicit Reg Vars::.

        * When `-O0' is in use, the compiler allocates distinct stack
          memory for all variables that do not have the `register'
          storage-class specifier; if `register' is specified, the
          variable may have a shorter lifespan than the code would
          indicate and may never be placed in memory.

        * On some rare x86 targets, `setjmp' doesn't save the registers
          in all circumstances.  In those cases, GCC doesn't allocate
          any variables in registers unless they are marked `register'.


   * `The extent to which suggestions made by using the inline function
     specifier are effective (6.7.4).'

     GCC will not inline any functions if the `-fno-inline' option is
     used or if `-O0' is used.  Otherwise, GCC may still be unable to
     inline a function for many reasons; the `-Winline' option may be
     used to determine if a function has not been inlined and why not.



File: gcc.info,  Node: Structures unions enumerations and bit-fields implementation,  Next: Qualifiers implementation,  Prev: Hints implementation,  Up: C Implementation

Structures, unions, enumerations, and bit-fields
================================================

   * `Whether a "plain" int bit-field is treated as a `signed int'
     bit-field or as an `unsigned int' bit-field (6.7.2, 6.7.2.1).'

   * `Allowable bit-field types other than `_Bool', `signed int', and
     `unsigned int' (6.7.2.1).'

   * `Whether a bit-field can straddle a storage-unit boundary
     (6.7.2.1).'

   * `The order of allocation of bit-fields within a unit (6.7.2.1).'

   * `The alignment of non-bit-field members of structures (6.7.2.1).'

   * `The integer type compatible with each enumerated type (6.7.2.2).'



File: gcc.info,  Node: Qualifiers implementation,  Next: Preprocessing directives implementation,  Prev: Structures unions enumerations and bit-fields implementation,  Up: C Implementation

Qualifiers
==========

   * `What constitutes an access to an object that has
     volatile-qualified type (6.7.3).'



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

   Standard C++ allows compound expressions and conditional expressions
as lvalues, and permits casts to reference type, so use of this
extension is deprecated 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.  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.

