1917 lines
67 KiB
Plaintext
1917 lines
67 KiB
Plaintext
@c Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
|
|
@c This is part of the GCC manual.
|
|
@c For copying conditions, see the file gcc.texi.
|
|
|
|
@node Extensions
|
|
@chapter GNU Extensions to the C Language
|
|
@cindex extensions, C language
|
|
@cindex GNU extensions to the C language
|
|
@cindex C language extensions
|
|
|
|
GNU C provides several language features not found in ANSI standard C.
|
|
(The @samp{-pedantic} option directs GNU CC 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
|
|
@code{__GNUC__}, which is always defined under GNU CC.
|
|
|
|
@menu
|
|
* Statement Exprs:: Putting statements and declarations inside expressions.
|
|
* Local Labels:: Labels local to a statement-expression.
|
|
* Labels as Values:: Getting pointers to labels, and computed gotos.
|
|
* Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
|
|
* Naming Types:: Giving a name to the type of some expression.
|
|
* Typeof:: @code{typeof}: referring to the type of an expression.
|
|
* Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
|
|
* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
|
|
* Long Long:: Double-word integers---@code{long long int}.
|
|
* Zero Length:: Zero-length arrays.
|
|
* Variable Length:: Arrays whose length is computed at run time.
|
|
* Macro Varargs:: Macros with variable number of arguments.
|
|
* Subscripting:: Any array can be subscripted, even if not an lvalue.
|
|
* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
|
|
* Initializers:: Non-constant initializers.
|
|
* Constructors:: Constructor expressions give structures, unions
|
|
or arrays as values.
|
|
* Labeled Elements:: Labeling elements of initializers.
|
|
* Cast to Union:: Casting to union type from any member of the union.
|
|
* Case Ranges:: `case 1 ... 9' and such.
|
|
* Function Attributes:: Declaring that functions have no side effects,
|
|
or that they can never return.
|
|
* Function Prototypes:: Prototype declarations and old-style definitions.
|
|
* Dollar Signs:: Dollar sign is allowed in identifiers.
|
|
* Character Escapes:: @samp{\e} stands for the character @key{ESC}.
|
|
* Variable Attributes:: Specifying attributes of variables.
|
|
* 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.)
|
|
* Asm Labels:: Specifying the assembler name to use for a C symbol.
|
|
* Explicit Reg Vars:: Defining variables residing in specified registers.
|
|
* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
|
|
* Incomplete Enums:: @code{enum foo;}, with details to follow.
|
|
@end menu
|
|
|
|
@node Statement Exprs
|
|
@section Statements and Declarations within Expressions
|
|
@cindex statements inside expressions
|
|
@cindex declarations inside expressions
|
|
@cindex expressions containing statements
|
|
@cindex macros, statements 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:
|
|
|
|
@example
|
|
(@{ int y = foo (); int z;
|
|
if (y > 0) z = y;
|
|
else z = - y;
|
|
z; @})
|
|
@end example
|
|
|
|
@noindent
|
|
is a valid (though slightly more complex than necessary) expression
|
|
for the absolute value of @code{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 @code{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:
|
|
|
|
@example
|
|
#define max(a,b) ((a) > (b) ? (a) : (b))
|
|
@end example
|
|
|
|
@noindent
|
|
@cindex side effects, macro argument
|
|
But this definition computes either @var{a} or @var{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 @code{int}), you can define
|
|
the macro safely as follows:
|
|
|
|
@example
|
|
#define maxint(a,b) \
|
|
(@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
|
|
@end example
|
|
|
|
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 @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
|
|
Types}).
|
|
|
|
@node Local Labels
|
|
@section Locally Declared Labels
|
|
@cindex local labels
|
|
@cindex macros, local labels
|
|
|
|
Each statement expression is a scope in which @dfn{local labels} can be
|
|
declared. A local label is simply an identifier; you can jump to it
|
|
with an ordinary @code{goto} statement, but only from within the
|
|
statement expression it belongs to.
|
|
|
|
A local label declaration looks like this:
|
|
|
|
@example
|
|
__label__ @var{label};
|
|
@end example
|
|
|
|
@noindent
|
|
or
|
|
|
|
@example
|
|
__label__ @var{label1}, @var{label2}, @dots{};
|
|
@end example
|
|
|
|
Local label declarations must come at the beginning of the statement
|
|
expression, right after the @samp{(@{}, before any ordinary
|
|
declarations.
|
|
|
|
The label declaration defines the label @emph{name}, but does not define
|
|
the label itself. You must do this in the usual way, with
|
|
@code{@var{label}:}, within the statements of the statement expression.
|
|
|
|
The local label feature is useful because statement expressions are
|
|
often used in macros. If the macro contains nested loops, a @code{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:
|
|
|
|
@example
|
|
#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; \
|
|
@})
|
|
@end example
|
|
|
|
@node Labels as Values
|
|
@section Labels as Values
|
|
@cindex labels as values
|
|
@cindex computed gotos
|
|
@cindex goto with computed label
|
|
@cindex address of a label
|
|
|
|
You can get the address of a label defined in the current function
|
|
(or a containing function) with the unary operator @samp{&&}. The
|
|
value has type @code{void *}. This value is a constant and can be used
|
|
wherever a constant of that type is valid. For example:
|
|
|
|
@example
|
|
void *ptr;
|
|
@dots{}
|
|
ptr = &&foo;
|
|
@end example
|
|
|
|
To use these values, you need to be able to jump to one. This is done
|
|
with the computed goto statement@footnote{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.}, @code{goto *@var{exp};}. For example,
|
|
|
|
@example
|
|
goto *ptr;
|
|
@end example
|
|
|
|
@noindent
|
|
Any expression of type @code{void *} is allowed.
|
|
|
|
One way of using these constants is in initializing a static array that
|
|
will serve as a jump table:
|
|
|
|
@example
|
|
static void *array[] = @{ &&foo, &&bar, &&hack @};
|
|
@end example
|
|
|
|
Then you can select a label with indexing, like this:
|
|
|
|
@example
|
|
goto *array[i];
|
|
@end example
|
|
|
|
@noindent
|
|
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
|
|
@code{switch} statement. The @code{switch} statement is cleaner, so
|
|
use that rather than an array unless the problem does not fit a
|
|
@code{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 can 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.
|
|
|
|
@node Nested Functions
|
|
@section Nested Functions
|
|
@cindex nested functions
|
|
@cindex downward funargs
|
|
@cindex thunks
|
|
|
|
A @dfn{nested function} is a function defined inside another function.
|
|
The nested function's name is local to the block where it is defined.
|
|
For example, here we define a nested function named @code{square},
|
|
and call it twice:
|
|
|
|
@example
|
|
foo (double a, double b)
|
|
@{
|
|
double square (double z) @{ return z * z; @}
|
|
|
|
return square (a) + square (b);
|
|
@}
|
|
@end example
|
|
|
|
The nested function can access all the variables of the containing
|
|
function that are visible at the point of its definition. This is
|
|
called @dfn{lexical scoping}. For example, here we show a nested
|
|
function which uses an inherited variable named @code{offset}:
|
|
|
|
@example
|
|
bar (int *array, int offset, int size)
|
|
@{
|
|
int access (int *array, int index)
|
|
@{ return array[index + offset]; @}
|
|
int i;
|
|
@dots{}
|
|
for (i = 0; i < size; i++)
|
|
@dots{} access (array, i) @dots{}
|
|
@}
|
|
@end example
|
|
|
|
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:
|
|
|
|
@example
|
|
hack (int *array, int size)
|
|
@{
|
|
void store (int index, int value)
|
|
@{ array[index] = value; @}
|
|
|
|
intermediate (store, size);
|
|
@}
|
|
@end example
|
|
|
|
Here, the function @code{intermediate} receives the address of
|
|
@code{store} as an argument. If @code{intermediate} calls
|
|
@code{store}, the arguments given to @code{store} are used to store
|
|
into @code{array}. But this technique works only so long as the
|
|
containing function (@code{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.
|
|
|
|
A nested function can jump to a label inherited from a containing
|
|
function, provided the label was explicitly declared in the containing
|
|
function (@pxref{Local Labels}). Such a jump returns instantly to the
|
|
containing function, exiting the nested function which did the
|
|
@code{goto} and any intermediate functions as well. Here is an example:
|
|
|
|
@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;
|
|
@dots{}
|
|
for (i = 0; i < size; i++)
|
|
@dots{} access (array, i) @dots{}
|
|
@dots{}
|
|
return 0;
|
|
|
|
/* @r{Control comes here from @code{access}
|
|
if it detects an error.} */
|
|
failure:
|
|
return -1;
|
|
@}
|
|
@end example
|
|
|
|
A nested function always has internal linkage. Declaring one with
|
|
@code{extern} is erroneous. If you need to declare the nested function
|
|
before its definition, use @code{auto} (which is otherwise meaningless
|
|
for function declarations).
|
|
|
|
@example
|
|
bar (int *array, int offset, int size)
|
|
@{
|
|
__label__ failure;
|
|
auto int access (int *, int);
|
|
@dots{}
|
|
int access (int *array, int index)
|
|
@{
|
|
if (index > size)
|
|
goto failure;
|
|
return array[index + offset];
|
|
@}
|
|
@dots{}
|
|
@}
|
|
@end example
|
|
|
|
@node Naming Types
|
|
@section Naming an Expression's Type
|
|
@cindex naming types
|
|
|
|
You can give a name to the type of an expression using a @code{typedef}
|
|
declaration with an initializer. Here is how to define @var{name} as a
|
|
type name for the type of @var{exp}:
|
|
|
|
@example
|
|
typedef @var{name} = @var{exp};
|
|
@end example
|
|
|
|
This is 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:
|
|
|
|
@example
|
|
#define max(a,b) \
|
|
(@{typedef _ta = (a), _tb = (b); \
|
|
_ta _a = (a); _tb _b = (b); \
|
|
_a > _b ? _a : _b; @})
|
|
@end example
|
|
|
|
@cindex underscores in variables in macros
|
|
@cindex @samp{_} in variables in macros
|
|
@cindex local variables in macros
|
|
@cindex variables, local, in macros
|
|
@cindex macros, local variables in
|
|
|
|
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 @code{a} and @code{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.
|
|
|
|
@node Typeof
|
|
@section Referring to a Type with @code{typeof}
|
|
@findex typeof
|
|
@findex sizeof
|
|
@cindex macros, types of arguments
|
|
|
|
Another way to refer to the type of an expression is with @code{typeof}.
|
|
The syntax of using of this keyword looks like @code{sizeof}, but the
|
|
construct acts semantically like a type name defined with @code{typedef}.
|
|
|
|
There are two ways of writing the argument to @code{typeof}: with an
|
|
expression or with a type. Here is an example with an expression:
|
|
|
|
@example
|
|
typeof (x[0](1))
|
|
@end example
|
|
|
|
@noindent
|
|
This assumes that @code{x} is an array of functions; the type described
|
|
is that of the values of the functions.
|
|
|
|
Here is an example with a typename as the argument:
|
|
|
|
@example
|
|
typeof (int *)
|
|
@end example
|
|
|
|
@noindent
|
|
Here the type described is that of pointers to @code{int}.
|
|
|
|
If you are writing a header file that must work when included in ANSI C
|
|
programs, write @code{__typeof__} instead of @code{typeof}.
|
|
@xref{Alternate Keywords}.
|
|
|
|
A @code{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 @code{sizeof} or @code{typeof}.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
This declares @code{y} with the type of what @code{x} points to.
|
|
|
|
@example
|
|
typeof (*x) y;
|
|
@end example
|
|
|
|
@item
|
|
This declares @code{y} as an array of such values.
|
|
|
|
@example
|
|
typeof (*x) y[4];
|
|
@end example
|
|
|
|
@item
|
|
This declares @code{y} as an array of pointers to characters:
|
|
|
|
@example
|
|
typeof (typeof (char *)[4]) y;
|
|
@end example
|
|
|
|
@noindent
|
|
It is equivalent to the following traditional C declaration:
|
|
|
|
@example
|
|
char *y[4];
|
|
@end example
|
|
|
|
To see the meaning of the declaration using @code{typeof}, and why it
|
|
might be a useful way to write, let's rewrite it with these macros:
|
|
|
|
@example
|
|
#define pointer(T) typeof(T *)
|
|
#define array(T, N) typeof(T [N])
|
|
@end example
|
|
|
|
@noindent
|
|
Now the declaration can be rewritten this way:
|
|
|
|
@example
|
|
array (pointer (char), 4) y;
|
|
@end example
|
|
|
|
@noindent
|
|
Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
|
|
pointers to @code{char}.
|
|
@end itemize
|
|
|
|
@node Lvalues
|
|
@section Generalized Lvalues
|
|
@cindex compound expressions as lvalues
|
|
@cindex expressions, compound, as lvalues
|
|
@cindex conditional expressions as lvalues
|
|
@cindex expressions, conditional, as lvalues
|
|
@cindex casts as lvalues
|
|
@cindex generalized lvalues
|
|
@cindex lvalues, generalized
|
|
@cindex extensions, @code{?:}
|
|
@cindex @code{?:} extensions
|
|
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.
|
|
|
|
For example, a compound expression can be assigned, provided the last
|
|
expression in the sequence is an lvalue. These two expressions are
|
|
equivalent:
|
|
|
|
@example
|
|
(a, b) += 5
|
|
a, (b += 5)
|
|
@end example
|
|
|
|
Similarly, the address of the compound expression can be taken. These two
|
|
expressions are equivalent:
|
|
|
|
@example
|
|
&(a, b)
|
|
a, &b
|
|
@end example
|
|
|
|
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:
|
|
|
|
@example
|
|
(a ? b : c) = 5
|
|
(a ? b = 5 : (c = 5))
|
|
@end example
|
|
|
|
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 @code{a} has type @code{char *}, the following two
|
|
expressions are equivalent:
|
|
|
|
@example
|
|
(int)a = 5
|
|
(int)(a = (char *)(int)5)
|
|
@end example
|
|
|
|
An assignment-with-arithmetic operation such as @samp{+=} 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:
|
|
|
|
@example
|
|
(int)a += 5
|
|
(int)(a = (char *)(int) ((int)a + 5))
|
|
@end example
|
|
|
|
You cannot take the address of an lvalue cast, because the use of its
|
|
address would not work out coherently. Suppose that @code{&(int)f} were
|
|
permitted, where @code{f} has type @code{float}. Then the following
|
|
statement would try to store an integer bit-pattern where a floating
|
|
point number belongs:
|
|
|
|
@example
|
|
*&(int)f = 1;
|
|
@end example
|
|
|
|
This is quite different from what @code{(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 @samp{&} on a cast.
|
|
|
|
If you really do want an @code{int *} pointer with the address of
|
|
@code{f}, you can simply write @code{(int *)&f}.
|
|
|
|
@node Conditionals
|
|
@section Conditional Expressions with Omitted Operands
|
|
@cindex conditional expressions, extensions
|
|
@cindex omitted middle-operands
|
|
@cindex middle-operands, omitted
|
|
@cindex extensions, @code{?:}
|
|
@cindex @code{?:} extensions
|
|
|
|
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
|
|
|
|
@example
|
|
x ? : y
|
|
@end example
|
|
|
|
@noindent
|
|
has the value of @code{x} if that is nonzero; otherwise, the value of
|
|
@code{y}.
|
|
|
|
This example is perfectly equivalent to
|
|
|
|
@example
|
|
x ? x : y
|
|
@end example
|
|
|
|
@cindex side effect in ?:
|
|
@cindex ?: side effect
|
|
@noindent
|
|
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.
|
|
|
|
@node Long Long
|
|
@section Double-Word Integers
|
|
@cindex @code{long long} data types
|
|
@cindex double-word arithmetic
|
|
@cindex multiprecision arithmetic
|
|
|
|
GNU C supports data types for integers that are twice as long as
|
|
@code{long int}. Simply write @code{long long int} for a signed
|
|
integer, or @code{unsigned long long int} for an unsigned 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 GNU CC.
|
|
|
|
There may be pitfalls when you use @code{long long} types for function
|
|
arguments, unless you declare function prototypes. If a function
|
|
expects type @code{int} for its argument, and you pass a value of type
|
|
@code{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 @code{long long int} and you pass
|
|
@code{int}. The best way to avoid such problems is to use prototypes.
|
|
|
|
@node Zero Length
|
|
@section Arrays of Length Zero
|
|
@cindex arrays of length zero
|
|
@cindex zero-length arrays
|
|
@cindex length-zero arrays
|
|
|
|
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:
|
|
|
|
@example
|
|
struct line @{
|
|
int length;
|
|
char contents[0];
|
|
@};
|
|
|
|
@{
|
|
struct line *thisline = (struct line *)
|
|
malloc (sizeof (struct line) + this_length);
|
|
thisline->length = this_length;
|
|
@}
|
|
@end example
|
|
|
|
In standard C, you would have to give @code{contents} a length of 1, which
|
|
means either you waste space or complicate the argument to @code{malloc}.
|
|
|
|
@node Variable Length
|
|
@section Arrays of Variable Length
|
|
@cindex variable-length arrays
|
|
@cindex arrays of variable length
|
|
|
|
Variable-length automatic arrays are allowed in GNU C. 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:
|
|
|
|
@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);
|
|
@}
|
|
@end example
|
|
|
|
@cindex scope of a variable length array
|
|
@cindex variable-length array scope
|
|
@cindex deallocating variable length arrays
|
|
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.
|
|
|
|
@cindex @code{alloca} vs variable-length arrays
|
|
You can use the function @code{alloca} to get an effect much like
|
|
variable-length arrays. The function @code{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 @code{alloca} exists until the containing @emph{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
|
|
@code{alloca} in the same function, deallocation of a variable-length array
|
|
will also deallocate anything more recently allocated with @code{alloca}.)
|
|
|
|
You can also use variable-length arrays as arguments to functions:
|
|
|
|
@example
|
|
struct entry
|
|
tester (int len, char data[len][len])
|
|
@{
|
|
@dots{}
|
|
@}
|
|
@end example
|
|
|
|
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
|
|
@code{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.
|
|
|
|
@example
|
|
struct entry
|
|
tester (int len; char data[len][len], int len)
|
|
@{
|
|
@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.
|
|
|
|
@node Macro Varargs
|
|
@section Macros with Variable Numbers of Arguments
|
|
@cindex variable number of arguments
|
|
@cindex macro with variable arguments
|
|
@cindex rest argument (in macro)
|
|
|
|
In GNU C, a macro can accept a variable number of arguments, much as a
|
|
function can. The syntax for defining the macro looks much like that
|
|
used for a function. Here is an example:
|
|
|
|
@example
|
|
#define eprintf(format, args...) \
|
|
fprintf (stderr, format, ## args)
|
|
@end example
|
|
|
|
Here @code{args} is a @dfn{rest argument}: it takes in zero or more
|
|
arguments, as many as the call contains. All of them plus the commas
|
|
between them form the value of @code{args}, which is substituted into
|
|
the macro body where @code{args} is used. Thus, we have these
|
|
expansions:
|
|
|
|
@example
|
|
eprintf ("%s:%d: ", input_file_name, line_number)
|
|
@expansion{}
|
|
fprintf (stderr, "%s:%d: ", input_file_name, line_number)
|
|
@end example
|
|
|
|
@noindent
|
|
Note that the comma after the string constant comes from the definition
|
|
of @code{eprintf}, whereas the last comma comes from the value of
|
|
@code{args}.
|
|
|
|
The reason for using @samp{##} is to handle the case when @code{args}
|
|
matches no arguments at all. In this case, @code{args} has an empty
|
|
value. In this case, the second comma in the definition becomes an
|
|
embarrassment: if it got through to the expansion of the macro, we would
|
|
get something like this:
|
|
|
|
@example
|
|
fprintf (stderr, "success!\n", )
|
|
@end example
|
|
|
|
@noindent
|
|
which is invalid C syntax. @samp{##} gets rid of the comma, so we get
|
|
the following instead:
|
|
|
|
@example
|
|
fprintf (stderr, "success!\n")
|
|
@end example
|
|
|
|
This is a special feature of the GNU C preprocessor: @samp{##} adjacent
|
|
to a rest argument discards the token on the other side of the
|
|
@samp{##}, if the rest argument value is empty.
|
|
|
|
@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. For example, this is valid in GNU C though
|
|
not valid in other C dialects:
|
|
|
|
@example
|
|
struct foo @{int a[4];@};
|
|
|
|
struct foo f();
|
|
|
|
bar (int index)
|
|
@{
|
|
return f().a[index];
|
|
@}
|
|
@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.
|
|
|
|
The option @samp{-Wpointer-arith} requests a warning if these extensions
|
|
are used.
|
|
|
|
@node Initializers
|
|
@section Non-Constant Initializers
|
|
@cindex initializers, non-constant
|
|
@cindex non-constant initializers
|
|
|
|
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 Constructors
|
|
@section Constructor Expressions
|
|
@cindex constructor expressions
|
|
@cindex initializations in expressions
|
|
@cindex structures, constructor expression
|
|
@cindex expressions, constructor
|
|
|
|
GNU C supports constructor expressions. A constructor 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.
|
|
|
|
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 constructor:
|
|
|
|
@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 constructor
|
|
are (made up of) simple constant expressions, suitable for use in
|
|
initializers, then the constructor 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 constructors whose elements are not simple constants are
|
|
not very useful, because the constructor is not an lvalue. There
|
|
are only two valid ways to use it: 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 constructor:
|
|
|
|
@example
|
|
output = ((int[]) @{ 2, x, 28 @}) [input];
|
|
@end example
|
|
|
|
Constructor expressions for scalar types and union types are is
|
|
also allowed, but then the constructor expression is equivalent
|
|
to a cast.
|
|
|
|
@node Labeled Elements
|
|
@section Labeled Elements in Initializers
|
|
@cindex initializers with labeled elements
|
|
@cindex labeled elements in initializers
|
|
@cindex case labels in initializers
|
|
|
|
Standard C 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 GNU C you can give the elements in any order, specifying the array
|
|
indices or structure field names they apply to.
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
You can also use an element label 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 label 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
|
|
|
|
@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
|
|
|
|
@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 like any other cast, 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.
|
|
|
|
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 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 @code{volatile} applied to function
|
|
@cindex @code{const} applied to function
|
|
|
|
In GNU C, you declare certain things about functions called in your program
|
|
which help the compiler optimize function calls.
|
|
|
|
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{volatile} to tell the compiler this fact. For example,
|
|
|
|
@example
|
|
extern void volatile fatal ();
|
|
|
|
void
|
|
fatal (@dots{})
|
|
@{
|
|
@dots{} /* @r{Print error message.} */ @dots{}
|
|
exit (1);
|
|
@}
|
|
@end example
|
|
|
|
The @code{volatile} keyword tells the compiler to assume that
|
|
@code{fatal} cannot return. This makes slightly better code, but more
|
|
importantly it helps avoid spurious warnings of uninitialized variables.
|
|
|
|
It does not make sense for a @code{volatile} function to have a return
|
|
type other than @code{void}.
|
|
|
|
Many functions do not examine any values except their arguments, and
|
|
have no effects except the return value. 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
|
|
@code{const}. For example,
|
|
|
|
@example
|
|
extern int const square ();
|
|
@end example
|
|
|
|
@noindent
|
|
says that the hypothetical function @code{square} is safe to call
|
|
fewer times than the program says.
|
|
|
|
@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}.
|
|
|
|
We recommend placing the keyword @code{const} after the function's
|
|
return type. It makes no difference in the example above, but when the
|
|
return type is a pointer, it is the only way to make the function itself
|
|
const. For example,
|
|
|
|
@example
|
|
const char *mincp (int);
|
|
@end example
|
|
|
|
@noindent
|
|
says that @code{mincp} returns @code{const char *}---a pointer to a
|
|
const object. To declare @code{mincp} const, you must write this:
|
|
|
|
@example
|
|
char * const mincp (int);
|
|
@end example
|
|
|
|
@cindex @code{#pragma}, reason for not using
|
|
@cindex pragma, reason for not using
|
|
Some people object to this 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
|
|
The @code{#pragma} command is just as likely as these keywords to mean
|
|
something else 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
|
|
|
|
@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.
|
|
|
|
Dollar signs are allowed on certain machines if you specify
|
|
@samp{-traditional}. On a few systems they are allowed by default, even
|
|
if @samp{-traditional} is not used. But they are never allowed if you
|
|
specify @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
|
|
|
|
@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. The only attributes
|
|
currently defined are the @code{aligned} and @code{format} attributes.
|
|
|
|
The @code{aligned} attribute specifies the alignment of the variable or
|
|
structure field. For example, the declaration:
|
|
|
|
@example
|
|
int x __attribute__ ((aligned (16))) = 0;
|
|
@end example
|
|
|
|
@noindent
|
|
causes the compiler to allocate the global variable @code{x} on a
|
|
16-byte boundary. On a 68000, 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:
|
|
|
|
@example
|
|
struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
|
|
@end example
|
|
|
|
@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.
|
|
|
|
The @code{format} attribute specifies that a function takes @code{printf}
|
|
or @code{scanf} style arguments which should be type-checked against a
|
|
format string. For example, the declaration:
|
|
|
|
@example
|
|
extern int
|
|
my_printf (void *my_object, const char *my_format, ...)
|
|
__attribute__ ((format (printf, 2, 3)));
|
|
@end example
|
|
|
|
@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 first parameter of the @code{format} attribute determines how the
|
|
format string is interpreted, and should be either @code{printf} or
|
|
@code{scanf}. The second parameter specifies the number of the
|
|
format string argument (starting from 1). The third parameter
|
|
specifies the number of the first argument which should be
|
|
checked 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.
|
|
|
|
In the example above, the format string (@code{my_format}) is the second
|
|
argument to @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.
|
|
|
|
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
|
|
checks formats for the ANSI library functions
|
|
@code{printf}, @code{fprintf}, @code{sprintf},
|
|
@code{scanf}, @code{fscanf}, @code{sscanf},
|
|
@code{vprintf}, @code{vfprintf} and @code{vsprintf}
|
|
whenever such warnings are requested (using @samp{-Wformat}), so there is no
|
|
need to modify the header file @file{stdio.h}.
|
|
|
|
@node Inline
|
|
@section An Inline Function is As Fast As a Macro
|
|
@cindex inline functions
|
|
@cindex integrating function code
|
|
@cindex open coding
|
|
@cindex macros, inline alternative
|
|
|
|
By declaring a function @code{inline}, you can direct GNU CC to integrate
|
|
that function's code into the code for its callers. This makes execution
|
|
faster by eliminating the function-call overhead; in addition, if any of
|
|
the actual argument values are constant, their known values may permit
|
|
simplifications at compile time so that not all of the inline function's
|
|
code needs to be included.
|
|
|
|
To declare a function inline, use the @code{inline} keyword in its
|
|
declaration, like this:
|
|
|
|
@example
|
|
inline int
|
|
inc (int *a)
|
|
@{
|
|
(*a)++;
|
|
@}
|
|
@end example
|
|
|
|
(If you are writing a header file to be included in ANSI C programs, write
|
|
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
|
|
|
|
You can also make all ``simple enough'' functions inline with the option
|
|
@samp{-finline-functions}. Note that certain usages in a function
|
|
definition can make it unsuitable for inline substitution.
|
|
|
|
@cindex inline functions, omission of
|
|
When a function is both inline and @code{static}, if all calls to the
|
|
function are integrated into the caller, and the function's address is
|
|
never used, then the function's own assembler code is never referenced.
|
|
In this case, GNU CC does not actually output assembler code for the
|
|
function, unless you specify the option @samp{-fkeep-inline-functions}.
|
|
Some calls cannot be integrated for various reasons (in particular,
|
|
calls that precede the function's definition cannot be integrated, and
|
|
neither can recursive calls within the definition). If there is a
|
|
nonintegrated call, then the function is compiled to assembler code as
|
|
usual. The function must also be compiled as usual if the program
|
|
refers to its address, because that can't be inlined.
|
|
|
|
@cindex non-static inline function
|
|
When an inline function is not @code{static}, then the compiler must assume
|
|
that there may be calls from other source files; since a global symbol can
|
|
be defined only once in any program, the function must not be defined in
|
|
the other source files, so the calls therein cannot be integrated.
|
|
Therefore, a non-@code{static} inline function is always compiled on its
|
|
own in the usual fashion.
|
|
|
|
If you specify both @code{inline} and @code{extern} in the function
|
|
definition, then the definition is used only for inlining. In no case
|
|
is the function compiled on its own, not even if you refer to its
|
|
address explicitly. Such an address becomes an external reference, as
|
|
if you had only declared the function, and had not defined it.
|
|
|
|
This combination of @code{inline} and @code{extern} has almost the
|
|
effect of a macro. The way to use it is to put a function definition in
|
|
a header file with these keywords, and put another copy of the
|
|
definition (lacking @code{inline} and @code{extern}) in a library file.
|
|
The definition in the header file will cause most calls to the function
|
|
to be inlined. If any uses of the function remain, they will refer to
|
|
the single copy in the library.
|
|
|
|
@node Extended Asm
|
|
@section Assembler Instructions with C Expression Operands
|
|
@cindex extended @code{asm}
|
|
@cindex @code{asm} expressions
|
|
@cindex assembler instructions
|
|
@cindex registers
|
|
|
|
In an assembler instruction using @code{asm}, you can now specify the
|
|
operands of the instruction using C expressions. This means no more
|
|
guessing which registers or memory locations will contain the data you want
|
|
to use.
|
|
|
|
You must specify an assembler instruction template much like what appears
|
|
in a machine description, plus an operand constraint string for each
|
|
operand.
|
|
|
|
For example, here is how to use the 68881's @code{fsinx} instruction:
|
|
|
|
@example
|
|
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
|
|
@end example
|
|
|
|
@noindent
|
|
@ifset INTERNALS
|
|
Here @code{angle} is the C expression for the input operand while
|
|
@code{result} is that of the output operand. Each has @samp{"f"} as its
|
|
operand constraint, saying that a floating point register is required. The
|
|
@samp{=} in @samp{=f} indicates that the operand is an output; all output
|
|
operands' constraints must use @samp{=}. The constraints use the same
|
|
language used in the machine description (@pxref{Constraints}).
|
|
@end ifset
|
|
@ifclear INTERNALS
|
|
Here @code{angle} is the C expression for the input operand while
|
|
@code{result} is that of the output operand. Each has @samp{"f"} as its
|
|
operand constraint, saying that a floating point register is required. The
|
|
@samp{=} in @samp{=f} indicates that the operand is an output; all output
|
|
operands' constraints must use @samp{=}. The constraints use the same
|
|
language used in the machine description (@pxref{Constraints,,Operand
|
|
Constraints, gcc.info, Using and Porting GCC}).
|
|
@end ifclear
|
|
|
|
Each operand is described by an operand-constraint string followed by the C
|
|
expression in parentheses. A colon separates the assembler template from
|
|
the first output operand, and another separates the last output operand
|
|
from the first input, if any. Commas separate output operands and separate
|
|
inputs. The total number of operands is limited to ten or to the maximum
|
|
number of operands in any instruction pattern in the machine description,
|
|
whichever is greater.
|
|
|
|
If there are no output operands, and there are input operands, then there
|
|
must be two consecutive colons surrounding the place where the output
|
|
operands would go.
|
|
|
|
Output operand expressions must be lvalues; the compiler can check this.
|
|
The input operands need not be lvalues. The compiler cannot check whether
|
|
the operands have data types that are reasonable for the instruction being
|
|
executed. It does not parse the assembler instruction template and does
|
|
not know what it means, or whether it is valid assembler input. The
|
|
extended @code{asm} feature is most often used for machine instructions
|
|
that the compiler itself does not know exist.
|
|
|
|
The output operands must be write-only; GNU CC will assume that the values
|
|
in these operands before the instruction are dead and need not be
|
|
generated. Extended asm does not support input-output or read-write
|
|
operands. For this reason, the constraint character @samp{+}, which
|
|
indicates such an operand, may not be used.
|
|
|
|
When the assembler instruction has a read-write operand, or an operand
|
|
in which only some of the bits are to be changed, you must logically
|
|
split its function into two separate operands, one input operand and one
|
|
write-only output operand. The connection between them is expressed by
|
|
constraints which say they need to be in the same location when the
|
|
instruction executes. You can use the same C expression for both
|
|
operands, or different expressions. For example, here we write the
|
|
(fictitious) @samp{combine} instruction with @code{bar} as its read-only
|
|
source operand and @code{foo} as its read-write destination:
|
|
|
|
@example
|
|
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
|
|
@end example
|
|
|
|
@noindent
|
|
The constraint @samp{"0"} for operand 1 says that it must occupy the same
|
|
location as operand 0. A digit in constraint is allowed only in an input
|
|
operand, and it must refer to an output operand.
|
|
|
|
Only a digit in the constraint can guarantee that one operand will be in
|
|
the same place as another. The mere fact that @code{foo} is the value of
|
|
both operands is not enough to guarantee that they will be in the same
|
|
place in the generated assembler code. The following would not work:
|
|
|
|
@example
|
|
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
|
|
@end example
|
|
|
|
Various optimizations or reloading could cause operands 0 and 1 to be in
|
|
different registers; GNU CC knows no reason not to do so. For example, the
|
|
compiler might find a copy of the value of @code{foo} in one register and
|
|
use it for operand 1, but generate the output operand 0 in a different
|
|
register (copying it afterward to @code{foo}'s own address). Of course,
|
|
since the register for operand 1 is not even mentioned in the assembler
|
|
code, the result will not work, but GNU CC can't tell that.
|
|
|
|
Some instructions clobber specific hard registers. To describe this, write
|
|
a third colon after the input operands, followed by the names of the
|
|
clobbered hard registers (given as strings). Here is a realistic example
|
|
for the Vax:
|
|
|
|
@example
|
|
asm volatile ("movc3 %0,%1,%2"
|
|
: /* no outputs */
|
|
: "g" (from), "g" (to), "g" (count)
|
|
: "r0", "r1", "r2", "r3", "r4", "r5");
|
|
@end example
|
|
|
|
If you refer to a particular hardware register from the assembler code,
|
|
then you will probably have to list the register after the third colon
|
|
to tell the compiler that the register's value is modified. In many
|
|
assemblers, the register names begin with @samp{%}; to produce one
|
|
@samp{%} in the assembler code, you must write @samp{%%} in the input.
|
|
|
|
If your assembler instruction can alter the condition code register,
|
|
add @samp{cc} to the list of clobbered registers. GNU CC on some
|
|
machines represents the condition codes as a specific hardware
|
|
register; @samp{cc} serves to name this register. On other machines,
|
|
the condition code is handled differently, and specifying @samp{cc}
|
|
has no effect. But it is valid no matter what the machine.
|
|
|
|
You can put multiple assembler instructions together in a single @code{asm}
|
|
template, separated either with newlines (written as @samp{\n}) or with
|
|
semicolons if the assembler allows such semicolons. The GNU assembler
|
|
allows semicolons and all Unix assemblers seem to do so. The input
|
|
operands are guaranteed not to use any of the clobbered registers, and
|
|
neither will the output operands' addresses, so you can read and write the
|
|
clobbered registers as many times as you like. Here is an example of
|
|
multiple instructions in a template; it assumes that the subroutine
|
|
@code{_foo} accepts arguments in registers 9 and 10:
|
|
|
|
@example
|
|
asm ("movl %0,r9;movl %1,r10;call _foo"
|
|
: /* no outputs */
|
|
: "g" (from), "g" (to)
|
|
: "r9", "r10");
|
|
@end example
|
|
|
|
@ifset INTERNALS
|
|
Unless an output operand has the @samp{&} constraint modifier, GNU CC may
|
|
allocate it in the same register as an unrelated input operand, on the
|
|
assumption that the inputs are consumed before the outputs are produced.
|
|
This assumption may be false if the assembler code actually consists of
|
|
more than one instruction. In such a case, use @samp{&} for each output
|
|
operand that may not overlap an input.
|
|
@xref{Modifiers}.
|
|
@end ifset
|
|
@ifclear INTERNALS
|
|
Unless an output operand has the @samp{&} constraint modifier, GNU CC may
|
|
allocate it in the same register as an unrelated input operand, on the
|
|
assumption that the inputs are consumed before the outputs are produced.
|
|
This assumption may be false if the assembler code actually consists of
|
|
more than one instruction. In such a case, use @samp{&} for each output
|
|
operand that may not overlap an input.
|
|
@xref{Modifiers,,Constraint Modifier Characters,gcc.info,Using and
|
|
Porting GCC}.
|
|
@end ifclear
|
|
|
|
If you want to test the condition code produced by an assembler instruction,
|
|
you must include a branch and a label in the @code{asm} construct, as follows:
|
|
|
|
@example
|
|
asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
|
|
: "g" (result)
|
|
: "g" (input));
|
|
@end example
|
|
|
|
@noindent
|
|
This assumes your assembler supports local labels, as the GNU assembler
|
|
and most Unix assemblers do.
|
|
|
|
@cindex macros containing @code{asm}
|
|
Usually the most convenient way to use these @code{asm} instructions is to
|
|
encapsulate them in macros that look like functions. For example,
|
|
|
|
@example
|
|
#define sin(x) \
|
|
(@{ double __value, __arg = (x); \
|
|
asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
|
|
__value; @})
|
|
@end example
|
|
|
|
@noindent
|
|
Here the variable @code{__arg} is used to make sure that the instruction
|
|
operates on a proper @code{double} value, and to accept only those
|
|
arguments @code{x} which can convert automatically to a @code{double}.
|
|
|
|
Another way to make sure the instruction operates on the correct data type
|
|
is to use a cast in the @code{asm}. This is different from using a
|
|
variable @code{__arg} in that it converts more different types. For
|
|
example, if the desired type were @code{int}, casting the argument to
|
|
@code{int} would accept a pointer with no complaint, while assigning the
|
|
argument to an @code{int} variable named @code{__arg} would warn about
|
|
using a pointer unless the caller explicitly casts it.
|
|
|
|
If an @code{asm} has output operands, GNU CC assumes for optimization
|
|
purposes that the instruction has no side effects except to change the
|
|
output operands. This does not mean that instructions with a side effect
|
|
cannot be used, but you must be careful, because the compiler may eliminate
|
|
them if the output operands aren't used, or move them out of loops, or
|
|
replace two with one if they constitute a common subexpression. Also, if
|
|
your instruction does have a side effect on a variable that otherwise
|
|
appears not to change, the old value of the variable may be reused later if
|
|
it happens to be found in a register.
|
|
|
|
You can prevent an @code{asm} instruction from being deleted, moved
|
|
significantly, or combined, by writing the keyword @code{volatile} after
|
|
the @code{asm}. For example:
|
|
|
|
@example
|
|
#define set_priority(x) \
|
|
asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
|
|
@end example
|
|
|
|
@noindent
|
|
An instruction without output operands will not be deleted or moved
|
|
significantly, regardless, unless it is unreachable.
|
|
|
|
Note that even a volatile @code{asm} instruction can be moved in ways
|
|
that appear insignificant to the compiler, such as across jump
|
|
instructions. You can't expect a sequence of volatile @code{asm}
|
|
instructions to remain perfectly consecutive. If you want consecutive
|
|
output, use a single @code{asm}.
|
|
|
|
It is a natural idea to look for a way to give access to the condition
|
|
code left by the assembler instruction. However, when we attempted to
|
|
implement this, we found no way to make it work reliably. The problem
|
|
is that output operands might need reloading, which would result in
|
|
additional following ``store'' instructions. On most machines, these
|
|
instructions would alter the condition code before there was time to
|
|
test it. This problem doesn't arise for ordinary ``test'' and
|
|
``compare'' instructions because they don't have any output operands.
|
|
|
|
If you are writing a header file that should be includable in ANSI C
|
|
programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
|
|
Keywords}.
|
|
|
|
@node Asm Labels
|
|
@section Controlling Names Used in Assembler Code
|
|
@cindex assembler names for identifiers
|
|
@cindex names used in assembler code
|
|
@cindex identifiers, names in assembler code
|
|
|
|
You can specify the name to be used in the assembler code for a C
|
|
function or variable by writing the @code{asm} (or @code{__asm__})
|
|
keyword after the declarator as follows:
|
|
|
|
@example
|
|
int foo asm ("myfoo") = 2;
|
|
@end example
|
|
|
|
@noindent
|
|
This specifies that the name to be used for the variable @code{foo} in
|
|
the assembler code should be @samp{myfoo} rather than the usual
|
|
@samp{_foo}.
|
|
|
|
On systems where an underscore is normally prepended to the name of a C
|
|
function or variable, this feature allows you to define names for the
|
|
linker that do not start with an underscore.
|
|
|
|
You cannot use @code{asm} in this way in a function @emph{definition}; but
|
|
you can get the same effect by writing a declaration for the function
|
|
before its definition and putting @code{asm} there, like this:
|
|
|
|
@example
|
|
extern func () asm ("FUNC");
|
|
|
|
func (x, y)
|
|
int x, y;
|
|
@dots{}
|
|
@end example
|
|
|
|
It is up to you to make sure that the assembler names you choose do not
|
|
conflict with any other assembler symbols. Also, you must not use a
|
|
register name; that would produce completely invalid assembler code. GNU
|
|
CC does not as yet have the ability to store static variables in registers.
|
|
Perhaps that will be added.
|
|
|
|
@node Explicit Reg Vars
|
|
@section Variables in Specified Registers
|
|
@cindex explicit register variables
|
|
@cindex variables in specified registers
|
|
@cindex specified registers
|
|
@cindex registers, global allocation
|
|
|
|
GNU C allows you to put a few global variables into specified hardware
|
|
registers. You can also specify the register in which an ordinary
|
|
register variable should be allocated.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Global register variables reserve registers throughout the program.
|
|
This may be useful in programs such as programming language
|
|
interpreters which have a couple of global variables that are accessed
|
|
very often.
|
|
|
|
@item
|
|
Local register variables in specific registers do not reserve the
|
|
registers. The compiler's data flow analysis is capable of determining
|
|
where the specified registers contain live values, and where they are
|
|
available for other uses.
|
|
|
|
These local variables are sometimes convenient for use with the extended
|
|
@code{asm} feature (@pxref{Extended Asm}), if you want to write one
|
|
output of the assembler instruction directly into a particular register.
|
|
(This will work provided the register you specify fits the constraints
|
|
specified for that operand in the @code{asm}.)
|
|
@end itemize
|
|
|
|
@menu
|
|
* Global Reg Vars::
|
|
* Local Reg Vars::
|
|
@end menu
|
|
|
|
@node Global Reg Vars
|
|
@subsection Defining Global Register Variables
|
|
@cindex global register variables
|
|
@cindex registers, global variables in
|
|
|
|
You can define a global register variable in GNU C like this:
|
|
|
|
@example
|
|
register int *foo asm ("a5");
|
|
@end example
|
|
|
|
@noindent
|
|
Here @code{a5} is the name of the register which should be used. Choose a
|
|
register which is normally saved and restored by function calls on your
|
|
machine, so that library routines will not clobber it.
|
|
|
|
Naturally the register name is cpu-dependent, so you would need to
|
|
conditionalize your program according to cpu type. The register
|
|
@code{a5} would be a good choice on a 68000 for a variable of pointer
|
|
type. On machines with register windows, be sure to choose a ``global''
|
|
register that is not affected magically by the function call mechanism.
|
|
|
|
In addition, operating systems on one type of cpu may differ in how they
|
|
name the registers; then you would need additional conditionals. For
|
|
example, some 68000 operating systems call this register @code{%a5}.
|
|
|
|
Eventually there may be a way of asking the compiler to choose a register
|
|
automatically, but first we need to figure out how it should choose and
|
|
how to enable you to guide the choice. No solution is evident.
|
|
|
|
Defining a global register variable in a certain register reserves that
|
|
register entirely for this use, at least within the current compilation.
|
|
The register will not be allocated for any other purpose in the functions
|
|
in the current compilation. The register will not be saved and restored by
|
|
these functions. Stores into this register are never deleted even if they
|
|
would appear to be dead, but references may be deleted or moved or
|
|
simplified.
|
|
|
|
It is not safe to access the global register variables from signal
|
|
handlers, or from more than one thread of control, because the system
|
|
library routines may temporarily use the register for other things (unless
|
|
you recompile them specially for the task at hand).
|
|
|
|
@cindex @code{qsort}, and global register variables
|
|
It is not safe for one function that uses a global register variable to
|
|
call another such function @code{foo} by way of a third function
|
|
@code{lose} that was compiled without knowledge of this variable (i.e. in a
|
|
different source file in which the variable wasn't declared). This is
|
|
because @code{lose} might save the register and put some other value there.
|
|
For example, you can't expect a global register variable to be available in
|
|
the comparison-function that you pass to @code{qsort}, since @code{qsort}
|
|
might have put something else in that register. (If you are prepared to
|
|
recompile @code{qsort} with the same global register variable, you can
|
|
solve this problem.)
|
|
|
|
If you want to recompile @code{qsort} or other source files which do not
|
|
actually use your global register variable, so that they will not use that
|
|
register for any other purpose, then it suffices to specify the compiler
|
|
option @samp{-ffixed-@var{reg}}. You need not actually add a global
|
|
register declaration to their source code.
|
|
|
|
A function which can alter the value of a global register variable cannot
|
|
safely be called from a function compiled without this variable, because it
|
|
could clobber the value the caller expects to find there on return.
|
|
Therefore, the function which is the entry point into the part of the
|
|
program that uses the global register variable must explicitly save and
|
|
restore the value which belongs to its caller.
|
|
|
|
@cindex register variable after @code{longjmp}
|
|
@cindex global register after @code{longjmp}
|
|
@cindex value after @code{longjmp}
|
|
@findex longjmp
|
|
@findex setjmp
|
|
On most machines, @code{longjmp} will restore to each global register
|
|
variable the value it had at the time of the @code{setjmp}. On some
|
|
machines, however, @code{longjmp} will not change the value of global
|
|
register variables. To be portable, the function that called @code{setjmp}
|
|
should make other arrangements to save the values of the global register
|
|
variables, and to restore them in a @code{longjmp}. This way, the same
|
|
thing will happen regardless of what @code{longjmp} does.
|
|
|
|
All global register variable declarations must precede all function
|
|
definitions. If such a declaration could appear after function
|
|
definitions, the declaration would be too late to prevent the register from
|
|
being used for other purposes in the preceding functions.
|
|
|
|
Global register variables may not have initial values, because an
|
|
executable file has no means to supply initial contents for a register.
|
|
|
|
On the Sparc, there are reports that g3 @dots{} g7 are suitable
|
|
registers, but certain library functions, such as @code{getwd}, as well
|
|
as the subroutines for division and remainder, modify g3 and g4. g1 and
|
|
g2 are local temporaries.
|
|
|
|
On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
|
|
Of course, it will not do to use more than a few of those.
|
|
|
|
@node Local Reg Vars
|
|
@subsection Specifying Registers for Local Variables
|
|
@cindex local variables, specifying registers
|
|
@cindex specifying registers for local variables
|
|
@cindex registers for local variables
|
|
|
|
You can define a local register variable with a specified register
|
|
like this:
|
|
|
|
@example
|
|
register int *foo asm ("a5");
|
|
@end example
|
|
|
|
@noindent
|
|
Here @code{a5} is the name of the register which should be used. Note
|
|
that this is the same syntax used for defining global register
|
|
variables, but for a local variable it would appear within a function.
|
|
|
|
Naturally the register name is cpu-dependent, but this is not a
|
|
problem, since specific registers are most often useful with explicit
|
|
assembler instructions (@pxref{Extended Asm}). Both of these things
|
|
generally require that you conditionalize your program according to
|
|
cpu type.
|
|
|
|
In addition, operating systems on one type of cpu may differ in how they
|
|
name the registers; then you would need additional conditionals. For
|
|
example, some 68000 operating systems call this register @code{%a5}.
|
|
|
|
Eventually there may be a way of asking the compiler to choose a register
|
|
automatically, but first we need to figure out how it should choose and
|
|
how to enable you to guide the choice. No solution is evident.
|
|
|
|
Defining such a register variable does not reserve the register; it
|
|
remains available for other uses in places where flow control determines
|
|
the variable's value is not live. However, these registers are made
|
|
unavailable for use in the reload pass. I would not be surprised if
|
|
excessive use of this feature leaves the compiler too few available
|
|
registers to compile certain functions.
|
|
|
|
@node Alternate Keywords
|
|
@section Alternate Keywords
|
|
@cindex alternate keywords
|
|
@cindex keywords, alternate
|
|
|
|
The option @samp{-traditional} disables certain keywords; @samp{-ansi}
|
|
disables certain others. This causes trouble when you want to use GNU C
|
|
extensions, or ANSI C features, in a general-purpose header file that
|
|
should be usable by all programs, including ANSI C programs and traditional
|
|
ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
|
|
used since they won't work in a program compiled with @samp{-ansi}, while
|
|
the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
|
|
and @code{inline} won't work in a program compiled with
|
|
@samp{-traditional}.@refill
|
|
|
|
The way to solve these problems is to put @samp{__} at the beginning and
|
|
end of each problematical keyword. For example, use @code{__asm__}
|
|
instead of @code{asm}, @code{__const__} instead of @code{const}, and
|
|
@code{__inline__} instead of @code{inline}.
|
|
|
|
Other C compilers won't accept these alternative keywords; if you want to
|
|
compile with another compiler, you can define the alternate keywords as
|
|
macros to replace them with the customary keywords. It looks like this:
|
|
|
|
@example
|
|
#ifndef __GNUC__
|
|
#define __asm__ asm
|
|
#endif
|
|
@end example
|
|
|
|
@samp{-pedantic} causes warnings for many GNU C extensions. You can
|
|
prevent such warnings within one expression by writing
|
|
@code{__extension__} before the expression. @code{__extension__} has no
|
|
effect aside from this.
|
|
|
|
@node Incomplete Enums
|
|
@section Incomplete @code{enum} Types
|
|
|
|
You can define an @code{enum} tag without specifying its possible values.
|
|
This results in an incomplete type, much like what you get if you write
|
|
@code{struct foo} without describing the elements. A later declaration
|
|
which does specify the possible values completes the type.
|
|
|
|
You can't allocate variables or storage using the type while it is
|
|
incomplete. However, you can work with pointers to that type.
|
|
|
|
This extension may not be very useful, but it makes the handling of
|
|
@code{enum} more consistent with the way @code{struct} and @code{union}
|
|
are handled.
|