extend.texi

gcc库的原代码,对编程有很大帮助.

declares @samp{f} to be a weak alias for @samp{__f}.  In C++, the
mangled name for the target must be used.

@item regparm (@var{number})
@cindex functions that are passed arguments in registers on the 386
On the Intel 386, the @code{regparm} attribute causes the compiler to
pass up to @var{number} integer arguments in registers @var{EAX},
@var{EDX}, and @var{ECX} instead of on the stack.  Functions that take a
variable number of arguments will continue to be passed all of their
arguments on the stack.

@item stdcall
@cindex functions that pop the argument stack on the 386
On the Intel 386, the @code{stdcall} attribute causes the compiler to
assume that the called function will pop off the stack space used to
pass arguments, unless it takes a variable number of arguments.

@item cdecl
@cindex functions that do pop the argument stack on the 386
On the Intel 386, the @code{cdecl} attribute causes the compiler to
assume that the called function will pop off the stack space used to
pass arguments, unless it takes a variable number of arguments.  This is
useful to override the effects of the @samp{-mrtd} switch.
@end table

You can specify multiple attributes in a declaration by separating them
by commas within the double parentheses or by immediately following an
attribute declaration with another attribute declaration.

@cindex @code{#pragma}, reason for not using
@cindex pragma, reason for not using
Some people object to the @code{__attribute__} feature, suggesting that ANSI C's
@code{#pragma} should be used instead.  There are two reasons for not
doing this.

@enumerate
@item
It is impossible to generate @code{#pragma} commands from a macro.

@item
There is no telling what the same @code{#pragma} might mean in another
compiler.
@end enumerate

These two reasons apply to almost any application that might be proposed
for @code{#pragma}.  It is basically a mistake to use @code{#pragma} for
@emph{anything}.

@node Function Prototypes
@section Prototypes and Old-Style Function Definitions
@cindex function prototype declarations
@cindex old-style function definitions
@cindex promotion of formal parameters

GNU C extends ANSI C to allow a function prototype to override a later
old-style non-prototype definition.  Consider the following example:

@example
/* @r{Use prototypes unless the compiler is old-fashioned.}  */
#if __STDC__
#define P(x) x
#else
#define P(x) ()
#endif

/* @r{Prototype function declaration.}  */
int isroot P((uid_t));

/* @r{Old-style function definition.}  */
int
isroot (x)   /* ??? lossage here ??? */
     uid_t x;
@{
  return x == 0;
@}
@end example

Suppose the type @code{uid_t} happens to be @code{short}.  ANSI C does
not allow this example, because subword arguments in old-style
non-prototype definitions are promoted.  Therefore in this example the
function definition's argument is really an @code{int}, which does not
match the prototype argument type of @code{short}.

This restriction of ANSI C makes it hard to write code that is portable
to traditional C compilers, because the programmer does not know
whether the @code{uid_t} type is @code{short}, @code{int}, or
@code{long}.  Therefore, in cases like these GNU C allows a prototype
to override a later old-style definition.  More precisely, in GNU C, a
function prototype argument type overrides the argument type specified
by a later old-style definition if the former type is the same as the
latter type before promotion.  Thus in GNU C the above example is
equivalent to the following:

@example
int isroot (uid_t);

int
isroot (uid_t x)
@{
  return x == 0;
@}
@end example

GNU C++ does not support old-style function definitions, so this
extension is irrelevant.

@node C++ Comments
@section C++ Style Comments
@cindex //
@cindex C++ comments
@cindex comments, C++ style

In GNU C, you may use C++ style comments, which start with @samp{//} and
continue until the end of the line.  Many other C implementations allow
such comments, and they are likely to be in a future C standard.
However, C++ style comments are not recognized if you specify
@w{@samp{-ansi}} or @w{@samp{-traditional}}, since they are incompatible
with traditional constructs like @code{dividend//*comment*/divisor}.

@node Dollar Signs
@section Dollar Signs in Identifier Names
@cindex $
@cindex dollar signs in identifier names
@cindex identifier names, dollar signs in

In GNU C, you may use dollar signs in identifier names.  This is because
many traditional C implementations allow such identifiers.

On some machines, dollar signs are allowed in identifiers if you specify
@w{@samp{-traditional}}.  On a few systems they are allowed by default,
even if you do not use @w{@samp{-traditional}}.  But they are never
allowed if you specify @w{@samp{-ansi}}.

There are certain ANSI C programs (obscure, to be sure) that would
compile incorrectly if dollar signs were permitted in identifiers.  For
example:

@example
#define foo(a) #a
#define lose(b) foo (b)
#define test$
lose (test)
@end example

@node Character Escapes
@section The Character @key{ESC} in Constants

You can use the sequence @samp{\e} in a string or character constant to
stand for the ASCII character @key{ESC}.

@node Alignment
@section Inquiring on Alignment of Types or Variables
@cindex alignment
@cindex type alignment
@cindex variable alignment

The keyword @code{__alignof__} allows you to inquire about how an object
is aligned, or the minimum alignment usually required by a type.  Its
syntax is just like @code{sizeof}.

For example, if the target machine requires a @code{double} value to be
aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
This is true on many RISC machines.  On more traditional machine
designs, @code{__alignof__ (double)} is 4 or even 2.

Some machines never actually require alignment; they allow reference to any
data type even at an odd addresses.  For these machines, @code{__alignof__}
reports the @emph{recommended} alignment of a type.

When the operand of @code{__alignof__} is an lvalue rather than a type, the
value is the largest alignment that the lvalue is known to have.  It may
have this alignment as a result of its data type, or because it is part of
a structure and inherits alignment from that structure.  For example, after
this declaration:

@example
struct foo @{ int x; char y; @} foo1;
@end example

@noindent
the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as
@code{__alignof__ (int)}, even though the data type of @code{foo1.y}
does not itself demand any alignment.@refill

A related feature which lets you specify the alignment of an object is
@code{__attribute__ ((aligned (@var{alignment})))}; see the following
section.

@node Variable Attributes
@section Specifying Attributes of Variables
@cindex attribute of variables
@cindex variable attributes

The keyword @code{__attribute__} allows you to specify special
attributes of variables or structure fields.  This keyword is followed
by an attribute specification inside double parentheses.  Eight
attributes are currently defined for variables: @code{aligned},
@code{mode}, @code{nocommon}, @code{packed}, @code{section},
@code{transparent_union}, @code{unused}, and @code{weak}.  Other
attributes are available for functions (@pxref{Function 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{__aligned__} instead of @code{aligned}.

@table @code
@cindex @code{aligned} attribute
@item aligned (@var{alignment})
This attribute specifies a minimum alignment for the variable or
structure field, measured in bytes.  For example, the declaration:

@smallexample
int x __attribute__ ((aligned (16))) = 0;
@end smallexample

@noindent
causes the compiler to allocate the global variable @code{x} on a
16-byte boundary.  On a 68040, this could be used in conjunction with
an @code{asm} expression to access the @code{move16} instruction which
requires 16-byte aligned operands.

You can also specify the alignment of structure fields.  For example, to
create a double-word aligned @code{int} pair, you could write:

@smallexample
struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
@end smallexample

@noindent
This is an alternative to creating a union with a @code{double} member
that forces the union to be double-word aligned.

It is not possible to specify the alignment of functions; the alignment
of functions is determined by the machine's requirements and cannot be
changed.  You cannot specify alignment for a typedef name because such a
name is just an alias, not a distinct type.

As in the preceding examples, you can explicitly specify the alignment
(in bytes) that you wish the compiler to use for a given variable or
structure field.  Alternatively, you can leave out the alignment factor
and just ask the compiler to align a variable or field to the maximum
useful alignment for the target machine you are compiling for.  For
example, you could write:

@smallexample
short array[3] __attribute__ ((aligned));
@end smallexample

Whenever you leave out the alignment factor in an @code{aligned} attribute
specification, the compiler automatically sets the alignment for the declared
variable or field to the largest alignment which is ever used for any data
type on the target machine you are compiling for.  Doing this can often make
copy operations more efficient, because the compiler can use whatever
instructions copy the biggest chunks of memory when performing copies to
or from the variables or fields that you have aligned this way.

The @code{aligned} attribute can only increase the alignment; but you
can decrease it by specifying @code{packed} as well.  See below.

Note that the effectiveness of @code{aligned} attributes may be limited
by inherent limitations in your linker.  On many systems, the linker is
only able to arrange for variables to be aligned up to a certain maximum
alignment.  (For some linkers, the maximum supported alignment may
be very very small.)  If your linker is only able to align variables
up to a maximum of 8 byte alignment, then specifying @code{aligned(16)}
in an @code{__attribute__} will still only provide you with 8 byte
alignment.  See your linker documentation for further information.

@item mode (@var{mode})
@cindex @code{mode} attribute
This attribute specifies the data type for the declaration---whichever
type corresponds to the mode @var{mode}.  This in effect lets you
request an integer or floating point type according to its width.

You may also specify a mode of @samp{byte} or @samp{__byte__} to
indicate the mode corresponding to a one-byte integer, @samp{word} or
@samp{__word__} for the mode of a one-word integer, and @samp{pointer}
or @samp{__pointer__} for the mode used to represent pointers.

@item nocommon
@cindex @code{nocommon} attribute
This attribute specifies requests GNU CC not to place a variable
``common'' but instead to allocate space for it directly.  If you
specify the @samp{-fno-common} flag, GNU CC will do this for all
variables.

Specifying the @code{nocommon} attribute for a variable provides an
initialization of zeros.  A variable may only be initialized in one
source file.

@item packed
@cindex @code{packed} attribute
The @code{packed} attribute specifies that a variable or structure field
should have the smallest possible alignment---one byte for a variable,
and one bit for a field, unless you specify a larger value with the
@code{aligned} attribute.

Here is a structure in which the field @code{x} is packed, so that it
immediately follows @code{a}:

@example
struct foo
@{
  char a;
  int x[2] __attribute__ ((packed));
@};
@end example

@item section ("section-name")
@cindex @code{section} variable attribute
Normally, the compiler places the objects it generates in sections like
@code{data} and @code{bss}.  Sometimes, however, you need additional sections,
or you need certain particular variables to appear in special sections,
for example to map to special hardware.  The @code{section}
attribute specifies that a variable (or function) lives in a particular
section.  For example, this small program uses several specific section names:

@smallexample
struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
int init_data_copy __attribute__ ((section ("INITDATACOPY"))) = 0;

main()
@{
  /* Initialize stack pointer */
  init_sp (stack + sizeof (stack));

  /* Initialize initialized data */
  memcpy (&init_data_copy, &data, &edata - &data);

  /* Turn on the serial ports */
  init_duart (&a);
  init_duart (&b);
@}
@end smallexample

@noindent
Use the @code{section} attribute with an @emph{initialized} definition
of a @emph{global} variable, as shown in the example.  GNU CC issues
a warning and otherwise ignores the @code{section} attribute in
uninitialized variable declarations.

You may only use the @code{section} attribute with a fully initialized
global definition because of the way linkers work.  The linker requires
each object be defined once, with the exception that uninitialized
variables tentatively go in the @code{common} (or @code{bss}) section
and can be multiply "defined".  You can force a variable to be
initialized with the @samp{-fno-common} flag or the @code{nocommon}
attribute.

Some file formats do not support arbitrary sections so the @code{section}
attribute is not available on all platforms.
If you need to map the entire contents of a module to a particular
section, consider using the facilities of the linker instead.

@item transparent_union
This attribute, attached to a function argument variable which is a
union, means to pass the argument in the same way that the first union
member would be passed.  You can also use this attribute on a
@code{typedef} for a union data type; then it applies to all function
arguments with that type.

@item unused
This attribute, attached to a variable, means that the variable is meant
to be