+2004-01-18 Joseph S. Myers <jsm@polyomino.org.uk>
+
+ * doc/c-tree.texi, doc/compat.texi, doc/cpp.texi,
+ doc/cppopts.texi, doc/extend.texi, doc/install.texi,
+ doc/interface.texi, doc/invoke.texi, doc/libgcc.texi, doc/md.texi,
+ doc/objc.texi, doc/rtl.texi, doc/tm.texi, doc/trouble.texi: Use
+ @smallexample instead of @example.
+
2004-01-17 Ziemowit Laski <zlaski@apple.com>
* objc/objc-act.c (build_objc_method_call): Use target
-@c Copyright (c) 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
+@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
predicates end in @samp{_P}. Do not rely on the result type of these
macros being of any particular type. You may, however, rely on the fact
that the type can be compared to @code{0}, so that statements like
-@example
+@smallexample
if (TEST_P (t) && !TEST_P (y))
x = 1;
-@end example
+@end smallexample
@noindent
and
-@example
+@smallexample
int i = (TEST_P (t) != 0);
-@end example
+@end smallexample
@noindent
are legal. Macros that return @code{int} values now may be changed to
return @code{tree} values, or other pointers in the future. Even those
that continue to return @code{int} may return multiple nonzero codes
where previously they returned only zero and one. Therefore, you should
not write code like
-@example
+@smallexample
if (TEST_P (t) == 1)
-@end example
+@end smallexample
@noindent
as this code is not guaranteed to work correctly in the future.
compiler. For example, this predicate will hold of an implicitly
declared member function, or of the @code{TYPE_DECL} implicitly
generated for a class type. Recall that in C++ code like:
-@example
+@smallexample
struct S @{@};
-@end example
+@end smallexample
@noindent
is roughly equivalent to C code like:
-@example
+@smallexample
struct S @{@};
typedef struct S S;
-@end example
+@end smallexample
The implicitly generated @code{typedef} declaration is represented by a
@code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds.
If a friend function is defined in a class scope, the
@code{DECL_FRIEND_CONTEXT} macro can be used to determine the class in
which it was defined. For example, in
-@example
+@smallexample
class C @{ friend void f() @{@} @};
-@end example
+@end smallexample
@noindent
the @code{DECL_CONTEXT} for @code{f} will be the
@code{global_namespace}, but the @code{DECL_FRIEND_CONTEXT} will be the
of statements, connected via their @code{TREE_CHAIN}s. So, you should
always process the statement tree by looping over substatements, like
this:
-@example
+@smallexample
void process_stmt (stmt)
tree stmt;
@{
stmt = TREE_CHAIN (stmt);
@}
@}
-@end example
+@end smallexample
In other words, while the @code{then} clause of an @code{if} statement
in C++ can be only one statement (although that one statement may be a
compound statement), the intermediate representation will sometimes use
Used to represent an inline assembly statement. For an inline assembly
statement like:
-@example
+@smallexample
asm ("mov x, y");
-@end example
+@end smallexample
The @code{ASM_STRING} macro will return a @code{STRING_CST} node for
@code{"mov x, y"}. If the original statement made use of the
extended-assembly syntax, then @code{ASM_OUTPUTS},
@code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs,
and clobbers for the statement, represented as @code{STRING_CST} nodes.
The extended-assembly syntax looks like:
-@example
+@smallexample
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end example
+@end smallexample
The first string is the @code{ASM_STRING}, containing the instruction
template. The next two strings are the output and inputs, respectively;
this statement has no clobbers. As this example indicates, ``plain''
Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the
statement is a range of case labels. Such statements originate with the
extension that allows users to write things of the form:
-@example
+@smallexample
case 2 ... 5:
-@end example
+@end smallexample
The first value will be @code{CASE_LOW}, while the second will be
@code{CASE_HIGH}.
@code{TREE_VALUE} should be used as the conditional expression itself.
This representation is used to handle C++ code like this:
-@example
+@smallexample
if (int i = 7) @dots{}
-@end example
+@end smallexample
where there is a new local variable (or variables) declared within the
condition.
If the function uses the G++ ``named return value'' extension, meaning
that the function has been defined like:
-@example
+@smallexample
S f(int) return s @{@dots{}@}
-@end example
+@end smallexample
then there will be a @code{RETURN_INIT}. There is never a named
returned value for a constructor. The first argument to the
@code{RETURN_INIT} is the name of the object returned; the second
Used to represent a @code{return} statement. The @code{RETURN_EXPR} is
the expression returned; it will be @code{NULL_TREE} if the statement
was just
-@example
+@smallexample
return;
-@end example
+@end smallexample
@item SCOPE_STMT
@code{TREE_OPERAND} macro. For example, to access the first operand to
a binary plus expression @code{expr}, use:
-@example
+@smallexample
TREE_OPERAND (expr, 0)
-@end example
+@end smallexample
@noindent
As this example indicates, the operands are zero-indexed.
constants is obtained with @code{TREE_TYPE}; they are not always of type
@code{int}. In particular, @code{char} constants are represented with
@code{INTEGER_CST} nodes. The value of the integer constant @code{e} is
-given by @example
+given by
+@smallexample
((TREE_INT_CST_HIGH (e) << HOST_BITS_PER_WIDE_INT)
+ TREE_INST_CST_LOW (e))
-@end example
+@end smallexample
@noindent
HOST_BITS_PER_WIDE_INT is at least thirty-two on all platforms. Both
@code{TREE_INT_CST_HIGH} and @code{TREE_INT_CST_LOW} return a
Note that the @code{DECL_CONTEXT} for the @code{PTRMEM_CST_MEMBER} is in
general different from the @code{PTRMEM_CST_CLASS}. For example,
given:
-@example
+@smallexample
struct B @{ int i; @};
struct D : public B @{@};
int D::*dp = &D::i;
-@end example
+@end smallexample
@noindent
The @code{PTRMEM_CST_CLASS} for @code{&D::i} is @code{D}, even though
the @code{DECL_CONTEXT} for the @code{PTRMEM_CST_MEMBER} is @code{B},
@item STMT_EXPR
These nodes are used to represent GCC's statement-expression extension.
The statement-expression extension allows code like this:
-@example
+@smallexample
int f() @{ return (@{ int j; j = 3; j + 7; @}); @}
-@end example
+@end smallexample
In other words, an sequence of statements may occur where a single
expression would normally appear. The @code{STMT_EXPR} node represents
such an expression. The @code{STMT_EXPR_STMT} gives the statement
@code{COMPOUND_STMT}. More precisely, the value is the value computed
by the last @code{EXPR_STMT} in the outermost scope of the
@code{COMPOUND_STMT}. For example, in:
-@example
+@smallexample
(@{ 3; @})
-@end example
+@end smallexample
the value is @code{3} while in:
-@example
+@smallexample
(@{ if (x) @{ 3; @} @})
-@end example
+@end smallexample
(represented by a nested @code{COMPOUND_STMT}), there is no value. If
the @code{STMT_EXPR} does not yield a value, it's type will be
@code{void}.
-@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c Copyright (C) 2002, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
With default configuration options for G++ 3.3 the compile line for a
different C++ compiler needs to include
-@example
+@smallexample
-I@var{gcc_install_directory}/include/c++/3.3
-@end example
+@end smallexample
Similarly, compiling code with G++ that must use a C++ library other
than the GNU C++ library requires specifying the location of the header
@copying
@c man begin COPYRIGHT
Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999, 2000, 2001, 2002, 2003
+1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
The nine trigraphs and their replacements are
-@example
+@smallexample
Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
Replacement: [ ] @{ @} # \ ^ | ~
-@end example
+@end smallexample
@item
@cindex continued lines
@samp{/*} and continue until the next @samp{*/}. Block comments do not
nest:
-@example
+@smallexample
/* @r{this is} /* @r{one comment} */ @r{text outside comment}
-@end example
+@end smallexample
@dfn{Line comments} begin with @samp{//} and continue to the end of the
current line. Line comments do not nest either, but it does not matter,
because they would end in the same place anyway.
-@example
+@smallexample
// @r{this is} // @r{one comment}
@r{text outside comment}
-@end example
+@end smallexample
@end enumerate
It is safe to put line comments inside block comments, or vice versa.
-@example
+@smallexample
@group
/* @r{block comment}
// @r{contains line comment}
// @r{line comment} /* @r{contains block comment} */
@end group
-@end example
+@end smallexample
But beware of commenting out one end of a block comment with a line
comment.
-@example
+@smallexample
@group
// @r{l.c.} /* @r{block comment begins}
@r{oops! this isn't a comment anymore} */
@end group
-@end example
+@end smallexample
Comments are not recognized within string literals.
@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not
@samp{*/}, and @samp{//} onto multiple lines with backslash-newline.
For example:
-@example
+@smallexample
@group
/\
*
O 10\
20
@end group
-@end example
+@end smallexample
@noindent
is equivalent to @code{@w{#define FOO 1020}}. All these tricks are
change, except when the @samp{##} preprocessing operator is used to paste
tokens together. @xref{Concatenation}. For example,
-@example
+@smallexample
@group
#define foo() bar
foo()baz
@emph{not}
@expansion{} barbaz
@end group
-@end example
+@end smallexample
The compiler does not re-tokenize the preprocessor's output. Each
preprocessing token becomes one compiler token.
unlike trigraphs, but does not cover as much ground. The digraphs and
their corresponding normal punctuators are:
-@example
+@smallexample
Digraph: <% %> <: :> %: %:%:
Punctuator: @{ @} [ ] # ##
-@end example
+@end smallexample
@cindex other tokens
Any other single character is considered ``other.'' It is passed on to
text, NUL is considered white space. For example, these two directives
have the same meaning.
-@example
+@smallexample
#define X^@@1
#define X 1
-@end example
+@end smallexample
@noindent
(where @samp{^@@} is ASCII NUL)@. Within string or character constants,
@samp{#include} directive. For example, if you have a header file
@file{header.h} as follows,
-@example
+@smallexample
char *test (void);
-@end example
+@end smallexample
@noindent
and a main program called @file{program.c} that uses the header file,
like this,
-@example
+@smallexample
int x;
#include "header.h"
@{
puts (test ());
@}
-@end example
+@end smallexample
@noindent
the compiler will see the same token stream as it would if
@file{program.c} read
-@example
+@smallexample
int x;
char *test (void);
@{
puts (test ());
@}
-@end example
+@end smallexample
Included files are not limited to declarations and macro definitions;
those are merely the typical uses. Any fragment of a C program can be
system, if you do not instruct it otherwise, it will look for headers
requested with @code{@w{#include <@var{file}>}} in:
-@example
+@smallexample
/usr/local/include
@var{libdir}/gcc/@var{target}/@var{version}/include
/usr/@var{target}/include
/usr/include
-@end example
+@end smallexample
For C++ programs, it will also look in @file{/usr/include/g++-v3},
first. In the above, @var{target} is the canonical name of the system
The standard way to prevent this is to enclose the entire real contents
of the file in a conditional, like this:
-@example
+@smallexample
@group
/* File foo. */
#ifndef FILE_FOO_SEEN
#endif /* !FILE_FOO_SEEN */
@end group
-@end example
+@end smallexample
This construct is commonly known as a @dfn{wrapper #ifndef}.
When the header is included again, the conditional will be false,
configuration parameters to be used on different sorts of operating
systems, for instance. You could do this with a series of conditionals,
-@example
+@smallexample
#if SYSTEM_1
# include "system_1.h"
#elif SYSTEM_2
#elif SYSTEM_3
@dots{}
#endif
-@end example
+@end smallexample
That rapidly becomes tedious. Instead, the preprocessor offers the
ability to use a macro for the header name. This is called a
@dfn{computed include}. Instead of writing a header name as the direct
argument of @samp{#include}, you simply put a macro name there instead:
-@example
+@smallexample
#define SYSTEM_H "system_1.h"
@dots{}
#include SYSTEM_H
-@end example
+@end smallexample
@noindent
@code{SYSTEM_H} will be expanded, and the preprocessor will look for
string for embedded quotes, but neither does it process backslash
escapes in the string. Therefore
-@example
+@smallexample
#define HEADER "a\"b"
#include HEADER
-@end example
+@end smallexample
@noindent
looks for a file named @file{a\"b}. CPP searches for the file according
Headers}), it will recurse infinitely and cause a fatal error.
You could include the old header with an absolute pathname:
-@example
+@smallexample
#include "/usr/include/old-header.h"
-@end example
+@end smallexample
@noindent
This works, but is not clean; should the system headers ever move, you
would have to edit the new headers to match.
be an abbreviation for, which is variously referred to as the macro's
@dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example,
-@example
+@smallexample
#define BUFFER_SIZE 1024
-@end example
+@end smallexample
@noindent
defines a macro named @code{BUFFER_SIZE} as an abbreviation for the
token @code{1024}. If somewhere after this @samp{#define} directive
there comes a C statement of the form
-@example
+@smallexample
foo = (char *) malloc (BUFFER_SIZE);
-@end example
+@end smallexample
@noindent
then the C preprocessor will recognize and @dfn{expand} the macro
@code{BUFFER_SIZE}. The C compiler will see the same tokens as it would
if you had written
-@example
+@smallexample
foo = (char *) malloc (1024);
-@end example
+@end smallexample
By convention, macro names are written in uppercase. Programs are
easier to read when it is possible to tell at a glance which names are
backslash-newline. When the macro is expanded, however, it will all
come out on one line. For example,
-@example
+@smallexample
#define NUMBERS 1, \
2, \
3
int x[] = @{ NUMBERS @};
@expansion{} int x[] = @{ 1, 2, 3 @};
-@end example
+@end smallexample
@noindent
The most common visible consequence of this is surprising line numbers
take effect at the place you write them. Therefore, the following input
to the C preprocessor
-@example
+@smallexample
foo = X;
#define X 4
bar = X;
-@end example
+@end smallexample
@noindent
produces
-@example
+@smallexample
foo = X;
bar = 4;
-@end example
+@end smallexample
When the preprocessor expands a macro name, the macro's expansion
replaces the macro invocation, then the expansion is examined for more
macros to expand. For example,
-@example
+@smallexample
@group
#define TABLESIZE BUFSIZE
#define BUFSIZE 1024
@expansion{} BUFSIZE
@expansion{} 1024
@end group
-@end example
+@end smallexample
@noindent
@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that
will always expand using the definition of @code{BUFSIZE} that is
currently in effect:
-@example
+@smallexample
#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
#undef BUFSIZE
#define BUFSIZE 37
-@end example
+@end smallexample
@noindent
Now @code{TABLESIZE} expands (in two stages) to @code{37}.
you use the same @samp{#define} directive, but you put a pair of
parentheses immediately after the macro name. For example,
-@example
+@smallexample
#define lang_init() c_init()
lang_init()
@expansion{} c_init()
-@end example
+@end smallexample
A function-like macro is only expanded if its name appears with a pair
of parentheses after it. If you write just the name, it is left alone.
This can be useful when you have a function and a macro of the same
name, and you wish to use the function sometimes.
-@example
+@smallexample
extern void foo(void);
#define foo() /* optimized inline version */
@dots{}
foo();
funcptr = foo;
-@end example
+@end smallexample
Here the call to @code{foo()} will use the macro, but the function
pointer will get the address of the real function. If the macro were to
an object-like macro whose expansion happens to begin with a pair of
parentheses.
-@example
+@smallexample
#define lang_init () c_init()
lang_init()
@expansion{} () c_init()()
-@end example
+@end smallexample
The first two pairs of parentheses in this expansion come from the
macro. The third is the pair that was originally after the macro
As an example, here is a macro that computes the minimum of two numeric
values, as it is defined in many C programs, and some uses.
-@example
+@smallexample
#define min(X, Y) ((X) < (Y) ? (X) : (Y))
x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b));
y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2));
z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p));
-@end example
+@end smallexample
@noindent
(In this small example you can already see several of the dangers of
requirement for square brackets or braces to balance, and they do not
prevent a comma from separating arguments. Thus,
-@example
+@smallexample
macro (array[x = y, x + 1])
-@end example
+@end smallexample
@noindent
passes two arguments to @code{macro}: @code{array[x = y} and @code{x +
For example, @code{min (min (a, b), c)} is first expanded to
-@example
+@smallexample
min (((a) < (b) ? (a) : (b)), (c))
-@end example
+@end smallexample
@noindent
and then to
-@example
+@smallexample
@group
((((a) < (b) ? (a) : (b))) < (c)
? (((a) < (b) ? (a) : (b)))
: (c))
@end group
-@end example
+@end smallexample
@noindent
(Line breaks shown here for clarity would not actually be generated.)
there must be exactly one comma at the top level of its argument list.
Here are some silly examples using @code{min}:
-@example
+@smallexample
min(, b) @expansion{} (( ) < (b) ? ( ) : (b))
min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( ))
min(,) @expansion{} (( ) < ( ) ? ( ) : ( ))
min() @error{} macro "min" requires 2 arguments, but only 1 given
min(,,) @error{} macro "min" passed 3 arguments, but takes just 2
-@end example
+@end smallexample
Whitespace is not a preprocessing token, so if a macro @code{foo} takes
one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an
Macro parameters appearing inside string literals are not replaced by
their corresponding actual arguments.
-@example
+@smallexample
#define foo(x) x, "x"
foo(bar) @expansion{} bar, "x"
-@end example
+@end smallexample
@node Stringification
@section Stringification
Here is an example of a macro definition that uses stringification:
-@example
+@smallexample
@group
#define WARN_IF(EXP) \
do @{ if (EXP) \
@expansion{} do @{ if (x == 0)
fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0);
@end group
-@end example
+@end smallexample
@noindent
The argument for @code{EXP} is substituted once, as-is, into the
If you want to stringify the result of expansion of a macro argument,
you have to use two levels of macros.
-@example
+@smallexample
#define xstr(s) str(s)
#define str(s) #s
#define foo 4
@expansion{} xstr (4)
@expansion{} str (4)
@expansion{} "4"
-@end example
+@end smallexample
@code{s} is stringified when it is used in @code{str}, so it is not
macro-expanded first. But @code{s} is an ordinary argument to
needs to be a table of commands, perhaps an array of structures declared
as follows:
-@example
+@smallexample
@group
struct command
@{
@dots{}
@};
@end group
-@end example
+@end smallexample
It would be cleaner not to have to give each command name twice, once in
the string constant and once in the function name. A macro which takes the
constant can be created with stringification, and the function name by
concatenating the argument with @samp{_command}. Here is how it is done:
-@example
+@smallexample
#define COMMAND(NAME) @{ #NAME, NAME ## _command @}
struct command commands[] =
COMMAND (help),
@dots{}
@};
-@end example
+@end smallexample
@node Variadic Macros
@section Variadic Macros
a function can. The syntax for defining the macro is similar to that of
a function. Here is an example:
-@example
+@smallexample
#define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__)
-@end example
+@end smallexample
This kind of macro is called @dfn{variadic}. When the macro is invoked,
all the tokens in its argument list after the last named argument (this
@code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we
have this expansion:
-@example
+@smallexample
eprintf ("%s:%d: ", input_file, lineno)
@expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno)
-@end example
+@end smallexample
The variable argument is completely macro-expanded before it is inserted
into the macro expansion, just like an ordinary argument. You may use
before the @samp{@dots{}}; that name is used for the variable argument.
The @code{eprintf} macro above could be written
-@example
+@smallexample
#define eprintf(args@dots{}) fprintf (stderr, args)
-@end example
+@end smallexample
@noindent
using this extension. You cannot use @code{@w{__VA_ARGS__}} and this
You can have named arguments as well as variable arguments in a variadic
macro. We could define @code{eprintf} like this, instead:
-@example
+@smallexample
#define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__)
-@end example
+@end smallexample
@noindent
This formulation looks more descriptive, but unfortunately it is less
variable argument empty, you will get a syntax error, because
there will be an extra comma after the format string.
-@example
+@smallexample
eprintf("success!\n", );
@expansion{} fprintf(stderr, "success!\n", );
-@end example
+@end smallexample
GNU CPP has a pair of extensions which deal with this problem. First,
you are allowed to leave the variable argument out entirely:
-@example
+@smallexample
eprintf ("success!\n")
@expansion{} fprintf(stderr, "success!\n", );
-@end example
+@end smallexample
@noindent
Second, the @samp{##} token paste operator has a special meaning when
placed between a comma and a variable argument. If you write
-@example
+@smallexample
#define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__)
-@end example
+@end smallexample
@noindent
and the variable argument is left out when the @code{eprintf} macro is
@emph{not} happen if you pass an empty argument, nor does it happen if
the token preceding @samp{##} is anything other than a comma.
-@example
+@smallexample
eprintf ("success!\n")
@expansion{} fprintf(stderr, "success!\n");
-@end example
+@end smallexample
@noindent
The above explanation is ambiguous about the case where the only macro
be a comma, and there must be white space between that comma and
whatever comes immediately before it:
-@example
+@smallexample
#define eprintf(format, args@dots{}) fprintf (stderr, format , ##args)
-@end example
+@end smallexample
@noindent
@xref{Differences from previous versions}, for the gory details.
can state the source line at which the inconsistency was detected. For
example,
-@example
+@smallexample
fprintf (stderr, "Internal error: "
"negative string length "
"%d at %s, line %d.",
length, __FILE__, __LINE__);
-@end example
+@end smallexample
An @samp{#include} directive changes the expansions of @code{__FILE__}
and @code{__LINE__} to correspond to the included file. At the end of
predefined macros directly in the conditional, you will need to write it
like this:
-@example
+@smallexample
/* @r{Test for GCC > 3.2.0} */
#if __GNUC__ > 3 || \
(__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
(__GNUC_MINOR__ == 2 && \
__GNUC_PATCHLEVEL__ > 0))
-@end example
+@end smallexample
@noindent
Another approach is to use the predefined macros to
calculate a single number, then compare that against a threshold:
-@example
+@smallexample
#define GCC_VERSION (__GNUC__ * 10000 \
+ __GNUC_MINOR__ * 100 \
+ __GNUC_PATCHLEVEL__)
@dots{}
/* @r{Test for GCC > 3.2.0} */
#if GCC_VERSION > 30200
-@end example
+@end smallexample
@noindent
Many people find this form easier to understand.
after the macro name. @samp{#undef} has no effect if the name is not a
macro.
-@example
+@smallexample
#define FOO 4
x = FOO; @expansion{} x = 4;
#undef FOO
x = FOO; @expansion{} x = FOO;
-@end example
+@end smallexample
Once a macro has been undefined, that identifier may be @dfn{redefined}
as a macro by a subsequent @samp{#define} directive. The new definition
@noindent
These definitions are effectively the same:
-@example
+@smallexample
#define FOUR (2 + 2)
#define FOUR (2 + 2)
#define FOUR (2 /* two */ + 2)
-@end example
+@end smallexample
@noindent
but these are not:
-@example
+@smallexample
#define FOUR (2 + 2)
#define FOUR ( 2+2 )
#define FOUR (2 * 2)
#define FOUR(score,and,seven,years,ago) (2 + 2)
-@end example
+@end smallexample
If a macro is redefined with a definition that is not effectively the
same as the old one, the preprocessor issues a warning and changes the
a macro call coming partially from the macro body and partially from the
arguments. For example,
-@example
+@smallexample
#define twice(x) (2*(x))
#define call_with_1(x) x(1)
call_with_1 (twice)
@expansion{} twice(1)
@expansion{} (2*(1))
-@end example
+@end smallexample
Macro definitions do not have to have balanced parentheses. By writing
an unbalanced open parenthesis in a macro body, it is possible to create
a macro call that begins inside the macro body but ends outside of it.
For example,
-@example
+@smallexample
#define strange(file) fprintf (file, "%s %d",
@dots{}
strange(stderr) p, 35)
@expansion{} fprintf (stderr, "%s %d", p, 35)
-@end example
+@end smallexample
The ability to piece together a macro call can be useful, but the use of
unbalanced open parentheses in a macro body is just confusing, and
Suppose you define a macro as follows,
-@example
+@smallexample
#define ceil_div(x, y) (x + y - 1) / y
-@end example
+@end smallexample
@noindent
whose purpose is to divide, rounding up. (One use for this operation is
to compute how many @code{int} objects are needed to hold a certain
number of @code{char} objects.) Then suppose it is used as follows:
-@example
+@smallexample
a = ceil_div (b & c, sizeof (int));
@expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int);
-@end example
+@end smallexample
@noindent
This does not do what is intended. The operator-precedence rules of
C make it equivalent to this:
-@example
+@smallexample
a = (b & (c + sizeof (int) - 1)) / sizeof (int);
-@end example
+@end smallexample
@noindent
What we want is this:
-@example
+@smallexample
a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
-@end example
+@end smallexample
@noindent
Defining the macro as
-@example
+@smallexample
#define ceil_div(x, y) ((x) + (y) - 1) / (y)
-@end example
+@end smallexample
@noindent
provides the desired result.
compute the size of the type of @code{ceil_div (1, 2)}, but in fact it
means something very different. Here is what it expands to:
-@example
+@smallexample
sizeof ((1) + (2) - 1) / (2)
-@end example
+@end smallexample
@noindent
This would take the size of an integer and divide it by two. The
Parentheses around the entire macro definition prevent such problems.
Here, then, is the recommended way to define @code{ceil_div}:
-@example
+@smallexample
#define ceil_div(x, y) (((x) + (y) - 1) / (y))
-@end example
+@end smallexample
@node Swallowing the Semicolon
@subsection Swallowing the Semicolon
pointer (the argument @code{p} says where to find it) across whitespace
characters:
-@example
+@smallexample
#define SKIP_SPACES(p, limit) \
@{ char *lim = (limit); \
while (p < lim) @{ \
if (*p++ != ' ') @{ \
p--; break; @}@}@}
-@end example
+@end smallexample
@noindent
Here backslash-newline is used to split the macro definition, which must
This can cause trouble before @code{else} statements, because the
semicolon is actually a null statement. Suppose you write
-@example
+@smallexample
if (*p != 0)
SKIP_SPACES (p, lim);
else @dots{}
-@end example
+@end smallexample
@noindent
The presence of two statements---the compound statement and a null
The definition of the macro @code{SKIP_SPACES} can be altered to solve
this problem, using a @code{do @dots{} while} statement. Here is how:
-@example
+@smallexample
#define SKIP_SPACES(p, limit) \
do @{ char *lim = (limit); \
while (p < lim) @{ \
if (*p++ != ' ') @{ \
p--; break; @}@}@} \
while (0)
-@end example
+@end smallexample
Now @code{SKIP_SPACES (p, lim);} expands into
-@example
+@smallexample
do @{@dots{}@} while (0);
-@end example
+@end smallexample
@noindent
which is one statement. The loop executes exactly once; most compilers
@cindex unsafe macros
Many C programs define a macro @code{min}, for ``minimum'', like this:
-@example
+@smallexample
#define min(X, Y) ((X) < (Y) ? (X) : (Y))
-@end example
+@end smallexample
When you use this macro with an argument containing a side effect,
as shown here,
-@example
+@smallexample
next = min (x + y, foo (z));
-@end example
+@end smallexample
@noindent
it expands as follows:
-@example
+@smallexample
next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
-@end example
+@end smallexample
@noindent
where @code{x + y} has been substituted for @code{X} and @code{foo (z)}
no standard way to do this, but it can be done with GNU extensions as
follows:
-@example
+@smallexample
#define min(X, Y) \
(@{ typeof (X) x_ = (X); \
typeof (Y) y_ = (Y); \
(x_ < y_) ? x_ : y_; @})
-@end example
+@end smallexample
The @samp{(@{ @dots{} @})} notation produces a compound statement that
acts as an expression. Its value is the value of its last statement.
calculate the value of @code{foo (z)}, save it in a variable, and use
that variable in @code{min}:
-@example
+@smallexample
@group
#define min(X, Y) ((X) < (Y) ? (X) : (Y))
@dots{}
next = min (x + y, tem);
@}
@end group
-@end example
+@end smallexample
@noindent
(where we assume that @code{foo} returns type @code{int}).
the self-reference is not considered a macro call. It is passed into
the preprocessor output unchanged. Let's consider an example:
-@example
+@smallexample
#define foo (4 + foo)
-@end example
+@end smallexample
@noindent
where @code{foo} is also a variable in your program.
One common, useful use of self-reference is to create a macro which
expands to itself. If you write
-@example
+@smallexample
#define EPERM EPERM
-@end example
+@end smallexample
@noindent
then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is
self-reference} of @code{x}. @code{x} is not expanded in this case
either. Thus, if we have
-@example
+@smallexample
#define x (4 + y)
#define y (2 * x)
-@end example
+@end smallexample
@noindent
then @code{x} and @code{y} expand as follows:
-@example
+@smallexample
@group
x @expansion{} (4 + y)
@expansion{} (4 + (2 * x))
y @expansion{} (2 * x)
@expansion{} (2 * (4 + y))
@end group
-@end example
+@end smallexample
@noindent
Each macro is expanded when it appears in the definition of the other
another macro that does the stringification or concatenation. For
instance, if you have
-@example
+@smallexample
#define AFTERX(x) X_ ## x
#define XAFTERX(x) AFTERX(x)
#define TABLESIZE 1024
#define BUFSIZE TABLESIZE
-@end example
+@end smallexample
then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and
@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to
This can cause a macro expanded on the second scan to be called with the
wrong number of arguments. Here is an example:
-@example
+@smallexample
#define foo a,b
#define bar(x) lose(x)
#define lose(x) (1 + (x))
-@end example
+@end smallexample
We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which
would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)}
by the same parentheses that ought to be used to prevent misnesting of
arithmetic operations:
-@example
+@smallexample
#define foo (a,b)
@exdent or
#define bar(x) lose((x))
-@end example
+@end smallexample
The extra pair of parentheses prevents the comma in @code{foo}'s
definition from being interpreted as an argument separator.
Here is an example illustrating this:
-@example
+@smallexample
#define ignore_second_arg(a,b,c) a; c
ignore_second_arg (foo (),
ignored (),
syntax error);
-@end example
+@end smallexample
@noindent
The syntax error triggered by the tokens @code{syntax error} results in
The simplest sort of conditional is
-@example
+@smallexample
@group
#ifdef @var{MACRO}
#endif /* @var{MACRO} */
@end group
-@end example
+@end smallexample
@cindex conditional group
This block is called a @dfn{conditional group}. @var{controlled text}
The @samp{#if} directive allows you to test the value of an arithmetic
expression, rather than the mere existence of one macro. Its syntax is
-@example
+@smallexample
@group
#if @var{expression}
#endif /* @var{expression} */
@end group
-@end example
+@end smallexample
@var{expression} is a C expression of integer type, subject to stringent
restrictions. It may contain
@code{defined} is useful when you wish to test more than one macro for
existence at once. For example,
-@example
+@smallexample
#if defined (__vax__) || defined (__ns16000__)
-@end example
+@end smallexample
@noindent
would succeed if either of the names @code{__vax__} or
Conditionals written like this:
-@example
+@smallexample
#if defined BUFSIZE && BUFSIZE >= 1024
-@end example
+@end smallexample
@noindent
can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}},
alternative text to be used if the condition fails. This is what it
looks like:
-@example
+@smallexample
@group
#if @var{expression}
@var{text-if-true}
@var{text-if-false}
#endif /* Not @var{expression} */
@end group
-@end example
+@end smallexample
@noindent
If @var{expression} is nonzero, the @var{text-if-true} is included and
One common case of nested conditionals is used to check for more than two
possible alternatives. For example, you might have
-@example
+@smallexample
#if X == 1
@dots{}
#else /* X != 1 */
@dots{}
#endif /* X != 2 */
#endif /* X != 1 */
-@end example
+@end smallexample
Another conditional directive, @samp{#elif}, allows this to be
abbreviated as follows:
-@example
+@smallexample
#if X == 1
@dots{}
#elif X == 2
#else /* X != 2 and X != 1*/
@dots{}
#endif /* X != 2 and X != 1*/
-@end example
+@end smallexample
@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the
middle of a conditional group and subdivides it; it does not require a
support. For example, if you know that the program will not run
properly on a VAX, you might write
-@example
+@smallexample
@group
#ifdef __vax__
#error "Won't work on VAXen. See comments at get_last_object."
#endif
@end group
-@end example
+@end smallexample
If you have several configuration parameters that must be set up by
the installation in a consistent way, you can use conditionals to detect
an inconsistency and report it with @samp{#error}. For example,
-@example
+@smallexample
#if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO)
#error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP."
#endif
-@end example
+@end smallexample
@findex #warning
The directive @samp{#warning} is like @samp{#error}, but causes the
processed as if it had appeared as the right hand side of a
@samp{#pragma} directive. For example,
-@example
+@smallexample
_Pragma ("GCC dependency \"parse.y\"")
-@end example
+@end smallexample
@noindent
has the same effect as @code{#pragma GCC dependency "parse.y"}. The
same effect could be achieved using macros, for example
-@example
+@smallexample
#define DO_PRAGMA(x) _Pragma (#x)
DO_PRAGMA (GCC dependency "parse.y")
-@end example
+@end smallexample
The standard is unclear on where a @code{_Pragma} operator can appear.
The preprocessor does not accept it within a preprocessing conditional
Optional trailing text can be used to give more information in the
warning message.
-@example
+@smallexample
#pragma GCC dependency "parse.y"
#pragma GCC dependency "/usr/include/time.h" rerun fixincludes
-@end example
+@end smallexample
@item #pragma GCC poison
Sometimes, there is an identifier that you want to remove completely
poison. If any of those identifiers appears anywhere in the source
after the directive, it is a hard error. For example,
-@example
+@smallexample
#pragma GCC poison printf sprintf fprintf
sprintf(some_string, "hello");
-@end example
+@end smallexample
@noindent
will produce an error.
For example,
-@example
+@smallexample
#define strrchr rindex
#pragma GCC poison rindex
strrchr(some_string, 'h');
-@end example
+@end smallexample
@noindent
will not produce an error.
Source file name and line number information is conveyed by lines
of the form
-@example
+@smallexample
# @var{linenum} @var{filename} @var{flags}
-@end example
+@end smallexample
@noindent
These are called @dfn{linemarkers}. They are inserted as needed into
@cindex predicates
An assertion looks like this:
-@example
+@smallexample
#@var{predicate} (@var{answer})
-@end example
+@end smallexample
@noindent
@var{predicate} must be a single identifier. @var{answer} can be any
conditional succeeds if either @code{vax} or @code{ns16000} has been
asserted as an answer for @code{machine}.
-@example
+@smallexample
#if #machine (vax) || #machine (ns16000)
-@end example
+@end smallexample
@noindent
You can test whether @emph{any} answer is asserted for a predicate by
omitting the answer in the conditional:
-@example
+@smallexample
#if #machine
-@end example
+@end smallexample
@findex #assert
Assertions are made with the @samp{#assert} directive. Its sole
argument is the assertion to make, without the leading @samp{#} that
identifies assertions in conditionals.
-@example
+@smallexample
#assert @var{predicate} (@var{answer})
-@end example
+@end smallexample
@noindent
You may make several assertions with the same predicate and different
for that predicate remain true. You can cancel an entire predicate by
leaving out the answer:
-@example
+@smallexample
#unassert @var{predicate}
-@end example
+@end smallexample
@noindent
In either form, if no such assertion has been made, @samp{#unassert} has
-@c Copyright (c) 1999, 2000, 2001, 2002, 2003
+@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004
@c Free Software Foundation, Inc.
@c This is part of the CPP and GCC manuals.
@c For copying conditions, see the file gcc.texi.
This is typical output:
-@example
+@smallexample
test.o: test.c test.h
test.h:
-@end example
+@end smallexample
@item -MT @var{target}
@opindex MT
For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
-@example
+@smallexample
$(objpfx)foo.o: foo.c
-@end example
+@end smallexample
@item -MQ @var{target}
@opindex MQ
Same as @option{-MT}, but it quotes any characters which are special to
Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives
-@example
+@smallexample
$$(objpfx)foo.o: foo.c
-@end example
+@end smallexample
The default target is automatically quoted, as if it were given with
@option{-MQ}.
finding out what is predefined in your version of the preprocessor.
Assuming you have no file @file{foo.h}, the command
-@example
+@smallexample
touch foo.h; cpp -dM foo.h
-@end example
+@end smallexample
@noindent
will show all the predefined macros.
by braces; in this construct, parentheses go around the braces. For
example:
-@example
+@smallexample
(@{ int y = foo (); int z;
if (y > 0) z = y;
else z = - y;
z; @})
-@end example
+@end smallexample
@noindent
is a valid (though slightly more complex than necessary) expression
``maximum'' function is commonly defined as a macro in standard C as
follows:
-@example
+@smallexample
#define max(a,b) ((a) > (b) ? (a) : (b))
-@end example
+@end smallexample
@noindent
@cindex side effects, macro argument
type of the operands (here let's assume @code{int}), you can define
the macro safely as follows:
-@example
+@smallexample
#define maxint(a,b) \
(@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
-@end example
+@end smallexample
Embedded statements are not allowed in constant expressions, such as
the value of an enumeration constant, the width of a bit-field, or
A local label declaration looks like this:
-@example
+@smallexample
__label__ @var{label};
-@end example
+@end smallexample
@noindent
or
-@example
+@smallexample
__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
-@end example
+@end smallexample
Local label declarations must come at the beginning of the block,
before any ordinary declarations or statements.
function, the label will be multiply defined in that function. A
local label avoids this problem. For example:
-@example
+@smallexample
#define SEARCH(value, array, target) \
do @{ \
__label__ found; \
(value) = -1; \
found:; \
@} while (0)
-@end example
+@end smallexample
This could also be written using a statement-expression:
-@example
+@smallexample
#define SEARCH(array, target) \
(@{ \
__label__ found; \
found: \
value; \
@})
-@end example
+@end smallexample
Local label declarations also make the labels they declare visible to
nested functions, if there are any. @xref{Nested Functions}, for details.
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
+@smallexample
void *ptr;
/* @r{@dots{}} */
ptr = &&foo;
-@end example
+@end smallexample
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
C, where one can do more than simply store label addresses in label
variables.}, @code{goto *@var{exp};}. For example,
-@example
+@smallexample
goto *ptr;
-@end example
+@end smallexample
@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
+@smallexample
static void *array[] = @{ &&foo, &&bar, &&hack @};
-@end example
+@end smallexample
Then you can select a label with indexing, like this:
-@example
+@smallexample
goto *array[i];
-@end example
+@end smallexample
@noindent
Note that this does not check whether the subscript is in bounds---array
An alternate way to write the above example is
-@example
+@smallexample
static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
&&hack - &&foo @};
goto *(&&foo + array[i]);
-@end example
+@end smallexample
@noindent
This is more friendly to code living in shared libraries, as it reduces
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
+@smallexample
@group
foo (double a, double b)
@{
return square (a) + square (b);
@}
@end group
-@end example
+@end smallexample
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
+@smallexample
@group
bar (int *array, int offset, int size)
@{
/* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
@}
@end group
-@end example
+@end smallexample
Nested function definitions are permitted within functions in the places
where variable definitions are allowed; that is, in any block, before
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
+@smallexample
hack (int *array, int size)
@{
void store (int index, int value)
intermediate (store, size);
@}
-@end example
+@end smallexample
Here, the function @code{intermediate} receives the address of
@code{store} as an argument. If @code{intermediate} calls @code{store},
containing function, exiting the nested function which did the
@code{goto} and any intermediate functions as well. Here is an example:
-@example
+@smallexample
@group
bar (int *array, int offset, int size)
@{
return -1;
@}
@end group
-@end example
+@end smallexample
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
+@smallexample
bar (int *array, int offset, int size)
@{
__label__ failure;
@}
/* @r{@dots{}} */
@}
-@end example
+@end smallexample
@node Constructing Calls
@section Constructing Function Calls
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
+@smallexample
typeof (x[0](1))
-@end example
+@end smallexample
@noindent
This assumes that @code{x} is an array of pointers to functions;
Here is an example with a typename as the argument:
-@example
+@smallexample
typeof (int *)
-@end example
+@end smallexample
@noindent
Here the type described is that of pointers to @code{int}.
be used to define a safe ``maximum'' macro that operates on any
arithmetic type and evaluates each of its arguments exactly once:
-@example
+@smallexample
#define max(a,b) \
(@{ typeof (a) _a = (a); \
typeof (b) _b = (b); \
_a > _b ? _a : _b; @})
-@end example
+@end smallexample
@cindex underscores in variables in macros
@cindex @samp{_} in variables in macros
@item
This declares @code{y} with the type of what @code{x} points to.
-@example
+@smallexample
typeof (*x) y;
-@end example
+@end smallexample
@item
This declares @code{y} as an array of such values.
-@example
+@smallexample
typeof (*x) y[4];
-@end example
+@end smallexample
@item
This declares @code{y} as an array of pointers to characters:
-@example
+@smallexample
typeof (typeof (char *)[4]) y;
-@end example
+@end smallexample
@noindent
It is equivalent to the following traditional C declaration:
-@example
+@smallexample
char *y[4];
-@end example
+@end smallexample
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
+@smallexample
#define pointer(T) typeof(T *)
#define array(T, N) typeof(T [N])
-@end example
+@end smallexample
@noindent
Now the declaration can be rewritten this way:
-@example
+@smallexample
array (pointer (char), 4) y;
-@end example
+@end smallexample
@noindent
Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported
a more limited extension which permitted one to write
-@example
+@smallexample
typedef @var{T} = @var{expr};
-@end example
+@end smallexample
@noindent
with the effect of declaring @var{T} to have the type of the expression
3.0 and 3.2 will crash; 3.2.1 and later give an error). Code which
relies on it should be rewritten to use @code{typeof}:
-@example
+@smallexample
typedef typeof(@var{expr}) @var{T};
-@end example
+@end smallexample
@noindent
This will work with all versions of GCC@.
expression in the sequence is an lvalue. These two expressions are
equivalent:
-@example
+@smallexample
(a, b) += 5
a, (b += 5)
-@end example
+@end smallexample
Similarly, the address of the compound expression can be taken. These two
expressions are equivalent:
-@example
+@smallexample
&(a, b)
a, &b
-@end example
+@end smallexample
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
+@smallexample
(a ? b : c) = 5
(a ? b = 5 : (c = 5))
-@end example
+@end smallexample
A cast is a valid lvalue if its operand is an lvalue. This extension
is deprecated. A simple
assignment. Thus, if @code{a} has type @code{char *}, the following two
expressions are equivalent:
-@example
+@smallexample
(int)a = 5
(int)(a = (char *)(int)5)
-@end example
+@end smallexample
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
+@smallexample
(int)a += 5
(int)(a = (char *)(int) ((int)a + 5))
-@end example
+@end smallexample
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
statement would try to store an integer bit-pattern where a floating
point number belongs:
-@example
+@smallexample
*&(int)f = 1;
-@end example
+@end smallexample
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
Therefore, the expression
-@example
+@smallexample
x ? : y
-@end example
+@end smallexample
@noindent
has the value of @code{x} if that is nonzero; otherwise, the value of
This example is perfectly equivalent to
-@example
+@smallexample
x ? x : y
-@end example
+@end smallexample
@cindex side effect in ?:
@cindex ?: side effect
last element of a structure which is really a header for a variable-length
object:
-@example
+@smallexample
struct line @{
int length;
char contents[0];
struct line *thisline = (struct line *)
malloc (sizeof (struct line) + this_length);
thisline->length = this_length;
-@end example
+@end smallexample
In ISO C90, you would have to give @code{contents} a length of 1, which
means either you waste space or complicate the argument to @code{malloc}.
I.e.@: in the following, @code{f1} is constructed as if it were declared
like @code{f2}.
-@example
+@smallexample
struct f1 @{
int x; int y[];
@} f1 = @{ 1, @{ 2, 3, 4 @} @};
struct f2 @{
struct f1 f1; int data[3];
@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
-@end example
+@end smallexample
@noindent
The convenience of this extension is that @code{f1} has the desired
non-empty initialization except when the structure is the top-level
object. For example:
-@example
+@smallexample
struct foo @{ int x; int y[]; @};
struct bar @{ struct foo z; @};
struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
-@end example
+@end smallexample
@node Empty Structures
@section Structures With No Members
GCC permits a C structure to have no members:
-@example
+@smallexample
struct empty @{
@};
-@end example
+@end smallexample
The structure will have size zero. In C++, empty structures are part
of the language. G++ treats empty structures as if they had a single
declaration and deallocated when the brace-level is exited. For
example:
-@example
+@smallexample
FILE *
concat_fopen (char *s1, char *s2, char *mode)
@{
strcat (str, s2);
return fopen (str, mode);
@}
-@end example
+@end smallexample
@cindex scope of a variable length array
@cindex variable-length array scope
You can also use variable-length arrays as arguments to functions:
-@example
+@smallexample
struct entry
tester (int len, char data[len][len])
@{
/* @r{@dots{}} */
@}
-@end example
+@end smallexample
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
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
+@smallexample
struct entry
tester (int len; char data[len][len], int len)
@{
/* @r{@dots{}} */
@}
-@end example
+@end smallexample
@cindex parameter forward declaration
The @samp{int len} before the semicolon is a @dfn{parameter forward
allowed you to give a name to the variable arguments just like any other
argument. Here is an example:
-@example
+@smallexample
#define debug(format, args...) fprintf (stderr, format, args)
-@end example
+@end smallexample
This is in all ways equivalent to the ISO C example above, but arguably
more readable and descriptive.
this invocation is invalid in ISO C, because there is no comma after
the string:
-@example
+@smallexample
debug ("A message")
-@end example
+@end smallexample
GNU CPP permits you to completely omit the variable arguments in this
way. In the above examples, the compiler would complain, though since
pointers outside C99 mode. For example,
this is valid in GNU C though not valid in C89:
-@example
+@smallexample
@group
struct foo @{int a[4];@};
return f().a[index];
@}
@end group
-@end example
+@end smallexample
@node Pointer Arith
@section Arithmetic on @code{void}- and Function-Pointers
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
+@smallexample
foo (float f, float g)
@{
float beat_freqs[2] = @{ f-g, f+g @};
/* @r{@dots{}} */
@}
-@end example
+@end smallexample
@node Compound Literals
@section Compound Literals
Usually, the specified type is a structure. Assume that
@code{struct foo} and @code{structure} are declared as shown:
-@example
+@smallexample
struct foo @{int a; char b[2];@} structure;
-@end example
+@end smallexample
@noindent
Here is an example of constructing a @code{struct foo} with a compound literal:
-@example
+@smallexample
structure = ((struct foo) @{x + y, 'a', 0@});
-@end example
+@end smallexample
@noindent
This is equivalent to writing the following:
-@example
+@smallexample
@{
struct foo temp = @{x + y, 'a', 0@};
structure = temp;
@}
-@end example
+@end smallexample
You can also construct an array. If all the elements of the compound literal
are (made up of) simple constant expressions, suitable for use in
literal can be coerced to a pointer to its first element and used in
such an initializer, as shown here:
-@example
+@smallexample
char **foo = (char *[]) @{ "x", "y", "z" @};
-@end example
+@end smallexample
Compound literals for scalar types and union types are is
also allowed, but then the compound literal is equivalent
If the object being initialized has array type of unknown size, the size is
determined by compound literal size.
-@example
+@smallexample
static struct foo x = (struct foo) @{1, 'a', 'b'@};
static int y[] = (int []) @{1, 2, 3@};
static int z[] = (int [3]) @{1@};
-@end example
+@end smallexample
@noindent
The above lines are equivalent to the following:
-@example
+@smallexample
static struct foo x = @{1, 'a', 'b'@};
static int y[] = @{1, 2, 3@};
static int z[] = @{1, 0, 0@};
-@end example
+@end smallexample
@node Designated Inits
@section Designated Initializers
To specify an array index, write
@samp{[@var{index}] =} before the element value. For example,
-@example
+@smallexample
int a[6] = @{ [4] = 29, [2] = 15 @};
-@end example
+@end smallexample
@noindent
is equivalent to
-@example
+@smallexample
int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
-@end example
+@end smallexample
@noindent
The index values must be constant expressions, even if the array being
@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
extension. For example,
-@example
+@smallexample
int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
-@end example
+@end smallexample
@noindent
If the value in it has side-effects, the side-effects will happen only once,
with @samp{.@var{fieldname} =} before the element value. For example,
given the following structure,
-@example
+@smallexample
struct point @{ int x, y; @};
-@end example
+@end smallexample
@noindent
the following initialization
-@example
+@smallexample
struct point p = @{ .y = yvalue, .x = xvalue @};
-@end example
+@end smallexample
@noindent
is equivalent to
-@example
+@smallexample
struct point p = @{ xvalue, yvalue @};
-@end example
+@end smallexample
Another syntax which has the same meaning, obsolete since GCC 2.5, is
@samp{@var{fieldname}:}, as shown here:
-@example
+@smallexample
struct point p = @{ y: yvalue, x: xvalue @};
-@end example
+@end smallexample
@cindex designators
The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
syntax) when initializing a union, to specify which element of the union
should be used. For example,
-@example
+@smallexample
union foo @{ int i; double d; @};
union foo f = @{ .d = 4 @};
-@end example
+@end smallexample
@noindent
will convert 4 to a @code{double} to store it in the union using
does not have a designator applies to the next consecutive element of the
array or structure. For example,
-@example
+@smallexample
int a[6] = @{ [1] = v1, v2, [4] = v4 @};
-@end example
+@end smallexample
@noindent
is equivalent to
-@example
+@smallexample
int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
-@end example
+@end smallexample
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
+@smallexample
int whitespace[256]
= @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
-@end example
+@end smallexample
@cindex designator lists
You can also write a series of @samp{.@var{fieldname}} and
You can specify a range of consecutive values in a single @code{case} label,
like this:
-@example
+@smallexample
case @var{low} ... @var{high}:
-@end example
+@end smallexample
@noindent
This has the same effect as the proper number of individual @code{case}
This feature is especially useful for ranges of ASCII character codes:
-@example
+@smallexample
case 'A' ... 'Z':
-@end example
+@end smallexample
@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
+@smallexample
case 1 ... 5:
-@end example
+@end smallexample
@noindent
rather than this:
-@example
+@smallexample
case 1...5:
-@end example
+@end smallexample
@node Cast to Union
@section Cast to a Union Type
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
+@smallexample
union foo @{ int i; double d; @};
int x;
double y;
-@end example
+@end smallexample
@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
+@smallexample
union foo u;
/* @r{@dots{}} */
u = (union foo) x @equiv{} u.i = x
u = (union foo) y @equiv{} u.d = y
-@end example
+@end smallexample
You can also use the union cast as a function argument:
-@example
+@smallexample
void hack (union foo);
/* @r{@dots{}} */
hack ((union foo) x);
-@end example
+@end smallexample
@node Mixed Declarations
@section Mixed Declarations and Code
within compound statements. As an extension, GCC also allows this in
C89 mode. For example, you could do:
-@example
+@smallexample
int i;
/* @r{@dots{}} */
i++;
int j = i + 2;
-@end example
+@end smallexample
Each identifier is visible from where it is declared until the end of
the enclosing block.
GNU C extends ISO C to allow a function prototype to override a later
old-style non-prototype definition. Consider the following example:
-@example
+@smallexample
/* @r{Use prototypes unless the compiler is old-fashioned.} */
#ifdef __STDC__
#define P(x) x
@{
return x == 0;
@}
-@end example
+@end smallexample
Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
not allow this example, because subword arguments in old-style
latter type before promotion. Thus in GNU C the above example is
equivalent to the following:
-@example
+@smallexample
int isroot (uid_t);
int
@{
return x == 0;
@}
-@end example
+@end smallexample
@noindent
GNU C++ does not support old-style function definitions, so this
extension (@pxref{Variable Attributes}). For example, after this
declaration:
-@example
+@smallexample
struct foo @{ int x; char y; @} foo1;
-@end example
+@end smallexample
@noindent
the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
Here is a structure in which the field @code{x} is packed, so that it
immediately follows @code{a}:
-@example
+@smallexample
struct foo
@{
char a;
int x[2] __attribute__ ((packed));
@};
-@end example
+@end smallexample
@item section ("@var{section-name}")
@cindex @code{section} variable attribute
arguments to be passed, using the @code{int *} calling convention.
The program can call @code{wait} with arguments of either type:
-@example
+@smallexample
int w1 () @{ int w; return wait (&w); @}
int w2 () @{ union wait w; return wait (&w); @}
-@end example
+@end smallexample
With this interface, @code{wait}'s implementation might look like this:
-@example
+@smallexample
pid_t wait (wait_status_ptr_t p)
@{
return waitpid (-1, p.__ip, 0);
@}
-@end example
+@end smallexample
@item unused
When attached to a type (including a @code{union} or a @code{struct}),
To declare a function inline, use the @code{inline} keyword in its
declaration, like this:
-@example
+@smallexample
inline int
inc (int *a)
@{
(*a)++;
@}
-@end example
+@end smallexample
(If you are writing a header file to be included in ISO C programs, write
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
GCC does not inline any functions when not optimizing unless you specify
the @samp{always_inline} attribute for the function, like this:
-@example
+@smallexample
/* Prototype. */
inline void foo (const char) __attribute__((always_inline));
-@end example
+@end smallexample
@node Extended Asm
@section Assembler Instructions with C Expression Operands
For example, here is how to use the 68881's @code{fsinx} instruction:
-@example
+@smallexample
asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end example
+@end smallexample
@noindent
Here @code{angle} is the C expression for the input operand while
followed by the operand number. Using named operands the above example
could look like:
-@example
+@smallexample
asm ("fsinx %[angle],%[output]"
: [output] "=f" (result)
: [angle] "f" (angle));
-@end example
+@end smallexample
@noindent
Note that the symbolic operand names have no relation whatsoever to
@samp{combine} instruction with @code{bar} as its read-only source
operand and @code{foo} as its read-write destination:
-@example
+@smallexample
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
-@end example
+@end smallexample
@noindent
The constraint @samp{"0"} for operand 1 says that it must occupy the
same place in the generated assembler code. The following would not
work reliably:
-@example
+@smallexample
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
-@end example
+@end smallexample
Various optimizations or reloading could cause operands 0 and 1 to be in
different registers; GCC knows no reason not to do so. For example, the
As of GCC version 3.1, one may write @code{[@var{name}]} instead of
the operand number for a matching constraint. For example:
-@example
+@smallexample
asm ("cmoveq %1,%2,%[result]"
: [result] "=r"(result)
: "r" (test), "r"(new), "[result]"(old));
-@end example
+@end smallexample
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
+@smallexample
asm volatile ("movc3 %0,%1,%2"
: /* no outputs */
: "g" (from), "g" (to), "g" (count)
: "r0", "r1", "r2", "r3", "r4", "r5");
-@end example
+@end smallexample
You may not write a clobber description in a way that overlaps with an
input or output operand. For example, you may not have an operand
is an example of multiple instructions in a template; it assumes the
subroutine @code{_foo} accepts arguments in registers 9 and 10:
-@example
+@smallexample
asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
: /* no outputs */
: "g" (from), "g" (to)
: "r9", "r10");
-@end example
+@end smallexample
Unless an output operand has the @samp{&} constraint modifier, GCC
may allocate it in the same register as an unrelated input operand, on
instruction, you must include a branch and a label in the @code{asm}
construct, as follows:
-@example
+@smallexample
asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
: "g" (result)
: "g" (input));
-@end example
+@end smallexample
@noindent
This assumes your assembler supports local labels, as the GNU assembler
Usually the most convenient way to use these @code{asm} instructions is to
encapsulate them in macros that look like functions. For example,
-@example
+@smallexample
#define sin(x) \
(@{ double __value, __arg = (x); \
asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
__value; @})
-@end example
+@end smallexample
@noindent
Here the variable @code{__arg} is used to make sure that the instruction
significantly, or combined, by writing the keyword @code{volatile} after
the @code{asm}. For example:
-@example
+@smallexample
#define get_and_set_priority(new) \
(@{ int __old; \
asm volatile ("get_and_set_priority %0, %1" \
: "=g" (__old) : "g" (new)); \
__old; @})
-@end example
+@end smallexample
@noindent
If you write an @code{asm} instruction with no outputs, GCC will know
instruction.) In addition, GCC will not reschedule instructions
across a volatile @code{asm} instruction. For example:
-@example
+@smallexample
*(volatile int *)addr = foo;
asm volatile ("eieio" : : );
-@end example
+@end smallexample
@noindent
Assume @code{addr} contains the address of a memory mapped device
It is possible that if an input dies in an insn, reload might
use the input reg for an output reload. Consider this example:
-@example
+@smallexample
asm ("foo" : "=t" (a) : "f" (b));
-@end example
+@end smallexample
This asm says that input B is not popped by the asm, and that
the asm pushes a result onto the reg-stack, i.e., the stack is one
The asm above would be written as
-@example
+@smallexample
asm ("foo" : "=&t" (a) : "f" (b));
-@end example
+@end smallexample
@item
Some operands need to be in particular places on the stack. All
Here are a couple of reasonable asms to want to write. This asm
takes one input, which is internally popped, and produces two outputs.
-@example
+@smallexample
asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
-@end example
+@end smallexample
This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode,
and replaces them with one output. The user must code the @code{st(1)}
clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs.
-@example
+@smallexample
asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
-@end example
+@end smallexample
@include md.texi
function or variable by writing the @code{asm} (or @code{__asm__})
keyword after the declarator as follows:
-@example
+@smallexample
int foo asm ("myfoo") = 2;
-@end example
+@end smallexample
@noindent
This specifies that the name to be used for the variable @code{foo} in
you can get the same effect by writing a declaration for the function
before its definition and putting @code{asm} there, like this:
-@example
+@smallexample
extern func () asm ("FUNC");
func (x, y)
int x, y;
/* @r{@dots{}} */
-@end example
+@end smallexample
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
You can define a global register variable in GNU C like this:
-@example
+@smallexample
register int *foo asm ("a5");
-@end example
+@end smallexample
@noindent
Here @code{a5} is the name of the register which should be used. Choose a
You can define a local register variable with a specified register
like this:
-@example
+@smallexample
register int *foo asm ("a5");
-@end example
+@end smallexample
@noindent
Here @code{a5} is the name of the register which should be used. Note
compile with another compiler, you can define the alternate keywords as
macros to replace them with the customary keywords. It looks like this:
-@example
+@smallexample
#ifndef __GNUC__
#define __asm__ asm
#endif
-@end example
+@end smallexample
@findex __extension__
@opindex pedantic
The first step in using these extensions is to provide the necessary data
types. This should be done using an appropriate @code{typedef}:
-@example
+@smallexample
typedef int v4si __attribute__ ((mode(V4SI)));
-@end example
+@end smallexample
The base type @code{int} is effectively ignored by the compiler, the
actual properties of the new type @code{v4si} are defined by the
added to the corresponding 4 elements in @var{b} and the resulting
vector will be stored in @var{c}.
-@example
+@smallexample
typedef int v4si __attribute__ ((mode(V4SI)));
v4si a, b, c;
c = a + b;
-@end example
+@end smallexample
Subtraction, multiplication, division, and the logical operations
operate in a similar manner. Likewise, the result of using the unary
example, a function to add two vectors and multiply the result by a
third could look like this:
-@example
+@smallexample
v4si f (v4si a, v4si b, v4si c)
@{
v4si tmp = __builtin_addv4si (a, b);
return __builtin_mulv4si (tmp, c);
@}
-@end example
+@end smallexample
@node Other Builtins
@section Other built-in functions provided by GCC
The following built-in functions are always available. They
all generate the machine instruction that is part of the name.
-@example
+@smallexample
long __builtin_alpha_implver (void)
long __builtin_alpha_rpcc (void)
long __builtin_alpha_amask (long)
long __builtin_alpha_umulh (long, long)
long __builtin_alpha_zap (long, long)
long __builtin_alpha_zapnot (long, long)
-@end example
+@end smallexample
The following built-in functions are always with @option{-mmax}
or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
later. They all generate the machine instruction that is part
of the name.
-@example
+@smallexample
long __builtin_alpha_pklb (long)
long __builtin_alpha_pkwb (long)
long __builtin_alpha_unpkbl (long)
long __builtin_alpha_maxuw4 (long, long)
long __builtin_alpha_maxsw4 (long, long)
long __builtin_alpha_perr (long, long)
-@end example
+@end smallexample
The following built-in functions are always with @option{-mcix}
or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
later. They all generate the machine instruction that is part
of the name.
-@example
+@smallexample
long __builtin_alpha_cttz (long)
long __builtin_alpha_ctlz (long)
long __builtin_alpha_ctpop (long)
-@end example
+@end smallexample
The following builtins are available on systems that use the OSF/1
PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
@code{rdval} and @code{wrval}.
-@example
+@smallexample
void *__builtin_thread_pointer (void)
void __builtin_set_thread_pointer (void *)
-@end example
+@end smallexample
@node ARM Built-in Functions
@subsection ARM Built-in Functions
These built-in functions are available for the ARM family of
processors, when the @option{-mcpu=iwmmxt} switch is used:
-@example
+@smallexample
typedef int __v2si __attribute__ ((__mode__ (__V2SI__)))
v2si __builtin_arm_waddw (v2si, v2si)
v2si __builtin_arm_wsubwss (v2si, v2si)
v2si __builtin_arm_wsraw (v2si, v2si)
v2si __builtin_arm_wsrad (v2si, v2si)
-@end example
+@end smallexample
@node X86 Built-in Functions
@subsection X86 Built-in Functions
The following built-in functions are made available by @option{-mmmx}.
All of them generate the machine instruction that is part of the name.
-@example
+@smallexample
v8qi __builtin_ia32_paddb (v8qi, v8qi)
v4hi __builtin_ia32_paddw (v4hi, v4hi)
v2si __builtin_ia32_paddd (v2si, v2si)
v8qi __builtin_ia32_packsswb (v4hi, v4hi)
v4hi __builtin_ia32_packssdw (v2si, v2si)
v8qi __builtin_ia32_packuswb (v4hi, v4hi)
-@end example
+@end smallexample
The following built-in functions are made available either with
@option{-msse}, or with a combination of @option{-m3dnow} and
@option{-march=athlon}. All of them generate the machine
instruction that is part of the name.
-@example
+@smallexample
v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
v8qi __builtin_ia32_pavgb (v8qi, v8qi)
v4hi __builtin_ia32_pavgw (v4hi, v4hi)
void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
void __builtin_ia32_movntq (di *, di)
void __builtin_ia32_sfence (void)
-@end example
+@end smallexample
The following built-in functions are available when @option{-msse} is used.
All of them generate the machine instruction that is part of the name.
-@example
+@smallexample
int __builtin_ia32_comieq (v4sf, v4sf)
int __builtin_ia32_comineq (v4sf, v4sf)
int __builtin_ia32_comilt (v4sf, v4sf)
v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
void __builtin_ia32_movntps (float *, v4sf)
int __builtin_ia32_movmskps (v4sf)
-@end example
+@end smallexample
The following built-in functions are available when @option{-msse} is used.
The following built-in functions are available when @option{-mpni} is used.
All of them generate the machine instruction that is part of the name.
-@example
+@smallexample
v2df __builtin_ia32_addsubpd (v2df, v2df)
v2df __builtin_ia32_addsubps (v2df, v2df)
v2df __builtin_ia32_haddpd (v2df, v2df)
v4sf __builtin_ia32_movshdup (v4sf)
v4sf __builtin_ia32_movsldup (v4sf)
void __builtin_ia32_mwait (unsigned int, unsigned int)
-@end example
+@end smallexample
The following built-in functions are available when @option{-mpni} is used.
The following built-in functions are available when @option{-m3dnow} is used.
All of them generate the machine instruction that is part of the name.
-@example
+@smallexample
void __builtin_ia32_femms (void)
v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
v2si __builtin_ia32_pf2id (v2sf)
v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
v2sf __builtin_ia32_pi2fd (v2si)
v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
-@end example
+@end smallexample
The following built-in functions are available when both @option{-m3dnow}
and @option{-march=athlon} are used. All of them generate the machine
instruction that is part of the name.
-@example
+@smallexample
v2si __builtin_ia32_pf2iw (v2sf)
v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
v2sf __builtin_ia32_pi2fw (v2si)
v2sf __builtin_ia32_pswapdsf (v2sf)
v2si __builtin_ia32_pswapdsi (v2si)
-@end example
+@end smallexample
@node PowerPC AltiVec Built-in Functions
@subsection PowerPC AltiVec Built-in Functions
a structure or union that contains, as fields, structures and unions
without names. For example:
-@example
+@smallexample
struct @{
int a;
union @{
@};
int d;
@} foo;
-@end example
+@end smallexample
In this example, the user would be able to access members of the unnamed
union with code like @samp{foo.b}. Note that only unnamed structs and
You must never create such structures that cause ambiguous field definitions.
For example, this structure:
-@example
+@smallexample
struct @{
int a;
struct @{
int a;
@};
@} foo;
-@end example
+@end smallexample
It is ambiguous which @code{a} is being referred to with @samp{foo.a}.
Such constructs are not supported and must be avoided. In the future,
At the user level, the extension is visible with a new storage
class keyword: @code{__thread}. For example:
-@example
+@smallexample
__thread int i;
extern __thread struct state s;
static __thread char *p;
-@end example
+@end smallexample
The @code{__thread} specifier may be used alone, with the @code{extern}
or @code{static} specifiers, but with no other storage class specifier.
use a macro to return the minimum of two things in C++, as in the
following example.
-@example
+@smallexample
#define MIN(X,Y) ((X) < (Y) ? : (X) : (Y))
-@end example
+@end smallexample
@noindent
You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to
In most expressions, it is intuitively obvious what is a read and what is
a write. For instance
-@example
+@smallexample
volatile int *dst = @var{somevalue};
volatile int *src = @var{someothervalue};
*dst = *src;
-@end example
+@end smallexample
@noindent
will cause a read of the volatile object pointed to by @var{src} and stores the
Less obvious expressions are where something which looks like an access
is used in a void context. An example would be,
-@example
+@smallexample
volatile int *src = @var{somevalue};
*src;
-@end example
+@end smallexample
With C, such expressions are rvalues, and as rvalues cause a read of
the object, GCC interprets this as a read of the volatile being pointed
of the object. When the object has incomplete type, G++ issues a
warning.
-@example
+@smallexample
struct S;
struct T @{int m;@};
volatile S *ptr1 = @var{somevalue};
volatile T *ptr2 = @var{somevalue};
*ptr1;
*ptr2;
-@end example
+@end smallexample
In this example, a warning is issued for @code{*ptr1}, and @code{*ptr2}
causes a read of the object pointed to. If you wish to force an error on
references, which indicate that the reference is not aliased in the local
context.
-@example
+@smallexample
void fn (int *__restrict__ rptr, int &__restrict__ rref)
@{
/* @r{@dots{}} */
@}
-@end example
+@end smallexample
@noindent
In the body of @code{fn}, @var{rptr} points to an unaliased integer and
You may also specify whether a member function's @var{this} pointer is
unaliased by using @code{__restrict__} as a member function qualifier.
-@example
+@smallexample
void T::fn () __restrict__
@{
/* @r{@dots{}} */
@}
-@end example
+@end smallexample
@noindent
Within the body of @code{T::fn}, @var{this} will have the effective
instantiations you need into one big file; or you can create small files
like
-@example
+@smallexample
#include "Foo.h"
#include "Foo.cc"
template class Foo<int>;
template ostream& operator <<
(ostream&, const Foo<int>&);
-@end example
+@end smallexample
for each of the instances you need, and create a template instantiation
library from those.
members of a template class, without the support data or member
functions (with (@code{static}):
-@example
+@smallexample
extern template int max (int, int);
inline template class Foo<int>;
static template class Foo<int>;
-@end example
+@end smallexample
@item
Do nothing. Pretend g++ does implement automatic instantiation
The syntax for this extension is
-@example
+@smallexample
extern A a;
extern int (A::*fp)();
typedef int (*fptr)(A *);
fptr p = (fptr)(a.*fp);
-@end example
+@end smallexample
For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
no object is needed to obtain the address of the function. They can be
converted to function pointers directly:
-@example
+@smallexample
fptr p1 = (fptr)(&A::foo);
-@end example
+@end smallexample
@opindex Wno-pmf-conversions
You must specify @option{-Wno-pmf-conversions} to use this extension.
To configure GCC:
-@example
+@smallexample
% mkdir @var{objdir}
% cd @var{objdir}
% @var{srcdir}/configure [@var{options}] [@var{target}]
-@end example
+@end smallexample
@heading Target specification
their runtime libraries should be built. For a list of valid values for
@var{langN} you can issue the following command in the
@file{gcc} directory of your GCC source tree:@*
-@example
+@smallexample
grep language= */config-lang.in
-@end example
+@end smallexample
Currently, you can use any of the following:
@code{ada}, @code{c}, @code{c++}, @code{f77}, @code{java}, @code{objc}.
Building the Ada compiler has special requirements, see below.@*
roughly 40% of disk space both for the bootstrap and the final installation.
(Libraries will still contain debugging information.)
-@example
+@smallexample
make CFLAGS='-O' LIBCFLAGS='-g -O2' \
LIBCXXFLAGS='-g -O2 -fno-implicit-templates' bootstrap
-@end example
+@end smallexample
If you wish to use non-default GCC flags when compiling the stage2 and
stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
For example, you can build a native Ada compiler by issuing the
following commands (assuming @command{make} is GNU make):
-@example
+@smallexample
cd @var{objdir}
@var{srcdir}/configure --enable-languages=c,ada
cd @var{objdir}
cd gcc
make gnatlib_and_tools
cd ..
-@end example
+@end smallexample
Currently, when compiling the Ada front end, you cannot use the parallel
build feature described in the previous section.
environment variables appropriately, as in the following example (which
assumes that DejaGnu has been installed under @file{/usr/local}):
-@example
+@smallexample
TCL_LIBRARY = /usr/local/share/tcl8.0
DEJAGNULIBS = /usr/local/share/dejagnu
-@end example
+@end smallexample
(On systems such as Cygwin, these paths are required to be actual
paths, not mounts or links; presumably this is due to some lack of
Finally, you can run the testsuite (which may take a long time):
-@example
+@smallexample
cd @var{objdir}; make -k check
-@end example
+@end smallexample
This will test various components of GCC, such as compiler
front ends and runtime libraries. While running the testsuite, DejaGnu
A more selective way to just run all @command{gcc} execute tests in the
testsuite is to use
-@example
+@smallexample
make check-gcc RUNTESTFLAGS="execute.exp @var{other-options}"
-@end example
+@end smallexample
Likewise, in order to run only the @command{g++} ``old-deja'' tests in
the testsuite with filenames matching @samp{9805*}, you would use
-@example
+@smallexample
make check-g++ RUNTESTFLAGS="old-deja.exp=9805* @var{other-options}"
-@end example
+@end smallexample
The @file{*.exp} files are located in the testsuite directories of the GCC
source, the most important ones being @file{compile.exp},
@samp{RUNTESTFLAGS}, or directly to @command{runtest} if you prefer to
work outside the makefiles. For example,
-@example
+@smallexample
make check-g++ RUNTESTFLAGS="--target_board=unix/-O3/-fno-strength-reduce"
-@end example
+@end smallexample
will run the standard @command{g++} testsuites (``unix'' is the target name
for a standard native testsuite situation), passing
You can run the testsuites multiple times using combinations of options
with a syntax similar to the brace expansion of popular shells:
-@example
+@smallexample
@dots{}"--target_board=arm-sim@{-mhard-float,-msoft-float@}@{-O1,-O2,-O3,@}"
-@end example
+@end smallexample
(Note the empty option caused by the trailing comma in the final group.)
The following will run each testsuite eight times using the @samp{arm-sim}
target, as if you had specified all possible combinations yourself:
-@example
+@smallexample
--target_board=arm-sim/-mhard-float/-O1
--target_board=arm-sim/-mhard-float/-O2
--target_board=arm-sim/-mhard-float/-O3
--target_board=arm-sim/-msoft-float/-O2
--target_board=arm-sim/-msoft-float/-O3
--target_board=arm-sim/-msoft-float
-@end example
+@end smallexample
They can be combined as many times as you wish, in arbitrary ways. This
list:
-@example
+@smallexample
@dots{}"--target_board=unix/-Wextra@{-O3,-fno-strength-reduce@}@{-fomit-frame-pointer,@}"
-@end example
+@end smallexample
will generate four combinations, all involving @samp{-Wextra}.
do the parallel runs. Instead of using @samp{--target_board}, use a
special makefile target:
-@example
+@smallexample
make -j@var{N} check-@var{testsuite}//@var{test-target}/@var{option1}/@var{option2}/@dots{}
-@end example
+@end smallexample
For example,
-@example
+@smallexample
make -j3 check-gcc//sh-hms-sim/@{-m1,-m2,-m3,-m3e,-m4@}/@{,-nofpu@}
-@end example
+@end smallexample
will run three concurrent ``make-gcc'' testsuites, eventually testing all
ten combinations as described above. Note that this is currently only
If you want to report the results to the GCC project, use the
@file{contrib/test_summary} shell script. Start it in the @var{objdir} with
-@example
+@smallexample
@var{srcdir}/contrib/test_summary -p your_commentary.txt \
-m gcc-testresults@@gcc.gnu.org |sh
-@end example
+@end smallexample
This script uses the @command{Mail} program to send the results, so
make sure it is in your @env{PATH}. The file @file{your_commentary.txt} is
@end ifnothtml
Now that GCC has been built (and optionally tested), you can install it with
-@example
+@smallexample
cd @var{objdir}; make install
-@end example
+@end smallexample
We strongly recommend to install into a target directory where there is
no previous version of GCC present.
Installation into a temporary staging area or into a @command{chroot}
jail can be achieved with the command
-@example
+@smallexample
make DESTDIR=@var{path-to-rootdir} install
-@end example
+@end smallexample
@noindent where @var{path-to-rootdir} is the absolute path of
a directory relative to which all installation paths will be
@option{-oldas} option. To bootstrap GCC, you either need to use the
Compaq C Compiler:
-@example
+@smallexample
% CC=cc @var{srcdir}/configure [@var{options}] [@var{target}]
-@end example
+@end smallexample
or you can use a copy of GCC 2.95.3 or higher built on Tru64 UNIX V4.0:
-@example
+@smallexample
% CC=gcc -Wa,-oldas @var{srcdir}/configure [@var{options}] [@var{target}]
-@end example
+@end smallexample
As of GNU binutils 2.11.2, neither GNU @command{as} nor GNU @command{ld}
are supported on Tru64 UNIX, so you must not configure GCC with
simplest way to do so is by providing @option{--with-as} and
@option{--with-ld} to @file{configure}, e.g.@:
-@example
+@smallexample
configure --with-as=/opt/ctl/bin/cam --with-ld=/opt/ctl/bin/cld \
--enable-languages=c
-@end example
+@end smallexample
The comparison test during @samp{make bootstrap} fails on Unicos/Mk
because the assembler inserts timestamps into object files. You should
We @emph{strongly} recommend using binutils 2.13 or newer.
The following error:
-@example
+@smallexample
Error: register required
-@end example
+@end smallexample
indicates that you should upgrade to a newer version of the binutils.
building a cross compiler. The easiest way to do this is with a configure
command like this:
-@example
+@smallexample
CC=/udk/usr/ccs/bin/cc @var{/your/path/to}/gcc/configure \
--host=i686-pc-udk --target=i686-pc-udk --program-prefix=udk-
-@end example
+@end smallexample
@emph{You should substitute @samp{i686} in the above command with the appropriate
processor for your host.}
Extract the shared object from each the GCC 3.1 @file{libstdc++.a}
archive:
-@example
+@smallexample
% ar -x libstdc++.a libstdc++.so.4
-@end example
+@end smallexample
Enable the @samp{F_LOADONLY} flag so that the shared object will be
available for runtime dynamic loading, but not linking:
-@example
+@smallexample
% strip -e libstdc++.so.4
-@end example
+@end smallexample
Archive the runtime-only shared object in the GCC 3.2
@file{libstdc++.a} archive:
-@example
+@smallexample
% ar -q libstdc++.a libstdc++.so.4
-@end example
+@end smallexample
Linking executables and shared libraries may produce warnings of
duplicate symbols. The assembly files generated by GCC for AIX always
GNU shell) to run @command{fixproto}. This bug will cause the fixproto
program to report an error of the form:
-@example
+@smallexample
./fixproto: sh internal 1K buffer overflow
-@end example
+@end smallexample
To fix this, you can also change the first line of the fixproto script
to look like:
-@example
+@smallexample
#!/bin/ksh
-@end example
+@end smallexample
@html
<hr />
file with @command{cc} and then run @command{file} on the
resulting object file. The output should look like:
-@example
+@smallexample
test.o: ELF N32 MSB @dots{}
-@end example
+@end smallexample
If you see:
-@example
+@smallexample
test.o: ELF 32-bit MSB @dots{}
-@end example
+@end smallexample
or
-@example
+@smallexample
test.o: ELF 64-bit MSB @dots{}
-@end example
+@end smallexample
then your version of @command{cc} uses the O32 or N64 ABI by default. You
should set the environment variable @env{CC} to @samp{cc -n32}
as the bootstrap compiler may result in mips4 code, which won't run at
all on mips3-only systems. For the test program above, you should see:
-@example
+@smallexample
test.o: ELF N32 MSB mips-3 @dots{}
-@end example
+@end smallexample
If you get:
-@example
+@smallexample
test.o: ELF N32 MSB mips-4 @dots{}
-@end example
+@end smallexample
instead, you should set the environment variable @env{CC} to @samp{cc
-n32 -mips3} or @samp{gcc -mips3} respectively before configuring GCC@.
The following compiler flags must be specified in the configure
step in order to bootstrap this target with the Sun compiler:
-@example
+@smallexample
% CC="cc -xildoff -xarch=v9" @var{srcdir}/configure [@var{options}] [@var{target}]
-@end example
+@end smallexample
@option{-xildoff} turns off the incremental linker, and @option{-xarch=v9}
specifies the SPARC-V9 architecture to the Sun linker and assembler.
On System V, if you get an error like this,
-@example
+@smallexample
/usr/local/lib/bison.simple: In function `yyparse':
/usr/local/lib/bison.simple:625: virtual memory exhausted
-@end example
+@end smallexample
@noindent
that too indicates a problem with disk space, ulimit, or @code{MAXUMEM}.
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001 Free Software Foundation, Inc.
+@c 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
taken, even if just to compute it and ignore it, then the variable cannot
go in a register:
-@example
+@smallexample
@{
int careful;
&careful;
@dots{}
@}
-@end example
+@end smallexample
(rather than letting the compiler choose a default based on the file
name suffix). This option applies to all following input files until
the next @option{-x} option. Possible values for @var{language} are:
-@example
+@smallexample
c c-header cpp-output
c++ c++-header c++-cpp-output
objective-c objective-c-header objc-cpp-output
f77 f77-cpp-input ratfor
java
treelang
-@end example
+@end smallexample
@item -x none
Turn off any specification of a language, so that subsequent files are
regardless of what language your program is in. For example, you
might compile a file @code{firstClass.C} like this:
-@example
+@smallexample
g++ -g -frepo -O -c firstClass.C
-@end example
+@end smallexample
@noindent
In this example, only @option{-frepo} is an option meant
options regardless of what language your program is in. For example,
you might compile a file @code{some_class.m} like this:
-@example
+@smallexample
gcc -g -fgnu-runtime -O -c some_class.m
-@end example
+@end smallexample
@noindent
In this example, @option{-fgnu-runtime} is an option meant only for
This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
but you do want to link with @file{libgcc.a}. You can do
-@example
+@smallexample
gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
-@end example
+@end smallexample
@item -print-search-dirs
@opindex print-search-dirs
type.
Pay special attention to code like this:
-@example
+@smallexample
union a_union @{
int i;
double d;
t.d = 3.0;
return t.i;
@}
-@end example
+@end smallexample
The practice of reading from a different union member than the one most
recently written to (called ``type-punning'') is common. Even with
@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
is accessed through the union type. So, the code above will work as
expected. However, this code might not:
-@example
+@smallexample
int f() @{
a_union t;
int* ip;
ip = &t.i;
return *ip;
@}
-@end example
+@end smallexample
Every language that wishes to perform language-specific alias analysis
should define a function that computes, given an @code{tree}
function, so the call site information may not be available to the
profiling functions otherwise.)
-@example
+@smallexample
void __cyg_profile_func_enter (void *this_fn,
void *call_site);
void __cyg_profile_func_exit (void *this_fn,
void *call_site);
-@end example
+@end smallexample
The first argument is the address of the start of the current function,
which may be looked up exactly in the symbol table.
the existing @samp{.X} file because it is newer than the source file.
For example:
-@example
+@smallexample
gcc -Dfoo=bar file1.c -aux-info file1.X
protoize *.c
-@end example
+@end smallexample
@noindent
You need to include the special files along with the rest in the
-@c Copyright (C) 2003 Free Software Foundation, Inc.
+@c Copyright (C) 2003, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@c Contributed by Aldy Hernandez <aldy@quesejoda.com>
document me!
-@example
+@smallexample
_Unwind_DeleteException
_Unwind_Find_FDE
_Unwind_ForcedUnwind
__register_frame_info_table
__register_frame_info_table_bases
__register_frame_table
-@end example
+@end smallexample
@node Miscellaneous routines
@section Miscellaneous runtime library routines
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
-@c 2002, 2003 Free Software Foundation, Inc.
+@c 2002, 2003, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
Here is an actual example of an instruction pattern, for the 68000/68020.
-@example
+@smallexample
(define_insn "tstsi"
[(set (cc0)
(match_operand:SI 0 "general_operand" "rm"))]
return \"tstl %0\";
return \"cmpl #0,%0\";
@}")
-@end example
+@end smallexample
@noindent
This can also be written using braced strings:
-@example
+@smallexample
(define_insn "tstsi"
[(set (cc0)
(match_operand:SI 0 "general_operand" "rm"))]
return "tstl %0";
return "cmpl #0,%0";
@})
-@end example
+@end smallexample
This is an instruction that sets the condition codes based on the value of
a general operand. It has no condition, so any insn whose RTL description
conditional branch names @samp{b@var{cond}}. The recognition template
must always have the form
-@example
+@smallexample
(set (pc)
(if_then_else (@var{cond} (cc0) (const_int 0))
(label_ref (match_operand 0 "" ""))
(pc)))
-@end example
+@end smallexample
@noindent
In addition, every machine description must have an anonymous pattern
for each of the possible reverse-conditional branches. Their templates
look like
-@example
+@smallexample
(set (pc)
(if_then_else (@var{cond} (cc0) (const_int 0))
(pc)
(label_ref (match_operand 0 "" ""))))
-@end example
+@end smallexample
@noindent
They are necessary because jump optimization can turn direct-conditional
reduce the number of patterns that must be specified for branches. For
example,
-@example
+@smallexample
(define_insn ""
[(set (pc)
(if_then_else (match_operator 0 "comparison_operator"
(label_ref (match_operand 1 "" ""))))]
"@var{condition}"
"@dots{}")
-@end example
+@end smallexample
In some cases machines support instructions identical except for the
machine mode of one or more operands. For example, there may be
``sign-extend halfword'' and ``sign-extend byte'' instructions whose
patterns are
-@example
+@smallexample
(set (match_operand:SI 0 @dots{})
(extend:SI (match_operand:HI 1 @dots{})))
(set (match_operand:SI 0 @dots{})
(extend:SI (match_operand:QI 1 @dots{})))
-@end example
+@end smallexample
@noindent
Constant integers do not specify a machine mode, so an instruction to
operand with the bitwise negation of the other should specify the pattern
for that instruction as
-@example
+@smallexample
(define_insn ""
[(set (match_operand:@var{m} 0 @dots{})
(and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
(match_operand:@var{m} 2 @dots{})))]
"@dots{}"
"@dots{}")
-@end example
+@end smallexample
@noindent
Similarly, a pattern for a ``NAND'' instruction should be written
-@example
+@smallexample
(define_insn ""
[(set (match_operand:@var{m} 0 @dots{})
(ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
(not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
"@dots{}"
"@dots{}")
-@end example
+@end smallexample
In both cases, it is not necessary to include patterns for the many
logically equivalent RTL expressions.
The sum of three items, one of which is a constant, will only appear in
the form
-@example
+@smallexample
(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
-@end example
+@end smallexample
@item
On machines that do not use @code{cc0},
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001 Free Software Foundation, Inc.
+@c 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@code{Stdin}, @code{Stdout} and @code{Stderr} as global variables, like
below:
-@example
+@smallexample
FileStream *Stdin = nil;
FileStream *Stdout = nil;
/* Other methods here */
@@end
-@end example
+@end smallexample
In this example, the initialization of @code{Stdin}, @code{Stdout} and
@code{Stderr} in @code{+initialize} occurs too late. The programmer can
The correct solution of the above problem is to use the @code{+load}
method instead of @code{+initialize}:
-@example
+@smallexample
@@implementation FileStream
/* Other methods here */
@@end
-@end example
+@end smallexample
The @code{+load} is a method that is not overridden by categories. If a
class and a category of it both implement @code{+load}, both methods are
@item Objective-C type
@tab Compiler encoding
@item
-@example
+@smallexample
int a[10];
-@end example
+@end smallexample
@tab @code{[10i]}
@item
-@example
+@smallexample
struct @{
int i;
float f[3];
int b:2;
char c;
@}
-@end example
+@end smallexample
@tab @code{@{?=i[3f]b128i3b131i2c@}}
@end multitable
implement a class whose instances hold a weak pointer reference; the
following class does this:
-@example
+@smallexample
@@interface WeakPointer : Object
@{
@@end
-@end example
+@end smallexample
Weak pointers are supported through a new type character specifier
represented by the @samp{!} character. The
directly by the compiler. You declare a constant string object by
prefixing a C constant string with the character @samp{@@}:
-@example
+@smallexample
id myString = @@"this is a constant string object";
-@end example
+@end smallexample
The constant string objects are by default instances of the
@code{NXConstantString} class which is provided by the GNU Objective-C
The provided class should adhere to a strict structure, the same
as @code{NXConstantString}'s structure:
-@example
+@smallexample
@@interface MyConstantStringClass
@{
@}
@@end
-@end example
+@end smallexample
@code{NXConstantString} inherits from @code{Object}; user class
libraries may choose to inherit the customized constant string class
The keyword @code{@@compatibility_alias} allows you to define a class name
as equivalent to another class name. For example:
-@example
+@smallexample
@@compatibility_alias WOApplication GSWApplication;
-@end example
+@end smallexample
tells the compiler that each time it encounters @code{WOApplication} as
a class name, it should replace it with @code{GSWApplication} (that is,
-@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003
+@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
two arguments: an expression-pointer (RTX) and an operand number
(counting from zero). Thus,
-@example
+@smallexample
XEXP (@var{x}, 2)
-@end example
+@end smallexample
@noindent
accesses operand 2 of expression @var{x}, as an expression.
-@example
+@smallexample
XINT (@var{x}, 2)
-@end example
+@end smallexample
@noindent
accesses the same operand as an integer. @code{XSTR}, used in the same
Some machines support a multiplication that generates a product wider
than the operands. Write the pattern for this as
-@example
+@smallexample
(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
-@end example
+@end smallexample
where @var{m} is wider than the modes of @var{x} and @var{y}, which need
not be the same.
quotient widths are not all the same; you should represent
such instructions using @code{truncate} and @code{sign_extend} as in,
-@example
+@smallexample
(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
-@end example
+@end smallexample
@findex udiv
@cindex unsigned division
Therefore, the byte-sized operand is enclosed in a conversion
operation, as in
-@example
+@smallexample
(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
-@end example
+@end smallexample
The conversion operation is not a mere placeholder, because there
may be more than one way of converting from a given starting mode
side-effects are computed, and second all the actual side-effects are
performed. For example,
-@example
+@smallexample
(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
(set (mem:SI (reg:SI 1)) (reg:SI 1))])
-@end example
+@end smallexample
@noindent
says unambiguously that the values of hard register 1 and the memory
For example, people sometimes attempt to represent a jump-if-zero
instruction this way:
-@example
+@smallexample
(parallel [(set (cc0) (reg:SI 34))
(set (pc) (if_then_else
(eq (cc0) (const_int 0))
(label_ref @dots{})
(pc)))])
-@end example
+@end smallexample
@noindent
But this is incorrect, because it says that the jump condition depends
reference of which this expression serves as the address. Here is an
example of its use:
-@example
+@smallexample
(mem:DF (pre_dec:SI (reg:SI 39)))
-@end example
+@end smallexample
@noindent
This says to decrement pseudo register 39 by the length of a @code{DFmode}
@code{PREV_INSN} pointers must always correspond: if @var{insn} is not
the first insn,
-@example
+@smallexample
NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
-@end example
+@end smallexample
@noindent
is always true and if @var{insn} is not the last insn,
-@example
+@smallexample
PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
-@end example
+@end smallexample
@noindent
is always true.
@cindex @code{call} usage
A @code{call} expression has two operands, as follows:
-@example
+@smallexample
(call (mem:@var{fm} @var{addr}) @var{nbytes})
-@end example
+@end smallexample
@noindent
Here @var{nbytes} is an operand that represents the number of bytes of
the value is returned in a hard register. If this register's number is
@var{r}, then the body of the call insn looks like this:
-@example
+@smallexample
(set (reg:@var{m} @var{r})
(call (mem:@var{fm} @var{addr}) @var{nbytes}))
-@end example
+@end smallexample
@noindent
This RTL expression makes it clear (to the optimizer passes) that the
@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,
-@c 2002, 2003 Free Software Foundation, Inc.
+@c 2002, 2003, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
The @file{config/rs6000/rs6000.h} target file defines:
-@example
+@smallexample
#define EXTRA_SPECS \
@{ "cpp_sysv_default", CPP_SYSV_DEFAULT @},
#define CPP_SYS_DEFAULT ""
-@end example
+@end smallexample
The @file{config/rs6000/sysv.h} target file defines:
@smallexample
For example, here is the definition used for VAX/VMS:
-@example
+@smallexample
#define INCLUDE_DEFAULTS \
@{ \
@{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \
@{ ".", 0, 0, 0@}, \
@{ 0, 0, 0, 0@} \
@}
-@end example
+@end smallexample
@end defmac
Here is the order of prefixes tried for exec files:
bit-fields as are used by another compiler, here is how to investigate
what the other compiler does. Compile and run this program:
-@example
+@smallexample
struct foo1
@{
char x;
sizeof (struct foo2));
exit (0);
@}
-@end example
+@end smallexample
If this prints 2 and 5, then the compiler's behavior is what you would
get from @code{PCC_BITFIELD_TYPE_MATTERS}.
The C++ compiler represents a pointer-to-member-function with a struct
that looks like:
-@example
+@smallexample
struct @{
union @{
void (*fn)();
@};
ptrdiff_t delta;
@};
-@end example
+@end smallexample
@noindent
The C++ compiler must use one bit to indicate whether the function that
@defmac N_REG_CLASSES
The number of distinct register classes, defined as follows:
-@example
+@smallexample
#define N_REG_CLASSES (int) LIM_REG_CLASSES
-@end example
+@end smallexample
@end defmac
@defmac REG_CLASS_NAMES
another, smaller class. On many machines, the following definition is
safe:
-@example
+@smallexample
#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
-@end example
+@end smallexample
Sometimes returning a more restrictive class makes better code. For
example, on the 68000, when @var{x} is an integer constant that is in range
register. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS}
as below:
-@example
+@smallexample
#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \
(GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \
? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0)
-@end example
+@end smallexample
@end defmac
Three other special macros describe which operands fit which constraint
depending on whether or not the frame pointer has been eliminated.
In this case, you might specify:
-@example
+@smallexample
#define ELIMINABLE_REGS \
@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \
@{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \
@{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@}
-@end example
+@end smallexample
Note that the elimination of the argument pointer with the stack pointer is
specified first since that is the preferred elimination.
On some machines, the definition
-@example
+@smallexample
#define PUSH_ROUNDING(BYTES) (BYTES)
-@end example
+@end smallexample
@noindent
will suffice. But on other machines, instructions that appear
to push one byte actually push two bytes in an attempt to maintain
alignment. Then the definition should be
-@example
+@smallexample
#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
-@end example
+@end smallexample
@end defmac
@findex current_function_outgoing_args_size
recognized by this macro. So for most machines, this definition
suffices:
-@example
+@smallexample
#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
-@end example
+@end smallexample
If the machine has register windows, so that the caller and the called
function use different registers for the return value, this macro
after adding @code{delta}. In particular, if @var{p} is the
adjusted pointer, the following adjustment should be made:
-@example
+@smallexample
p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)]
-@end example
+@end smallexample
@noindent
If this function is defined, it will always be used in place of
memory address for an operand of mode @var{mode}. @var{win} will be a
C statement label elsewhere in the code; the macro definition may use
-@example
+@smallexample
GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
-@end example
+@end smallexample
@noindent
to avoid further processing if the address has become legitimate.
responsible for outputting the label definition at the proper place.
Here is how to do this:
-@example
+@smallexample
@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno});
-@end example
+@end smallexample
When you output a pool entry specially, you should end with a
@code{goto} to the label @var{jumpto}. This will prevent the same pool
parts of @file{crtstuff.c} are compiled into that section. The
program is linked by the @command{gcc} driver like this:
-@example
+@smallexample
ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o
-@end example
+@end smallexample
The prologue of a function (@code{__init}) appears in the @code{.init}
section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise
@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same
way here. For example,
-@example
+@smallexample
fprintf (@var{stream}, "\t.word L%d-L%d\n",
@var{value}, @var{rel})
-@end example
+@end smallexample
You must provide this macro on machines where the addresses in a
dispatch table are relative to the table's own address. If defined, GCC
definition is output using @code{(*targetm.asm_out.internal_label)}.
For example,
-@example
+@smallexample
fprintf (@var{stream}, "\t.word L%d\n", @var{value})
-@end example
+@end smallexample
@end defmac
@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
+@c 1999, 2000, 2001, 2003, 2004 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@option{-I/usr/include/mit} to use the MIT versions of the header files,
or fixing the header files by adding this:
-@example
+@smallexample
#ifdef __STDC__
#define NeedFunctionPrototypes 0
#endif
-@end example
+@end smallexample
@item
On various 386 Unix systems derived from System V, including SCO, ISC,
If you have installed GNU malloc as a separate library package, use this
option when you relink GCC:
-@example
+@smallexample
MALLOC=/usr/local/lib/libgmalloc.a
-@end example
+@end smallexample
Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
the object file to @file{gmalloc.o} and use this option when you relink
GCC:
-@example
+@smallexample
MALLOC=gmalloc.o
-@end example
+@end smallexample
@end itemize
@node Incompatibilities
GCC does not substitute macro arguments when they appear inside of
string constants. For example, the following macro in GCC
-@example
+@smallexample
#define foo(a) "a"
-@end example
+@end smallexample
@noindent
will produce output @code{"a"} regardless of what the argument @var{a} is.
@code{volatile}. This is a consequence of automatic register
allocation. Consider this function:
-@example
+@smallexample
jmp_buf j;
foo ()
/* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
return a + fun3 ();
@}
-@end example
+@end smallexample
Here @code{a} may or may not be restored to its first value when the
@code{longjmp} occurs. If @code{a} is allocated in a register, then
arguments do not work with GCC@. For example, a program like this
will not work:
-@example
+@smallexample
@group
foobar (
#define luser
hack)
@end group
-@end example
+@end smallexample
ISO C does not permit such a construct.
In traditional C, you can combine @code{long}, etc., with a typedef name,
as shown here:
-@example
+@smallexample
typedef int foo;
typedef long foo bar;
-@end example
+@end smallexample
In ISO C, this is not allowed: @code{long} and other type modifiers
require an explicit @code{int}.
Traditional C allows the following erroneous pair of declarations to
appear together in a given scope:
-@example
+@smallexample
typedef int foo;
typedef foo foo;
-@end example
+@end smallexample
@item
GCC treats all characters of identifiers as significant. According to
comments contain apostrophes, GCC will probably report an error. For
example, this code would produce an error:
-@example
+@smallexample
#if 0
You can't expect this to work.
#endif
-@end example
+@end smallexample
The best solution to such a problem is to put the text into an actual
C comment delimited by @samp{/*@dots{}*/}.
Users often think it is a bug when GCC reports an error for code
like this:
-@example
+@smallexample
int foo (struct mumble *);
struct mumble @{ @dots{} @};
int foo (struct mumble *x)
@{ @dots{} @}
-@end example
+@end smallexample
This code really is erroneous, because the scope of @code{struct
mumble} in the prototype is limited to the argument list containing it.
When a class has static data members, it is not enough to @emph{declare}
the static member; you must also @emph{define} it. For example:
-@example
+@smallexample
class Foo
@{
@dots{}
void method();
static int bar;
@};
-@end example
+@end smallexample
This declaration only establishes that the class @code{Foo} has an
@code{int} named @code{Foo::bar}, and a member function named
standard, you must supply an initializer in one (and only one) source
file, such as:
-@example
+@smallexample
int Foo::bar = 0;
-@end example
+@end smallexample
Other C++ compilers may not correctly implement the standard behavior.
As a result, when you switch to @command{g++} from one of these compilers,
this section.} Only names that are dependent are looked up at the point
of instantiation. For example, consider
-@example
+@smallexample
void foo(double);
struct A @{
static const int N;
@};
-@end example
+@end smallexample
Here, the names @code{foo} and @code{N} appear in a context that does
not depend on the type of @code{T}. The compiler will thus require that
Two-stage name lookup sometimes leads to situations with behavior
different from non-template codes. The most common is probably this:
-@example
+@smallexample
template <typename T> struct Base @{
int i;
@};
template <typename T> struct Derived : public Base<T> @{
int get_i() @{ return i; @}
@};
-@end example
+@end smallexample
In @code{get_i()}, @code{i} is not used in a dependent context, so the
compiler will look for a name declared at the enclosing namespace scope
Another, similar example involves calling member functions of a base
class:
-@example
+@smallexample
template <typename T> struct Base @{
int f();
@};
template <typename T> struct Derived : Base<T> @{
int g() @{ return f(); @};
@};
-@end example
+@end smallexample
Again, the call to @code{f()} is not dependent on template arguments
(there are no arguments that depend on the type @code{T}, and it is also
the one in the base class is not visible until instantiation time. The
compiler will consequently produce the following error message:
-@example
+@smallexample
x.cc: In member function `int Derived<T>::g()':
x.cc:6: error: there are no arguments to `f' that depend on a template
parameter, so a declaration of `f' must be available
x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but
allowing the use of an undeclared name is deprecated)
-@end example
+@end smallexample
To make the code valid either use @code{this->f()}, or
@code{Base<T>::f()}. Using the @code{-fpermissive} flag will also let
@code{string} objects, and another function @code{charfunc} that
operates on pointers to @code{char}:
-@example
+@smallexample
string strfunc ();
void charfunc (const char *);
@dots{}
charfunc (p);
@}
-@end example
+@end smallexample
@noindent
In this situation, it may seem reasonable to save a pointer to the C
forces it to remain until the end of the scope of the name. For
example:
-@example
+@smallexample
string& tmp = strfunc ();
charfunc (tmp.c_str ());
-@end example
+@end smallexample
@node Copy Assignment
@subsection Implicit Copy-Assignment for Virtual Bases
invoked only once, and called from the most-derived class. However, such
objects behave unspecified when being assigned. For example:
-@example
+@smallexample
struct Base@{
char *name;
Base(char *n) : name(strdup(n))@{@}
@{
d1 = d2;
@}
-@end example
+@end smallexample
The C++ standard specifies that @samp{Base::Base} is only called once
when constructing or copy-constructing a Derived object. It is
For example, a function call like this may very well behave differently
from one compiler to another:
-@example
+@smallexample
void func (int, int);
int i = 2;
func (i++, i++);
-@end example
+@end smallexample
There is no guarantee (in either the C or the C++ standard language
definitions) that the increments will be evaluated in any particular
OSDN Git Service
