-@c Copyright (C) 1988,89,92,93,94,96,98,99,2000,01 Free Software Foundation, Inc.
+@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
also available in C++. @xref{C++ Extensions,,Extensions to the
C++ Language}, for extensions that apply @emph{only} to C++.
-@c FIXME: document clearly which features are in ISO C99, but also
-@c accepted as extensions for -std=gnu89 and possibly for C++.
-@c See PR other/930.
-
-@c FIXME: the documentation for preprocessor extensions here is out of
-@c date. See PR other/928.
+Some features that are in ISO C99 but not C89 or C++ are also, as
+extensions, accepted by GCC in C89 mode and in C++.
@c The only difference between the two versions of this menu is that the
@c version for clear INTERNALS has an extra node, "Constraints" (which
* Subscripting:: Any array can be subscripted, even if not an lvalue.
* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
* Initializers:: Non-constant initializers.
-* Constructors:: Constructor expressions give structures, unions
+* Compound Literals:: Compound literals give structures, unions
or arrays as values.
-* Labeled Elements:: Labeling elements of initializers.
+* Designated Inits:: Labeling elements of initializers.
* Cast to Union:: Casting to union type from any member of the union.
* Case Ranges:: `case 1 ... 9' and such.
+* Mixed Declarations:: Mixing declarations and code.
* Function Attributes:: Declaring that functions have no side effects,
or that they can never return.
* Attribute Syntax:: Formal syntax for attributes.
* Subscripting:: Any array can be subscripted, even if not an lvalue.
* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
* Initializers:: Non-constant initializers.
-* Constructors:: Constructor expressions give structures, unions
+* Compound Literals:: Compound literals give structures, unions
or arrays as values.
-* Labeled Elements:: Labeling elements of initializers.
+* Designated Inits:: Labeling elements of initializers.
* Cast to Union:: Casting to union type from any member of the union.
* Case Ranges:: `case 1 ... 9' and such.
+* Mixed Declarations:: Mixing declarations and code.
* Function Attributes:: Declaring that functions have no side effects,
or that they can never return.
* Attribute Syntax:: Formal syntax for attributes.
there is unclear. (It is possible that they will become fully supported
at some point, or that they will be deprecated, or that the bugs that
are present will continue to exist indefinitely.) Presently, statement
-expressions do not work well as default arguments.
+expressions do not work well as default arguments.
In addition, there are semantic issues with statement-expressions in
C++. If you try to use statement-expressions instead of inline
The labels within the interpreter function can be stored in the
threaded code for super-fast dispatching.
-You may not use this mechanism to jump to code in a different function.
+You may not use this mechanism to jump to code in a different function.
If you do that, totally unpredictable things will happen. The best way to
avoid this is to store the label address only in automatic variables and
never pass it as an argument.
@cindex @code{long long} data types
@cindex double-word arithmetic
@cindex multiprecision arithmetic
+@cindex @code{LL} integer suffix
+@cindex @code{ULL} integer suffix
-GNU C supports data types for integers that are twice as long as
-@code{int}. Simply write @code{long long int} for a signed integer, or
+ISO C99 supports data types for integers that are at least 64 bits wide,
+and as an extension GCC supports them in C89 mode and in C++.
+Simply write @code{long long int} for a signed integer, or
@code{unsigned long long int} for an unsigned integer. To make an
integer constant of type @code{long long int}, add the suffix @code{LL}
to the integer. To make an integer constant of type @code{unsigned long
@node Complex
@section Complex Numbers
@cindex complex numbers
+@cindex @code{_Complex} keyword
+@cindex @code{__complex__} keyword
-GNU C supports complex data types. You can declare both complex integer
-types and complex floating types, using the keyword @code{__complex__}.
+ISO C99 supports complex floating data types, and as an extension GCC
+supports them in C89 mode and in C++, and supports complex integer data
+types which are not part of ISO C99. You can declare complex types
+using the keyword @code{_Complex}. As an extension, the older GNU
+keyword @code{__complex__} is also supported.
-For example, @samp{__complex__ double x;} declares @code{x} as a
+For example, @samp{_Complex double x;} declares @code{x} as a
variable whose real part and imaginary part are both of type
-@code{double}. @samp{__complex__ short int y;} declares @code{y} to
+@code{double}. @samp{_Complex short int y;} declares @code{y} to
have real and imaginary parts of type @code{short int}; this is not
likely to be useful, but it shows that the set of complex types is
complete.
To write a constant with a complex data type, use the suffix @samp{i} or
@samp{j} (either one; they are equivalent). For example, @code{2.5fi}
-has type @code{__complex__ float} and @code{3i} has type
-@code{__complex__ int}. Such a constant always has a pure imaginary
+has type @code{_Complex float} and @code{3i} has type
+@code{_Complex int}. Such a constant always has a pure imaginary
value, but you can form any complex value you like by adding one to a
-real constant.
+real constant. This is a GNU extension; if you have an ISO C99
+conforming C library (such as GNU libc), and want to construct complex
+constants of floating type, you should include @code{<complex.h>} and
+use the macros @code{I} or @code{_Complex_I} instead.
+@cindex @code{__real__} keyword
+@cindex @code{__imag__} keyword
To extract the real part of a complex-valued expression @var{exp}, write
@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
-extract the imaginary part.
+extract the imaginary part. This is a GNU extension; for values of
+floating type, you should use the ISO C99 functions @code{crealf},
+@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
+@code{cimagl}, declared in @code{<complex.h>} and also provided as
+builtin functions by GCC.
+@cindex complex conjugation
The operator @samp{~} performs complex conjugation when used on a value
-with a complex type.
+with a complex type. This is a GNU extension; for values of
+floating type, you should use the ISO C99 functions @code{conjf},
+@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
+provided as builtin functions by GCC.
GNU CC can allocate complex automatic variables in a noncontiguous
fashion; it's even possible for the real part to be in a register while
@section Hex Floats
@cindex hex floats
-GNU CC recognizes floating-point numbers written not only in the usual
+ISO C99 supports floating-point numbers written not only in the usual
decimal notation, such as @code{1.55e1}, but also numbers such as
-@code{0x1.fp3} written in hexadecimal format. In that format the
+@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
+supports this in C89 mode (except in some cases when strictly
+conforming) and in C++. In that format the
@code{0x} hex introducer and the @code{p} or @code{P} exponent field are
mandatory. The exponent is a decimal number that indicates the power of
2 by which the significant part will be multiplied. Thus @code{0x1.f} is
In ISO C89, you would have to give @code{contents} a length of 1, which
means either you waste space or complicate the argument to @code{malloc}.
-In ISO C99, you would use a @dfn{flexible array member}, which is
+In ISO C99, you would use a @dfn{flexible array member}, which is
slightly different in syntax and semantics:
@itemize @bullet
@item
Flexible array members may only appear as the last member of a
-@code{struct} that is otherwise non-empty. GCC currently allows
+@code{struct} that is otherwise non-empty. GCC currently allows
zero-length arrays anywhere. You may encounter problems, however,
defining structures containing only a zero-length array. Such usage
is deprecated, and we recommend using zero-length arrays only in
@section Arrays of Variable Length
@cindex variable-length arrays
@cindex arrays of variable length
+@cindex VLAs
-Variable-length automatic arrays are allowed in GNU C. These arrays are
+Variable-length automatic arrays are allowed in ISO C99, and as an
+extension GCC accepts them in C89 mode and in C++. (However, GCC's
+implementation of variable-length arrays does not yet conform in detail
+to the ISO C99 standard.) These arrays are
declared like any other automatic arrays, but with a length that is not
a constant expression. The storage is allocated at the point of
declaration and deallocated when the brace-level is exited. For
parameter list. They can be separated by commas or semicolons, but the
last one must end with a semicolon, which is followed by the ``real''
parameter declarations. Each forward declaration must match a ``real''
-declaration in parameter name and data type.
+declaration in parameter name and data type. ISO C99 does not support
+parameter forward declarations.
@node Variadic Macros
@section Macros with a Variable Number of Arguments.
@cindex subscripting and function values
Subscripting is allowed on arrays that are not lvalues, even though the
-unary @samp{&} operator is not. For example, this is valid in GNU C though
-not valid in other C dialects:
+unary @samp{&} operator is not. (In ISO C99, both are allowed (though
+the array may not be used after the next sequence point), but this ISO
+C99 feature is not yet fully supported in GCC.) For example,
+this is valid in GNU C though not valid in C89:
@example
@group
@cindex initializers, non-constant
@cindex non-constant initializers
-As in standard C++, the elements of an aggregate initializer for an
+As in standard C++ and ISO C99, the elements of an aggregate initializer for an
automatic variable are not required to be constant expressions in GNU C.
Here is an example of an initializer with run-time varying elements:
@}
@end example
-@node Constructors
-@section Constructor Expressions
+@node Compound Literals
+@section Compound Literals
@cindex constructor expressions
@cindex initializations in expressions
@cindex structures, constructor expression
@cindex expressions, constructor
+@cindex compound literals
+@c The GNU C name for what C99 calls compound literals was "constructor expressions".
-GNU C supports constructor expressions. A constructor looks like
+ISO C99 supports compound literals. A compound literal looks like
a cast containing an initializer. Its value is an object of the
type specified in the cast, containing the elements specified in
-the initializer.
+the initializer. (GCC does not yet implement the full ISO C99 semantics
+for compound literals.) As an extension, GCC supports compound literals
+in C89 mode and in C++.
Usually, the specified type is a structure. Assume that
@code{struct foo} and @code{structure} are declared as shown:
@end example
@noindent
-Here is an example of constructing a @code{struct foo} with a constructor:
+Here is an example of constructing a @code{struct foo} with a compound literal:
@example
structure = ((struct foo) @{x + y, 'a', 0@});
@}
@end example
-You can also construct an array. If all the elements of the constructor
+You can also construct an array. If all the elements of the compound literal
are (made up of) simple constant expressions, suitable for use in
-initializers, then the constructor is an lvalue and can be coerced to a
+initializers, then the compound literal is an lvalue and can be coerced to a
pointer to its first element, as shown here:
@example
char **foo = (char *[]) @{ "x", "y", "z" @};
@end example
-Array constructors whose elements are not simple constants are
-not very useful, because the constructor is not an lvalue. There
-are only two valid ways to use it: to subscript it, or initialize
+Array compound literals whose elements are not simple constants are
+not very useful, because the compound literal is not an lvalue; ISO C99
+specifies that it is, being a temporary object with automatic storage
+duration associated with the enclosing block, but GCC does not yet
+implement this. There are currently only two valid ways to use it with
+GCC: to subscript it, or initialize
an array variable with it. The former is probably slower than a
@code{switch} statement, while the latter does the same thing an
ordinary C initializer would do. Here is an example of
-subscripting an array constructor:
+subscripting an array compound literal:
@example
output = ((int[]) @{ 2, x, 28 @}) [input];
@end example
-Constructor expressions for scalar types and union types are is
-also allowed, but then the constructor expression is equivalent
+Compound literals for scalar types and union types are is
+also allowed, but then the compound literal is equivalent
to a cast.
-@node Labeled Elements
-@section Labeled Elements in Initializers
+@node Designated Inits
+@section Designated Initializers
@cindex initializers with labeled elements
@cindex labeled elements in initializers
@cindex case labels in initializers
+@cindex designated initializers
Standard C89 requires the elements of an initializer to appear in a fixed
order, the same as the order of the elements in the array or structure
struct point p = @{ y: yvalue, x: xvalue @};
@end example
-You can also use an element label (with either the colon syntax or the
-period-equal syntax) when initializing a union, to specify which element
-of the union should be used. For example,
+@cindex designators
+The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
+@dfn{designator}. You can also use a designator (or the obsolete colon
+syntax) when initializing a union, to specify which element of the union
+should be used. For example,
@example
union foo @{ int i; double d; @};
You can combine this technique of naming elements with ordinary C
initialization of successive elements. Each initializer element that
-does not have a label applies to the next consecutive element of the
+does not have a designator applies to the next consecutive element of the
array or structure. For example,
@example
['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
@end example
+@cindex designator lists
You can also write a series of @samp{.@var{fieldname}} and
-@samp{[@var{index}]} element labels before an @samp{=} to specify a
+@samp{[@var{index}]} designators before an @samp{=} to specify a
nested subobject to initialize; the list is taken relative to the
subobject corresponding to the closest surrounding brace pair. For
example, with the @samp{struct point} declaration above:
specified is a union type. You can specify the type either with
@code{union @var{tag}} or with a typedef name. A cast to union is actually
a constructor though, not a cast, and hence does not yield an lvalue like
-normal casts. (@xref{Constructors}.)
+normal casts. (@xref{Compound Literals}.)
The types that may be cast to the union type are those of the members
of the union. Thus, given the following union and variables:
hack ((union foo) x);
@end example
+@node Mixed Declarations
+@section Mixed Declarations and Code
+@cindex mixed declarations and code
+@cindex declarations, mixed with code
+@cindex code, mixed with declarations
+
+ISO C99 and ISO C++ allow declarations and code to be freely mixed
+within compound statements. As an extension, GCC also allows this in
+C89 mode. For example, you could do:
+
+@example
+int i;
+@dots{}
+i++;
+int j = i + 2;
+@end example
+
+Each identifier is visible from where it is declared until the end of
+the enclosing block.
+
@node Function Attributes
@section Declaring Attributes of Functions
@cindex function attributes
addresses can be loaded with the @code{ld24} instruction), and are
callable with the @code{bl} instruction.
-Medium model objects may live anywhere in the 32 bit address space (the
+Medium model objects may live anywhere in the 32-bit address space (the
compiler will generate @code{seth/add3} instructions to load their addresses),
and are callable with the @code{bl} instruction.
-Large model objects may live anywhere in the 32 bit address space (the
+Large model objects may live anywhere in the 32-bit address space (the
compiler will generate @code{seth/add3} instructions to load their addresses),
and may not be reachable with the @code{bl} instruction (the compiler will
generate the much slower @code{seth/add3/jl} instruction sequence).
to that declaration (which may be nested in another declaration, for
example in the case of a parameter declaration). In future, attribute
specifiers in some places may however apply to a particular declarator
-within a declaration instead; these cases are noted below.
+within a declaration instead; these cases are noted below. Where an
+attribute specifier is applied to a parameter declared as a function or
+an array, it should apply to the function or array rather than the
+pointer to which the parameter is implicitly converted, but this is not
+yet correctly implemented.
Any list of specifiers and qualifiers at the start of a declaration may
contain attribute specifiers, whether or not such a list may in that
@item shared
@cindex @code{shared} variable attribute
-On Windows NT, in addition to putting variable definitions in a named
-section, the section can also be shared among all running copies of an
-executable or DLL. For example, this small program defines shared data
-by putting it in a named section "shared" and marking the section
+On Windows NT, in addition to putting variable definitions in a named
+section, the section can also be shared among all running copies of an
+executable or DLL. For example, this small program defines shared data
+by putting it in a named section "shared" and marking the section
shareable:
@smallexample
@noindent
You may only use the @code{shared} attribute along with @code{section}
-attribute with a fully initialized global definition because of the way
+attribute with a fully initialized global definition because of the way
linkers work. See @code{section} attribute for more information.
The @code{shared} attribute is only available on Windows NT.
Small model objects live in the lower 16MB of memory (so that their
addresses can be loaded with the @code{ld24} instruction).
-Medium and large model objects may live anywhere in the 32 bit address space
+Medium and large model objects may live anywhere in the 32-bit address space
(the compiler will generate @code{seth/add3} instructions to load their
addresses).
optimization and it really ``works'' only in optimizing compilation. If
you don't use @samp{-O}, no function is really inline.
+Inline functions are included in the ISO C99 standard, but there are
+currently substantial differences between what GCC implements and what
+the ISO C99 standard requires.
+
To declare a function inline, use the @code{inline} keyword in its
declaration, like this:
(If you are writing a header file to be included in ISO C programs, write
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
You can also make all ``simple enough'' functions inline with the option
-@samp{-finline-functions}.
+@samp{-finline-functions}.
Note that certain usages in a function definition can make it unsuitable
for inline substitution. Among these usages are: use of varargs, use of
to be inlined. If any uses of the function remain, they will refer to
the single copy in the library.
+For future compatibility with when GCC implements ISO C99 semantics for
+inline functions, it is best to use @code{static inline} only. (The
+existing semantics will remain available when @option{-std=gnu89} is
+specified, but eventually the default will be @option{-std=gnu99} and
+that will implement the C99 semantics, though it does not do so yet.)
+
GNU C does not inline any functions when not optimizing. It is not
clear whether it is better to inline or not, in this case, but we found
that a correct implementation when not optimizing was difficult. So we
@noindent
If you write an @code{asm} instruction with no outputs, GNU CC will know
the instruction has side-effects and will not delete the instruction or
-move it outside of loops. If the side-effects of your instruction are
-not purely external, but will affect variables in your program in ways
-other than reading the inputs and clobbering the specified registers or
-memory, you should write the @code{volatile} keyword to prevent future
-versions of GNU CC from moving the instruction around within a core
-region.
-
-An @code{asm} instruction without any operands or clobbers (and ``old
-style'' @code{asm}) will not be deleted or moved significantly,
-regardless, unless it is unreachable, the same way as if you had
-written a @code{volatile} keyword.
+move it outside of loops.
+
+The @code{volatile} keyword indicates that the instruction has
+important side-effects. GCC will not delete a volatile @code{asm} if
+it is reachable. (The instruction can still be deleted if GCC can
+prove that control-flow will never reach the location of the
+instruction.) In addition, GCC will not reschedule instructions
+across a volatile @code{asm} instruction. For example:
+
+@example
+*(volatile int *)addr = foo;
+asm volatile ("eieio" : : );
+@end example
+
+@noindent
+Assume @code{addr} contains the address of a memory mapped device
+register. The PowerPC @code{eieio} instruction (Enforce In-order
+Execution of I/O) tells the cpu to make sure that the store to that
+device register happens before it issues any other I/O.
Note that even a volatile @code{asm} instruction can be moved in ways
that appear insignificant to the compiler, such as across jump
instructions. You can't expect a sequence of volatile @code{asm}
instructions to remain perfectly consecutive. If you want consecutive
-output, use a single @code{asm}.
+output, use a single @code{asm}. Also, GCC will perform some
+optimizations across a volatile @code{asm} instruction; GCC does not
+``forget everything'' when it encounters a volatile @code{asm}
+instruction the way some other compilers do.
+
+An @code{asm} instruction without any operands or clobbers (an ``old
+style'' @code{asm}) will be treated identically to a volatile
+@code{asm} instruction.
It is a natural idea to look for a way to give access to the condition
code left by the assembler instruction. However, when we attempted to
function or variable, this feature allows you to define names for the
linker that do not start with an underscore.
+It does not make sense to use this feature with a non-static local
+variable since such variables do not have assembler names. If you are
+trying to put the variable in a particular register, see @ref{Explicit
+Reg Vars}. GCC presently accepts such code with a warning, but will
+probably be changed to issue an error, rather than a warning, in the
+future.
+
You cannot use @code{asm} in this way in a function @emph{definition}; but
you can get the same effect by writing a declaration for the function
before its definition and putting @code{asm} there, like this:
@node Function Names
@section Function Names as Strings
+@cindex @code{__FUNCTION__} identifier
+@cindex @code{__PRETTY_FUNCTION__} identifier
+@cindex @code{__func__} identifier
GNU CC predefines two magic identifiers to hold the name of the current
function. The identifier @code{__FUNCTION__} holds the name of the function
special with the identifier @code{__FUNCTION__}.
GNU CC also supports the magic word @code{__func__}, defined by the
-ISO standard C-99:
+ISO standard C99:
@display
The identifier @code{__func__} is implicitly declared by the translator
function. However, if you use it in an inlined function and pass an
argument of the function as the argument to the builtin, GNU CC will
never return 1 when you call the inline function with a string constant
-or constructor expression (@pxref{Constructors}) and will not return 1
+or compound literal (@pxref{Compound Literals}) and will not return 1
when you pass a constant numeric value to the inline function unless you
specify the @samp{-O} option.
@findex __builtin_expect
@item __builtin_expect(@var{exp}, @var{c})
-You may use @code{__builtin_expect} to provide the compiler with
+You may use @code{__builtin_expect} to provide the compiler with
branch prediction information. In general, you should prefer to
use actual profile feedback for this (@samp{-fprofile-arcs}), as
programmers are notoriously bad at predicting how their programs
* Min and Max:: C++ Minimum and maximum operators.
* Volatiles:: What constitutes an access to a volatile object.
* Restricted Pointers:: C99 restricted pointers and references.
+* Vague Linkage:: Where G++ puts inlines, vtables and such.
* C++ Interface:: You can use a single C++ header file for both
declarations and definitions.
* Template Instantiation:: Methods for ensuring that exactly one copy of
* Bound member functions:: You can extract a function pointer to the
method denoted by a @samp{->*} or @samp{.*} expression.
* C++ Attributes:: Variable, function, and type attributes for C++ only.
+* Java Exceptions:: Tweaking exception handling to work with Java.
* Deprecated Features:: Things might disappear from g++.
* Backwards Compatibility:: Compatibilities with earlier definitions of C++.
@end menu
specify @code{__restrict__} in a function definition, rather than
in a function prototype as well.
+@node Vague Linkage
+@section Vague Linkage
+@cindex vague linkage
+
+There are several constructs in C++ which require space in the object
+file but are not clearly tied to a single translation unit. We say that
+these constructs have ``vague linkage''. Typically such constructs are
+emitted wherever they are needed, though sometimes we can be more
+clever.
+
+@table @asis
+@item Inline Functions
+Inline functions are typically defined in a header file which can be
+included in many different compilations. Hopefully they can usually be
+inlined, but sometimes an out-of-line copy is necessary, if the address
+of the function is taken or if inlining fails. In general, we emit an
+out-of-line copy in all translation units where one is needed. As an
+exception, we only emit inline virtual functions with the vtable, since
+it will always require a copy.
+
+Local static variables and string constants used in an inline function
+are also considered to have vague linkage, since they must be shared
+between all inlined and out-of-line instances of the function.
+
+@item VTables
+@cindex vtable
+C++ virtual functions are implemented in most compilers using a lookup
+table, known as a vtable. The vtable contains pointers to the virtual
+functions provided by a class, and each object of the class contains a
+pointer to its vtable (or vtables, in some multiple-inheritance
+situations). If the class declares any non-inline, non-pure virtual
+functions, the first one is chosen as the ``key method'' for the class,
+and the vtable is only emitted in the translation unit where the key
+method is defined.
+
+@emph{Note:} If the chosen key method is later defined as inline, the
+vtable will still be emitted in every translation unit which defines it.
+Make sure that any inline virtuals are declared inline in the class
+body, even if they are not defined there.
+
+@item type_info objects
+@cindex type_info
+@cindex RTTI
+C++ requires information about types to be written out in order to
+implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
+For polymorphic classes (classes with virtual functions), the type_info
+object is written out along with the vtable so that @samp{dynamic_cast}
+can determine the dynamic type of a class object at runtime. For all
+other types, we write out the type_info object when it is used: when
+applying @samp{typeid} to an expression, throwing an object, or
+referring to a type in a catch clause or exception specification.
+
+@item Template Instantiations
+Most everything in this section also applies to template instantiations,
+but there are other options as well.
+@xref{Template Instantiation,,Where's the Template?}.
+
+@end table
+
+When used with GNU ld version 2.8 or later on an ELF system such as
+Linux/GNU or Solaris 2, or on Microsoft Windows, duplicate copies of
+these constructs will be discarded at link time. This is known as
+COMDAT support.
+
+On targets that don't support COMDAT, but do support weak symbols, GCC
+will use them. This way one copy will override all the others, but
+the unused copies will still take up space in the executable.
+
+For targets which do not support either COMDAT or weak symbols,
+most entities with vague linkage will be emitted as local symbols to
+avoid duplicate definition errors from the linker. This will not happen
+for local statics in inlines, however, as having multiple copies will
+almost certainly break things.
+
+@xref{C++ Interface,,Declarations and Definitions in One Header}, for
+another way to control placement of these constructs.
+
@node C++ Interface
@section Declarations and Definitions in One Header
Note that the particular values of @var{priority} do not matter; only their
relative ordering.
-
-@item com_interface
-@cindex com_interface attribute
-
-@c This is based on: 1) grepping the code,
-@c 2) http://gcc.gnu.org/ml/gcc-bugs/1999-08n/msg01212.html
-@c 3) http://gcc.gnu.org/ml/gcc-bugs/1999-08n/msg01215.html
-@c and 4) a lot of guesswork. You can tell I don't use COM. -pme 21Dec00
-
-This type attribute takes no parameters, and marks a class or struct as an
-interface for communication via COM; the class will support the COM ABI
-rather than the full C++ ABI. Currently this means that RTTI is not possible
-with the resulting class heirarchy. The virtual pointer table will be
-changed to be COM-compliant. Also, all classes and structs derived from one
-marked with this attribute are implicitly marked with the same attribute;
-thus, only the base class in a COM hierarchy needs @code{com_interface}.
-
@item java_interface
@cindex java_interface attribute
-This type attribute informs C++ that the class is a Java interface. It may
+This type attribute informs C++ that the class is a Java interface. It may
only be applied to classes declared within an @code{extern "Java"} block.
-Calls to methods declared in this interface will be dispatched using GCJ's
-interface table mechanism, instead of regular virtual table dispatch.
+Calls to methods declared in this interface will be dispatched using GCJ's
+interface table mechanism, instead of regular virtual table dispatch.
@end table
+@node Java Exceptions
+@section Java Exceptions
+
+The Java language uses a slightly different exception handling model
+from C++. Normally, GNU C++ will automatically detect when you are
+writing C++ code that uses Java exceptions, and handle them
+appropriately. However, if C++ code only needs to execute destructors
+when Java exceptions are thrown through it, GCC will guess incorrectly.
+Sample problematic code:
+
+@example
+ struct S @{ ~S(); @};
+ extern void bar(); // is implemented in Java and may throw exceptions
+ void foo()
+ @{
+ S s;
+ bar();
+ @}
+@end example
+
+@noindent
+The usual effect of an incorrect guess is a link failure, complaining of
+a missing routine called @samp{__gxx_personality_v0}.
+
+You can inform the compiler that Java exceptions are to be used in a
+translation unit, irrespective of what it might think, by writing
+@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This
+@samp{#pragma} must appear before any functions that throw or catch
+exceptions, or run destructors when exceptions are thrown through them.
+
+You cannot mix Java and C++ exceptions in the same translation unit. It
+is believed to be safe to throw a C++ exception from one file through
+another file compiled for the for the Java exception model, or vice
+versa, but there may be bugs in this area.
+
@node Deprecated Features
@section Deprecated Features
@code{()} will be treated as an unspecified number of arguments, rather
than no arguments, as C++ demands.
@end table
-