Makefile.in (install): Some of HEADERS come from the stl dir now.

[thirdparty/gcc.git] / gcc / gcc.info-10

This is Info file gcc.info, produced by Makeinfo version 1.68 from the
input file gcc.texi.

   This file documents the use and the internals of the GNU compiler.

   Published by the Free Software Foundation 59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

   Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997 Free
Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License," "Funding for
Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License," "Funding for Free Software," and "Protect Your Freedom--Fight
`Look And Feel'", and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.

\1f
File: gcc.info,  Node: Inline,  Next: Extended Asm,  Prev: Alignment,  Up: C Extensions

An Inline Function is As Fast As a Macro
========================================

   By declaring a function `inline', you can direct GNU CC to integrate
that function's code into the code for its callers.  This makes
execution faster by eliminating the function-call overhead; in
addition, if any of the actual argument values are constant, their known
values may permit simplifications at compile time so that not all of the
inline function's code needs to be included.  The effect on code size is
less predictable; object code may be larger or smaller with function
inlining, depending on the particular case.  Inlining of functions is an
optimization and it really "works" only in optimizing compilation.  If
you don't use `-O', no function is really inline.

   To declare a function inline, use the `inline' keyword in its
declaration, like this:

     inline int
     inc (int *a)
     {
       (*a)++;
     }

   (If you are writing a header file to be included in ANSI C programs,
write `__inline__' instead of `inline'.  *Note Alternate Keywords::.)

   You can also make all "simple enough" functions inline with the
option `-finline-functions'.  Note that certain usages in a function
definition can make it unsuitable for inline substitution.

   Note that in C and Objective C, unlike C++, the `inline' keyword
does not affect the linkage of the function.

   GNU CC automatically inlines member functions defined within the
class body of C++ programs even if they are not explicitly declared
`inline'.  (You can override this with `-fno-default-inline'; *note
Options Controlling C++ Dialect: C++ Dialect Options..)

   When a function is both inline and `static', if all calls to the
function are integrated into the caller, and the function's address is
never used, then the function's own assembler code is never referenced.
In this case, GNU CC does not actually output assembler code for the
function, unless you specify the option `-fkeep-inline-functions'.
Some calls cannot be integrated for various reasons (in particular,
calls that precede the function's definition cannot be integrated, and
neither can recursive calls within the definition).  If there is a
nonintegrated call, then the function is compiled to assembler code as
usual.  The function must also be compiled as usual if the program
refers to its address, because that can't be inlined.

   When an inline function is not `static', then the compiler must
assume that there may be calls from other source files; since a global
symbol can be defined only once in any program, the function must not
be defined in the other source files, so the calls therein cannot be
integrated.  Therefore, a non-`static' inline function is always
compiled on its own in the usual fashion.

   If you specify both `inline' and `extern' in the function
definition, then the definition is used only for inlining.  In no case
is the function compiled on its own, not even if you refer to its
address explicitly.  Such an address becomes an external reference, as
if you had only declared the function, and had not defined it.

   This combination of `inline' and `extern' has almost the effect of a
macro.  The way to use it is to put a function definition in a header
file with these keywords, and put another copy of the definition
(lacking `inline' and `extern') in a library file.  The definition in
the header file will cause most calls to the function to be inlined.
If any uses of the function remain, they will refer to the single copy
in the library.

   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
did the easy thing, and turned it off.

\1f
File: gcc.info,  Node: Extended Asm,  Next: Asm Labels,  Prev: Inline,  Up: C Extensions

Assembler Instructions with C Expression Operands
=================================================

   In an assembler instruction using `asm', you can now specify the
operands of the instruction using C expressions.  This means no more
guessing which registers or memory locations will contain the data you
want to use.

   You must specify an assembler instruction template much like what
appears in a machine description, plus an operand constraint string for
each operand.

   For example, here is how to use the 68881's `fsinx' instruction:

     asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));

Here `angle' is the C expression for the input operand while `result'
is that of the output operand.  Each has `"f"' as its operand
constraint, saying that a floating point register is required.  The `='
in `=f' indicates that the operand is an output; all output operands'
constraints must use `='.  The constraints use the same language used
in the machine description (*note Constraints::.).

   Each operand is described by an operand-constraint string followed
by the C expression in parentheses.  A colon separates the assembler
template from the first output operand, and another separates the last
output operand from the first input, if any.  Commas separate output
operands and separate inputs.  The total number of operands is limited
to ten or to the maximum number of operands in any instruction pattern
in the machine description, whichever is greater.

   If there are no output operands, and there are input operands, then
there must be two consecutive colons surrounding the place where the
output operands would go.

   Output operand expressions must be lvalues; the compiler can check
this.  The input operands need not be lvalues.  The compiler cannot
check whether the operands have data types that are reasonable for the
instruction being executed.  It does not parse the assembler
instruction template and does not know what it means, or whether it is
valid assembler input.  The extended `asm' feature is most often used
for machine instructions that the compiler itself does not know exist.
If the output expression cannot be directly addressed (for example, it
is a bit field), your constraint must allow a register.  In that case,
GNU CC will use the register as the output of the `asm', and then store
that register into the output.

   The ordinary output operands must be write-only; GNU CC will assume
that the values in these operands before the instruction are dead and
need not be generated.  Extended asm supports input-output or
read-write operands.  Use the constraint character `+' to indicate such
an operand and list it with the output operands.

   When the constraints for the read-write operand (or the operand in
which only some of the bits are to be changed) allows a register, you
may, as an alternative, logically split its function into two separate
operands, one input operand and one write-only output operand.  The
connection between them is expressed by constraints which say they need
to be in the same location when the instruction executes.  You can use
the same C expression for both operands, or different expressions.  For
example, here we write the (fictitious) `combine' instruction with
`bar' as its read-only source operand and `foo' as its read-write
destination:

     asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));

The constraint `"0"' for operand 1 says that it must occupy the same
location as operand 0.  A digit in constraint is allowed only in an
input operand, and it must refer to an output operand.

   Only a digit in the constraint can guarantee that one operand will
be in the same place as another.  The mere fact that `foo' is the value
of both operands is not enough to guarantee that they will be in the
same place in the generated assembler code.  The following would not
work:

     asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));

   Various optimizations or reloading could cause operands 0 and 1 to
be in different registers; GNU CC knows no reason not to do so.  For
example, the compiler might find a copy of the value of `foo' in one
register and use it for operand 1, but generate the output operand 0 in
a different register (copying it afterward to `foo''s own address).  Of
course, since the register for operand 1 is not even mentioned in the
assembler code, the result will not work, but GNU CC can't tell that.

   Some instructions clobber specific hard registers.  To describe
this, write a third colon after the input operands, followed by the
names of the clobbered hard registers (given as strings).  Here is a
realistic example for the Vax:

     asm volatile ("movc3 %0,%1,%2"
                   : /* no outputs */
                   : "g" (from), "g" (to), "g" (count)
                   : "r0", "r1", "r2", "r3", "r4", "r5");

   If you refer to a particular hardware register from the assembler
code, then you will probably have to list the register after the third
colon to tell the compiler that the register's value is modified.  In
many assemblers, the register names begin with `%'; to produce one `%'
in the assembler code, you must write `%%' in the input.

   If your assembler instruction can alter the condition code register,
add `cc' to the list of clobbered registers.  GNU CC on some machines
represents the condition codes as a specific hardware register; `cc'
serves to name this register.  On other machines, the condition code is
handled differently, and specifying `cc' has no effect.  But it is
valid no matter what the machine.

   If your assembler instruction modifies memory in an unpredictable
fashion, add `memory' to the list of clobbered registers.  This will
cause GNU CC to not keep memory values cached in registers across the
assembler instruction.

   You can put multiple assembler instructions together in a single
`asm' template, separated either with newlines (written as `\n') or with
semicolons if the assembler allows such semicolons.  The GNU assembler
allows semicolons and all Unix assemblers seem to do so.  The input
operands are guaranteed not to use any of the clobbered registers, and
neither will the output operands' addresses, so you can read and write
the clobbered registers as many times as you like.  Here is an example
of multiple instructions in a template; it assumes that the subroutine
`_foo' accepts arguments in registers 9 and 10:

     asm ("movl %0,r9;movl %1,r10;call _foo"
          : /* no outputs */
          : "g" (from), "g" (to)
          : "r9", "r10");

   Unless an output operand has the `&' constraint modifier, GNU CC may
allocate it in the same register as an unrelated input operand, on the
assumption that the inputs are consumed before the outputs are produced.
This assumption may be false if the assembler code actually consists of
more than one instruction.  In such a case, use `&' for each output
operand that may not overlap an input.  *Note Modifiers::.

   If you want to test the condition code produced by an assembler
instruction, you must include a branch and a label in the `asm'
construct, as follows:

     asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
          : "g" (result)
          : "g" (input));

This assumes your assembler supports local labels, as the GNU assembler
and most Unix assemblers do.

   Speaking of labels, jumps from one `asm' to another are not
supported.  The compiler's optimizers do not know about these jumps,
and therefore they cannot take account of them when deciding how to
optimize.

   Usually the most convenient way to use these `asm' instructions is to
encapsulate them in macros that look like functions.  For example,

     #define sin(x)       \
     ({ double __value, __arg = (x);   \
        asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
        __value; })

Here the variable `__arg' is used to make sure that the instruction
operates on a proper `double' value, and to accept only those arguments
`x' which can convert automatically to a `double'.

   Another way to make sure the instruction operates on the correct
data type is to use a cast in the `asm'.  This is different from using a
variable `__arg' in that it converts more different types.  For
example, if the desired type were `int', casting the argument to `int'
would accept a pointer with no complaint, while assigning the argument
to an `int' variable named `__arg' would warn about using a pointer
unless the caller explicitly casts it.

   If an `asm' has output operands, GNU CC assumes for optimization
purposes that the instruction has no side effects except to change the
output operands.  This does not mean that instructions with a side
effect cannot be used, but you must be careful, because the compiler
may eliminate them if the output operands aren't used, or move them out
of loops, or replace two with one if they constitute a common
subexpression.  Also, if your instruction does have a side effect on a
variable that otherwise appears not to change, the old value of the
variable may be reused later if it happens to be found in a register.

   You can prevent an `asm' instruction from being deleted, moved
significantly, or combined, by writing the keyword `volatile' after the
`asm'.  For example:

     #define set_priority(x)  \
     asm volatile ("set_priority %0": /* no outputs */ : "g" (x))

An instruction without output operands will not be deleted or moved
significantly, regardless, unless it is unreachable.

   Note that even a volatile `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 `asm'
instructions to remain perfectly consecutive.  If you want consecutive
output, use a single `asm'.

   It is a natural idea to look for a way to give access to the
condition code left by the assembler instruction.  However, when we
attempted to implement this, we found no way to make it work reliably.
The problem is that output operands might need reloading, which would
result in additional following "store" instructions.  On most machines,
these instructions would alter the condition code before there was time
to test it.  This problem doesn't arise for ordinary "test" and
"compare" instructions because they don't have any output operands.

   If you are writing a header file that should be includable in ANSI C
programs, write `__asm__' instead of `asm'.  *Note Alternate Keywords::.

\1f
File: gcc.info,  Node: Asm Labels,  Next: Explicit Reg Vars,  Prev: Extended Asm,  Up: C Extensions

Controlling Names Used in Assembler Code
========================================

   You can specify the name to be used in the assembler code for a C
function or variable by writing the `asm' (or `__asm__') keyword after
the declarator as follows:

     int foo asm ("myfoo") = 2;

This specifies that the name to be used for the variable `foo' in the
assembler code should be `myfoo' rather than the usual `_foo'.

   On systems where an underscore is normally prepended to the name of
a C function or variable, this feature allows you to define names for
the linker that do not start with an underscore.

   You cannot use `asm' in this way in a function *definition*; but you
can get the same effect by writing a declaration for the function
before its definition and putting `asm' there, like this:

     extern func () asm ("FUNC");
     
     func (x, y)
          int x, y;
     ...

   It is up to you to make sure that the assembler names you choose do
not conflict with any other assembler symbols.  Also, you must not use a
register name; that would produce completely invalid assembler code.
GNU CC does not as yet have the ability to store static variables in
registers.  Perhaps that will be added.

\1f
File: gcc.info,  Node: Explicit Reg Vars,  Next: Alternate Keywords,  Prev: Asm Labels,  Up: C Extensions

Variables in Specified Registers
================================

   GNU C allows you to put a few global variables into specified
hardware registers.  You can also specify the register in which an
ordinary register variable should be allocated.

   * Global register variables reserve registers throughout the program.
     This may be useful in programs such as programming language
     interpreters which have a couple of global variables that are
     accessed very often.

   * Local register variables in specific registers do not reserve the
     registers.  The compiler's data flow analysis is capable of
     determining where the specified registers contain live values, and
     where they are available for other uses.

     These local variables are sometimes convenient for use with the
     extended `asm' feature (*note Extended Asm::.), if you want to
     write one output of the assembler instruction directly into a
     particular register.  (This will work provided the register you
     specify fits the constraints specified for that operand in the
     `asm'.)

* Menu:

* Global Reg Vars::
* Local Reg Vars::

\1f
File: gcc.info,  Node: Global Reg Vars,  Next: Local Reg Vars,  Up: Explicit Reg Vars

Defining Global Register Variables
----------------------------------

   You can define a global register variable in GNU C like this:

     register int *foo asm ("a5");

Here `a5' is the name of the register which should be used.  Choose a
register which is normally saved and restored by function calls on your
machine, so that library routines will not clobber it.

   Naturally the register name is cpu-dependent, so you would need to
conditionalize your program according to cpu type.  The register `a5'
would be a good choice on a 68000 for a variable of pointer type.  On
machines with register windows, be sure to choose a "global" register
that is not affected magically by the function call mechanism.

   In addition, operating systems on one type of cpu may differ in how
they name the registers; then you would need additional conditionals.
For example, some 68000 operating systems call this register `%a5'.

   Eventually there may be a way of asking the compiler to choose a
register automatically, but first we need to figure out how it should
choose and how to enable you to guide the choice.  No solution is
evident.

   Defining a global register variable in a certain register reserves
that register entirely for this use, at least within the current
compilation.  The register will not be allocated for any other purpose
in the functions in the current compilation.  The register will not be
saved and restored by these functions.  Stores into this register are
never deleted even if they would appear to be dead, but references may
be deleted or moved or simplified.

   It is not safe to access the global register variables from signal
handlers, or from more than one thread of control, because the system
library routines may temporarily use the register for other things
(unless you recompile them specially for the task at hand).

   It is not safe for one function that uses a global register variable
to call another such function `foo' by way of a third function `lose'
that was compiled without knowledge of this variable (i.e. in a
different source file in which the variable wasn't declared).  This is
because `lose' might save the register and put some other value there.
For example, you can't expect a global register variable to be
available in the comparison-function that you pass to `qsort', since
`qsort' might have put something else in that register.  (If you are
prepared to recompile `qsort' with the same global register variable,
you can solve this problem.)

   If you want to recompile `qsort' or other source files which do not
actually use your global register variable, so that they will not use
that register for any other purpose, then it suffices to specify the
compiler option `-ffixed-REG'.  You need not actually add a global
register declaration to their source code.

   A function which can alter the value of a global register variable
cannot safely be called from a function compiled without this variable,
because it could clobber the value the caller expects to find there on
return.  Therefore, the function which is the entry point into the part
of the program that uses the global register variable must explicitly
save and restore the value which belongs to its caller.

   On most machines, `longjmp' will restore to each global register
variable the value it had at the time of the `setjmp'.  On some
machines, however, `longjmp' will not change the value of global
register variables.  To be portable, the function that called `setjmp'
should make other arrangements to save the values of the global register
variables, and to restore them in a `longjmp'.  This way, the same
thing will happen regardless of what `longjmp' does.

   All global register variable declarations must precede all function
definitions.  If such a declaration could appear after function
definitions, the declaration would be too late to prevent the register
from being used for other purposes in the preceding functions.

   Global register variables may not have initial values, because an
executable file has no means to supply initial contents for a register.

   On the Sparc, there are reports that g3 ... g7 are suitable
registers, but certain library functions, such as `getwd', as well as
the subroutines for division and remainder, modify g3 and g4.  g1 and
g2 are local temporaries.

   On the 68000, a2 ... a5 should be suitable, as should d2 ... d7.  Of
course, it will not do to use more than a few of those.

\1f
File: gcc.info,  Node: Local Reg Vars,  Prev: Global Reg Vars,  Up: Explicit Reg Vars

Specifying Registers for Local Variables
----------------------------------------

   You can define a local register variable with a specified register
like this:

     register int *foo asm ("a5");

Here `a5' is the name of the register which should be used.  Note that
this is the same syntax used for defining global register variables,
but for a local variable it would appear within a function.

   Naturally the register name is cpu-dependent, but this is not a
problem, since specific registers are most often useful with explicit
assembler instructions (*note Extended Asm::.).  Both of these things
generally require that you conditionalize your program according to cpu
type.

   In addition, operating systems on one type of cpu may differ in how
they name the registers; then you would need additional conditionals.
For example, some 68000 operating systems call this register `%a5'.

   Eventually there may be a way of asking the compiler to choose a
register automatically, but first we need to figure out how it should
choose and how to enable you to guide the choice.  No solution is
evident.

   Defining such a register variable does not reserve the register; it
remains available for other uses in places where flow control determines
the variable's value is not live.  However, these registers are made
unavailable for use in the reload pass.  I would not be surprised if
excessive use of this feature leaves the compiler too few available
registers to compile certain functions.

\1f
File: gcc.info,  Node: Alternate Keywords,  Next: Incomplete Enums,  Prev: Explicit Reg Vars,  Up: C Extensions

Alternate Keywords
==================

   The option `-traditional' disables certain keywords; `-ansi'
disables certain others.  This causes trouble when you want to use GNU C
extensions, or ANSI C features, in a general-purpose header file that
should be usable by all programs, including ANSI C programs and
traditional ones.  The keywords `asm', `typeof' and `inline' cannot be
used since they won't work in a program compiled with `-ansi', while
the keywords `const', `volatile', `signed', `typeof' and `inline' won't
work in a program compiled with `-traditional'.

   The way to solve these problems is to put `__' at the beginning and
end of each problematical keyword.  For example, use `__asm__' instead
of `asm', `__const__' instead of `const', and `__inline__' instead of
`inline'.

   Other C compilers won't accept these alternative keywords; if you
want to compile with another compiler, you can define the alternate
keywords as macros to replace them with the customary keywords.  It
looks like this:

     #ifndef __GNUC__
     #define __asm__ asm
     #endif

   `-pedantic' causes warnings for many GNU C extensions.  You can
prevent such warnings within one expression by writing `__extension__'
before the expression.  `__extension__' has no effect aside from this.

\1f
File: gcc.info,  Node: Incomplete Enums,  Next: Function Names,  Prev: Alternate Keywords,  Up: C Extensions

Incomplete `enum' Types
=======================

   You can define an `enum' tag without specifying its possible values.
This results in an incomplete type, much like what you get if you write
`struct foo' without describing the elements.  A later declaration
which does specify the possible values completes the type.

   You can't allocate variables or storage using the type while it is
incomplete.  However, you can work with pointers to that type.

   This extension may not be very useful, but it makes the handling of
`enum' more consistent with the way `struct' and `union' are handled.

   This extension is not supported by GNU C++.

\1f
File: gcc.info,  Node: Function Names,  Next: Return Address,  Prev: Incomplete Enums,  Up: C Extensions

Function Names as Strings
=========================

   GNU CC predefines two string variables to be the name of the current
function.  The variable `__FUNCTION__' is the name of the function as
it appears in the source.  The variable `__PRETTY_FUNCTION__' is the
name of the function pretty printed in a language specific fashion.

   These names are always the same in a C function, but in a C++
function they may be different.  For example, this program:

     extern "C" {
     extern int printf (char *, ...);
     }
     
     class a {
      public:
       sub (int i)
         {
           printf ("__FUNCTION__ = %s\n", __FUNCTION__);
           printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
         }
     };
     
     int
     main (void)
     {
       a ax;
       ax.sub (0);
       return 0;
     }

gives this output:

     __FUNCTION__ = sub
     __PRETTY_FUNCTION__ = int  a::sub (int)

   These names are not macros: they are predefined string variables.
For example, `#ifdef __FUNCTION__' does not have any special meaning
inside a function, since the preprocessor does not do anything special
with the identifier `__FUNCTION__'.

\1f
File: gcc.info,  Node: Return Address,  Prev: Function Names,  Up: C Extensions

Getting the Return or Frame Address of a Function
=================================================

   These functions may be used to get information about the callers of a
function.

`__builtin_return_address (LEVEL)'
     This function returns the return address of the current function,
     or of one of its callers.  The LEVEL argument is number of frames
     to scan up the call stack.  A value of `0' yields the return
     address of the current function, a value of `1' yields the return
     address of the caller of the current function, and so forth.

     The LEVEL argument must be a constant integer.

     On some machines it may be impossible to determine the return
     address of any function other than the current one; in such cases,
     or when the top of the stack has been reached, this function will
     return `0'.

     This function should only be used with a non-zero argument for
     debugging purposes.

`__builtin_frame_address (LEVEL)'
     This function is similar to `__builtin_return_address', but it
     returns the address of the function frame rather than the return
     address of the function.  Calling `__builtin_frame_address' with a
     value of `0' yields the frame address of the current function, a
     value of `1' yields the frame address of the caller of the current
     function, and so forth.

     The frame is the area on the stack which holds local variables and
     saved registers.  The frame address is normally the address of the
     first word pushed on to the stack by the function.  However, the
     exact definition depends upon the processor and the calling
     convention.  If the processor has a dedicated frame pointer
     register, and the function has a frame, then
     `__builtin_frame_address' will return the value of the frame
     pointer register.

     The caveats that apply to `__builtin_return_address' apply to this
     function as well.

\1f
File: gcc.info,  Node: C++ Extensions,  Next: Gcov,  Prev: C Extensions,  Up: Top

Extensions to the C++ Language
******************************

   The GNU compiler provides these extensions to the C++ language (and
you can also use most of the C language extensions in your C++
programs).  If you want to write code that checks whether these
features are available, you can test for the GNU compiler the same way
as for C programs: check for a predefined macro `__GNUC__'.  You can
also use `__GNUG__' to test specifically for GNU C++ (*note Standard
Predefined Macros: (cpp.info)Standard Predefined.).

* Menu:

* Naming Results::      Giving a name to C++ function return values.
* Min and Max::		C++ Minimum and maximum operators.
* Destructors and Goto:: Goto is safe to use in C++ even when destructors
                           are needed.
* 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
                         each needed template instantiation is emitted.
* C++ Signatures::	You can specify abstract types to get subtype
			 polymorphism independent from inheritance.

\1f
File: gcc.info,  Node: Naming Results,  Next: Min and Max,  Up: C++ Extensions

Named Return Values in C++
==========================

   GNU C++ extends the function-definition syntax to allow you to
specify a name for the result of a function outside the body of the
definition, in C++ programs:

     TYPE
     FUNCTIONNAME (ARGS) return RESULTNAME;
     {
       ...
       BODY
       ...
     }

   You can use this feature to avoid an extra constructor call when a
function result has a class type.  For example, consider a function
`m', declared as `X v = m ();', whose result is of class `X':

     X
     m ()
     {
       X b;
       b.a = 23;
       return b;
     }

   Although `m' appears to have no arguments, in fact it has one
implicit argument: the address of the return value.  At invocation, the
address of enough space to hold `v' is sent in as the implicit argument.
Then `b' is constructed and its `a' field is set to the value 23.
Finally, a copy constructor (a constructor of the form `X(X&)') is
applied to `b', with the (implicit) return value location as the
target, so that `v' is now bound to the return value.

   But this is wasteful.  The local `b' is declared just to hold
something that will be copied right out.  While a compiler that
combined an "elision" algorithm with interprocedural data flow analysis
could conceivably eliminate all of this, it is much more practical to
allow you to assist the compiler in generating efficient code by
manipulating the return value explicitly, thus avoiding the local
variable and copy constructor altogether.

   Using the extended GNU C++ function-definition syntax, you can avoid
the temporary allocation and copying by naming `r' as your return value
at the outset, and assigning to its `a' field directly:

     X
     m () return r;
     {
       r.a = 23;
     }

The declaration of `r' is a standard, proper declaration, whose effects
are executed *before* any of the body of `m'.

   Functions of this type impose no additional restrictions; in
particular, you can execute `return' statements, or return implicitly by
reaching the end of the function body ("falling off the edge").  Cases
like

     X
     m () return r (23);
     {
       return;
     }

(or even `X m () return r (23); { }') are unambiguous, since the return
value `r' has been initialized in either case.  The following code may
be hard to read, but also works predictably:

     X
     m () return r;
     {
       X b;
       return b;
     }

   The return value slot denoted by `r' is initialized at the outset,
but the statement `return b;' overrides this value.  The compiler deals
with this by destroying `r' (calling the destructor if there is one, or
doing nothing if there is not), and then reinitializing `r' with `b'.

   This extension is provided primarily to help people who use
overloaded operators, where there is a great need to control not just
the arguments, but the return values of functions.  For classes where
the copy constructor incurs a heavy performance penalty (especially in
the common case where there is a quick default constructor), this is a
major savings.  The disadvantage of this extension is that you do not
control when the default constructor for the return value is called: it
is always called at the beginning.

\1f
File: gcc.info,  Node: Min and Max,  Next: Destructors and Goto,  Prev: Naming Results,  Up: C++ Extensions

Minimum and Maximum Operators in C++
====================================

   It is very convenient to have operators which return the "minimum"
or the "maximum" of two arguments.  In GNU C++ (but not in GNU C),

`A <? B'
     is the "minimum", returning the smaller of the numeric values A
     and B;

`A >? B'
     is the "maximum", returning the larger of the numeric values A and
     B.

   These operations are not primitive in ordinary C++, since you can
use a macro to return the minimum of two things in C++, as in the
following example.

     #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y))

You might then use `int min = MIN (i, j);' to set MIN to the minimum
value of variables I and J.

   However, side effects in `X' or `Y' may cause unintended behavior.
For example, `MIN (i++, j++)' will fail, incrementing the smaller
counter twice.  A GNU C extension allows you to write safe macros that
avoid this kind of problem (*note Naming an Expression's Type: Naming
Types.).  However, writing `MIN' and `MAX' as macros also forces you to
use function-call notation for a fundamental arithmetic operation.
Using GNU C++ extensions, you can write `int min = i <? j;' instead.

   Since `<?' and `>?' are built into the compiler, they properly
handle expressions with side-effects;  `int min = i++ <? j++;' works
correctly.

\1f
File: gcc.info,  Node: Destructors and Goto,  Next: C++ Interface,  Prev: Min and Max,  Up: C++ Extensions

`goto' and Destructors in GNU C++
=================================

   In C++ programs, you can safely use the `goto' statement.  When you
use it to exit a block which contains aggregates requiring destructors,
the destructors will run before the `goto' transfers control.

   The compiler still forbids using `goto' to *enter* a scope that
requires constructors.

\1f
File: gcc.info,  Node: C++ Interface,  Next: Template Instantiation,  Prev: Destructors and Goto,  Up: C++ Extensions

Declarations and Definitions in One Header
==========================================

   C++ object definitions can be quite complex.  In principle, your
source code will need two kinds of things for each object that you use
across more than one source file.  First, you need an "interface"
specification, describing its structure with type declarations and
function prototypes.  Second, you need the "implementation" itself.  It
can be tedious to maintain a separate interface description in a header
file, in parallel to the actual implementation.  It is also dangerous,
since separate interface and implementation definitions may not remain
parallel.

   With GNU C++, you can use a single header file for both purposes.

     *Warning:* The mechanism to specify this is in transition.  For the
     nonce, you must use one of two `#pragma' commands; in a future
     release of GNU C++, an alternative mechanism will make these
     `#pragma' commands unnecessary.

   The header file contains the full definitions, but is marked with
`#pragma interface' in the source code.  This allows the compiler to
use the header file only as an interface specification when ordinary
source files incorporate it with `#include'.  In the single source file
where the full implementation belongs, you can use either a naming
convention or `#pragma implementation' to indicate this alternate use
of the header file.

`#pragma interface'
`#pragma interface "SUBDIR/OBJECTS.h"'
     Use this directive in *header files* that define object classes,
     to save space in most of the object files that use those classes.
     Normally, local copies of certain information (backup copies of
     inline member functions, debugging information, and the internal
     tables that implement virtual functions) must be kept in each
     object file that includes class definitions.  You can use this
     pragma to avoid such duplication.  When a header file containing
     `#pragma interface' is included in a compilation, this auxiliary
     information will not be generated (unless the main input source
     file itself uses `#pragma implementation').  Instead, the object
     files will contain references to be resolved at link time.

     The second form of this directive is useful for the case where you
     have multiple headers with the same name in different directories.
     If you use this form, you must specify the same string to `#pragma
     implementation'.

`#pragma implementation'
`#pragma implementation "OBJECTS.h"'
     Use this pragma in a *main input file*, when you want full output
     from included header files to be generated (and made globally
     visible).  The included header file, in turn, should use `#pragma
     interface'.  Backup copies of inline member functions, debugging
     information, and the internal tables used to implement virtual
     functions are all generated in implementation files.

     If you use `#pragma implementation' with no argument, it applies to
     an include file with the same basename(1) as your source file.
     For example, in `allclass.cc', giving just `#pragma implementation'
     by itself is equivalent to `#pragma implementation "allclass.h"'.

     In versions of GNU C++ prior to 2.6.0 `allclass.h' was treated as
     an implementation file whenever you would include it from
     `allclass.cc' even if you never specified `#pragma
     implementation'.  This was deemed to be more trouble than it was
     worth, however, and disabled.

     If you use an explicit `#pragma implementation', it must appear in
     your source file *before* you include the affected header files.

     Use the string argument if you want a single implementation file to
     include code from multiple header files.  (You must also use
     `#include' to include the header file; `#pragma implementation'
     only specifies how to use the file--it doesn't actually include
     it.)

     There is no way to split up the contents of a single header file
     into multiple implementation files.

   `#pragma implementation' and `#pragma interface' also have an effect
on function inlining.

   If you define a class in a header file marked with `#pragma
interface', the effect on a function defined in that class is similar to
an explicit `extern' declaration--the compiler emits no code at all to
define an independent version of the function.  Its definition is used
only for inlining with its callers.

   Conversely, when you include the same header file in a main source
file that declares it as `#pragma implementation', the compiler emits
code for the function itself; this defines a version of the function
that can be found via pointers (or by callers compiled without
inlining).  If all calls to the function can be inlined, you can avoid
emitting the function by compiling with `-fno-implement-inlines'.  If
any calls were not inlined, you will get linker errors.

   ---------- Footnotes ----------

   (1) A file's "basename" was the name stripped of all leading path
information and of trailing suffixes, such as `.h' or `.C' or `.cc'.

\1f
File: gcc.info,  Node: Template Instantiation,  Next: C++ Signatures,  Prev: C++ Interface,  Up: C++ Extensions

Where's the Template?
=====================

   C++ templates are the first language feature to require more
intelligence from the environment than one usually finds on a UNIX
system.  Somehow the compiler and linker have to make sure that each
template instance occurs exactly once in the executable if it is needed,
and not at all otherwise.  There are two basic approaches to this
problem, which I will refer to as the Borland model and the Cfront
model.

Borland model
     Borland C++ solved the template instantiation problem by adding
     the code equivalent of common blocks to their linker; the compiler
     emits template instances in each translation unit that uses them,
     and the linker collapses them together.  The advantage of this
     model is that the linker only has to consider the object files
     themselves; there is no external complexity to worry about.  This
     disadvantage is that compilation time is increased because the
     template code is being compiled repeatedly.  Code written for this
     model tends to include definitions of all templates in the header
     file, since they must be seen to be instantiated.

Cfront model
     The AT&T C++ translator, Cfront, solved the template instantiation
     problem by creating the notion of a template repository, an
     automatically maintained place where template instances are
     stored.  A more modern version of the repository works as follows:
     As individual object files are built, the compiler places any
     template definitions and instantiations encountered in the
     repository.  At link time, the link wrapper adds in the objects in
     the repository and compiles any needed instances that were not
     previously emitted.  The advantages of this model are more optimal
     compilation speed and the ability to use the system linker; to
     implement the Borland model a compiler vendor also needs to
     replace the linker.  The disadvantages are vastly increased
     complexity, and thus potential for error; for some code this can be
     just as transparent, but in practice it can been very difficult to
     build multiple programs in one directory and one program in
     multiple directories.  Code written for this model tends to
     separate definitions of non-inline member templates into a
     separate file, which should be compiled separately.

   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, g++ supports the
Borland model.  On other systems, g++ implements neither automatic
model.

   A future version of g++ will support a hybrid model whereby the
compiler will emit any instantiations for which the template definition
is included in the compile, and store template definitions and
instantiation context information into the object file for the rest.
The link wrapper will extract that information as necessary and invoke
the compiler to produce the remaining instantiations.  The linker will
then combine duplicate instantiations.

   In the mean time, you have the following options for dealing with
template instantiations:

  1. Compile your code with `-fno-implicit-templates' to disable the
     implicit generation of template instances, and explicitly
     instantiate all the ones you use.  This approach requires more
     knowledge of exactly which instances you need than do the others,
     but it's less mysterious and allows greater control.  You can
     scatter the explicit instantiations throughout your program,
     perhaps putting them in the translation units where the instances
     are used or the translation units that define the templates
     themselves; you can put all of the explicit instantiations you
     need into one big file; or you can create small files like

          #include "Foo.h"
          #include "Foo.cc"
          
          template class Foo<int>;
          template ostream& operator <<
                          (ostream&, const Foo<int>&);

     for each of the instances you need, and create a template
     instantiation library from those.

     If you are using Cfront-model code, you can probably get away with
     not using `-fno-implicit-templates' when compiling files that don't
     `#include' the member template definitions.

     If you use one big file to do the instantiations, you may want to
     compile it without `-fno-implicit-templates' so you get all of the
     instances required by your explicit instantiations (but not by any
     other files) without having to specify them as well.

     g++ has extended the template instantiation syntax outlined in the
     Working Paper to allow forward declaration of explicit
     instantiations, explicit instantiation of members of template
     classes and instantiation of the compiler support data for a
     template class (i.e. the vtable) without instantiating any of its
     members:

          extern template int max (int, int);
          template void Foo<int>::f ();
          inline template class Foo<int>;

  2. Do nothing.  Pretend g++ does implement automatic instantiation
     management.  Code written for the Borland model will work fine, but
     each translation unit will contain instances of each of the
     templates it uses.  In a large program, this can lead to an
     unacceptable amount of code duplication.

  3. Add `#pragma interface' to all files containing template
     definitions.  For each of these files, add `#pragma implementation
     "FILENAME"' to the top of some `.C' file which `#include's it.
     Then compile everything with `-fexternal-templates'.  The
     templates will then only be expanded in the translation unit which
     implements them (i.e. has a `#pragma implementation' line for the
     file where they live); all other files will use external
     references.  If you're lucky, everything should work properly.  If
     you get undefined symbol errors, you need to make sure that each
     template instance which is used in the program is used in the file
     which implements that template.  If you don't have any use for a
     particular instance in that file, you can just instantiate it
     explicitly, using the syntax from the latest C++ working paper:

          template class A<int>;
          template ostream& operator << (ostream&, const A<int>&);

     This strategy will work with code written for either model.  If
     you are using code written for the Cfront model, the file
     containing a class template and the file containing its member
     templates should be implemented in the same translation unit.

     A slight variation on this approach is to instead use the flag
     `-falt-external-templates'; this flag causes template instances to
     be emitted in the translation unit that implements the header
     where they are first instantiated, rather than the one which
     implements the file where the templates are defined.  This header
     must be the same in all translation units, or things are likely to
     break.

     *Note Declarations and Definitions in One Header: C++ Interface,
     for more discussion of these pragmas.