extend.texi

GCC

@{
  @dots{}
@}
@end example

@cindex parameter forward declaration
The @samp{int len} before the semicolon is a @dfn{parameter forward
declaration}, and it serves the purpose of making the name @code{len}
known when the declaration of @code{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.

@node Variadic Macros
@section Macros with a Variable Number of Arguments.
@cindex variable number of arguments
@cindex macro with variable arguments
@cindex rest argument (in macro)
@cindex variadic macros

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:

@example
#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
@end example

Here @samp{@dots{}} is a @dfn{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 @code{__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:

@example
#define debug(format, args...) fprintf (stderr, format, args)
@end example

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:

@example
debug ("A message")
@end example

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, @samp{##}.  If instead you write

@example
#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
@end example

and if the variable arguments are omitted or empty, the @samp{##}
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.

@node Escaped Newlines
@section Slightly Looser Rules for Escaped Newlines
@cindex escaped newlines
@cindex newlines (escaped)

Recently, the non-traditional 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, including multi-line strings, as well as between tokens.
Comments are @emph{not} treated as whitespace for the purposes of this
relaxation, since they have not yet been replaced with spaces.

@node Multi-line Strings
@section String Literals with Embedded Newlines
@cindex multi-line string literals

As an extension, GNU CPP permits string literals to cross multiple lines
without escaping the embedded newlines.  Each embedded newline is
replaced with a single @samp{\n} character in the resulting string
literal, regardless of what form the newline took originally.

CPP currently allows such strings in directives as well (other than the
@samp{#include} family).  This is deprecated and will eventually be
removed.

@node Subscripting
@section Non-Lvalue Arrays May Have Subscripts
@cindex subscripting
@cindex arrays, non-lvalue

@cindex subscripting and function values
Subscripting is allowed on arrays that are not lvalues, even though the
unary @samp{&} operator is not.  (In ISO C99, both are allowed (though
the array may not be used after the next sequence point), but this ISO
C99 feature is not yet fully supported in GCC.)  For example,
this is valid in GNU C though not valid in C89:

@example
@group
struct foo @{int a[4];@};

struct foo f();

bar (int index)
@{
  return f().a[index];
@}
@end group
@end example

@node Pointer Arith
@section Arithmetic on @code{void}- and Function-Pointers
@cindex void pointers, arithmetic
@cindex void, size of pointer to
@cindex function pointers, arithmetic
@cindex function, size of pointer to

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

A consequence of this is that @code{sizeof} is also allowed on @code{void}
and on function types, and returns 1.

@opindex Wpointer-arith
The option @option{-Wpointer-arith} requests a warning if these extensions
are used.

@node Initializers
@section Non-Constant Initializers
@cindex initializers, non-constant
@cindex 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:

@example
foo (float f, float g)
@{
  float beat_freqs[2] = @{ f-g, f+g @};
  @dots{}
@}
@end example

@node Compound Literals
@section Compound Literals
@cindex constructor expressions
@cindex initializations in expressions
@cindex structures, constructor expression
@cindex expressions, constructor
@cindex compound literals
@c The GNU C name for what C99 calls compound literals was "constructor expressions".

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.  (GCC does not yet implement the full ISO C99 semantics
for compound literals.)  As an extension, GCC supports compound literals
in C89 mode and in C++.

Usually, the specified type is a structure.  Assume that
@code{struct foo} and @code{structure} are declared as shown:

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

@noindent
Here is an example of constructing a @code{struct foo} with a compound literal:

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

@noindent
This is equivalent to writing the following:

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

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, then the compound literal is an lvalue and can be coerced to a
pointer to its first element, as shown here:

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

Array compound literals whose elements are not simple constants are
not very useful, because the compound literal is not an lvalue; ISO C99
specifies that it is, being a temporary object with automatic storage
duration associated with the enclosing block, but GCC does not yet
implement this.  There are currently only two valid ways to use it with
GCC: to subscript it, or initialize
an array variable with it.  The former is probably slower than a
@code{switch} statement, while the latter does the same thing an
ordinary C initializer would do.  Here is an example of
subscripting an array compound literal:

@example
output = ((int[]) @{ 2, x, 28 @}) [input];
@end example

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

@node Designated Inits
@section Designated Initializers
@cindex initializers with labeled elements
@cindex labeled elements in initializers
@cindex case labels in initializers
@cindex designated initializers

Standard C89 requires the elements of an initializer to appear in a fixed
order, the same as the order of the elements in the array or structure
being initialized.

In ISO C99 you can give the elements in any order, specifying the array
indices or structure field names they apply to, and GNU C allows this as
an extension in C89 mode as well.  This extension is not
implemented in GNU C++.

To specify an array index, write
@samp{[@var{index}] =} before the element value.  For example,

@example
int a[6] = @{ [4] = 29, [2] = 15 @};
@end example

@noindent
is equivalent to

@example
int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
@end example

@noindent
The index values must be constant expressions, even if the array being
initialized is automatic.

An alternative syntax for this which has been obsolete since GCC 2.5 but
GCC still accepts is to write @samp{[@var{index}]} before the element
value, with no @samp{=}.

To initialize a range of elements to the same value, write
@samp{[@var{first} ... @var{last}] = @var{value}}.  This is a GNU
extension.  For example,

@example
int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
@end example

@noindent
If the value in it has side-effects, the side-effects will happen only once,
not for each initialized field by the range initializer.

@noindent
Note that the length of the array is the highest value specified
plus one.

In a structure initializer, specify the name of a field to initialize
with @samp{.@var{fieldname} =} before the element value.  For example,
given the following structure,

@example
struct point @{ int x, y; @};
@end example

@noindent
the following initialization

@example
struct point p = @{ .y = yvalue, .x = xvalue @};
@end example

@noindent
is equivalent to

@example
struct point p = @{ xvalue, yvalue @};
@end example

Another syntax which has the same meaning, obsolete since GCC 2.5, is
@samp{@var{fieldname}:}, as shown here:

@example
struct point p = @{ y: yvalue, x: xvalue @};
@end example

@cindex designators
The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
@dfn{designator}.  You can also use a designator (or the obsolete colon
syntax) when initializing a union, to specify which element of the union
should be used.  For example,

@example
union foo @{ int i; double d; @};

union foo f = @{ .d = 4 @};
@end example

@noindent
will convert 4 to a @code{double} to store it in the union using
the second element.  By contrast, casting 4 to type @code{union foo}
would store it into the union as the integer @code{i}, since it is
an integer.  (@xref{Cast to Union}.)

You can combine this technique of naming elements with ordinary C
initialization of successive elements.  Each initializer element that
does not have a designator applies to the next consecutive element of the
array or structure.  For example,

@example
int a[6] = @{ [1] = v1, v2, [4] = v4 @};
@end example

@noindent
is equivalent to