extend.texi

GCC

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

Labeling the elements of an array initializer is especially useful
when the indices are characters or belong to an @code{enum} type.
For example:

@example
int whitespace[256]
  = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
      ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
@end example

@cindex designator lists
You can also write a series of @samp{.@var{fieldname}} and
@samp{[@var{index}]} designators before an @samp{=} to specify a
nested subobject to initialize; the list is taken relative to the
subobject corresponding to the closest surrounding brace pair.  For
example, with the @samp{struct point} declaration above:

@example
struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
@end example

@noindent
If the same field is initialized multiple times, it will have value from
the last initialization.  If any such overridden initialization has
side-effect, it is unspecified whether the side-effect happens or not.
Currently, gcc will discard them and issue a warning.

@node Case Ranges
@section Case Ranges
@cindex case ranges
@cindex ranges in case statements

You can specify a range of consecutive values in a single @code{case} label,
like this:

@example
case @var{low} ... @var{high}:
@end example

@noindent
This has the same effect as the proper number of individual @code{case}
labels, one for each integer value from @var{low} to @var{high}, inclusive.

This feature is especially useful for ranges of ASCII character codes:

@example
case 'A' ... 'Z':
@end example

@strong{Be careful:} Write spaces around the @code{...}, for otherwise
it may be parsed wrong when you use it with integer values.  For example,
write this:

@example
case 1 ... 5:
@end example

@noindent
rather than this:

@example
case 1...5:
@end example

@node Cast to Union
@section Cast to a Union Type
@cindex cast to a union
@cindex union, casting to a

A cast to union type is similar to other casts, except that the type
specified is a union type.  You can specify the type either with
@code{union @var{tag}} or with a typedef name.  A cast to union is actually
a constructor though, not a cast, and hence does not yield an lvalue like
normal casts.  (@xref{Compound Literals}.)

The types that may be cast to the union type are those of the members
of the union.  Thus, given the following union and variables:

@example
union foo @{ int i; double d; @};
int x;
double y;
@end example

@noindent
both @code{x} and @code{y} can be cast to type @code{union} foo.

Using the cast as the right-hand side of an assignment to a variable of
union type is equivalent to storing in a member of the union:

@example
union foo u;
@dots{}
u = (union foo) x  @equiv{}  u.i = x
u = (union foo) y  @equiv{}  u.d = y
@end example

You can also use the union cast as a function argument:

@example
void hack (union foo);
@dots{}
hack ((union foo) x);
@end example

@node Mixed Declarations
@section Mixed Declarations and Code
@cindex mixed declarations and code
@cindex declarations, mixed with code
@cindex code, mixed with declarations

ISO C99 and ISO C++ allow declarations and code to be freely mixed
within compound statements.  As an extension, GCC also allows this in
C89 mode.  For example, you could do:

@example
int i;
@dots{}
i++;
int j = i + 2;
@end example

Each identifier is visible from where it is declared until the end of
the enclosing block.

@node Function Attributes
@section Declaring Attributes of Functions
@cindex function attributes
@cindex declaring attributes of functions
@cindex functions that never return
@cindex functions that have no side effects
@cindex functions in arbitrary sections
@cindex functions that behave like malloc
@cindex @code{volatile} applied to function
@cindex @code{const} applied to function
@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
@cindex functions that are passed arguments in registers on the 386
@cindex functions that pop the argument stack on the 386
@cindex functions that do not pop the argument stack on the 386

In GNU C, you declare certain things about functions called in your program
which help the compiler optimize function calls and check your code more
carefully.

The keyword @code{__attribute__} allows you to specify special
attributes when making a declaration.  This keyword is followed by an
attribute specification inside double parentheses.  Fourteen attributes,
@code{noreturn}, @code{pure}, @code{const}, @code{format},
@code{format_arg}, @code{no_instrument_function}, @code{section},
@code{constructor}, @code{destructor}, @code{unused}, @code{weak},
@code{malloc}, @code{alias} and @code{no_check_memory_usage} are
currently defined for functions.  Several other attributes are defined
for functions on particular target systems.  Other attributes, including
@code{section} are supported for variables declarations (@pxref{Variable
Attributes}) and for types (@pxref{Type Attributes}).

You may also specify attributes with @samp{__} preceding and following
each keyword.  This allows you to use them in header files without
being concerned about a possible macro of the same name.  For example,
you may use @code{__noreturn__} instead of @code{noreturn}.

@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.

@table @code
@cindex @code{noreturn} function attribute
@item noreturn
A few standard library functions, such as @code{abort} and @code{exit},
cannot return.  GNU CC knows this automatically.  Some programs define
their own functions that never return.  You can declare them
@code{noreturn} to tell the compiler this fact.  For example,

@smallexample
void fatal () __attribute__ ((noreturn));

void
fatal (@dots{})
@{
  @dots{} /* @r{Print error message.} */ @dots{}
  exit (1);
@}
@end smallexample

The @code{noreturn} keyword tells the compiler to assume that
@code{fatal} cannot return.  It can then optimize without regard to what
would happen if @code{fatal} ever did return.  This makes slightly
better code.  More importantly, it helps avoid spurious warnings of
uninitialized variables.

Do not assume that registers saved by the calling function are
restored before calling the @code{noreturn} function.

It does not make sense for a @code{noreturn} function to have a return
type other than @code{void}.

The attribute @code{noreturn} is not implemented in GNU C versions
earlier than 2.5.  An alternative way to declare that a function does
not return, which works in the current version and in some older
versions, is as follows:

@smallexample
typedef void voidfn ();

volatile voidfn fatal;
@end smallexample

@cindex @code{pure} function attribute
@item pure
Many functions have no effects except the return value and their
return value depends only on the parameters and/or global variables.
Such a function can be subject
to common subexpression elimination and loop optimization just as an
arithmetic operator would be.  These functions should be declared
with the attribute @code{pure}.  For example,

@smallexample
int square (int) __attribute__ ((pure));
@end smallexample

@noindent
says that the hypothetical function @code{square} is safe to call
fewer times than the program says.

Some of common examples of pure functions are @code{strlen} or @code{memcmp}.
Interesting non-pure functions are functions with infinite loops or those
depending on volatile memory or other system resource, that may change between
two consecutive calls (such as @code{feof} in a multithreading environment).

The attribute @code{pure} is not implemented in GNU C versions earlier
than 2.96.
@cindex @code{const} function attribute
@item const
Many functions do not examine any values except their arguments, and
have no effects except the return value.  Basically this is just slightly
more strict class than the @code{pure} attribute above, since function is not
allowed to read global memory.

@cindex pointer arguments
Note that a function that has pointer arguments and examines the data
pointed to must @emph{not} be declared @code{const}.  Likewise, a
function that calls a non-@code{const} function usually must not be
@code{const}.  It does not make sense for a @code{const} function to
return @code{void}.

The attribute @code{const} is not implemented in GNU C versions earlier
than 2.5.  An alternative way to declare that a function has no side
effects, which works in the current version and in some older versions,
is as follows:

@smallexample
typedef int intfn ();

extern const intfn square;
@end smallexample

This approach does not work in GNU C++ from 2.6.0 on, since the language
specifies that the @samp{const} must be attached to the return value.


@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
@cindex @code{format} function attribute
@opindex Wformat
The @code{format} attribute specifies that a function takes @code{printf},
@code{scanf}, @code{strftime} or @code{strfmon} style arguments which
should be type-checked against a format string.  For example, the
declaration:

@smallexample
extern int
my_printf (void *my_object, const char *my_format, ...)
      __attribute__ ((format (printf, 2, 3)));
@end smallexample

@noindent
causes the compiler to check the arguments in calls to @code{my_printf}
for consistency with the @code{printf} style format string argument
@code{my_format}.

The parameter @var{archetype} determines how the format string is
interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}
or @code{strfmon}.  (You can also use @code{__printf__},
@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.)  The
parameter @var{string-index} specifies which argument is the format
string argument (starting from 1), while @var{first-to-check} is the
number of the first argument to check against the format string.  For
functions where the arguments are not available to be checked (such as
@code{vprintf}), specify the third parameter as zero.  In this case the
compiler only checks the format string for consistency.  For
@code{strftime} formats, the third parameter is required to be zero.

In the example above, the format string (@code{my_format}) is the second
argument of the function @code{my_print}, and the arguments to check
start with the third argument, so the correct parameters for the format
attribute are 2 and 3.

@opindex ffreestanding
The @code{format} attribute allows you to identify your own functions
which take format strings as arguments, so that GNU CC can check the
calls to these functions for errors.  The compiler always (unless
@option{-ffreestanding} is used) checks formats
for the standard library functions @code{printf}, @code{fprintf},
@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
warnings are requested (using @option{-Wformat}), so there is no need to
modify the header file @file{stdio.h}.  In C99 mode, the functions
@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
@code{vsscanf} are also checked.  Except in strictly conforming C
standard modes, the X/Open function @code{strfmon} is also checked.
@xref{C Dialect Options,,Options Controlling C Dialect}.

@item format_arg (@var{string-index})
@cindex @code{format_arg} function attribute
@opindex Wformat-nonliteral
The @code{format_arg} attribute specifies that a function takes a format
string for a @code{printf}, @code{scanf}, @code{strftime} or
@code{strfmon} style function and modifies it (for example, to translate
it into another language), so the result can be passed to a
@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
function (with the remaining arguments to the format function the same
as they would have been for the unmodified string).  For example, the
declaration:

@smallexample
extern char *
my_dgettext (char *my_domain, const char *my_format)
      __attribute__ ((format_arg (2)));
@end smallexample

@noindent
causes the compiler to check the arguments in calls to a @code{printf},
@code{scanf}, @code{strftime} or @code{strfmon} type function, whose
format string argument is a call to the @code{my_dgettext} function, for
consistency with the format string argument @code{my_format}.  If the
@code{format_arg} attribute had not been specified, all the compiler
could tell in such calls to format functions would be that the format
string argument is not constant; this would generate a warning when
@option{-Wformat-nonliteral} is used, but the calls could not be checked
without the attribute.

The parameter @var{string-index} specifies which argument is the format
string argument (starting from 1).

The @code{format-arg} attribute allows you to identify your