This is doc/gcc.info, produced by makeinfo version 4.8 from
doc/gcc.texi.

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gcc: (gcc).                  The GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the use of the GNU compilers.

   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, 1998,
1999, 2000, 2001, 2002 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.


File: gcc.info,  Node: Other Builtins,  Next: Target Builtins,  Prev: Vector Extensions,  Up: C Extensions

5.44 Other built-in functions provided by GCC
=============================================

GCC provides a large number of built-in functions other than the ones
mentioned above.  Some of these are for internal use in the processing
of exceptions or variable-length argument lists and will not be
documented here because they may change from time to time; we do not
recommend general use of these functions.

   The remaining functions are provided for optimization purposes.

   GCC includes built-in versions of many of the functions in the
standard C library.  The versions prefixed with `__builtin_' will
always be treated as having the same meaning as the C library function
even if you specify the `-fno-builtin' option. (*note C Dialect
Options::) Many of these functions are only optimized in certain cases;
if they are not optimized in a particular case, a call to the library
function will be emitted.

   The functions `abort', `exit', `_Exit' and `_exit' are recognized
and presumed not to return, but otherwise are not built in.  `_exit' is
not recognized in strict ISO C mode (`-ansi', `-std=c89' or
`-std=c99').  `_Exit' is not recognized in strict C89 mode (`-ansi' or
`-std=c89').

   Outside strict ISO C mode, the functions `alloca', `bcmp', `bzero',
`index', `rindex', `ffs', `fputs_unlocked', `printf_unlocked' and
`fprintf_unlocked' may be handled as built-in functions.  All these
functions have corresponding versions prefixed with `__builtin_', which
may be used even in strict C89 mode.

   The ISO C99 functions `conj', `conjf', `conjl', `creal', `crealf',
`creall', `cimag', `cimagf', `cimagl', `llabs' and `imaxabs' are
handled as built-in functions except in strict ISO C89 mode.  There are
also built-in versions of the ISO C99 functions `cosf', `cosl',
`fabsf', `fabsl', `sinf', `sinl', `sqrtf', and `sqrtl', that are
recognized in any mode since ISO C89 reserves these names for the
purpose to which ISO C99 puts them.  All these functions have
corresponding versions prefixed with `__builtin_'.

   The ISO C89 functions `abs', `cos', `fabs', `fprintf', `fputs',
`labs', `memcmp', `memcpy', `memset', `printf', `sin', `sqrt', `strcat',
`strchr', `strcmp', `strcpy', `strcspn', `strlen', `strncat',
`strncmp', `strncpy', `strpbrk', `strrchr', `strspn', and `strstr' are
all recognized as built-in functions unless `-fno-builtin' is specified
(or `-fno-builtin-FUNCTION' is specified for an individual function).
All of these functions have corresponding versions prefixed with
`__builtin_'.

   GCC provides built-in versions of the ISO C99 floating point
comparison macros that avoid raising exceptions for unordered operands.
They have the same names as the standard macros ( `isgreater',
`isgreaterequal', `isless', `islessequal', `islessgreater', and
`isunordered') , with `__builtin_' prefixed.  We intend for a library
implementor to be able to simply `#define' each standard macro to its
built-in equivalent.

 -- Built-in Function: int __builtin_types_compatible_p (TYPE1, TYPE2)
     You can use the built-in function `__builtin_types_compatible_p' to
     determine whether two types are the same.

     This built-in function returns 1 if the unqualified versions of the
     types TYPE1 and TYPE2 (which are types, not expressions) are
     compatible, 0 otherwise.  The result of this built-in function can
     be used in integer constant expressions.

     This built-in function ignores top level qualifiers (e.g., `const',
     `volatile').  For example, `int' is equivalent to `const int'.

     The type `int[]' and `int[5]' are compatible.  On the other hand,
     `int' and `char *' are not compatible, even if the size of their
     types, on the particular architecture are the same.  Also, the
     amount of pointer indirection is taken into account when
     determining similarity.  Consequently, `short *' is not similar to
     `short **'.  Furthermore, two types that are typedefed are
     considered compatible if their underlying types are compatible.

     An `enum' type is considered to be compatible with another `enum'
     type.  For example, `enum {foo, bar}' is similar to `enum {hot,
     dog}'.

     You would typically use this function in code whose execution
     varies depending on the arguments' types.  For example:

          #define foo(x)                                                  \
            ({                                                           \
              typeof (x) tmp;                                             \
              if (__builtin_types_compatible_p (typeof (x), long double)) \
                tmp = foo_long_double (tmp);                              \
              else if (__builtin_types_compatible_p (typeof (x), double)) \
                tmp = foo_double (tmp);                                   \
              else if (__builtin_types_compatible_p (typeof (x), float))  \
                tmp = foo_float (tmp);                                    \
              else                                                        \
                abort ();                                                 \
              tmp;                                                        \
            })

     _Note:_ This construct is only available for C.


 -- Built-in Function: TYPE __builtin_choose_expr (CONST_EXP, EXP1,
          EXP2)
     You can use the built-in function `__builtin_choose_expr' to
     evaluate code depending on the value of a constant expression.
     This built-in function returns EXP1 if CONST_EXP, which is a
     constant expression that must be able to be determined at compile
     time, is nonzero.  Otherwise it returns 0.

     This built-in function is analogous to the `? :' operator in C,
     except that the expression returned has its type unaltered by
     promotion rules.  Also, the built-in function does not evaluate
     the expression that was not chosen.  For example, if CONST_EXP
     evaluates to true, EXP2 is not evaluated even if it has
     side-effects.

     This built-in function can return an lvalue if the chosen argument
     is an lvalue.

     If EXP1 is returned, the return type is the same as EXP1's type.
     Similarly, if EXP2 is returned, its return type is the same as
     EXP2.

     Example:

          #define foo(x)                                                               \
            __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), double),  \
              foo_double (x),                                                          \
              __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), float), \
                foo_float (x),                                                         \
                /* The void expression results in a compile-time error             \
                   when assigning the result to something.  */                     \
                (void)0))

     _Note:_ This construct is only available for C.  Furthermore, the
     unused expression (EXP1 or EXP2 depending on the value of
     CONST_EXP) may still generate syntax errors.  This may change in
     future revisions.


 -- Built-in Function: int __builtin_constant_p (EXP)
     You can use the built-in function `__builtin_constant_p' to
     determine if a value is known to be constant at compile-time and
     hence that GCC can perform constant-folding on expressions
     involving that value.  The argument of the function is the value
     to test.  The function returns the integer 1 if the argument is
     known to be a compile-time constant and 0 if it is not known to be
     a compile-time constant.  A return of 0 does not indicate that the
     value is _not_ a constant, but merely that GCC cannot prove it is
     a constant with the specified value of the `-O' option.

     You would typically use this function in an embedded application
     where memory was a critical resource.  If you have some complex
     calculation, you may want it to be folded if it involves
     constants, but need to call a function if it does not.  For
     example:

          #define Scale_Value(X)      \
            (__builtin_constant_p (X) \
            ? ((X) * SCALE + OFFSET) : Scale (X))

     You may use this built-in function in either a macro or an inline
     function.  However, if you use it in an inlined function and pass
     an argument of the function as the argument to the built-in, GCC
     will never return 1 when you call the inline function with a
     string constant or compound literal (*note Compound Literals::)
     and will not return 1 when you pass a constant numeric value to
     the inline function unless you specify the `-O' option.

     You may also use `__builtin_constant_p' in initializers for static
     data.  For instance, you can write

          static const int table[] = {
             __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
             /* ... */
          };

     This is an acceptable initializer even if EXPRESSION is not a
     constant expression.  GCC must be more conservative about
     evaluating the built-in in this case, because it has no
     opportunity to perform optimization.

     Previous versions of GCC did not accept this built-in in data
     initializers.  The earliest version where it is completely safe is
     3.0.1.

 -- Built-in Function: long __builtin_expect (long EXP, long C)
     You may use `__builtin_expect' to provide the compiler with branch
     prediction information.  In general, you should prefer to use
     actual profile feedback for this (`-fprofile-arcs'), as
     programmers are notoriously bad at predicting how their programs
     actually perform.  However, there are applications in which this
     data is hard to collect.

     The return value is the value of EXP, which should be an integral
     expression.  The value of C must be a compile-time constant.  The
     semantics of the built-in are that it is expected that EXP == C.
     For example:

          if (__builtin_expect (x, 0))
            foo ();

     would indicate that we do not expect to call `foo', since we
     expect `x' to be zero.  Since you are limited to integral
     expressions for EXP, you should use constructions such as

          if (__builtin_expect (ptr != NULL, 1))
            error ();

     when testing pointer or floating-point values.

 -- Built-in Function: void __builtin_prefetch (const void *ADDR, ...)
     This function is used to minimize cache-miss latency by moving
     data into a cache before it is accessed.  You can insert calls to
     `__builtin_prefetch' into code for which you know addresses of
     data in memory that is likely to be accessed soon.  If the target
     supports them, data prefetch instructions will be generated.  If
     the prefetch is done early enough before the access then the data
     will be in the cache by the time it is accessed.

     The value of ADDR is the address of the memory to prefetch.  There
     are two optional arguments, RW and LOCALITY.  The value of RW is a
     compile-time constant one or zero; one means that the prefetch is
     preparing for a write to the memory address and zero, the default,
     means that the prefetch is preparing for a read.  The value
     LOCALITY must be a compile-time constant integer between zero and
     three.  A value of zero means that the data has no temporal
     locality, so it need not be left in the cache after the access.  A
     value of three means that the data has a high degree of temporal
     locality and should be left in all levels of cache possible.
     Values of one and two mean, respectively, a low or moderate degree
     of temporal locality.  The default is three.

          for (i = 0; i < n; i++)
            {
              a[i] = a[i] + b[i];
              __builtin_prefetch (&a[i+j], 1, 1);
              __builtin_prefetch (&b[i+j], 0, 1);
              /* ... */
            }

     Data prefetch does not generate faults if ADDR is invalid, but the
     address expression itself must be valid.  For example, a prefetch
     of `p->next' will not fault if `p->next' is not a valid address,
     but evaluation will fault if `p' is not a valid address.

     If the target does not support data prefetch, the address
     expression is evaluated if it includes side effects but no other
     code is generated and GCC does not issue a warning.


File: gcc.info,  Node: Target Builtins,  Next: Pragmas,  Prev: Other Builtins,  Up: C Extensions

5.45 Built-in Functions Specific to Particular Target Machines
==============================================================

On some target machines, GCC supports many built-in functions specific
to those machines.  Generally these generate calls to specific machine
instructions, but allow the compiler to schedule those calls.

* Menu:

* X86 Built-in Functions::
* PowerPC AltiVec Built-in Functions::


File: gcc.info,  Node: X86 Built-in Functions,  Next: PowerPC AltiVec Built-in Functions,  Up: Target Builtins

5.45.1 X86 Built-in Functions
-----------------------------

These built-in functions are available for the i386 and x86-64 family
of computers, depending on the command-line switches used.

   The following machine modes are available for use with MMX built-in
functions (*note Vector Extensions::): `V2SI' for a vector of two
32-bit integers, `V4HI' for a vector of four 16-bit integers, and
`V8QI' for a vector of eight 8-bit integers.  Some of the built-in
functions operate on MMX registers as a whole 64-bit entity, these use
`DI' as their mode.

   If 3Dnow extensions are enabled, `V2SF' is used as a mode for a
vector of two 32-bit floating point values.

   If SSE extensions are enabled, `V4SF' is used for a vector of four
32-bit floating point values.  Some instructions use a vector of four
32-bit integers, these use `V4SI'.  Finally, some instructions operate
on an entire vector register, interpreting it as a 128-bit integer,
these use mode `TI'.

   The following built-in functions are made available by `-mmmx'.  All
of them generate the machine instruction that is part of the name.

     v8qi __builtin_ia32_paddb (v8qi, v8qi)
     v4hi __builtin_ia32_paddw (v4hi, v4hi)
     v2si __builtin_ia32_paddd (v2si, v2si)
     v8qi __builtin_ia32_psubb (v8qi, v8qi)
     v4hi __builtin_ia32_psubw (v4hi, v4hi)
     v2si __builtin_ia32_psubd (v2si, v2si)
     v8qi __builtin_ia32_paddsb (v8qi, v8qi)
     v4hi __builtin_ia32_paddsw (v4hi, v4hi)
     v8qi __builtin_ia32_psubsb (v8qi, v8qi)
     v4hi __builtin_ia32_psubsw (v4hi, v4hi)
     v8qi __builtin_ia32_paddusb (v8qi, v8qi)
     v4hi __builtin_ia32_paddusw (v4hi, v4hi)
     v8qi __builtin_ia32_psubusb (v8qi, v8qi)
     v4hi __builtin_ia32_psubusw (v4hi, v4hi)
     v4hi __builtin_ia32_pmullw (v4hi, v4hi)
     v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
     di __builtin_ia32_pand (di, di)
     di __builtin_ia32_pandn (di,di)
     di __builtin_ia32_por (di, di)
     di __builtin_ia32_pxor (di, di)
     v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
     v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
     v2si __builtin_ia32_pcmpeqd (v2si, v2si)
     v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
     v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
     v2si __builtin_ia32_pcmpgtd (v2si, v2si)
     v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
     v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
     v2si __builtin_ia32_punpckhdq (v2si, v2si)
     v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
     v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
     v2si __builtin_ia32_punpckldq (v2si, v2si)
     v8qi __builtin_ia32_packsswb (v4hi, v4hi)
     v4hi __builtin_ia32_packssdw (v2si, v2si)
     v8qi __builtin_ia32_packuswb (v4hi, v4hi)

   The following built-in functions are made available either with
`-msse', or with a combination of `-m3dnow' and `-march=athlon'.  All
of them generate the machine instruction that is part of the name.

     v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
     v8qi __builtin_ia32_pavgb (v8qi, v8qi)
     v4hi __builtin_ia32_pavgw (v4hi, v4hi)
     v4hi __builtin_ia32_psadbw (v8qi, v8qi)
     v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
     v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
     v8qi __builtin_ia32_pminub (v8qi, v8qi)
     v4hi __builtin_ia32_pminsw (v4hi, v4hi)
     int __builtin_ia32_pextrw (v4hi, int)
     v4hi __builtin_ia32_pinsrw (v4hi, int, int)
     int __builtin_ia32_pmovmskb (v8qi)
     void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
     void __builtin_ia32_movntq (di *, di)
     void __builtin_ia32_sfence (void)

   The following built-in functions are available when `-msse' is used.
All of them generate the machine instruction that is part of the name.

     int __builtin_ia32_comieq (v4sf, v4sf)
     int __builtin_ia32_comineq (v4sf, v4sf)
     int __builtin_ia32_comilt (v4sf, v4sf)
     int __builtin_ia32_comile (v4sf, v4sf)
     int __builtin_ia32_comigt (v4sf, v4sf)
     int __builtin_ia32_comige (v4sf, v4sf)
     int __builtin_ia32_ucomieq (v4sf, v4sf)
     int __builtin_ia32_ucomineq (v4sf, v4sf)
     int __builtin_ia32_ucomilt (v4sf, v4sf)
     int __builtin_ia32_ucomile (v4sf, v4sf)
     int __builtin_ia32_ucomigt (v4sf, v4sf)
     int __builtin_ia32_ucomige (v4sf, v4sf)
     v4sf __builtin_ia32_addps (v4sf, v4sf)
     v4sf __builtin_ia32_subps (v4sf, v4sf)
     v4sf __builtin_ia32_mulps (v4sf, v4sf)
     v4sf __builtin_ia32_divps (v4sf, v4sf)
     v4sf __builtin_ia32_addss (v4sf, v4sf)
     v4sf __builtin_ia32_subss (v4sf, v4sf)
     v4sf __builtin_ia32_mulss (v4sf, v4sf)
     v4sf __builtin_ia32_divss (v4sf, v4sf)
     v4si __builtin_ia32_cmpeqps (v4sf, v4sf)
     v4si __builtin_ia32_cmpltps (v4sf, v4sf)
     v4si __builtin_ia32_cmpleps (v4sf, v4sf)
     v4si __builtin_ia32_cmpgtps (v4sf, v4sf)
     v4si __builtin_ia32_cmpgeps (v4sf, v4sf)
     v4si __builtin_ia32_cmpunordps (v4sf, v4sf)
     v4si __builtin_ia32_cmpneqps (v4sf, v4sf)
     v4si __builtin_ia32_cmpnltps (v4sf, v4sf)
     v4si __builtin_ia32_cmpnleps (v4sf, v4sf)
     v4si __builtin_ia32_cmpngtps (v4sf, v4sf)
     v4si __builtin_ia32_cmpngeps (v4sf, v4sf)
     v4si __builtin_ia32_cmpordps (v4sf, v4sf)
     v4si __builtin_ia32_cmpeqss (v4sf, v4sf)
     v4si __builtin_ia32_cmpltss (v4sf, v4sf)
     v4si __builtin_ia32_cmpless (v4sf, v4sf)
     v4si __builtin_ia32_cmpgtss (v4sf, v4sf)
     v4si __builtin_ia32_cmpgess (v4sf, v4sf)
     v4si __builtin_ia32_cmpunordss (v4sf, v4sf)
     v4si __builtin_ia32_cmpneqss (v4sf, v4sf)
     v4si __builtin_ia32_cmpnlts (v4sf, v4sf)
     v4si __builtin_ia32_cmpnless (v4sf, v4sf)
     v4si __builtin_ia32_cmpngtss (v4sf, v4sf)
     v4si __builtin_ia32_cmpngess (v4sf, v4sf)
     v4si __builtin_ia32_cmpordss (v4sf, v4sf)
     v4sf __builtin_ia32_maxps (v4sf, v4sf)
     v4sf __builtin_ia32_maxss (v4sf, v4sf)
     v4sf __builtin_ia32_minps (v4sf, v4sf)
     v4sf __builtin_ia32_minss (v4sf, v4sf)
     v4sf __builtin_ia32_andps (v4sf, v4sf)
     v4sf __builtin_ia32_andnps (v4sf, v4sf)
     v4sf __builtin_ia32_orps (v4sf, v4sf)
     v4sf __builtin_ia32_xorps (v4sf, v4sf)
     v4sf __builtin_ia32_movss (v4sf, v4sf)
     v4sf __builtin_ia32_movhlps (v4sf, v4sf)
     v4sf __builtin_ia32_movlhps (v4sf, v4sf)
     v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
     v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
     v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
     v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
     v2si __builtin_ia32_cvtps2pi (v4sf)
     int __builtin_ia32_cvtss2si (v4sf)
     v2si __builtin_ia32_cvttps2pi (v4sf)
     int __builtin_ia32_cvttss2si (v4sf)
     v4sf __builtin_ia32_rcpps (v4sf)
     v4sf __builtin_ia32_rsqrtps (v4sf)
     v4sf __builtin_ia32_sqrtps (v4sf)
     v4sf __builtin_ia32_rcpss (v4sf)
     v4sf __builtin_ia32_rsqrtss (v4sf)
     v4sf __builtin_ia32_sqrtss (v4sf)
     v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
     void __builtin_ia32_movntps (float *, v4sf)
     int __builtin_ia32_movmskps (v4sf)

   The following built-in functions are available when `-msse' is used.

`v4sf __builtin_ia32_loadaps (float *)'
     Generates the `movaps' machine instruction as a load from memory.

`void __builtin_ia32_storeaps (float *, v4sf)'
     Generates the `movaps' machine instruction as a store to memory.

`v4sf __builtin_ia32_loadups (float *)'
     Generates the `movups' machine instruction as a load from memory.

`void __builtin_ia32_storeups (float *, v4sf)'
     Generates the `movups' machine instruction as a store to memory.

`v4sf __builtin_ia32_loadsss (float *)'
     Generates the `movss' machine instruction as a load from memory.

`void __builtin_ia32_storess (float *, v4sf)'
     Generates the `movss' machine instruction as a store to memory.

`v4sf __builtin_ia32_loadhps (v4sf, v2si *)'
     Generates the `movhps' machine instruction as a load from memory.

`v4sf __builtin_ia32_loadlps (v4sf, v2si *)'
     Generates the `movlps' machine instruction as a load from memory

`void __builtin_ia32_storehps (v4sf, v2si *)'
     Generates the `movhps' machine instruction as a store to memory.

`void __builtin_ia32_storelps (v4sf, v2si *)'
     Generates the `movlps' machine instruction as a store to memory.

   The following built-in functions are available when `-m3dnow' is
used.  All of them generate the machine instruction that is part of the
name.

     void __builtin_ia32_femms (void)
     v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
     v2si __builtin_ia32_pf2id (v2sf)
     v2sf __builtin_ia32_pfacc (v2sf, v2sf)
     v2sf __builtin_ia32_pfadd (v2sf, v2sf)
     v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
     v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
     v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
     v2sf __builtin_ia32_pfmax (v2sf, v2sf)
     v2sf __builtin_ia32_pfmin (v2sf, v2sf)
     v2sf __builtin_ia32_pfmul (v2sf, v2sf)
     v2sf __builtin_ia32_pfrcp (v2sf)
     v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
     v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
     v2sf __builtin_ia32_pfrsqrt (v2sf)
     v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf)
     v2sf __builtin_ia32_pfsub (v2sf, v2sf)
     v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
     v2sf __builtin_ia32_pi2fd (v2si)
     v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)

   The following built-in functions are available when both `-m3dnow'
and `-march=athlon' are used.  All of them generate the machine
instruction that is part of the name.

     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)


File: gcc.info,  Node: PowerPC AltiVec Built-in Functions,  Prev: X86 Built-in Functions,  Up: Target Builtins

5.45.2 PowerPC AltiVec Built-in Functions
-----------------------------------------

These built-in functions are available for the PowerPC family of
computers, depending on the command-line switches used.

   The following machine modes are available for use with AltiVec
built-in functions (*note Vector Extensions::): `V4SI' for a vector of
four 32-bit integers, `V4SF' for a vector of four 32-bit floating point
numbers, `V8HI' for a vector of eight 16-bit integers, and `V16QI' for
a vector of sixteen 8-bit integers.

   The following functions are made available by including
`<altivec.h>' and using `-maltivec' and `-mabi=altivec'.  The functions
implement the functionality described in Motorola's AltiVec Programming
Interface Manual.

   _Note:_ Only the `<altivec.h>' interface is supported.  Internally,
GCC uses built-in functions to achieve the functionality in the
aforementioned header file, but they are not supported and are subject
to change without notice.

     vector signed char vec_abs (vector signed char, vector signed char);
     vector signed short vec_abs (vector signed short, vector signed short);
     vector signed int vec_abs (vector signed int, vector signed int);
     vector signed float vec_abs (vector signed float, vector signed float);

     vector signed char vec_abss (vector signed char, vector signed char);
     vector signed short vec_abss (vector signed short, vector signed short);

     vector signed char vec_add (vector signed char, vector signed char);
     vector unsigned char vec_add (vector signed char, vector unsigned char);

     vector unsigned char vec_add (vector unsigned char, vector signed char);

     vector unsigned char vec_add (vector unsigned char,
                                   vector unsigned char);
     vector signed short vec_add (vector signed short, vector signed short);
     vector unsigned short vec_add (vector signed short,
                                    vector unsigned short);
     vector unsigned short vec_add (vector unsigned short,
                                    vector signed short);
     vector unsigned short vec_add (vector unsigned short,
                                    vector unsigned short);
     vector signed int vec_add (vector signed int, vector signed int);
     vector unsigned int vec_add (vector signed int, vector unsigned int);
     vector unsigned int vec_add (vector unsigned int, vector signed int);
     vector unsigned int vec_add (vector unsigned int, vector unsigned int);
     vector float vec_add (vector float, vector float);

     vector unsigned int vec_addc (vector unsigned int, vector unsigned int);

     vector unsigned char vec_adds (vector signed char,
                                    vector unsigned char);
     vector unsigned char vec_adds (vector unsigned char,
                                    vector signed char);
     vector unsigned char vec_adds (vector unsigned char,
                                    vector unsigned char);
     vector signed char vec_adds (vector signed char, vector signed char);
     vector unsigned short vec_adds (vector signed short,
                                     vector unsigned short);
     vector unsigned short vec_adds (vector unsigned short,
                                     vector signed short);
     vector unsigned short vec_adds (vector unsigned short,
                                     vector unsigned short);
     vector signed short vec_adds (vector signed short, vector signed short);

     vector unsigned int vec_adds (vector signed int, vector unsigned int);
     vector unsigned int vec_adds (vector unsigned int, vector signed int);
     vector unsigned int vec_adds (vector unsigned int, vector unsigned int);

     vector signed int vec_adds (vector signed int, vector signed int);

     vector float vec_and (vector float, vector float);
     vector float vec_and (vector float, vector signed int);
     vector float vec_and (vector signed int, vector float);
     vector signed int vec_and (vector signed int, vector signed int);
     vector unsigned int vec_and (vector signed int, vector unsigned int);
     vector unsigned int vec_and (vector unsigned int, vector signed int);
     vector unsigned int vec_and (vector unsigned int, vector unsigned int);
     vector signed short vec_and (vector signed short, vector signed short);
     vector unsigned short vec_and (vector signed short,
                                    vector unsigned short);
     vector unsigned short vec_and (vector unsigned short,
                                    vector signed short);
     vector unsigned short vec_and (vector unsigned short,
                                    vector unsigned short);
     vector signed char vec_and (vector signed char, vector signed char);
     vector unsigned char vec_and (vector signed char, vector unsigned char);

     vector unsigned char vec_and (vector unsigned char, vector signed char);

     vector unsigned char vec_and (vector unsigned char,
                                   vector unsigned char);

     vector float vec_andc (vector float, vector float);
     vector float vec_andc (vector float, vector signed int);
     vector float vec_andc (vector signed int, vector float);
     vector signed int vec_andc (vector signed int, vector signed int);
     vector unsigned int vec_andc (vector signed int, vector unsigned int);
     vector unsigned int vec_andc (vector unsigned int, vector signed int);
     vector unsigned int vec_andc (vector unsigned int, vector unsigned int);

     vector signed short vec_andc (vector signed short, vector signed short);

     vector unsigned short vec_andc (vector signed short,
                                     vector unsigned short);
     vector unsigned short vec_andc (vector unsigned short,
                                     vector signed short);
     vector unsigned short vec_andc (vector unsigned short,
                                     vector unsigned short);
     vector signed char vec_andc (vector signed char, vector signed char);
     vector unsigned char vec_andc (vector signed char,
                                    vector unsigned char);
     vector unsigned char vec_andc (vector unsigned char,
                                    vector signed char);
     vector unsigned char vec_andc (vector unsigned char,
                                    vector unsigned char);

     vector unsigned char vec_avg (vector unsigned char,
                                   vector unsigned char);
     vector signed char vec_avg (vector signed char, vector signed char);
     vector unsigned short vec_avg (vector unsigned short,
                                    vector unsigned short);
     vector signed short vec_avg (vector signed short, vector signed short);
     vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
     vector signed int vec_avg (vector signed int, vector signed int);

     vector float vec_ceil (vector float);

     vector signed int vec_cmpb (vector float, vector float);

     vector signed char vec_cmpeq (vector signed char, vector signed char);
     vector signed char vec_cmpeq (vector unsigned char,
                                   vector unsigned char);
     vector signed short vec_cmpeq (vector signed short,
                                    vector signed short);
     vector signed short vec_cmpeq (vector unsigned short,
                                    vector unsigned short);
     vector signed int vec_cmpeq (vector signed int, vector signed int);
     vector signed int vec_cmpeq (vector unsigned int, vector unsigned int);
     vector signed int vec_cmpeq (vector float, vector float);

     vector signed int vec_cmpge (vector float, vector float);

     vector signed char vec_cmpgt (vector unsigned char,
                                   vector unsigned char);
     vector signed char vec_cmpgt (vector signed char, vector signed char);
     vector signed short vec_cmpgt (vector unsigned short,
                                    vector unsigned short);
     vector signed short vec_cmpgt (vector signed short,
                                    vector signed short);
     vector signed int vec_cmpgt (vector unsigned int, vector unsigned int);
     vector signed int vec_cmpgt (vector signed int, vector signed int);
     vector signed int vec_cmpgt (vector float, vector float);

     vector signed int vec_cmple (vector float, vector float);

     vector signed char vec_cmplt (vector unsigned char,
                                   vector unsigned char);
     vector signed char vec_cmplt (vector signed char, vector signed char);
     vector signed short vec_cmplt (vector unsigned short,
                                    vector unsigned short);
     vector signed short vec_cmplt (vector signed short,
                                    vector signed short);
     vector signed int vec_cmplt (vector unsigned int, vector unsigned int);
     vector signed int vec_cmplt (vector signed int, vector signed int);
     vector signed int vec_cmplt (vector float, vector float);

     vector float vec_ctf (vector unsigned int, const char);
     vector float vec_ctf (vector signed int, const char);

     vector signed int vec_cts (vector float, const char);

     vector unsigned int vec_ctu (vector float, const char);

     void vec_dss (const char);

     void vec_dssall (void);

     void vec_dst (void *, int, const char);

     void vec_dstst (void *, int, const char);

     void vec_dststt (void *, int, const char);

     void vec_dstt (void *, int, const char);

     vector float vec_expte (vector float, vector float);

     vector float vec_floor (vector float, vector float);

     vector float vec_ld (int, vector float *);
     vector float vec_ld (int, float *):
     vector signed int vec_ld (int, int *);
     vector signed int vec_ld (int, vector signed int *);
     vector unsigned int vec_ld (int, vector unsigned int *);
     vector unsigned int vec_ld (int, unsigned int *);
     vector signed short vec_ld (int, short *, vector signed short *);
     vector unsigned short vec_ld (int, unsigned short *,
                                   vector unsigned short *);
     vector signed char vec_ld (int, signed char *);
     vector signed char vec_ld (int, vector signed char *);
     vector unsigned char vec_ld (int, unsigned char *);
     vector unsigned char vec_ld (int, vector unsigned char *);

     vector signed char vec_lde (int, signed char *);
     vector unsigned char vec_lde (int, unsigned char *);
     vector signed short vec_lde (int, short *);
     vector unsigned short vec_lde (int, unsigned short *);
     vector float vec_lde (int, float *);
     vector signed int vec_lde (int, int *);
     vector unsigned int vec_lde (int, unsigned int *);

     void float vec_ldl (int, float *);
     void float vec_ldl (int, vector float *);
     void signed int vec_ldl (int, vector signed int *);
     void signed int vec_ldl (int, int *);
     void unsigned int vec_ldl (int, unsigned int *);
     void unsigned int vec_ldl (int, vector unsigned int *);
     void signed short vec_ldl (int, vector signed short *);
     void signed short vec_ldl (int, short *);
     void unsigned short vec_ldl (int, vector unsigned short *);
     void unsigned short vec_ldl (int, unsigned short *);
     void signed char vec_ldl (int, vector signed char *);
     void signed char vec_ldl (int, signed char *);
     void unsigned char vec_ldl (int, vector unsigned char *);
     void unsigned char vec_ldl (int, unsigned char *);

     vector float vec_loge (vector float);

     vector unsigned char vec_lvsl (int, void *, int *);

     vector unsigned char vec_lvsr (int, void *, int *);

     vector float vec_madd (vector float, vector float, vector float);

     vector signed short vec_madds (vector signed short, vector signed short,
                                    vector signed short);

     vector unsigned char vec_max (vector signed char, vector unsigned char);

     vector unsigned char vec_max (vector unsigned char, vector signed char);

     vector unsigned char vec_max (vector unsigned char,
                                   vector unsigned char);
     vector signed char vec_max (vector signed char, vector signed char);
     vector unsigned short vec_max (vector signed short,
                                    vector unsigned short);
     vector unsigned short vec_max (vector unsigned short,
                                    vector signed short);
     vector unsigned short vec_max (vector unsigned short,
                                    vector unsigned short);
     vector signed short vec_max (vector signed short, vector signed short);
     vector unsigned int vec_max (vector signed int, vector unsigned int);
     vector unsigned int vec_max (vector unsigned int, vector signed int);
     vector unsigned int vec_max (vector unsigned int, vector unsigned int);
     vector signed int vec_max (vector signed int, vector signed int);
     vector float vec_max (vector float, vector float);

     vector signed char vec_mergeh (vector signed char, vector signed char);
     vector unsigned char vec_mergeh (vector unsigned char,
                                      vector unsigned char);
     vector signed short vec_mergeh (vector signed short,
                                     vector signed short);
     vector unsigned short vec_mergeh (vector unsigned short,
                                       vector unsigned short);
     vector float vec_mergeh (vector float, vector float);
     vector signed int vec_mergeh (vector signed int, vector signed int);
     vector unsigned int vec_mergeh (vector unsigned int,
                                     vector unsigned int);

     vector signed char vec_mergel (vector signed char, vector signed char);
     vector unsigned char vec_mergel (vector unsigned char,
                                      vector unsigned char);
     vector signed short vec_mergel (vector signed short,
                                     vector signed short);
     vector unsigned short vec_mergel (vector unsigned short,
                                       vector unsigned short);
     vector float vec_mergel (vector float, vector float);
     vector signed int vec_mergel (vector signed int, vector signed int);
     vector unsigned int vec_mergel (vector unsigned int,
                                     vector unsigned int);

     vector unsigned short vec_mfvscr (void);

     vector unsigned char vec_min (vector signed char, vector unsigned char);

     vector unsigned char vec_min (vector unsigned char, vector signed char);

     vector unsigned char vec_min (vector unsigned char,
                                   vector unsigned char);
     vector signed char vec_min (vector signed char, vector signed char);
     vector unsigned short vec_min (vector signed short,
                                    vector unsigned short);
     vector unsigned short vec_min (vector unsigned short,
                                    vector signed short);
     vector unsigned short vec_min (vector unsigned short,
                                    vector unsigned short);
     vector signed short vec_min (vector signed short, vector signed short);
     vector unsigned int vec_min (vector signed int, vector unsigned int);
     vector unsigned int vec_min (vector unsigned int, vector signed int);
     vector unsigned int vec_min (vector unsigned int, vector unsigned int);
     vector signed int vec_min (vector signed int, vector signed int);
     vector float vec_min (vector float, vector float);

     vector signed short vec_mladd (vector signed short, vector signed short,
                                    vector signed short);
     vector signed short vec_mladd (vector signed short,
                                    vector unsigned short,
                                    vector unsigned short);
     vector signed short vec_mladd (vector unsigned short,
                                    vector signed short,
                                    vector signed short);
     vector unsigned short vec_mladd (vector unsigned short,
                                      vector unsigned short,
                                      vector unsigned short);

     vector signed short vec_mradds (vector signed short,
                                     vector signed short,
                                     vector signed short);

     vector unsigned int vec_msum (vector unsigned char,
                                   vector unsigned char,
                                   vector unsigned int);
     vector signed int vec_msum (vector signed char, vector unsigned char,
                                 vector signed int);
     vector unsigned int vec_msum (vector unsigned short,
                                   vector unsigned short,
                                   vector unsigned int);
     vector signed int vec_msum (vector signed short, vector signed short,
                                 vector signed int);

     vector unsigned int vec_msums (vector unsigned short,
                                    vector unsigned short,
                                    vector unsigned int);
     vector signed int vec_msums (vector signed short, vector signed short,
                                  vector signed int);

     void vec_mtvscr (vector signed int);
     void vec_mtvscr (vector unsigned int);
     void vec_mtvscr (vector signed short);
     void vec_mtvscr (vector unsigned short);
     void vec_mtvscr (vector signed char);
     void vec_mtvscr (vector unsigned char);

     vector unsigned short vec_mule (vector unsigned char,
                                     vector unsigned char);
     vector signed short vec_mule (vector signed char, vector signed char);
     vector unsigned int vec_mule (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_mule (vector signed short, vector signed short);

     vector unsigned short vec_mulo (vector unsigned char,
                                     vector unsigned char);
     vector signed short vec_mulo (vector signed char, vector signed char);
     vector unsigned int vec_mulo (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_mulo (vector signed short, vector signed short);

     vector float vec_nmsub (vector float, vector float, vector float);

     vector float vec_nor (vector float, vector float);
     vector signed int vec_nor (vector signed int, vector signed int);
     vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
     vector signed short vec_nor (vector signed short, vector signed short);
     vector unsigned short vec_nor (vector unsigned short,
                                    vector unsigned short);
     vector signed char vec_nor (vector signed char, vector signed char);
     vector unsigned char vec_nor (vector unsigned char,
                                   vector unsigned char);

     vector float vec_or (vector float, vector float);
     vector float vec_or (vector float, vector signed int);
     vector float vec_or (vector signed int, vector float);
     vector signed int vec_or (vector signed int, vector signed int);
     vector unsigned int vec_or (vector signed int, vector unsigned int);
     vector unsigned int vec_or (vector unsigned int, vector signed int);
     vector unsigned int vec_or (vector unsigned int, vector unsigned int);
     vector signed short vec_or (vector signed short, vector signed short);
     vector unsigned short vec_or (vector signed short,
                                   vector unsigned short);
     vector unsigned short vec_or (vector unsigned short,
                                   vector signed short);
     vector unsigned short vec_or (vector unsigned short,
                                   vector unsigned short);
     vector signed char vec_or (vector signed char, vector signed char);
     vector unsigned char vec_or (vector signed char, vector unsigned char);
     vector unsigned char vec_or (vector unsigned char, vector signed char);
     vector unsigned char vec_or (vector unsigned char,
                                  vector unsigned char);

     vector signed char vec_pack (vector signed short, vector signed short);
     vector unsigned char vec_pack (vector unsigned short,
                                    vector unsigned short);
     vector signed short vec_pack (vector signed int, vector signed int);
     vector unsigned short vec_pack (vector unsigned int,
                                     vector unsigned int);

     vector signed short vec_packpx (vector unsigned int,
                                     vector unsigned int);

     vector unsigned char vec_packs (vector unsigned short,
                                     vector unsigned short);
     vector signed char vec_packs (vector signed short, vector signed short);

     vector unsigned short vec_packs (vector unsigned int,
                                      vector unsigned int);
     vector signed short vec_packs (vector signed int, vector signed int);

     vector unsigned char vec_packsu (vector unsigned short,
                                      vector unsigned short);
     vector unsigned char vec_packsu (vector signed short,
                                      vector signed short);
     vector unsigned short vec_packsu (vector unsigned int,
                                       vector unsigned int);
     vector unsigned short vec_packsu (vector signed int, vector signed int);

     vector float vec_perm (vector float, vector float,
                            vector unsigned char);
     vector signed int vec_perm (vector signed int, vector signed int,
                                 vector unsigned char);
     vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
                                   vector unsigned char);
     vector signed short vec_perm (vector signed short, vector signed short,
                                   vector unsigned char);
     vector unsigned short vec_perm (vector unsigned short,
                                     vector unsigned short,
                                     vector unsigned char);
     vector signed char vec_perm (vector signed char, vector signed char,
                                  vector unsigned char);
     vector unsigned char vec_perm (vector unsigned char,
                                    vector unsigned char,
                                    vector unsigned char);

     vector float vec_re (vector float);

     vector signed char vec_rl (vector signed char, vector unsigned char);
     vector unsigned char vec_rl (vector unsigned char,
                                  vector unsigned char);
     vector signed short vec_rl (vector signed short, vector unsigned short);

     vector unsigned short vec_rl (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_rl (vector signed int, vector unsigned int);
     vector unsigned int vec_rl (vector unsigned int, vector unsigned int);

     vector float vec_round (vector float);

     vector float vec_rsqrte (vector float);

     vector float vec_sel (vector float, vector float, vector signed int);
     vector float vec_sel (vector float, vector float, vector unsigned int);
     vector signed int vec_sel (vector signed int, vector signed int,
                                vector signed int);
     vector signed int vec_sel (vector signed int, vector signed int,
                                vector unsigned int);
     vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
                                  vector signed int);
     vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
                                  vector unsigned int);
     vector signed short vec_sel (vector signed short, vector signed short,
                                  vector signed short);
     vector signed short vec_sel (vector signed short, vector signed short,
                                  vector unsigned short);
     vector unsigned short vec_sel (vector unsigned short,
                                    vector unsigned short,
                                    vector signed short);
     vector unsigned short vec_sel (vector unsigned short,
                                    vector unsigned short,
                                    vector unsigned short);
     vector signed char vec_sel (vector signed char, vector signed char,
                                 vector signed char);
     vector signed char vec_sel (vector signed char, vector signed char,
                                 vector unsigned char);
     vector unsigned char vec_sel (vector unsigned char,
                                   vector unsigned char,
                                   vector signed char);
     vector unsigned char vec_sel (vector unsigned char,
                                   vector unsigned char,
                                   vector unsigned char);

     vector signed char vec_sl (vector signed char, vector unsigned char);
     vector unsigned char vec_sl (vector unsigned char,
                                  vector unsigned char);
     vector signed short vec_sl (vector signed short, vector unsigned short);

     vector unsigned short vec_sl (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_sl (vector signed int, vector unsigned int);
     vector unsigned int vec_sl (vector unsigned int, vector unsigned int);

     vector float vec_sld (vector float, vector float, const char);
     vector signed int vec_sld (vector signed int, vector signed int,
                                const char);
     vector unsigned int vec_sld (vector unsigned int, vector unsigned int,
                                  const char);
     vector signed short vec_sld (vector signed short, vector signed short,
                                  const char);
     vector unsigned short vec_sld (vector unsigned short,
                                    vector unsigned short, const char);
     vector signed char vec_sld (vector signed char, vector signed char,
                                 const char);
     vector unsigned char vec_sld (vector unsigned char,
                                   vector unsigned char,
                                   const char);

     vector signed int vec_sll (vector signed int, vector unsigned int);
     vector signed int vec_sll (vector signed int, vector unsigned short);
     vector signed int vec_sll (vector signed int, vector unsigned char);
     vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
     vector unsigned int vec_sll (vector unsigned int,
                                  vector unsigned short);
     vector unsigned int vec_sll (vector unsigned int, vector unsigned char);

     vector signed short vec_sll (vector signed short, vector unsigned int);
     vector signed short vec_sll (vector signed short,
                                  vector unsigned short);
     vector signed short vec_sll (vector signed short, vector unsigned char);

     vector unsigned short vec_sll (vector unsigned short,
                                    vector unsigned int);
     vector unsigned short vec_sll (vector unsigned short,
                                    vector unsigned short);
     vector unsigned short vec_sll (vector unsigned short,
                                    vector unsigned char);
     vector signed char vec_sll (vector signed char, vector unsigned int);
     vector signed char vec_sll (vector signed char, vector unsigned short);
     vector signed char vec_sll (vector signed char, vector unsigned char);
     vector unsigned char vec_sll (vector unsigned char,
                                   vector unsigned int);
     vector unsigned char vec_sll (vector unsigned char,
                                   vector unsigned short);
     vector unsigned char vec_sll (vector unsigned char,
                                   vector unsigned char);

     vector float vec_slo (vector float, vector signed char);
     vector float vec_slo (vector float, vector unsigned char);
     vector signed int vec_slo (vector signed int, vector signed char);
     vector signed int vec_slo (vector signed int, vector unsigned char);
     vector unsigned int vec_slo (vector unsigned int, vector signed char);
     vector unsigned int vec_slo (vector unsigned int, vector unsigned char);

     vector signed short vec_slo (vector signed short, vector signed char);
     vector signed short vec_slo (vector signed short, vector unsigned char);

     vector unsigned short vec_slo (vector unsigned short,
                                    vector signed char);
     vector unsigned short vec_slo (vector unsigned short,
                                    vector unsigned char);
     vector signed char vec_slo (vector signed char, vector signed char);
     vector signed char vec_slo (vector signed char, vector unsigned char);
     vector unsigned char vec_slo (vector unsigned char, vector signed char);

     vector unsigned char vec_slo (vector unsigned char,
                                   vector unsigned char);

     vector signed char vec_splat (vector signed char, const char);
     vector unsigned char vec_splat (vector unsigned char, const char);
     vector signed short vec_splat (vector signed short, const char);
     vector unsigned short vec_splat (vector unsigned short, const char);
     vector float vec_splat (vector float, const char);
     vector signed int vec_splat (vector signed int, const char);
     vector unsigned int vec_splat (vector unsigned int, const char);

     vector signed char vec_splat_s8 (const char);

     vector signed short vec_splat_s16 (const char);

     vector signed int vec_splat_s32 (const char);

     vector unsigned char vec_splat_u8 (const char);

     vector unsigned short vec_splat_u16 (const char);

     vector unsigned int vec_splat_u32 (const char);

     vector signed char vec_sr (vector signed char, vector unsigned char);
     vector unsigned char vec_sr (vector unsigned char,
                                  vector unsigned char);
     vector signed short vec_sr (vector signed short, vector unsigned short);

     vector unsigned short vec_sr (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_sr (vector signed int, vector unsigned int);
     vector unsigned int vec_sr (vector unsigned int, vector unsigned int);

     vector signed char vec_sra (vector signed char, vector unsigned char);
     vector unsigned char vec_sra (vector unsigned char,
                                   vector unsigned char);
     vector signed short vec_sra (vector signed short,
                                  vector unsigned short);
     vector unsigned short vec_sra (vector unsigned short,
                                    vector unsigned short);
     vector signed int vec_sra (vector signed int, vector unsigned int);
     vector unsigned int vec_sra (vector unsigned int, vector unsigned int);

     vector signed int vec_srl (vector signed int, vector unsigned int);
     vector signed int vec_srl (vector signed int, vector unsigned short);
     vector signed int vec_srl (vector signed int, vector unsigned char);
     vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
     vector unsigned int vec_srl (vector unsigned int,
                                  vector unsigned short);
     vector unsigned int vec_srl (vector unsigned int, vector unsigned char);

     vector signed short vec_srl (vector signed short, vector unsigned int);
     vector signed short vec_srl (vector signed short,
                                  vector unsigned short);
     vector signed short vec_srl (vector signed short, vector unsigned char);

     vector unsigned short vec_srl (vector unsigned short,
                                    vector unsigned int);
     vector unsigned short vec_srl (vector unsigned short,
                                    vector unsigned short);
     vector unsigned short vec_srl (vector unsigned short,
                                    vector unsigned char);
     vector signed char vec_srl (vector signed char, vector unsigned int);
     vector signed char vec_srl (vector signed char, vector unsigned short);
     vector signed char vec_srl (vector signed char, vector unsigned char);
     vector unsigned char vec_srl (vector unsigned char,
                                   vector unsigned int);
     vector unsigned char vec_srl (vector unsigned char,
                                   vector unsigned short);
     vector unsigned char vec_srl (vector unsigned char,
                                   vector unsigned char);

     vector float vec_sro (vector float, vector signed char);
     vector float vec_sro (vector float, vector unsigned char);
     vector signed int vec_sro (vector signed int, vector signed char);
     vector signed int vec_sro (vector signed int, vector unsigned char);
     vector unsigned int vec_sro (vector unsigned int, vector signed char);
     vector unsigned int vec_sro (vector unsigned int, vector unsigned char);

     vector signed short vec_sro (vector signed short, vector signed char);
     vector signed short vec_sro (vector signed short, vector unsigned char);

     vector unsigned short vec_sro (vector unsigned short,
                                    vector signed char);
     vector unsigned short vec_sro (vector unsigned short,
                                    vector unsigned char);
     vector signed char vec_sro (vector signed char, vector signed char);
     vector signed char vec_sro (vector signed char, vector unsigned char);
     vector unsigned char vec_sro (vector unsigned char, vector signed char);

     vector unsigned char vec_sro (vector unsigned char,
                                   vector unsigned char);

     void vec_st (vector float, int, float *);
     void vec_st (vector float, int, vector float *);
     void vec_st (vector signed int, int, int *);
     void vec_st (vector signed int, int, unsigned int *);
     void vec_st (vector unsigned int, int, unsigned int *);
     void vec_st (vector unsigned int, int, vector unsigned int *);
     void vec_st (vector signed short, int, short *);
     void vec_st (vector signed short, int, vector unsigned short *);
     void vec_st (vector signed short, int, vector signed short *);
     void vec_st (vector unsigned short, int, unsigned short *);
     void vec_st (vector unsigned short, int, vector unsigned short *);
     void vec_st (vector signed char, int, signed char *);
     void vec_st (vector signed char, int, unsigned char *);
     void vec_st (vector signed char, int, vector signed char *);
     void vec_st (vector unsigned char, int, unsigned char *);
     void vec_st (vector unsigned char, int, vector unsigned char *);

     void vec_ste (vector signed char, int, unsigned char *);
     void vec_ste (vector signed char, int, signed char *);
     void vec_ste (vector unsigned char, int, unsigned char *);
     void vec_ste (vector signed short, int, short *);
     void vec_ste (vector signed short, int, unsigned short *);
     void vec_ste (vector unsigned short, int, void *);
     void vec_ste (vector signed int, int, unsigned int *);
     void vec_ste (vector signed int, int, int *);
     void vec_ste (vector unsigned int, int, unsigned int *);
     void vec_ste (vector float, int, float *);

     void vec_stl (vector float, int, vector float *);
     void vec_stl (vector float, int, float *);
     void vec_stl (vector signed int, int, vector signed int *);
     void vec_stl (vector signed int, int, int *);
     void vec_stl (vector signed int, int, unsigned int *);
     void vec_stl (vector unsigned int, int, vector unsigned int *);
     void vec_stl (vector unsigned int, int, unsigned int *);
     void vec_stl (vector signed short, int, short *);
     void vec_stl (vector signed short, int, unsigned short *);
     void vec_stl (vector signed short, int, vector signed short *);
     void vec_stl (vector unsigned short, int, unsigned short *);
     void vec_stl (vector unsigned short, int, vector signed short *);
     void vec_stl (vector signed char, int, signed char *);
     void vec_stl (vector signed char, int, unsigned char *);
     void vec_stl (vector signed char, int, vector signed char *);
     void vec_stl (vector unsigned char, int, unsigned char *);
     void vec_stl (vector unsigned char, int, vector unsigned char *);

     vector signed char vec_sub (vector signed char, vector signed char);
     vector unsigned char vec_sub (vector signed char, vector unsigned char);

     vector unsigned char vec_sub (vector unsigned char, vector signed char);

     vector unsigned char vec_sub (vector unsigned char,
                                   vector unsigned char);
     vector signed short vec_sub (vector signed short, vector signed short);
     vector unsigned short vec_sub (vector signed short,
                                    vector unsigned short);
     vector unsigned short vec_sub (vector unsigned short,
                                    vector signed short);
     vector unsigned short vec_sub (vector unsigned short,
                                    vector unsigned short);
     vector signed int vec_sub (vector signed int, vector signed int);
     vector unsigned int vec_sub (vector signed int, vector unsigned int);
     vector unsigned int vec_sub (vector unsigned int, vector signed int);
     vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
     vector float vec_sub (vector float, vector float);

     vector unsigned int vec_subc (vector unsigned int, vector unsigned int);

     vector unsigned char vec_subs (vector signed char,
                                    vector unsigned char);
     vector unsigned char vec_subs (vector unsigned char,
                                    vector signed char);
     vector unsigned char vec_subs (vector unsigned char,
                                    vector unsigned char);
     vector signed char vec_subs (vector signed char, vector signed char);
     vector unsigned short vec_subs (vector signed short,
                                     vector unsigned short);
     vector unsigned short vec_subs (vector unsigned short,
                                     vector signed short);
     vector unsigned short vec_subs (vector unsigned short,
                                     vector unsigned short);
     vector signed short vec_subs (vector signed short, vector signed short);

     vector unsigned int vec_subs (vector signed int, vector unsigned int);
     vector unsigned int vec_subs (vector unsigned int, vector signed int);
     vector unsigned int vec_subs (vector unsigned int, vector unsigned int);

     vector signed int vec_subs (vector signed int, vector signed int);

     vector unsigned int vec_sum4s (vector unsigned char,
                                    vector unsigned int);
     vector signed int vec_sum4s (vector signed char, vector signed int);
     vector signed int vec_sum4s (vector signed short, vector signed int);

     vector signed int vec_sum2s (vector signed int, vector signed int);

     vector signed int vec_sums (vector signed int, vector signed int);

     vector float vec_trunc (vector float);

     vector signed short vec_unpackh (vector signed char);
     vector unsigned int vec_unpackh (vector signed short);
     vector signed int vec_unpackh (vector signed short);

     vector signed short vec_unpackl (vector signed char);
     vector unsigned int vec_unpackl (vector signed short);
     vector signed int vec_unpackl (vector signed short);

     vector float vec_xor (vector float, vector float);
     vector float vec_xor (vector float, vector signed int);
     vector float vec_xor (vector signed int, vector float);
     vector signed int vec_xor (vector signed int, vector signed int);
     vector unsigned int vec_xor (vector signed int, vector unsigned int);
     vector unsigned int vec_xor (vector unsigned int, vector signed int);
     vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
     vector signed short vec_xor (vector signed short, vector signed short);
     vector unsigned short vec_xor (vector signed short,
                                    vector unsigned short);
     vector unsigned short vec_xor (vector unsigned short,
                                    vector signed short);
     vector unsigned short vec_xor (vector unsigned short,
                                    vector unsigned short);
     vector signed char vec_xor (vector signed char, vector signed char);
     vector unsigned char vec_xor (vector signed char, vector unsigned char);

     vector unsigned char vec_xor (vector unsigned char, vector signed char);

     vector unsigned char vec_xor (vector unsigned char,
                                   vector unsigned char);

     vector signed int vec_all_eq (vector signed char, vector unsigned char);

     vector signed int vec_all_eq (vector signed char, vector signed char);
     vector signed int vec_all_eq (vector unsigned char, vector signed char);

     vector signed int vec_all_eq (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_all_eq (vector signed short,
                                   vector unsigned short);
     vector signed int vec_all_eq (vector signed short, vector signed short);

     vector signed int vec_all_eq (vector unsigned short,
                                   vector signed short);
     vector signed int vec_all_eq (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_all_eq (vector signed int, vector unsigned int);
     vector signed int vec_all_eq (vector signed int, vector signed int);
     vector signed int vec_all_eq (vector unsigned int, vector signed int);
     vector signed int vec_all_eq (vector unsigned int, vector unsigned int);

     vector signed int vec_all_eq (vector float, vector float);

     vector signed int vec_all_ge (vector signed char, vector unsigned char);

     vector signed int vec_all_ge (vector unsigned char, vector signed char);

     vector signed int vec_all_ge (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_all_ge (vector signed char, vector signed char);
     vector signed int vec_all_ge (vector signed short,
                                   vector unsigned short);
     vector signed int vec_all_ge (vector unsigned short,
                                   vector signed short);
     vector signed int vec_all_ge (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_all_ge (vector signed short, vector signed short);

     vector signed int vec_all_ge (vector signed int, vector unsigned int);
     vector signed int vec_all_ge (vector unsigned int, vector signed int);
     vector signed int vec_all_ge (vector unsigned int, vector unsigned int);

     vector signed int vec_all_ge (vector signed int, vector signed int);
     vector signed int vec_all_ge (vector float, vector float);

     vector signed int vec_all_gt (vector signed char, vector unsigned char);

     vector signed int vec_all_gt (vector unsigned char, vector signed char);

     vector signed int vec_all_gt (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_all_gt (vector signed char, vector signed char);
     vector signed int vec_all_gt (vector signed short,
                                   vector unsigned short);
     vector signed int vec_all_gt (vector unsigned short,
                                   vector signed short);
     vector signed int vec_all_gt (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_all_gt (vector signed short, vector signed short);

     vector signed int vec_all_gt (vector signed int, vector unsigned int);
     vector signed int vec_all_gt (vector unsigned int, vector signed int);
     vector signed int vec_all_gt (vector unsigned int, vector unsigned int);

     vector signed int vec_all_gt (vector signed int, vector signed int);
     vector signed int vec_all_gt (vector float, vector float);

     vector signed int vec_all_in (vector float, vector float);

     vector signed int vec_all_le (vector signed char, vector unsigned char);

     vector signed int vec_all_le (vector unsigned char, vector signed char);

     vector signed int vec_all_le (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_all_le (vector signed char, vector signed char);
     vector signed int vec_all_le (vector signed short,
                                   vector unsigned short);
     vector signed int vec_all_le (vector unsigned short,
                                   vector signed short);
     vector signed int vec_all_le (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_all_le (vector signed short, vector signed short);

     vector signed int vec_all_le (vector signed int, vector unsigned int);
     vector signed int vec_all_le (vector unsigned int, vector signed int);
     vector signed int vec_all_le (vector unsigned int, vector unsigned int);

     vector signed int vec_all_le (vector signed int, vector signed int);
     vector signed int vec_all_le (vector float, vector float);

     vector signed int vec_all_lt (vector signed char, vector unsigned char);

     vector signed int vec_all_lt (vector unsigned char, vector signed char);

     vector signed int vec_all_lt (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_all_lt (vector signed char, vector signed char);
     vector signed int vec_all_lt (vector signed short,
                                   vector unsigned short);
     vector signed int vec_all_lt (vector unsigned short,
                                   vector signed short);
     vector signed int vec_all_lt (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_all_lt (vector signed short, vector signed short);

     vector signed int vec_all_lt (vector signed int, vector unsigned int);
     vector signed int vec_all_lt (vector unsigned int, vector signed int);
     vector signed int vec_all_lt (vector unsigned int, vector unsigned int);

     vector signed int vec_all_lt (vector signed int, vector signed int);
     vector signed int vec_all_lt (vector float, vector float);

     vector signed int vec_all_nan (vector float);

     vector signed int vec_all_ne (vector signed char, vector unsigned char);

     vector signed int vec_all_ne (vector signed char, vector signed char);
     vector signed int vec_all_ne (vector unsigned char, vector signed char);

     vector signed int vec_all_ne (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_all_ne (vector signed short,
                                   vector unsigned short);
     vector signed int vec_all_ne (vector signed short, vector signed short);

     vector signed int vec_all_ne (vector unsigned short,
                                   vector signed short);
     vector signed int vec_all_ne (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_all_ne (vector signed int, vector unsigned int);
     vector signed int vec_all_ne (vector signed int, vector signed int);
     vector signed int vec_all_ne (vector unsigned int, vector signed int);
     vector signed int vec_all_ne (vector unsigned int, vector unsigned int);

     vector signed int vec_all_ne (vector float, vector float);

     vector signed int vec_all_nge (vector float, vector float);

     vector signed int vec_all_ngt (vector float, vector float);

     vector signed int vec_all_nle (vector float, vector float);

     vector signed int vec_all_nlt (vector float, vector float);

     vector signed int vec_all_numeric (vector float);

     vector signed int vec_any_eq (vector signed char, vector unsigned char);

     vector signed int vec_any_eq (vector signed char, vector signed char);
     vector signed int vec_any_eq (vector unsigned char, vector signed char);

     vector signed int vec_any_eq (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_any_eq (vector signed short,
                                   vector unsigned short);
     vector signed int vec_any_eq (vector signed short, vector signed short);

     vector signed int vec_any_eq (vector unsigned short,
                                   vector signed short);
     vector signed int vec_any_eq (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_any_eq (vector signed int, vector unsigned int);
     vector signed int vec_any_eq (vector signed int, vector signed int);
     vector signed int vec_any_eq (vector unsigned int, vector signed int);
     vector signed int vec_any_eq (vector unsigned int, vector unsigned int);

     vector signed int vec_any_eq (vector float, vector float);

     vector signed int vec_any_ge (vector signed char, vector unsigned char);

     vector signed int vec_any_ge (vector unsigned char, vector signed char);

     vector signed int vec_any_ge (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_any_ge (vector signed char, vector signed char);
     vector signed int vec_any_ge (vector signed short,
                                   vector unsigned short);
     vector signed int vec_any_ge (vector unsigned short,
                                   vector signed short);
     vector signed int vec_any_ge (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_any_ge (vector signed short, vector signed short);

     vector signed int vec_any_ge (vector signed int, vector unsigned int);
     vector signed int vec_any_ge (vector unsigned int, vector signed int);
     vector signed int vec_any_ge (vector unsigned int, vector unsigned int);

     vector signed int vec_any_ge (vector signed int, vector signed int);
     vector signed int vec_any_ge (vector float, vector float);

     vector signed int vec_any_gt (vector signed char, vector unsigned char);

     vector signed int vec_any_gt (vector unsigned char, vector signed char);

     vector signed int vec_any_gt (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_any_gt (vector signed char, vector signed char);
     vector signed int vec_any_gt (vector signed short,
                                   vector unsigned short);
     vector signed int vec_any_gt (vector unsigned short,
                                   vector signed short);
     vector signed int vec_any_gt (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_any_gt (vector signed short, vector signed short);

     vector signed int vec_any_gt (vector signed int, vector unsigned int);
     vector signed int vec_any_gt (vector unsigned int, vector signed int);
     vector signed int vec_any_gt (vector unsigned int, vector unsigned int);

     vector signed int vec_any_gt (vector signed int, vector signed int);
     vector signed int vec_any_gt (vector float, vector float);

     vector signed int vec_any_le (vector signed char, vector unsigned char);

     vector signed int vec_any_le (vector unsigned char, vector signed char);

     vector signed int vec_any_le (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_any_le (vector signed char, vector signed char);
     vector signed int vec_any_le (vector signed short,
                                   vector unsigned short);
     vector signed int vec_any_le (vector unsigned short,
                                   vector signed short);
     vector signed int vec_any_le (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_any_le (vector signed short, vector signed short);

     vector signed int vec_any_le (vector signed int, vector unsigned int);
     vector signed int vec_any_le (vector unsigned int, vector signed int);
     vector signed int vec_any_le (vector unsigned int, vector unsigned int);

     vector signed int vec_any_le (vector signed int, vector signed int);
     vector signed int vec_any_le (vector float, vector float);

     vector signed int vec_any_lt (vector signed char, vector unsigned char);

     vector signed int vec_any_lt (vector unsigned char, vector signed char);

     vector signed int vec_any_lt (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_any_lt (vector signed char, vector signed char);
     vector signed int vec_any_lt (vector signed short,
                                   vector unsigned short);
     vector signed int vec_any_lt (vector unsigned short,
                                   vector signed short);
     vector signed int vec_any_lt (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_any_lt (vector signed short, vector signed short);

     vector signed int vec_any_lt (vector signed int, vector unsigned int);
     vector signed int vec_any_lt (vector unsigned int, vector signed int);
     vector signed int vec_any_lt (vector unsigned int, vector unsigned int);

     vector signed int vec_any_lt (vector signed int, vector signed int);
     vector signed int vec_any_lt (vector float, vector float);

     vector signed int vec_any_nan (vector float);

     vector signed int vec_any_ne (vector signed char, vector unsigned char);

     vector signed int vec_any_ne (vector signed char, vector signed char);
     vector signed int vec_any_ne (vector unsigned char, vector signed char);

     vector signed int vec_any_ne (vector unsigned char,
                                   vector unsigned char);
     vector signed int vec_any_ne (vector signed short,
                                   vector unsigned short);
     vector signed int vec_any_ne (vector signed short, vector signed short);

     vector signed int vec_any_ne (vector unsigned short,
                                   vector signed short);
     vector signed int vec_any_ne (vector unsigned short,
                                   vector unsigned short);
     vector signed int vec_any_ne (vector signed int, vector unsigned int);
     vector signed int vec_any_ne (vector signed int, vector signed int);
     vector signed int vec_any_ne (vector unsigned int, vector signed int);
     vector signed int vec_any_ne (vector unsigned int, vector unsigned int);

     vector signed int vec_any_ne (vector float, vector float);

     vector signed int vec_any_nge (vector float, vector float);

     vector signed int vec_any_ngt (vector float, vector float);

     vector signed int vec_any_nle (vector float, vector float);

     vector signed int vec_any_nlt (vector float, vector float);

     vector signed int vec_any_numeric (vector float);

     vector signed int vec_any_out (vector float, vector float);


File: gcc.info,  Node: Pragmas,  Next: Unnamed Fields,  Prev: Target Builtins,  Up: C Extensions

5.46 Pragmas Accepted by GCC
============================

GCC supports several types of pragmas, primarily in order to compile
code originally written for other compilers.  Note that in general we
do not recommend the use of pragmas; *Note Function Attributes::, for
further explanation.

* Menu:

* ARM Pragmas::
* Darwin Pragmas::
* Solaris Pragmas::
* Tru64 Pragmas::


File: gcc.info,  Node: ARM Pragmas,  Next: Darwin Pragmas,  Up: Pragmas

5.46.1 ARM Pragmas
------------------

The ARM target defines pragmas for controlling the default addition of
`long_call' and `short_call' attributes to functions.  *Note Function
Attributes::, for information about the effects of these attributes.

`long_calls'
     Set all subsequent functions to have the `long_call' attribute.

`no_long_calls'
     Set all subsequent functions to have the `short_call' attribute.

`long_calls_off'
     Do not affect the `long_call' or `short_call' attributes of
     subsequent functions.


File: gcc.info,  Node: Darwin Pragmas,  Next: Solaris Pragmas,  Prev: ARM Pragmas,  Up: Pragmas

5.46.2 Darwin Pragmas
---------------------

The following pragmas are available for all architectures running the
Darwin operating system.  These are useful for compatibility with other
MacOS compilers.

`mark TOKENS...'
     This pragma is accepted, but has no effect.

`options align=ALIGNMENT'
     This pragma sets the alignment of fields in structures.  The
     values of ALIGNMENT may be `mac68k', to emulate m68k alignment, or
     `power', to emulate PowerPC alignment.  Uses of this pragma nest
     properly; to restore the previous setting, use `reset' for the
     ALIGNMENT.

`segment TOKENS...'
     This pragma is accepted, but has no effect.

`unused (VAR [, VAR]...)'
     This pragma declares variables to be possibly unused.  GCC will not
     produce warnings for the listed variables.  The effect is similar
     to that of the `unused' attribute, except that this pragma may
     appear anywhere within the variables' scopes.


File: gcc.info,  Node: Solaris Pragmas,  Next: Tru64 Pragmas,  Prev: Darwin Pragmas,  Up: Pragmas

5.46.3 Solaris Pragmas
----------------------

For compatibility with the SunPRO compiler, the following pragma is
supported.

`redefine_extname OLDNAME NEWNAME'
     This pragma gives the C function OLDNAME the assembler label
     NEWNAME.  The pragma must appear before the function declaration.
     This pragma is equivalent to the asm labels extension (*note Asm
     Labels::).  The preprocessor defines `__PRAGMA_REDEFINE_EXTNAME'
     if the pragma is available.


File: gcc.info,  Node: Tru64 Pragmas,  Prev: Solaris Pragmas,  Up: Pragmas

5.46.4 Tru64 Pragmas
--------------------

For compatibility with the Compaq C compiler, the following pragma is
supported.

`extern_prefix STRING'
     This pragma renames all subsequent function and variable
     declarations such that STRING is prepended to the name.  This
     effect may be terminated by using another `extern_prefix' pragma
     with the empty string.

     This pragma is similar in intent to to the asm labels extension
     (*note Asm Labels::) in that the system programmer wants to change
     the assembly-level ABI without changing the source-level API.  The
     preprocessor defines `__EXTERN_PREFIX' if the pragma is available.


File: gcc.info,  Node: Unnamed Fields,  Prev: Pragmas,  Up: C Extensions

5.47 Unnamed struct/union fields within structs/unions.
=======================================================

For compatibility with other compilers, GCC allows you to define a
structure or union that contains, as fields, structures and unions
without names.  For example:

     struct {
       int a;
       union {
         int b;
         float c;
       };
       int d;
     } foo;

   In this example, the user would be able to access members of the
unnamed union with code like `foo.b'.  Note that only unnamed structs
and unions are allowed, you may not have, for example, an unnamed `int'.

   You must never create such structures that cause ambiguous field
definitions.  For example, this structure:

     struct {
       int a;
       struct {
         int a;
       };
     } foo;

   It is ambiguous which `a' is being referred to with `foo.a'.  Such
constructs are not supported and must be avoided.  In the future, such
constructs may be detected and treated as compilation errors.


File: gcc.info,  Node: C++ Extensions,  Next: Objective-C,  Prev: C Extensions,  Up: Top

6 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:

* 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
                        each needed template instantiation is emitted.
* Bound member functions:: You can extract a function pointer to the
                        method denoted by a `->*' or `.*' 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++.


File: gcc.info,  Node: Min and Max,  Next: Volatiles,  Up: C++ Extensions

6.1 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.  The GNU C `typeof' extension allows you to write safe
macros that avoid this kind of problem (*note Typeof::).  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.


File: gcc.info,  Node: Volatiles,  Next: Restricted Pointers,  Prev: Min and Max,  Up: C++ Extensions

6.2 When is a Volatile Object Accessed?
=======================================

Both the C and C++ standard have the concept of volatile objects.  These
are normally accessed by pointers and used for accessing hardware.  The
standards encourage compilers to refrain from optimizations concerning
accesses to volatile objects that it might perform on non-volatile
objects.  The C standard leaves it implementation defined as to what
constitutes a volatile access.  The C++ standard omits to specify this,
except to say that C++ should behave in a similar manner to C with
respect to volatiles, where possible.  The minimum either standard
specifies is that at a sequence point all previous accesses to volatile
objects have stabilized and no subsequent accesses have occurred.  Thus
an implementation is free to reorder and combine volatile accesses
which occur between sequence points, but cannot do so for accesses
across a sequence point.  The use of volatiles does not allow you to
violate the restriction on updating objects multiple times within a
sequence point.

   In most expressions, it is intuitively obvious what is a read and
what is a write.  For instance

     volatile int *dst = SOMEVALUE;
     volatile int *src = SOMEOTHERVALUE;
     *dst = *src;

will cause a read of the volatile object pointed to by SRC and stores
the value into the volatile object pointed to by DST.  There is no
guarantee that these reads and writes are atomic, especially for objects
larger than `int'.

   Less obvious expressions are where something which looks like an
access is used in a void context.  An example would be,

     volatile int *src = SOMEVALUE;
     *src;

   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
to.  The C++ standard specifies that such expressions do not undergo
lvalue to rvalue conversion, and that the type of the dereferenced
object may be incomplete.  The C++ standard does not specify explicitly
that it is this lvalue to rvalue conversion which is responsible for
causing an access.  However, there is reason to believe that it is,
because otherwise certain simple expressions become undefined.  However,
because it would surprise most programmers, G++ treats dereferencing a
pointer to volatile object of complete type in a void context as a read
of the object.  When the object has incomplete type, G++ issues a
warning.

     struct S;
     struct T {int m;};
     volatile S *ptr1 = SOMEVALUE;
     volatile T *ptr2 = SOMEVALUE;
     *ptr1;
     *ptr2;

   In this example, a warning is issued for `*ptr1', and `*ptr2' causes
a read of the object pointed to.  If you wish to force an error on the
first case, you must force a conversion to rvalue with, for instance a
static cast, `static_cast<S>(*ptr1)'.

   When using a reference to volatile, G++ does not treat equivalent
expressions as accesses to volatiles, but instead issues a warning that
no volatile is accessed.  The rationale for this is that otherwise it
becomes difficult to determine where volatile access occur, and not
possible to ignore the return value from functions returning volatile
references.  Again, if you wish to force a read, cast the reference to
an rvalue.


File: gcc.info,  Node: Restricted Pointers,  Next: Vague Linkage,  Prev: Volatiles,  Up: C++ Extensions

6.3 Restricting Pointer Aliasing
================================

As with gcc, g++ understands the C99 feature of restricted pointers,
specified with the `__restrict__', or `__restrict' type qualifier.
Because you cannot compile C++ by specifying the `-std=c99' language
flag, `restrict' is not a keyword in C++.

   In addition to allowing restricted pointers, you can specify
restricted references, which indicate that the reference is not aliased
in the local context.

     void fn (int *__restrict__ rptr, int &__restrict__ rref)
     {
       ...
     }

In the body of `fn', RPTR points to an unaliased integer and RREF
refers to a (different) unaliased integer.

   You may also specify whether a member function's THIS pointer is
unaliased by using `__restrict__' as a member function qualifier.

     void T::fn () __restrict__
     {
       ...
     }

Within the body of `T::fn', THIS will have the effective definition `T
*__restrict__ const this'.  Notice that the interpretation of a
`__restrict__' member function qualifier is different to that of
`const' or `volatile' qualifier, in that it is applied to the pointer
rather than the object.  This is consistent with other compilers which
implement restricted pointers.

   As with all outermost parameter qualifiers, `__restrict__' is
ignored in function definition matching.  This means you only need to
specify `__restrict__' in a function definition, rather than in a
function prototype as well.


File: gcc.info,  Node: Vague Linkage,  Next: C++ Interface,  Prev: Restricted Pointers,  Up: C++ Extensions

6.4 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.

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.

VTables
     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.

     _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.

type_info objects
     C++ requires information about types to be written out in order to
     implement `dynamic_cast', `typeid' and exception handling.  For
     polymorphic classes (classes with virtual functions), the type_info
     object is written out along with the vtable so that `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 `typeid' to an expression, throwing an object,
     or referring to a type in a catch clause or exception
     specification.

Template Instantiations
     Most everything in this section also applies to template
     instantiations, but there are other options as well.  *Note
     Where's the Template?: Template Instantiation.


   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.

   *Note Declarations and Definitions in One Header: C++ Interface, for
another way to control placement of these constructs.


File: gcc.info,  Node: C++ Interface,  Next: Template Instantiation,  Prev: Vague Linkage,  Up: C++ Extensions

6.5 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'.


File: gcc.info,  Node: Template Instantiation,  Next: Bound member functions,  Prev: C++ Interface,  Up: C++ Extensions

6.6 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 template-using code with `-frepo'.  The compiler will
     generate files with the extension `.rpo' listing all of the
     template instantiations used in the corresponding object files
     which could be instantiated there; the link wrapper, `collect2',
     will then update the `.rpo' files to tell the compiler where to
     place those instantiations and rebuild any affected object files.
     The link-time overhead is negligible after the first pass, as the
     compiler will continue to place the instantiations in the same
     files.

     This is your best option for application code written for the
     Borland model, as it will just work.  Code written for the Cfront
     model will need to be modified so that the template definitions
     are available at one or more points of instantiation; usually this
     is as simple as adding `#include <tmethods.cc>' to the end of each
     template header.

     For library code, if you want the library to provide all of the
     template instantiations it needs, just try to link all of its
     object files together; the link will fail, but cause the
     instantiations to be generated as a side effect.  Be warned,
     however, that this may cause conflicts if multiple libraries try
     to provide the same instantiations.  For greater control, use
     explicit instantiation as described in the next option.

  2. 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 (with `extern'), instantiation of the compiler
     support data for a template class (i.e. the vtable) without
     instantiating any of its members (with `inline'), and
     instantiation of only the static data members of a template class,
     without the support data or member functions (with (`static'):

          extern template int max (int, int);
          inline template class Foo<int>;
          static template class Foo<int>;

  3. 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.

  4. 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.

  5. A slight variation on this approach is to use the flag
     `-falt-external-templates' instead.  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.


File: gcc.info,  Node: Bound member functions,  Next: C++ Attributes,  Prev: Template Instantiation,  Up: C++ Extensions

6.7 Extracting the function pointer from a bound pointer to member function
===========================================================================

In C++, pointer to member functions (PMFs) are implemented using a wide
pointer of sorts to handle all the possible call mechanisms; the PMF
needs to store information about how to adjust the `this' pointer, and
if the function pointed to is virtual, where to find the vtable, and
where in the vtable to look for the member function.  If you are using
PMFs in an inner loop, you should really reconsider that decision.  If
that is not an option, you can extract the pointer to the function that
would be called for a given object/PMF pair and call it directly inside
the inner loop, to save a bit of time.

   Note that you will still be paying the penalty for the call through a
function pointer; on most modern architectures, such a call defeats the
branch prediction features of the CPU.  This is also true of normal
virtual function calls.

   The syntax for this extension is

     extern A a;
     extern int (A::*fp)();
     typedef int (*fptr)(A *);

     fptr p = (fptr)(a.*fp);

   For PMF constants (i.e. expressions of the form `&Klasse::Member'),
no object is needed to obtain the address of the function.  They can be
converted to function pointers directly:

     fptr p1 = (fptr)(&A::foo);

   You must specify `-Wno-pmf-conversions' to use this extension.


File: gcc.info,  Node: C++ Attributes,  Next: Java Exceptions,  Prev: Bound member functions,  Up: C++ Extensions

6.8 C++-Specific Variable, Function, and Type Attributes
========================================================

Some attributes only make sense for C++ programs.

`init_priority (PRIORITY)'
     In Standard C++, objects defined at namespace scope are guaranteed
     to be initialized in an order in strict accordance with that of
     their definitions _in a given translation unit_.  No guarantee is
     made for initializations across translation units.  However, GNU
     C++ allows users to control the order of initialization of objects
     defined at namespace scope with the `init_priority' attribute by
     specifying a relative PRIORITY, a constant integral expression
     currently bounded between 101 and 65535 inclusive.  Lower numbers
     indicate a higher priority.

     In the following example, `A' would normally be created before
     `B', but the `init_priority' attribute has reversed that order:

          Some_Class  A  __attribute__ ((init_priority (2000)));
          Some_Class  B  __attribute__ ((init_priority (543)));

     Note that the particular values of PRIORITY do not matter; only
     their relative ordering.

`java_interface'
     This type attribute informs C++ that the class is a Java
     interface.  It may only be applied to classes declared within an
     `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.



File: gcc.info,  Node: Java Exceptions,  Next: Deprecated Features,  Prev: C++ Attributes,  Up: C++ Extensions

6.9 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 is:

       struct S { ~S(); };
       extern void bar();    // is written in Java, and may throw exceptions
       void foo()
       {
         S s;
         bar();
       }

The usual effect of an incorrect guess is a link failure, complaining of
a missing routine called `__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
`#pragma GCC java_exceptions' at the head of the file.  This `#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 Java exception model, or vice
versa, but there may be bugs in this area.


File: gcc.info,  Node: Deprecated Features,  Next: Backwards Compatibility,  Prev: Java Exceptions,  Up: C++ Extensions

6.10 Deprecated Features
========================

In the past, the GNU C++ compiler was extended to experiment with new
features, at a time when the C++ language was still evolving.  Now that
the C++ standard is complete, some of those features are superseded by
superior alternatives.  Using the old features might cause a warning in
some cases that the feature will be dropped in the future.  In other
cases, the feature might be gone already.

   While the list below is not exhaustive, it documents some of the
options that are now deprecated:

`-fexternal-templates'
`-falt-external-templates'
     These are two of the many ways for g++ to implement template
     instantiation.  *Note Template Instantiation::.  The C++ standard
     clearly defines how template definitions have to be organized
     across implementation units.  g++ has an implicit instantiation
     mechanism that should work just fine for standard-conforming code.

`-fstrict-prototype'
`-fno-strict-prototype'
     Previously it was possible to use an empty prototype parameter
     list to indicate an unspecified number of parameters (like C),
     rather than no parameters, as C++ demands.  This feature has been
     removed, except where it is required for backwards compatibility
     *Note Backwards Compatibility::.

   The named return value extension has been deprecated, and is now
removed from g++.

   The use of initializer lists with new expressions has been
deprecated, and is now removed from g++.

   Floating and complex non-type template parameters have been
deprecated, and are now removed from g++.

   The implicit typename extension has been deprecated and will be
removed from g++ at some point.  In some cases g++ determines that a
dependant type such as `TPL<T>::X' is a type without needing a
`typename' keyword, contrary to the standard.


File: gcc.info,  Node: Backwards Compatibility,  Prev: Deprecated Features,  Up: C++ Extensions

6.11 Backwards Compatibility
============================

Now that there is a definitive ISO standard C++, G++ has a specification
to adhere to.  The C++ language evolved over time, and features that
used to be acceptable in previous drafts of the standard, such as the
ARM [Annotated C++ Reference Manual], are no longer accepted.  In order
to allow compilation of C++ written to such drafts, G++ contains some
backwards compatibilities.  _All such backwards compatibility features
are liable to disappear in future versions of G++._ They should be
considered deprecated *Note Deprecated Features::.

`For scope'
     If a variable is declared at for scope, it used to remain in scope
     until the end of the scope which contained the for statement
     (rather than just within the for scope).  G++ retains this, but
     issues a warning, if such a variable is accessed outside the for
     scope.

`Implicit C language'
     Old C system header files did not contain an `extern "C" {...}'
     scope to set the language.  On such systems, all header files are
     implicitly scoped inside a C language scope.  Also, an empty
     prototype `()' will be treated as an unspecified number of
     arguments, rather than no arguments, as C++ demands.


File: gcc.info,  Node: Objective-C,  Next: Compatibility,  Prev: C++ Extensions,  Up: Top

7 GNU Objective-C runtime features
**********************************

This document is meant to describe some of the GNU Objective-C runtime
features.  It is not intended to teach you Objective-C, there are
several resources on the Internet that present the language.  Questions
and comments about this document to Ovidiu Predescu <ovidiu@cup.hp.com>.

* Menu:

* Executing code before main::
* Type encoding::
* Garbage Collection::
* Constant string objects::
* compatibility_alias::


File: gcc.info,  Node: Executing code before main,  Next: Type encoding,  Prev: Objective-C,  Up: Objective-C

7.1 `+load': Executing code before main
=======================================

The GNU Objective-C runtime provides a way that allows you to execute
code before the execution of the program enters the `main' function.
The code is executed on a per-class and a per-category basis, through a
special class method `+load'.

   This facility is very useful if you want to initialize global
variables which can be accessed by the program directly, without
sending a message to the class first.  The usual way to initialize
global variables, in the `+initialize' method, might not be useful
because `+initialize' is only called when the first message is sent to a
class object, which in some cases could be too late.

   Suppose for example you have a `FileStream' class that declares
`Stdin', `Stdout' and `Stderr' as global variables, like below:


     FileStream *Stdin = nil;
     FileStream *Stdout = nil;
     FileStream *Stderr = nil;

     @implementation FileStream

     + (void)initialize
     {
         Stdin = [[FileStream new] initWithFd:0];
         Stdout = [[FileStream new] initWithFd:1];
         Stderr = [[FileStream new] initWithFd:2];
     }

     /* Other methods here */
     @end

   In this example, the initialization of `Stdin', `Stdout' and
`Stderr' in `+initialize' occurs too late.  The programmer can send a
message to one of these objects before the variables are actually
initialized, thus sending messages to the `nil' object.  The
`+initialize' method which actually initializes the global variables is
not invoked until the first message is sent to the class object.  The
solution would require these variables to be initialized just before
entering `main'.

   The correct solution of the above problem is to use the `+load'
method instead of `+initialize':


     @implementation FileStream

     + (void)load
     {
         Stdin = [[FileStream new] initWithFd:0];
         Stdout = [[FileStream new] initWithFd:1];
         Stderr = [[FileStream new] initWithFd:2];
     }

     /* Other methods here */
     @end

   The `+load' is a method that is not overridden by categories.  If a
class and a category of it both implement `+load', both methods are
invoked.  This allows some additional initializations to be performed in
a category.

   This mechanism is not intended to be a replacement for `+initialize'.
You should be aware of its limitations when you decide to use it
instead of `+initialize'.

* Menu:

* What you can and what you cannot do in +load::


File: gcc.info,  Node: What you can and what you cannot do in +load,  Prev: Executing code before main,  Up: Executing code before main

7.1.1 What you can and what you cannot do in `+load'
----------------------------------------------------

The `+load' implementation in the GNU runtime guarantees you the
following things:

   * you can write whatever C code you like;

   * you can send messages to Objective-C constant strings (`@"this is a
     constant string"');

   * you can allocate and send messages to objects whose class is
     implemented in the same file;

   * the `+load' implementation of all super classes of a class are
     executed before the `+load' of that class is executed;

   * the `+load' implementation of a class is executed before the
     `+load' implementation of any category.


   In particular, the following things, even if they can work in a
particular case, are not guaranteed:

   * allocation of or sending messages to arbitrary objects;

   * allocation of or sending messages to objects whose classes have a
     category implemented in the same file;


   You should make no assumptions about receiving `+load' in sibling
classes when you write `+load' of a class.  The order in which sibling
classes receive `+load' is not guaranteed.

   The order in which `+load' and `+initialize' are called could be
problematic if this matters.  If you don't allocate objects inside
`+load', it is guaranteed that `+load' is called before `+initialize'.
If you create an object inside `+load' the `+initialize' method of
object's class is invoked even if `+load' was not invoked.  Note if you
explicitly call `+load' on a class, `+initialize' will be called first.
To avoid possible problems try to implement only one of these methods.

   The `+load' method is also invoked when a bundle is dynamically
loaded into your running program.  This happens automatically without
any intervening operation from you.  When you write bundles and you
need to write `+load' you can safely create and send messages to
objects whose classes already exist in the running program.  The same
restrictions as above apply to classes defined in bundle.


File: gcc.info,  Node: Type encoding,  Next: Garbage Collection,  Prev: Executing code before main,  Up: Objective-C

7.2 Type encoding
=================

The Objective-C compiler generates type encodings for all the types.
These type encodings are used at runtime to find out information about
selectors and methods and about objects and classes.

   The types are encoded in the following way:

`char'             `c'
`unsigned char'    `C'
`short'            `s'
`unsigned short'   `S'
`int'              `i'
`unsigned int'     `I'
`long'             `l'
`unsigned long'    `L'
`long long'        `q'
`unsigned long     `Q'
long'              
`float'            `f'
`double'           `d'
`void'             `v'
`id'               `@'
`Class'            `#'
`SEL'              `:'
`char*'            `*'
unknown type       `?'
bit-fields         `b' followed by the starting position of the
                   bit-field, the type of the bit-field and the size of
                   the bit-field (the bit-fields encoding was changed
                   from the NeXT's compiler encoding, see below)

   The encoding of bit-fields has changed to allow bit-fields to be
properly handled by the runtime functions that compute sizes and
alignments of types that contain bit-fields.  The previous encoding
contained only the size of the bit-field.  Using only this information
it is not possible to reliably compute the size occupied by the
bit-field.  This is very important in the presence of the Boehm's
garbage collector because the objects are allocated using the typed
memory facility available in this collector.  The typed memory
allocation requires information about where the pointers are located
inside the object.

   The position in the bit-field is the position, counting in bits, of
the bit closest to the beginning of the structure.

   The non-atomic types are encoded as follows:

pointers       `^' followed by the pointed type.
arrays         `[' followed by the number of elements in the array
               followed by the type of the elements followed by `]'
structures     `{' followed by the name of the structure (or `?' if the
               structure is unnamed), the `=' sign, the type of the
               members and by `}'
unions         `(' followed by the name of the structure (or `?' if the
               union is unnamed), the `=' sign, the type of the members
               followed by `)'

   Here are some types and their encodings, as they are generated by the
compiler on an i386 machine:


Objective-C type   Compiler encoding
     int a[10];    `[10i]'
     struct {      `{?=i[3f]b128i3b131i2c}'
       int i;      
       float f[3]; 
       int a:3;    
       int b:2;    
       char c;     
     }             


   In addition to the types the compiler also encodes the type
specifiers.  The table below describes the encoding of the current
Objective-C type specifiers:


Specifier          Encoding
`const'            `r'
`in'               `n'
`inout'            `N'
`out'              `o'
`bycopy'           `O'
`oneway'           `V'


   The type specifiers are encoded just before the type.  Unlike types
however, the type specifiers are only encoded when they appear in method
argument types.


File: gcc.info,  Node: Garbage Collection,  Next: Constant string objects,  Prev: Type encoding,  Up: Objective-C

7.3 Garbage Collection
======================

Support for a new memory management policy has been added by using a
powerful conservative garbage collector, known as the
Boehm-Demers-Weiser conservative garbage collector.  It is available
from `http://www.hpl.hp.com/personal/Hans_Boehm/gc/'.

   To enable the support for it you have to configure the compiler
using an additional argument, `--enable-objc-gc'.  You need to have
garbage collector installed before building the compiler.  This will
build an additional runtime library which has several enhancements to
support the garbage collector.  The new library has a new name,
`libobjc_gc.a' to not conflict with the non-garbage-collected library.

   When the garbage collector is used, the objects are allocated using
the so-called typed memory allocation mechanism available in the
Boehm-Demers-Weiser collector.  This mode requires precise information
on where pointers are located inside objects.  This information is
computed once per class, immediately after the class has been
initialized.

   There is a new runtime function `class_ivar_set_gcinvisible()' which
can be used to declare a so-called "weak pointer" reference.  Such a
pointer is basically hidden for the garbage collector; this can be
useful in certain situations, especially when you want to keep track of
the allocated objects, yet allow them to be collected.  This kind of
pointers can only be members of objects, you cannot declare a global
pointer as a weak reference.  Every type which is a pointer type can be
declared a weak pointer, including `id', `Class' and `SEL'.

   Here is an example of how to use this feature.  Suppose you want to
implement a class whose instances hold a weak pointer reference; the
following class does this:


     @interface WeakPointer : Object
     {
         const void* weakPointer;
     }

     - initWithPointer:(const void*)p;
     - (const void*)weakPointer;
     @end


     @implementation WeakPointer

     + (void)initialize
     {
       class_ivar_set_gcinvisible (self, "weakPointer", YES);
     }

     - initWithPointer:(const void*)p
     {
       weakPointer = p;
       return self;
     }

     - (const void*)weakPointer
     {
       return weakPointer;
     }

     @end

   Weak pointers are supported through a new type character specifier
represented by the `!' character.  The `class_ivar_set_gcinvisible()'
function adds or removes this specifier to the string type description
of the instance variable named as argument.


File: gcc.info,  Node: Constant string objects,  Next: compatibility_alias,  Prev: Garbage Collection,  Up: Objective-C

7.4 Constant string objects
===========================

GNU Objective-C provides constant string objects that are generated
directly by the compiler.  You declare a constant string object by
prefixing a C constant string with the character `@':

       id myString = @"this is a constant string object";

   The constant string objects are usually instances of the
`NXConstantString' class which is provided by the GNU Objective-C
runtime.  To get the definition of this class you must include the
`objc/NXConstStr.h' header file.

   User defined libraries may want to implement their own constant
string class.  To be able to support them, the GNU Objective-C compiler
provides a new command line options
`-fconstant-string-class=CLASS-NAME'.  The provided class should adhere
to a strict structure, the same as `NXConstantString''s structure:


     @interface NXConstantString : Object
     {
       char *c_string;
       unsigned int len;
     }
     @end

   User class libraries may choose to inherit the customized constant
string class from a different class than `Object'.  There is no
requirement in the methods the constant string class has to implement.

   When a file is compiled with the `-fconstant-string-class' option,
all the constant string objects will be instances of the class specified
as argument to this option.  It is possible to have multiple compilation
units referring to different constant string classes, neither the
compiler nor the linker impose any restrictions in doing this.


File: gcc.info,  Node: compatibility_alias,  Prev: Constant string objects,  Up: Objective-C

7.5 compatibility_alias
=======================

This is a feature of the Objective-C compiler rather than of the
runtime, anyway since it is documented nowhere and its existence was
forgotten, we are documenting it here.

   The keyword `@compatibility_alias' allows you to define a class name
as equivalent to another class name.  For example:

     @compatibility_alias WOApplication GSWApplication;

   tells the compiler that each time it encounters `WOApplication' as a
class name, it should replace it with `GSWApplication' (that is,
`WOApplication' is just an alias for `GSWApplication').

   There are some constraints on how this can be used--

   * `WOApplication' (the alias) must not be an existing class;

   * `GSWApplication' (the real class) must be an existing class.



File: gcc.info,  Node: Compatibility,  Next: Gcov,  Prev: Objective-C,  Up: Top

8 Binary Compatibility
**********************

Binary compatibility encompasses several related concepts:

"application binary interface (ABI)"
     The set of runtime conventions followed by all of the tools that
     deal with binary representations of a program, including
     compilers, assemblers, linkers, and language runtime support.
     Some ABIs are formal with a written specification, possibly
     designed by multiple interested parties.  Others are simply the
     way things are actually done by a particular set of tools.

"ABI conformance"
     A compiler conforms to an ABI if it generates code that follows
     all of the specifications enumerated by that ABI.  A library
     conforms to an ABI if it is implemented according to that ABI.  An
     application conforms to an ABI if it is built using tools that
     conform to that ABI and does not contain source code that
     specifically changes behavior specified by the ABI.

"calling conventions"
     Calling conventions are a subset of an ABI that specify of how
     arguments are passed and function results are returned.

"interoperability"
     Different sets of tools are interoperable if they generate files
     that can be used in the same program.  The set of tools includes
     compilers, assemblers, linkers, libraries, header files, startup
     files, and debuggers.  Binaries produced by different sets of
     tools are not interoperable unless they implement the same ABI.
     This applies to different versions of the same tools as well as
     tools from different vendors.

"intercallability"
     Whether a function in a binary built by one set of tools can call a
     function in a binary built by a different set of tools is a subset
     of interoperability.

"implementation-defined features"
     Language standards include lists of implementation-defined
     features whose behavior can vary from one implementation to
     another.  Some of these features are normally covered by a
     platform's ABI and others are not.  The features that are not
     covered by an ABI generally affect how a program behaves, but not
     intercallability.

"compatibility"
     Conformance to the same ABI and the same behavior of
     implementation-defined features are both relevant for
     compatibility.

   The application binary interface implemented by a C or C++ compiler
affects code generation and runtime support for:

   * size and alignment of data types

   * layout of structured types

   * calling conventions

   * register usage conventions

   * interfaces for runtime arithmetic support

   * object file formats

   In addition, the application binary interface implemented by a C++
compiler affects code generation and runtime support for:
   * name mangling

   * exception handling

   * invoking constructors and destructors

   * layout, alignment, and padding of classes

   * layout and alignment of virtual tables

   Some GCC compilation options cause the compiler to generate code that
does not conform to the platform's default ABI.  Other options cause
different program behavior for implementation-defined features that are
not covered by an ABI.  These options are provided for consistency with
other compilers that do not follow the platform's default ABI or the
usual behavior of implementation-defined features for the platform.  Be
very careful about using such options.

   Most platforms have a well-defined ABI that covers C code, but ABIs
that cover C++ functionality are not yet common.

   Starting with GCC 3.2, GCC binary conventions for C++ are based on a
written, vendor-neutral C++ ABI that was designed to be specific to
64-bit Itanium but also includes generic specifications that apply to
any platform.  This C++ ABI is also implemented by other compiler
vendors on some platforms, notably GNU/Linux and BSD systems.  We have
tried hard to provide a stable ABI that will be compatible with future
GCC releases, but it is possible that we will encounter problems that
make this difficult.  Such problems could include different
interpretations of the C++ ABI by different vendors, bugs in the ABI, or
bugs in the implementation of the ABI in different compilers.  GCC's
`-Wabi' switch warns when G++ generates code that is probably not
compatible with the C++ ABI.

   The C++ library used with a C++ compiler includes the Standard C++
Library, with functionality defined in the C++ Standard, plus language
runtime support.  The runtime support is included in a C++ ABI, but
there is no formal ABI for the Standard C++ Library.  Two
implementations of that library are interoperable if one follows the
de-facto ABI of the other and if they are both built with the same
compiler, or with compilers that conform to the same ABI for C++
compiler and runtime support.

   When G++ and another C++ compiler conform to the same C++ ABI, but
the implementations of the Standard C++ Library that they normally use
do not follow the same ABI for the Standard C++ Library, object files
built with those compilers can be used in the same program only if they
use the same C++ library.  This requires specifying the location of the
C++ library header files when invoking the compiler whose usual library
is not being used.  The location of GCC's C++ header files depends on
how the GCC build was configured, but can be seen by using the G++ `-v'
option.  With default configuration options for G++ 3.2 the compile
line for a different C++ compiler needs to include

         -IGCC_INSTALL_DIRECTORY/include/c++/3.2

   Similarly, compiling code with G++ that must use a C++ library other
than the GNU C++ library requires specifying the location of the header
files for that other library.

   The most straightforward way to link a program to use a particular
C++ library is to use a C++ driver that specifies that C++ library by
default.  The `g++' driver, for example, tells the linker where to find
GCC's C++ library (`libstdc++') plus the other libraries and startup
files it needs, in the proper order.

   If a program must use a different C++ library and it's not possible
to do the final link using a C++ driver that uses that library by
default, it is necessary to tell `g++' the location and name of that
library.  It might also be necessary to specify different startup files
and other runtime support libraries, and to suppress the use of GCC's
support libraries with one or more of the options `-nostdlib',
`-nostartfiles', and `-nodefaultlibs'.


File: gcc.info,  Node: Gcov,  Next: Trouble,  Prev: Compatibility,  Up: Top

9 `gcov'--a Test Coverage Program
*********************************

`gcov' is a tool you can use in conjunction with GCC to test code
coverage in your programs.

* Menu:

* Gcov Intro::         	        Introduction to gcov.
* Invoking Gcov::       	How to use gcov.
* Gcov and Optimization::       Using gcov with GCC optimization.
* Gcov Data Files::             The files used by gcov.


File: gcc.info,  Node: Gcov Intro,  Next: Invoking Gcov,  Up: Gcov

9.1 Introduction to `gcov'
==========================

`gcov' is a test coverage program.  Use it in concert with GCC to
analyze your programs to help create more efficient, faster running
code.  You can use `gcov' as a profiling tool to help discover where
your optimization efforts will best affect your code.  You can also use
`gcov' along with the other profiling tool, `gprof', to assess which
parts of your code use the greatest amount of computing time.

   Profiling tools help you analyze your code's performance.  Using a
profiler such as `gcov' or `gprof', you can find out some basic
performance statistics, such as:

   * how often each line of code executes

   * what lines of code are actually executed

   * how much computing time each section of code uses

   Once you know these things about how your code works when compiled,
you can look at each module to see which modules should be optimized.
`gcov' helps you determine where to work on optimization.

   Software developers also use coverage testing in concert with
testsuites, to make sure software is actually good enough for a release.
Testsuites can verify that a program works as expected; a coverage
program tests to see how much of the program is exercised by the
testsuite.  Developers can then determine what kinds of test cases need
to be added to the testsuites to create both better testing and a better
final product.

   You should compile your code without optimization if you plan to use
`gcov' because the optimization, by combining some lines of code into
one function, may not give you as much information as you need to look
for `hot spots' where the code is using a great deal of computer time.
Likewise, because `gcov' accumulates statistics by line (at the lowest
resolution), it works best with a programming style that places only
one statement on each line.  If you use complicated macros that expand
to loops or to other control structures, the statistics are less
helpful--they only report on the line where the macro call appears.  If
your complex macros behave like functions, you can replace them with
inline functions to solve this problem.

   `gcov' creates a logfile called `SOURCEFILE.gcov' which indicates
how many times each line of a source file `SOURCEFILE.c' has executed.
You can use these logfiles along with `gprof' to aid in fine-tuning the
performance of your programs.  `gprof' gives timing information you can
use along with the information you get from `gcov'.

   `gcov' works only on code compiled with GCC.  It is not compatible
with any other profiling or test coverage mechanism.


File: gcc.info,  Node: Invoking Gcov,  Next: Gcov and Optimization,  Prev: Gcov Intro,  Up: Gcov

9.2 Invoking gcov
=================

     gcov [OPTIONS] SOURCEFILE

   `gcov' accepts the following options:

`-h'
`--help'
     Display help about using `gcov' (on the standard output), and exit
     without doing any further processing.

`-v'
`--version'
     Display the `gcov' version number (on the standard output), and
     exit without doing any further processing.

`-b'
`--branch-probabilities'
     Write branch frequencies to the output file, and write branch
     summary info to the standard output.  This option allows you to
     see how often each branch in your program was taken.

`-c'
`--branch-counts'
     Write branch frequencies as the number of branches taken, rather
     than the percentage of branches taken.

`-n'
`--no-output'
     Do not create the `gcov' output file.

`-l'
`--long-file-names'
     Create long file names for included source files.  For example, if
     the header file `x.h' contains code, and was included in the file
     `a.c', then running `gcov' on the file `a.c' will produce an
     output file called `a.c.x.h.gcov' instead of `x.h.gcov'.  This can
     be useful if `x.h' is included in multiple source files.

`-f'
`--function-summaries'
     Output summaries for each function in addition to the file level
     summary.

`-o DIRECTORY'
`--object-directory DIRECTORY'
     The directory where the object files live.  Gcov will search for
     `.bb', `.bbg', and `.da' files in this directory.

   When using `gcov', you must first compile your program with two
special GCC options: `-fprofile-arcs -ftest-coverage'.  This tells the
compiler to generate additional information needed by gcov (basically a
flow graph of the program) and also includes additional code in the
object files for generating the extra profiling information needed by
gcov.  These additional files are placed in the directory where the
source code is located.

   Running the program will cause profile output to be generated.  For
each source file compiled with `-fprofile-arcs', an accompanying `.da'
file will be placed in the source directory.

   Running `gcov' with your program's source file names as arguments
will now produce a listing of the code along with frequency of execution
for each line.  For example, if your program is called `tmp.c', this is
what you see when you use the basic `gcov' facility:

     $ gcc -fprofile-arcs -ftest-coverage tmp.c
     $ a.out
     $ gcov tmp.c
      87.50% of 8 source lines executed in file tmp.c
     Creating tmp.c.gcov.

   The file `tmp.c.gcov' contains output from `gcov'.  Here is a sample:

                     main()
                     {
                1      int i, total;

                1      total = 0;

               11      for (i = 0; i < 10; i++)
               10        total += i;

                1      if (total != 45)
           ######        printf ("Failure\n");
                       else
                1        printf ("Success\n");
                1    }

   When you use the `-b' option, your output looks like this:

     $ gcov -b tmp.c
      87.50% of 8 source lines executed in file tmp.c
      80.00% of 5 branches executed in file tmp.c
      80.00% of 5 branches taken at least once in file tmp.c
      50.00% of 2 calls executed in file tmp.c
     Creating tmp.c.gcov.

   Here is a sample of a resulting `tmp.c.gcov' file:

                     main()
                     {
                1      int i, total;

                1      total = 0;

               11      for (i = 0; i < 10; i++)
     branch 0 taken = 91%
     branch 1 taken = 100%
     branch 2 taken = 100%
               10        total += i;

                1      if (total != 45)
     branch 0 taken = 100%
           ######        printf ("Failure\n");
     call 0 never executed
     branch 1 never executed
                       else
                1        printf ("Success\n");
     call 0 returns = 100%
                1    }

   For each basic block, a line is printed after the last line of the
basic block describing the branch or call that ends the basic block.
There can be multiple branches and calls listed for a single source
line if there are multiple basic blocks that end on that line.  In this
case, the branches and calls are each given a number.  There is no
simple way to map these branches and calls back to source constructs.
In general, though, the lowest numbered branch or call will correspond
to the leftmost construct on the source line.

   For a branch, if it was executed at least once, then a percentage
indicating the number of times the branch was taken divided by the
number of times the branch was executed will be printed.  Otherwise, the
message "never executed" is printed.

   For a call, if it was executed at least once, then a percentage
indicating the number of times the call returned divided by the number
of times the call was executed will be printed.  This will usually be
100%, but may be less for functions call `exit' or `longjmp', and thus
may not return every time they are called.

   The execution counts are cumulative.  If the example program were
executed again without removing the `.da' file, the count for the
number of times each line in the source was executed would be added to
the results of the previous run(s).  This is potentially useful in
several ways.  For example, it could be used to accumulate data over a
number of program runs as part of a test verification suite, or to
provide more accurate long-term information over a large number of
program runs.

   The data in the `.da' files is saved immediately before the program
exits.  For each source file compiled with `-fprofile-arcs', the
profiling code first attempts to read in an existing `.da' file; if the
file doesn't match the executable (differing number of basic block
counts) it will ignore the contents of the file.  It then adds in the
new execution counts and finally writes the data to the file.


File: gcc.info,  Node: Gcov and Optimization,  Next: Gcov Data Files,  Prev: Invoking Gcov,  Up: Gcov

9.3 Using `gcov' with GCC Optimization
======================================

If you plan to use `gcov' to help optimize your code, you must first
compile your program with two special GCC options: `-fprofile-arcs
-ftest-coverage'.  Aside from that, you can use any other GCC options;
but if you want to prove that every single line in your program was
executed, you should not compile with optimization at the same time.
On some machines the optimizer can eliminate some simple code lines by
combining them with other lines.  For example, code like this:

     if (a != b)
       c = 1;
     else
       c = 0;

can be compiled into one instruction on some machines.  In this case,
there is no way for `gcov' to calculate separate execution counts for
each line because there isn't separate code for each line.  Hence the
`gcov' output looks like this if you compiled the program with
optimization:

           100  if (a != b)
           100    c = 1;
           100  else
           100    c = 0;

   The output shows that this block of code, combined by optimization,
executed 100 times.  In one sense this result is correct, because there
was only one instruction representing all four of these lines.  However,
the output does not indicate how many times the result was 0 and how
many times the result was 1.


File: gcc.info,  Node: Gcov Data Files,  Prev: Gcov and Optimization,  Up: Gcov

9.4 Brief description of `gcov' data files
==========================================

`gcov' uses three files for doing profiling.  The names of these files
are derived from the original _source_ file by substituting the file
suffix with either `.bb', `.bbg', or `.da'.  All of these files are
placed in the same directory as the source file, and contain data
stored in a platform-independent method.

   The `.bb' and `.bbg' files are generated when the source file is
compiled with the GCC `-ftest-coverage' option.  The `.bb' file
contains a list of source files (including headers), functions within
those files, and line numbers corresponding to each basic block in the
source file.

   The `.bb' file format consists of several lists of 4-byte integers
which correspond to the line numbers of each basic block in the file.
Each list is terminated by a line number of 0.  A line number of -1 is
used to designate that the source file name (padded to a 4-byte
boundary and followed by another -1) follows.  In addition, a line
number of -2 is used to designate that the name of a function (also
padded to a 4-byte boundary and followed by a -2) follows.

   The `.bbg' file is used to reconstruct the program flow graph for
the source file.  It contains a list of the program flow arcs (possible
branches taken from one basic block to another) for each function which,
in combination with the `.bb' file, enables gcov to reconstruct the
program flow.

   In the `.bbg' file, the format is:
             number of basic blocks for function #0 (4-byte number)
             total number of arcs for function #0 (4-byte number)
             count of arcs in basic block #0 (4-byte number)
             destination basic block of arc #0 (4-byte number)
             flag bits (4-byte number)
             destination basic block of arc #1 (4-byte number)
             flag bits (4-byte number)
             ...
             destination basic block of arc #N (4-byte number)
             flag bits (4-byte number)
             count of arcs in basic block #1 (4-byte number)
             destination basic block of arc #0 (4-byte number)
             flag bits (4-byte number)
             ...

   A -1 (stored as a 4-byte number) is used to separate each function's
list of basic blocks, and to verify that the file has been read
correctly.

   The `.da' file is generated when a program containing object files
built with the GCC `-fprofile-arcs' option is executed.  A separate
`.da' file is created for each source file compiled with this option,
and the name of the `.da' file is stored as an absolute pathname in the
resulting object file.  This path name is derived from the source file
name by substituting a `.da' suffix.

   The format of the `.da' file is fairly simple.  The first 8-byte
number is the number of counts in the file, followed by the counts
(stored as 8-byte numbers).  Each count corresponds to the number of
times each arc in the program is executed.  The counts are cumulative;
each time the program is executed, it attempts to combine the existing
`.da' files with the new counts for this invocation of the program.  It
ignores the contents of any `.da' files whose number of arcs doesn't
correspond to the current program, and merely overwrites them instead.

   All three of these files use the functions in `gcov-io.h' to store
integers; the functions in this header provide a machine-independent
mechanism for storing and retrieving data from a stream.


File: gcc.info,  Node: Trouble,  Next: Bugs,  Prev: Gcov,  Up: Top

10 Known Causes of Trouble with GCC
***********************************

This section describes known problems that affect users of GCC.  Most
of these are not GCC bugs per se--if they were, we would fix them.  But
the result for a user may be like the result of a bug.

   Some of these problems are due to bugs in other software, some are
missing features that are too much work to add, and some are places
where people's opinions differ as to what is best.

* Menu:

* Actual Bugs::		      Bugs we will fix later.
* Cross-Compiler Problems::   Common problems of cross compiling with GCC.
* Interoperation::      Problems using GCC with other compilers,
			   and with certain linkers, assemblers and debuggers.
* External Bugs::	Problems compiling certain programs.
* Incompatibilities::   GCC is incompatible with traditional C.
* Fixed Headers::       GCC uses corrected versions of system header files.
                           This is necessary, but doesn't always work smoothly.
* Standard Libraries::  GCC uses the system C library, which might not be
                           compliant with the ISO C standard.
* Disappointments::     Regrettable things we can't change, but not quite bugs.
* C++ Misunderstandings::     Common misunderstandings with GNU C++.
* Protoize Caveats::    Things to watch out for when using `protoize'.
* Non-bugs::		Things we think are right, but some others disagree.
* Warnings and Errors:: Which problems in your code get warnings,
                         and which get errors.


File: gcc.info,  Node: Actual Bugs,  Next: Cross-Compiler Problems,  Up: Trouble

10.1 Actual Bugs We Haven't Fixed Yet
=====================================

   * The `fixincludes' script interacts badly with automounters; if the
     directory of system header files is automounted, it tends to be
     unmounted while `fixincludes' is running.  This would seem to be a
     bug in the automounter.  We don't know any good way to work around
     it.

   * The `fixproto' script will sometimes add prototypes for the
     `sigsetjmp' and `siglongjmp' functions that reference the
     `jmp_buf' type before that type is defined.  To work around this,
     edit the offending file and place the typedef in front of the
     prototypes.

   * When `-pedantic-errors' is specified, GCC will incorrectly give an
     error message when a function name is specified in an expression
     involving the comma operator.


File: gcc.info,  Node: Cross-Compiler Problems,  Next: Interoperation,  Prev: Actual Bugs,  Up: Trouble

10.2 Cross-Compiler Problems
============================

You may run into problems with cross compilation on certain machines,
for several reasons.

   * Cross compilation can run into trouble for certain machines because
     some target machines' assemblers require floating point numbers to
     be written as _integer_ constants in certain contexts.

     The compiler writes these integer constants by examining the
     floating point value as an integer and printing that integer,
     because this is simple to write and independent of the details of
     the floating point representation.  But this does not work if the
     compiler is running on a different machine with an incompatible
     floating point format, or even a different byte-ordering.

     In addition, correct constant folding of floating point values
     requires representing them in the target machine's format.  (The C
     standard does not quite require this, but in practice it is the
     only way to win.)

     It is now possible to overcome these problems by defining macros
     such as `REAL_VALUE_TYPE'.  But doing so is a substantial amount of
     work for each target machine.  *Note Cross Compilation and
     Floating Point: (gccint)Cross-compilation.

   * At present, the program `mips-tfile' which adds debug support to
     object files on MIPS systems does not work in a cross compile
     environment.


File: gcc.info,  Node: Interoperation,  Next: External Bugs,  Prev: Cross-Compiler Problems,  Up: Trouble

10.3 Interoperation
===================

This section lists various difficulties encountered in using GCC
together with other compilers or with the assemblers, linkers,
libraries and debuggers on certain systems.

   * On many platforms, GCC supports a different ABI for C++ than do
     other compilers, so the object files compiled by GCC cannot be
     used with object files generated by another C++ compiler.

     An area where the difference is most apparent is name mangling.
     The use of different name mangling is intentional, to protect you
     from more subtle problems.  Compilers differ as to many internal
     details of C++ implementation, including: how class instances are
     laid out, how multiple inheritance is implemented, and how virtual
     function calls are handled.  If the name encoding were made the
     same, your programs would link against libraries provided from
     other compilers--but the programs would then crash when run.
     Incompatible libraries are then detected at link time, rather than
     at run time.

   * Older GDB versions sometimes fail to read the output of GCC version
     2.  If you have trouble, get GDB version 4.4 or later.

   * DBX rejects some files produced by GCC, though it accepts similar
     constructs in output from PCC.  Until someone can supply a coherent
     description of what is valid DBX input and what is not, there is
     nothing I can do about these problems.  You are on your own.

   * The GNU assembler (GAS) does not support PIC.  To generate PIC
     code, you must use some other assembler, such as `/bin/as'.

   * On some BSD systems, including some versions of Ultrix, use of
     profiling causes static variable destructors (currently used only
     in C++) not to be run.

   * On some SGI systems, when you use `-lgl_s' as an option, it gets
     translated magically to `-lgl_s -lX11_s -lc_s'.  Naturally, this
     does not happen when you use GCC.  You must specify all three
     options explicitly.

   * On a Sparc, GCC aligns all values of type `double' on an 8-byte
     boundary, and it expects every `double' to be so aligned.  The Sun
     compiler usually gives `double' values 8-byte alignment, with one
     exception: function arguments of type `double' may not be aligned.

     As a result, if a function compiled with Sun CC takes the address
     of an argument of type `double' and passes this pointer of type
     `double *' to a function compiled with GCC, dereferencing the
     pointer may cause a fatal signal.

     One way to solve this problem is to compile your entire program
     with GCC.  Another solution is to modify the function that is
     compiled with Sun CC to copy the argument into a local variable;
     local variables are always properly aligned.  A third solution is
     to modify the function that uses the pointer to dereference it via
     the following function `access_double' instead of directly with
     `*':

          inline double
          access_double (double *unaligned_ptr)
          {
            union d2i { double d; int i[2]; };

            union d2i *p = (union d2i *) unaligned_ptr;
            union d2i u;

            u.i[0] = p->i[0];
            u.i[1] = p->i[1];

            return u.d;
          }

     Storing into the pointer can be done likewise with the same union.

   * On Solaris, the `malloc' function in the `libmalloc.a' library may
     allocate memory that is only 4 byte aligned.  Since GCC on the
     Sparc assumes that doubles are 8 byte aligned, this may result in a
     fatal signal if doubles are stored in memory allocated by the
     `libmalloc.a' library.

     The solution is to not use the `libmalloc.a' library.  Use instead
     `malloc' and related functions from `libc.a'; they do not have
     this problem.

   * Sun forgot to include a static version of `libdl.a' with some
     versions of SunOS (mainly 4.1).  This results in undefined symbols
     when linking static binaries (that is, if you use `-static').  If
     you see undefined symbols `_dlclose', `_dlsym' or `_dlopen' when
     linking, compile and link against the file `mit/util/misc/dlsym.c'
     from the MIT version of X windows.

   * The 128-bit long double format that the Sparc port supports
     currently works by using the architecturally defined quad-word
     floating point instructions.  Since there is no hardware that
     supports these instructions they must be emulated by the operating
     system.  Long doubles do not work in Sun OS versions 4.0.3 and
     earlier, because the kernel emulator uses an obsolete and
     incompatible format.  Long doubles do not work in Sun OS version
     4.1.1 due to a problem in a Sun library.  Long doubles do work on
     Sun OS versions 4.1.2 and higher, but GCC does not enable them by
     default.  Long doubles appear to work in Sun OS 5.x (Solaris 2.x).

   * On HP-UX version 9.01 on the HP PA, the HP compiler `cc' does not
     compile GCC correctly.  We do not yet know why.  However, GCC
     compiled on earlier HP-UX versions works properly on HP-UX 9.01
     and can compile itself properly on 9.01.

   * On the HP PA machine, ADB sometimes fails to work on functions
     compiled with GCC.  Specifically, it fails to work on functions
     that use `alloca' or variable-size arrays.  This is because GCC
     doesn't generate HP-UX unwind descriptors for such functions.  It
     may even be impossible to generate them.

   * Debugging (`-g') is not supported on the HP PA machine, unless you
     use the preliminary GNU tools.

   * Taking the address of a label may generate errors from the HP-UX
     PA assembler.  GAS for the PA does not have this problem.

   * Using floating point parameters for indirect calls to static
     functions will not work when using the HP assembler.  There simply
     is no way for GCC to specify what registers hold arguments for
     static functions when using the HP assembler.  GAS for the PA does
     not have this problem.

   * In extremely rare cases involving some very large functions you may
     receive errors from the HP linker complaining about an out of
     bounds unconditional branch offset.  This used to occur more often
     in previous versions of GCC, but is now exceptionally rare.  If
     you should run into it, you can work around by making your
     function smaller.

   * GCC compiled code sometimes emits warnings from the HP-UX
     assembler of the form:

          (warning) Use of GR3 when
            frame >= 8192 may cause conflict.

     These warnings are harmless and can be safely ignored.

   * On the IBM RS/6000, compiling code of the form

          extern int foo;

          ... foo ...

          static int foo;

     will cause the linker to report an undefined symbol `foo'.
     Although this behavior differs from most other systems, it is not a
     bug because redefining an `extern' variable as `static' is
     undefined in ISO C.

   * In extremely rare cases involving some very large functions you may
     receive errors from the AIX Assembler complaining about a
     displacement that is too large.  If you should run into it, you
     can work around by making your function smaller.

   * The `libstdc++.a' library in GCC relies on the SVR4 dynamic linker
     semantics which merges global symbols between libraries and
     applications, especially necessary for C++ streams functionality.
     This is not the default behavior of AIX shared libraries and
     dynamic linking.  `libstdc++.a' is built on AIX with
     "runtime-linking" enabled so that symbol merging can occur.  To
     utilize this feature, the application linked with `libstdc++.a'
     must include the `-Wl,-brtl' flag on the link line.  G++ cannot
     impose this because this option may interfere with the semantics
     of the user program and users may not always use `g++' to link his
     or her application. Applications are not required to use the
     `-Wl,-brtl' flag on the link line--the rest of the `libstdc++.a'
     library which is not dependent on the symbol merging semantics
     will continue to function correctly.

   * An application can interpose its own definition of functions for
     functions invoked by `libstdc++.a' with "runtime-linking" enabled
     on AIX.  To accomplish this the application must be linked with
     "runtime-linking" option and the functions explicitly must be
     exported by the application (`-Wl,-brtl,-bE:exportfile').

   * AIX on the RS/6000 provides support (NLS) for environments outside
     of the United States.  Compilers and assemblers use NLS to support
     locale-specific representations of various objects including
     floating-point numbers (`.' vs `,' for separating decimal
     fractions). There have been problems reported where the library
     linked with GCC does not produce the same floating-point formats
     that the assembler accepts. If you have this problem, set the
     `LANG' environment variable to `C' or `En_US'.

   * Even if you specify `-fdollars-in-identifiers', you cannot
     successfully use `$' in identifiers on the RS/6000 due to a
     restriction in the IBM assembler.  GAS supports these identifiers.

   * There is an assembler bug in versions of DG/UX prior to 5.4.2.01
     that occurs when the `fldcr' instruction is used.  GCC uses
     `fldcr' on the 88100 to serialize volatile memory references.  Use
     the option `-mno-serialize-volatile' if your version of the
     assembler has this bug.

   * On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
     messages from the linker.  These warning messages complain of
     mismatched psect attributes.  You can ignore them.

   * On NewsOS version 3, if you include both of the files `stddef.h'
     and `sys/types.h', you get an error because there are two typedefs
     of `size_t'.  You should change `sys/types.h' by adding these
     lines around the definition of `size_t':

          #ifndef _SIZE_T
          #define _SIZE_T
          ACTUAL-TYPEDEF-HERE
          #endif

   * On the Alliant, the system's own convention for returning
     structures and unions is unusual, and is not compatible with GCC
     no matter what options are used.

   * On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
     convention for structure and union returning.  Use the option
     `-mhc-struct-return' to tell GCC to use a convention compatible
     with it.

   * On Ultrix, the Fortran compiler expects registers 2 through 5 to
     be saved by function calls.  However, the C compiler uses
     conventions compatible with BSD Unix: registers 2 through 5 may be
     clobbered by function calls.

     GCC uses the same convention as the Ultrix C compiler.  You can use
     these options to produce code compatible with the Fortran compiler:

          -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5

   * On the WE32k, you may find that programs compiled with GCC do not
     work with the standard shared C library.  You may need to link with
     the ordinary C compiler.  If you do so, you must specify the
     following options:

          -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s

     The first specifies where to find the library `libgcc.a' specified
     with the `-lgcc' option.

     GCC does linking by invoking `ld', just as `cc' does, and there is
     no reason why it _should_ matter which compilation program you use
     to invoke `ld'.  If someone tracks this problem down, it can
     probably be fixed easily.

   * On the Alpha, you may get assembler errors about invalid syntax as
     a result of floating point constants.  This is due to a bug in the
     C library functions `ecvt', `fcvt' and `gcvt'.  Given valid
     floating point numbers, they sometimes print `NaN'.

   * On Irix 4.0.5F (and perhaps in some other versions), an assembler
     bug sometimes reorders instructions incorrectly when optimization
     is turned on.  If you think this may be happening to you, try
     using the GNU assembler; GAS version 2.1 supports ECOFF on Irix.

     Or use the `-noasmopt' option when you compile GCC with itself,
     and then again when you compile your program.  (This is a temporary
     kludge to turn off assembler optimization on Irix.)  If this
     proves to be what you need, edit the assembler spec in the file
     `specs' so that it unconditionally passes `-O0' to the assembler,
     and never passes `-O2' or `-O3'.


File: gcc.info,  Node: External Bugs,  Next: Incompatibilities,  Prev: Interoperation,  Up: Trouble

10.4 Problems Compiling Certain Programs
========================================

Certain programs have problems compiling.

   * Parse errors may occur compiling X11 on a Decstation running
     Ultrix 4.2 because of problems in DEC's versions of the X11 header
     files `X11/Xlib.h' and `X11/Xutil.h'.  People recommend adding
     `-I/usr/include/mit' to use the MIT versions of the header files,
     using the `-traditional' switch to turn off ISO C, or fixing the
     header files by adding this:

          #ifdef __STDC__
          #define NeedFunctionPrototypes 0
          #endif

   * On various 386 Unix systems derived from System V, including SCO,
     ISC, and ESIX, you may get error messages about running out of
     virtual memory while compiling certain programs.

     You can prevent this problem by linking GCC with the GNU malloc
     (which thus replaces the malloc that comes with the system).  GNU
     malloc is available as a separate package, and also in the file
     `src/gmalloc.c' in the GNU Emacs 19 distribution.

     If you have installed GNU malloc as a separate library package,
     use this option when you relink GCC:

          MALLOC=/usr/local/lib/libgmalloc.a

     Alternatively, if you have compiled `gmalloc.c' from Emacs 19, copy
     the object file to `gmalloc.o' and use this option when you relink
     GCC:

          MALLOC=gmalloc.o


File: gcc.info,  Node: Incompatibilities,  Next: Fixed Headers,  Prev: External Bugs,  Up: Trouble

10.5 Incompatibilities of GCC
=============================

There are several noteworthy incompatibilities between GNU C and K&R
(non-ISO) versions of C.  The `-traditional' option eliminates many of
these incompatibilities, _but not all_, by telling GCC to behave like a
K&R C compiler.

   * GCC normally makes string constants read-only.  If several
     identical-looking string constants are used, GCC stores only one
     copy of the string.

     One consequence is that you cannot call `mktemp' with a string
     constant argument.  The function `mktemp' always alters the string
     its argument points to.

     Another consequence is that `sscanf' does not work on some systems
     when passed a string constant as its format control string or
     input.  This is because `sscanf' incorrectly tries to write into
     the string constant.  Likewise `fscanf' and `scanf'.

     The best solution to these problems is to change the program to use
     `char'-array variables with initialization strings for these
     purposes instead of string constants.  But if this is not possible,
     you can use the `-fwritable-strings' flag, which directs GCC to
     handle string constants the same way most C compilers do.
     `-traditional' also has this effect, among others.

   * `-2147483648' is positive.

     This is because 2147483648 cannot fit in the type `int', so
     (following the ISO C rules) its data type is `unsigned long int'.
     Negating this value yields 2147483648 again.

   * GCC does not substitute macro arguments when they appear inside of
     string constants.  For example, the following macro in GCC

          #define foo(a) "a"

     will produce output `"a"' regardless of what the argument A is.

     The `-traditional' option directs GCC to handle such cases (among
     others) in the old-fashioned (non-ISO) fashion.

   * When you use `setjmp' and `longjmp', the only automatic variables
     guaranteed to remain valid are those declared `volatile'.  This is
     a consequence of automatic register allocation.  Consider this
     function:

          jmp_buf j;

          foo ()
          {
            int a, b;

            a = fun1 ();
            if (setjmp (j))
              return a;

            a = fun2 ();
            /* `longjmp (j)' may occur in `fun3'. */
            return a + fun3 ();
          }

     Here `a' may or may not be restored to its first value when the
     `longjmp' occurs.  If `a' is allocated in a register, then its
     first value is restored; otherwise, it keeps the last value stored
     in it.

     If you use the `-W' option with the `-O' option, you will get a
     warning when GCC thinks such a problem might be possible.

     The `-traditional' option directs GCC to put variables in the
     stack by default, rather than in registers, in functions that call
     `setjmp'.  This results in the behavior found in traditional C
     compilers.

   * Programs that use preprocessing directives in the middle of macro
     arguments do not work with GCC.  For example, a program like this
     will not work:

          foobar (
          #define luser
                  hack)

     ISO C does not permit such a construct.  It would make sense to
     support it when `-traditional' is used, but it is too much work to
     implement.

   * K&R compilers allow comments to cross over an inclusion boundary
     (i.e. started in an include file and ended in the including file).
     I think this would be quite ugly and can't imagine it could be
     needed.

   * Declarations of external variables and functions within a block
     apply only to the block containing the declaration.  In other
     words, they have the same scope as any other declaration in the
     same place.

     In some other C compilers, a `extern' declaration affects all the
     rest of the file even if it happens within a block.

     The `-traditional' option directs GCC to treat all `extern'
     declarations as global, like traditional compilers.

   * In traditional C, you can combine `long', etc., with a typedef
     name, as shown here:

          typedef int foo;
          typedef long foo bar;

     In ISO C, this is not allowed: `long' and other type modifiers
     require an explicit `int'.  Because this criterion is expressed by
     Bison grammar rules rather than C code, the `-traditional' flag
     cannot alter it.

   * PCC allows typedef names to be used as function parameters.  The
     difficulty described immediately above applies here too.

   * When in `-traditional' mode, GCC allows the following erroneous
     pair of declarations to appear together in a given scope:

          typedef int foo;
          typedef foo foo;

   * GCC treats all characters of identifiers as significant, even when
     in `-traditional' mode.  According to K&R-1 (2.2), "No more than
     the first eight characters are significant, although more may be
     used.".  Also according to K&R-1 (2.2), "An identifier is a
     sequence of letters and digits; the first character must be a
     letter.  The underscore _ counts as a letter.", but GCC also
     allows dollar signs in identifiers.

   * PCC allows whitespace in the middle of compound assignment
     operators such as `+='.  GCC, following the ISO standard, does not
     allow this.  The difficulty described immediately above applies
     here too.

   * GCC complains about unterminated character constants inside of
     preprocessing conditionals that fail.  Some programs have English
     comments enclosed in conditionals that are guaranteed to fail; if
     these comments contain apostrophes, GCC will probably report an
     error.  For example, this code would produce an error:

          #if 0
          You can't expect this to work.
          #endif

     The best solution to such a problem is to put the text into an
     actual C comment delimited by `/*...*/'.  However, `-traditional'
     suppresses these error messages.

   * Many user programs contain the declaration `long time ();'.  In the
     past, the system header files on many systems did not actually
     declare `time', so it did not matter what type your program
     declared it to return.  But in systems with ISO C headers, `time'
     is declared to return `time_t', and if that is not the same as
     `long', then `long time ();' is erroneous.

     The solution is to change your program to use appropriate system
     headers (`<time.h>' on systems with ISO C headers) and not to
     declare `time' if the system header files declare it, or failing
     that to use `time_t' as the return type of `time'.

   * When compiling functions that return `float', PCC converts it to a
     double.  GCC actually returns a `float'.  If you are concerned
     with PCC compatibility, you should declare your functions to return
     `double'; you might as well say what you mean.

   * When compiling functions that return structures or unions, GCC
     output code normally uses a method different from that used on most
     versions of Unix.  As a result, code compiled with GCC cannot call
     a structure-returning function compiled with PCC, and vice versa.

     The method used by GCC is as follows: a structure or union which is
     1, 2, 4 or 8 bytes long is returned like a scalar.  A structure or
     union with any other size is stored into an address supplied by
     the caller (usually in a special, fixed register, but on some
     machines it is passed on the stack).  The machine-description
     macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE' tell GCC where
     to pass this address.

     By contrast, PCC on most target machines returns structures and
     unions of any size by copying the data into an area of static
     storage, and then returning the address of that storage as if it
     were a pointer value.  The caller must copy the data from that
     memory area to the place where the value is wanted.  GCC does not
     use this method because it is slower and nonreentrant.

     On some newer machines, PCC uses a reentrant convention for all
     structure and union returning.  GCC on most of these machines uses
     a compatible convention when returning structures and unions in
     memory, but still returns small structures and unions in registers.

     You can tell GCC to use a compatible convention for all structure
     and union returning with the option `-fpcc-struct-return'.

   * GCC complains about program fragments such as `0x74ae-0x4000'
     which appear to be two hexadecimal constants separated by the minus
     operator.  Actually, this string is a single "preprocessing token".
     Each such token must correspond to one token in C.  Since this
     does not, GCC prints an error message.  Although it may appear
     obvious that what is meant is an operator and two values, the ISO
     C standard specifically requires that this be treated as erroneous.

     A "preprocessing token" is a "preprocessing number" if it begins
     with a digit and is followed by letters, underscores, digits,
     periods and `e+', `e-', `E+', `E-', `p+', `p-', `P+', or `P-'
     character sequences.  (In strict C89 mode, the sequences `p+',
     `p-', `P+' and `P-' cannot appear in preprocessing numbers.)

     To make the above program fragment valid, place whitespace in
     front of the minus sign.  This whitespace will end the
     preprocessing number.


File: gcc.info,  Node: Fixed Headers,  Next: Standard Libraries,  Prev: Incompatibilities,  Up: Trouble

10.6 Fixed Header Files
=======================

GCC needs to install corrected versions of some system header files.
This is because most target systems have some header files that won't
work with GCC unless they are changed.  Some have bugs, some are
incompatible with ISO C, and some depend on special features of other
compilers.

   Installing GCC automatically creates and installs the fixed header
files, by running a program called `fixincludes' (or for certain
targets an alternative such as `fixinc.svr4').  Normally, you don't
need to pay attention to this.  But there are cases where it doesn't do
the right thing automatically.

   * If you update the system's header files, such as by installing a
     new system version, the fixed header files of GCC are not
     automatically updated.  The easiest way to update them is to
     reinstall GCC.  (If you want to be clever, look in the makefile
     and you can find a shortcut.)

   * On some systems, in particular SunOS 4, header file directories
     contain machine-specific symbolic links in certain places.  This
     makes it possible to share most of the header files among hosts
     running the same version of SunOS 4 on different machine models.

     The programs that fix the header files do not understand this
     special way of using symbolic links; therefore, the directory of
     fixed header files is good only for the machine model used to
     build it.

     In SunOS 4, only programs that look inside the kernel will notice
     the difference between machine models.  Therefore, for most
     purposes, you need not be concerned about this.

     It is possible to make separate sets of fixed header files for the
     different machine models, and arrange a structure of symbolic
     links so as to use the proper set, but you'll have to do this by
     hand.

   * On Lynxos, GCC by default does not fix the header files.  This is
     because bugs in the shell cause the `fixincludes' script to fail.

     This means you will encounter problems due to bugs in the system
     header files.  It may be no comfort that they aren't GCC's fault,
     but it does mean that there's nothing for us to do about them.


File: gcc.info,  Node: Standard Libraries,  Next: Disappointments,  Prev: Fixed Headers,  Up: Trouble

10.7 Standard Libraries
=======================

GCC by itself attempts to be a conforming freestanding implementation.
*Note Language Standards Supported by GCC: Standards, for details of
what this means.  Beyond the library facilities required of such an
implementation, the rest of the C library is supplied by the vendor of
the operating system.  If that C library doesn't conform to the C
standards, then your programs might get warnings (especially when using
`-Wall') that you don't expect.

   For example, the `sprintf' function on SunOS 4.1.3 returns `char *'
while the C standard says that `sprintf' returns an `int'.  The
`fixincludes' program could make the prototype for this function match
the Standard, but that would be wrong, since the function will still
return `char *'.

   If you need a Standard compliant library, then you need to find one,
as GCC does not provide one.  The GNU C library (called `glibc')
provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
GNU/Linux and HURD-based GNU systems; no recent version of it supports
other systems, though some very old versions did.  Version 2.2 of the
GNU C library includes nearly complete C99 support.  You could also ask
your operating system vendor if newer libraries are available.


File: gcc.info,  Node: Disappointments,  Next: C++ Misunderstandings,  Prev: Standard Libraries,  Up: Trouble

10.8 Disappointments and Misunderstandings
==========================================

These problems are perhaps regrettable, but we don't know any practical
way around them.

   * Certain local variables aren't recognized by debuggers when you
     compile with optimization.

     This occurs because sometimes GCC optimizes the variable out of
     existence.  There is no way to tell the debugger how to compute the
     value such a variable "would have had", and it is not clear that
     would be desirable anyway.  So GCC simply does not mention the
     eliminated variable when it writes debugging information.

     You have to expect a certain amount of disagreement between the
     executable and your source code, when you use optimization.

   * Users often think it is a bug when GCC reports an error for code
     like this:

          int foo (struct mumble *);

          struct mumble { ... };

          int foo (struct mumble *x)
          { ... }

     This code really is erroneous, because the scope of `struct
     mumble' in the prototype is limited to the argument list
     containing it.  It does not refer to the `struct mumble' defined
     with file scope immediately below--they are two unrelated types
     with similar names in different scopes.

     But in the definition of `foo', the file-scope type is used
     because that is available to be inherited.  Thus, the definition
     and the prototype do not match, and you get an error.

     This behavior may seem silly, but it's what the ISO standard
     specifies.  It is easy enough for you to make your code work by
     moving the definition of `struct mumble' above the prototype.
     It's not worth being incompatible with ISO C just to avoid an
     error for the example shown above.

   * Accesses to bit-fields even in volatile objects works by accessing
     larger objects, such as a byte or a word.  You cannot rely on what
     size of object is accessed in order to read or write the
     bit-field; it may even vary for a given bit-field according to the
     precise usage.

     If you care about controlling the amount of memory that is
     accessed, use volatile but do not use bit-fields.

   * GCC comes with shell scripts to fix certain known problems in
     system header files.  They install corrected copies of various
     header files in a special directory where only GCC will normally
     look for them.  The scripts adapt to various systems by searching
     all the system header files for the problem cases that we know
     about.

     If new system header files are installed, nothing automatically
     arranges to update the corrected header files.  You will have to
     reinstall GCC to fix the new header files.  More specifically, go
     to the build directory and delete the files `stmp-fixinc' and
     `stmp-headers', and the subdirectory `include'; then do `make
     install' again.

   * On 68000 and x86 systems, for instance, you can get paradoxical
     results if you test the precise values of floating point numbers.
     For example, you can find that a floating point value which is not
     a NaN is not equal to itself.  This results from the fact that the
     floating point registers hold a few more bits of precision than
     fit in a `double' in memory.  Compiled code moves values between
     memory and floating point registers at its convenience, and moving
     them into memory truncates them.

     You can partially avoid this problem by using the `-ffloat-store'
     option (*note Optimize Options::).

   * On the MIPS, variable argument functions using `varargs.h' cannot
     have a floating point value for the first argument.  The reason
     for this is that in the absence of a prototype in scope, if the
     first argument is a floating point, it is passed in a floating
     point register, rather than an integer register.

     If the code is rewritten to use the ISO standard `stdarg.h' method
     of variable arguments, and the prototype is in scope at the time
     of the call, everything will work fine.

   * On the H8/300 and H8/300H, variable argument functions must be
     implemented using the ISO standard `stdarg.h' method of variable
     arguments.  Furthermore, calls to functions using `stdarg.h'
     variable arguments must have a prototype for the called function
     in scope at the time of the call.

   * On AIX and other platforms without weak symbol support, templates
     need to be instantiated explicitly and symbols for static members
     of templates will not be generated.


File: gcc.info,  Node: C++ Misunderstandings,  Next: Protoize Caveats,  Prev: Disappointments,  Up: Trouble

10.9 Common Misunderstandings with GNU C++
==========================================

C++ is a complex language and an evolving one, and its standard
definition (the ISO C++ standard) was only recently completed.  As a
result, your C++ compiler may occasionally surprise you, even when its
behavior is correct.  This section discusses some areas that frequently
give rise to questions of this sort.

* Menu:

* Static Definitions::  Static member declarations are not definitions
* Temporaries::         Temporaries may vanish before you expect
* Copy Assignment::     Copy Assignment operators copy virtual bases twice


File: gcc.info,  Node: Static Definitions,  Next: Temporaries,  Up: C++ Misunderstandings

10.9.1 Declare _and_ Define Static Members
------------------------------------------

When a class has static data members, it is not enough to _declare_ the
static member; you must also _define_ it.  For example:

     class Foo
     {
       ...
       void method();
       static int bar;
     };

   This declaration only establishes that the class `Foo' has an `int'
named `Foo::bar', and a member function named `Foo::method'.  But you
still need to define _both_ `method' and `bar' elsewhere.  According to
the ISO standard, you must supply an initializer in one (and only one)
source file, such as:

     int Foo::bar = 0;

   Other C++ compilers may not correctly implement the standard
behavior.  As a result, when you switch to `g++' from one of these
compilers, you may discover that a program that appeared to work
correctly in fact does not conform to the standard: `g++' reports as
undefined symbols any static data members that lack definitions.


File: gcc.info,  Node: Temporaries,  Next: Copy Assignment,  Prev: Static Definitions,  Up: C++ Misunderstandings

10.9.2 Temporaries May Vanish Before You Expect
-----------------------------------------------

It is dangerous to use pointers or references to _portions_ of a
temporary object.  The compiler may very well delete the object before
you expect it to, leaving a pointer to garbage.  The most common place
where this problem crops up is in classes like string classes,
especially ones that define a conversion function to type `char *' or
`const char *'--which is one reason why the standard `string' class
requires you to call the `c_str' member function.  However, any class
that returns a pointer to some internal structure is potentially
subject to this problem.

   For example, a program may use a function `strfunc' that returns
`string' objects, and another function `charfunc' that operates on
pointers to `char':

     string strfunc ();
     void charfunc (const char *);

     void
     f ()
     {
       const char *p = strfunc().c_str();
       ...
       charfunc (p);
       ...
       charfunc (p);
     }

In this situation, it may seem reasonable to save a pointer to the C
string returned by the `c_str' member function and use that rather than
call `c_str' repeatedly.  However, the temporary string created by the
call to `strfunc' is destroyed after `p' is initialized, at which point
`p' is left pointing to freed memory.

   Code like this may run successfully under some other compilers,
particularly obsolete cfront-based compilers that delete temporaries
along with normal local variables.  However, the GNU C++ behavior is
standard-conforming, so if your program depends on late destruction of
temporaries it is not portable.

   The safe way to write such code is to give the temporary a name,
which forces it to remain until the end of the scope of the name.  For
example:

     string& tmp = strfunc ();
     charfunc (tmp.c_str ());


File: gcc.info,  Node: Copy Assignment,  Prev: Temporaries,  Up: C++ Misunderstandings

10.9.3 Implicit Copy-Assignment for Virtual Bases
-------------------------------------------------

When a base class is virtual, only one subobject of the base class
belongs to each full object.  Also, the constructors and destructors are
invoked only once, and called from the most-derived class.  However,
such objects behave unspecified when being assigned.  For example:

     struct Base{
       char *name;
       Base(char *n) : name(strdup(n)){}
       Base& operator= (const Base& other){
        free (name);
        name = strdup (other.name);
       }
     };

     struct A:virtual Base{
       int val;
       A():Base("A"){}
     };

     struct B:virtual Base{
       int bval;
       B():Base("B"){}
     };

     struct Derived:public A, public B{
       Derived():Base("Derived"){}
     };

     void func(Derived &d1, Derived &d2)
     {
       d1 = d2;
     }

   The C++ standard specifies that `Base::Base' is only called once
when constructing or copy-constructing a Derived object.  It is
unspecified whether `Base::operator=' is called more than once when the
implicit copy-assignment for Derived objects is invoked (as it is
inside `func' in the example).

   g++ implements the "intuitive" algorithm for copy-assignment: assign
all direct bases, then assign all members.  In that algorithm, the
virtual base subobject can be encountered many times.  In the example,
copying proceeds in the following order: `val', `name' (via `strdup'),
`bval', and `name' again.

   If application code relies on copy-assignment, a user-defined
copy-assignment operator removes any uncertainties.  With such an
operator, the application can define whether and how the virtual base
subobject is assigned.


File: gcc.info,  Node: Protoize Caveats,  Next: Non-bugs,  Prev: C++ Misunderstandings,  Up: Trouble

10.10 Caveats of using `protoize'
=================================

The conversion programs `protoize' and `unprotoize' can sometimes
change a source file in a way that won't work unless you rearrange it.

   * `protoize' can insert references to a type name or type tag before
     the definition, or in a file where they are not defined.

     If this happens, compiler error messages should show you where the
     new references are, so fixing the file by hand is straightforward.

   * There are some C constructs which `protoize' cannot figure out.
     For example, it can't determine argument types for declaring a
     pointer-to-function variable; this you must do by hand.  `protoize'
     inserts a comment containing `???' each time it finds such a
     variable; so you can find all such variables by searching for this
     string.  ISO C does not require declaring the argument types of
     pointer-to-function types.

   * Using `unprotoize' can easily introduce bugs.  If the program
     relied on prototypes to bring about conversion of arguments, these
     conversions will not take place in the program without prototypes.
     One case in which you can be sure `unprotoize' is safe is when you
     are removing prototypes that were made with `protoize'; if the
     program worked before without any prototypes, it will work again
     without them.

     You can find all the places where this problem might occur by
     compiling the program with the `-Wconversion' option.  It prints a
     warning whenever an argument is converted.

   * Both conversion programs can be confused if there are macro calls
     in and around the text to be converted.  In other words, the
     standard syntax for a declaration or definition must not result
     from expanding a macro.  This problem is inherent in the design of
     C and cannot be fixed.  If only a few functions have confusing
     macro calls, you can easily convert them manually.

   * `protoize' cannot get the argument types for a function whose
     definition was not actually compiled due to preprocessing
     conditionals.  When this happens, `protoize' changes nothing in
     regard to such a function.  `protoize' tries to detect such
     instances and warn about them.

     You can generally work around this problem by using `protoize' step
     by step, each time specifying a different set of `-D' options for
     compilation, until all of the functions have been converted.
     There is no automatic way to verify that you have got them all,
     however.

   * Confusion may result if there is an occasion to convert a function
     declaration or definition in a region of source code where there
     is more than one formal parameter list present.  Thus, attempts to
     convert code containing multiple (conditionally compiled) versions
     of a single function header (in the same vicinity) may not produce
     the desired (or expected) results.

     If you plan on converting source files which contain such code, it
     is recommended that you first make sure that each conditionally
     compiled region of source code which contains an alternative
     function header also contains at least one additional follower
     token (past the final right parenthesis of the function header).
     This should circumvent the problem.

   * `unprotoize' can become confused when trying to convert a function
     definition or declaration which contains a declaration for a
     pointer-to-function formal argument which has the same name as the
     function being defined or declared.  We recommend you avoid such
     choices of formal parameter names.

   * You might also want to correct some of the indentation by hand and
     break long lines.  (The conversion programs don't write lines
     longer than eighty characters in any case.)


File: gcc.info,  Node: Non-bugs,  Next: Warnings and Errors,  Prev: Protoize Caveats,  Up: Trouble

10.11 Certain Changes We Don't Want to Make
===========================================

This section lists changes that people frequently request, but which we
do not make because we think GCC is better without them.

   * Checking the number and type of arguments to a function which has
     an old-fashioned definition and no prototype.

     Such a feature would work only occasionally--only for calls that
     appear in the same file as the called function, following the
     definition.  The only way to check all calls reliably is to add a
     prototype for the function.  But adding a prototype eliminates the
     motivation for this feature.  So the feature is not worthwhile.

   * Warning about using an expression whose type is signed as a shift
     count.

     Shift count operands are probably signed more often than unsigned.
     Warning about this would cause far more annoyance than good.

   * Warning about assigning a signed value to an unsigned variable.

     Such assignments must be very common; warning about them would
     cause more annoyance than good.

   * Warning when a non-void function value is ignored.

     Coming as I do from a Lisp background, I balk at the idea that
     there is something dangerous about discarding a value.  There are
     functions that return values which some callers may find useful;
     it makes no sense to clutter the program with a cast to `void'
     whenever the value isn't useful.

   * Making `-fshort-enums' the default.

     This would cause storage layout to be incompatible with most other
     C compilers.  And it doesn't seem very important, given that you
     can get the same result in other ways.  The case where it matters
     most is when the enumeration-valued object is inside a structure,
     and in that case you can specify a field width explicitly.

   * Making bit-fields unsigned by default on particular machines where
     "the ABI standard" says to do so.

     The ISO C standard leaves it up to the implementation whether a
     bit-field declared plain `int' is signed or not.  This in effect
     creates two alternative dialects of C.

     The GNU C compiler supports both dialects; you can specify the
     signed dialect with `-fsigned-bitfields' and the unsigned dialect
     with `-funsigned-bitfields'.  However, this leaves open the
     question of which dialect to use by default.

     Currently, the preferred dialect makes plain bit-fields signed,
     because this is simplest.  Since `int' is the same as `signed int'
     in every other context, it is cleanest for them to be the same in
     bit-fields as well.

     Some computer manufacturers have published Application Binary
     Interface standards which specify that plain bit-fields should be
     unsigned.  It is a mistake, however, to say anything about this
     issue in an ABI.  This is because the handling of plain bit-fields
     distinguishes two dialects of C.  Both dialects are meaningful on
     every type of machine.  Whether a particular object file was
     compiled using signed bit-fields or unsigned is of no concern to
     other object files, even if they access the same bit-fields in the
     same data structures.

     A given program is written in one or the other of these two
     dialects.  The program stands a chance to work on most any machine
     if it is compiled with the proper dialect.  It is unlikely to work
     at all if compiled with the wrong dialect.

     Many users appreciate the GNU C compiler because it provides an
     environment that is uniform across machines.  These users would be
     inconvenienced if the compiler treated plain bit-fields
     differently on certain machines.

     Occasionally users write programs intended only for a particular
     machine type.  On these occasions, the users would benefit if the
     GNU C compiler were to support by default the same dialect as the
     other compilers on that machine.  But such applications are rare.
     And users writing a program to run on more than one type of
     machine cannot possibly benefit from this kind of compatibility.

     This is why GCC does and will treat plain bit-fields in the same
     fashion on all types of machines (by default).

     There are some arguments for making bit-fields unsigned by default
     on all machines.  If, for example, this becomes a universal de
     facto standard, it would make sense for GCC to go along with it.
     This is something to be considered in the future.

     (Of course, users strongly concerned about portability should
     indicate explicitly in each bit-field whether it is signed or not.
     In this way, they write programs which have the same meaning in
     both C dialects.)

   * Undefining `__STDC__' when `-ansi' is not used.

     Currently, GCC defines `__STDC__' as long as you don't use
     `-traditional'.  This provides good results in practice.

     Programmers normally use conditionals on `__STDC__' to ask whether
     it is safe to use certain features of ISO C, such as function
     prototypes or ISO token concatenation.  Since plain `gcc' supports
     all the features of ISO C, the correct answer to these questions is
     "yes".

     Some users try to use `__STDC__' to check for the availability of
     certain library facilities.  This is actually incorrect usage in
     an ISO C program, because the ISO C standard says that a conforming
     freestanding implementation should define `__STDC__' even though it
     does not have the library facilities.  `gcc -ansi -pedantic' is a
     conforming freestanding implementation, and it is therefore
     required to define `__STDC__', even though it does not come with
     an ISO C library.

     Sometimes people say that defining `__STDC__' in a compiler that
     does not completely conform to the ISO C standard somehow violates
     the standard.  This is illogical.  The standard is a standard for
     compilers that claim to support ISO C, such as `gcc -ansi'--not
     for other compilers such as plain `gcc'.  Whatever the ISO C
     standard says is relevant to the design of plain `gcc' without
     `-ansi' only for pragmatic reasons, not as a requirement.

     GCC normally defines `__STDC__' to be 1, and in addition defines
     `__STRICT_ANSI__' if you specify the `-ansi' option, or a `-std'
     option for strict conformance to some version of ISO C.  On some
     hosts, system include files use a different convention, where
     `__STDC__' is normally 0, but is 1 if the user specifies strict
     conformance to the C Standard.  GCC follows the host convention
     when processing system include files, but when processing user
     files it follows the usual GNU C convention.

   * Undefining `__STDC__' in C++.

     Programs written to compile with C++-to-C translators get the
     value of `__STDC__' that goes with the C compiler that is
     subsequently used.  These programs must test `__STDC__' to
     determine what kind of C preprocessor that compiler uses: whether
     they should concatenate tokens in the ISO C fashion or in the
     traditional fashion.

     These programs work properly with GNU C++ if `__STDC__' is defined.
     They would not work otherwise.

     In addition, many header files are written to provide prototypes
     in ISO C but not in traditional C.  Many of these header files can
     work without change in C++ provided `__STDC__' is defined.  If
     `__STDC__' is not defined, they will all fail, and will all need
     to be changed to test explicitly for C++ as well.

   * Deleting "empty" loops.

     Historically, GCC has not deleted "empty" loops under the
     assumption that the most likely reason you would put one in a
     program is to have a delay, so deleting them will not make real
     programs run any faster.

     However, the rationale here is that optimization of a nonempty loop
     cannot produce an empty one, which holds for C but is not always
     the case for C++.

     Moreover, with `-funroll-loops' small "empty" loops are already
     removed, so the current behavior is both sub-optimal and
     inconsistent and will change in the future.

   * Making side effects happen in the same order as in some other
     compiler.

     It is never safe to depend on the order of evaluation of side
     effects.  For example, a function call like this may very well
     behave differently from one compiler to another:

          void func (int, int);

          int i = 2;
          func (i++, i++);

     There is no guarantee (in either the C or the C++ standard language
     definitions) that the increments will be evaluated in any
     particular order.  Either increment might happen first.  `func'
     might get the arguments `2, 3', or it might get `3, 2', or even
     `2, 2'.

   * Not allowing structures with volatile fields in registers.

     Strictly speaking, there is no prohibition in the ISO C standard
     against allowing structures with volatile fields in registers, but
     it does not seem to make any sense and is probably not what you
     wanted to do.  So the compiler will give an error message in this
     case.

   * Making certain warnings into errors by default.

     Some ISO C testsuites report failure when the compiler does not
     produce an error message for a certain program.

     ISO C requires a "diagnostic" message for certain kinds of invalid
     programs, but a warning is defined by GCC to count as a
     diagnostic.  If GCC produces a warning but not an error, that is
     correct ISO C support.  If test suites call this "failure", they
     should be run with the GCC option `-pedantic-errors', which will
     turn these warnings into errors.



File: gcc.info,  Node: Warnings and Errors,  Prev: Non-bugs,  Up: Trouble

10.12 Warning Messages and Error Messages
=========================================

The GNU compiler can produce two kinds of diagnostics: errors and
warnings.  Each kind has a different purpose:

     "Errors" report problems that make it impossible to compile your
     program.  GCC reports errors with the source file name and line
     number where the problem is apparent.

     "Warnings" report other unusual conditions in your code that _may_
     indicate a problem, although compilation can (and does) proceed.
     Warning messages also report the source file name and line number,
     but include the text `warning:' to distinguish them from error
     messages.

   Warnings may indicate danger points where you should check to make
sure that your program really does what you intend; or the use of
obsolete features; or the use of nonstandard features of GNU C or C++.
Many warnings are issued only if you ask for them, with one of the `-W'
options (for instance, `-Wall' requests a variety of useful warnings).

   GCC always tries to compile your program if possible; it never
gratuitously rejects a program whose meaning is clear merely because
(for instance) it fails to conform to a standard.  In some cases,
however, the C and C++ standards specify that certain extensions are
forbidden, and a diagnostic _must_ be issued by a conforming compiler.
The `-pedantic' option tells GCC to issue warnings in such cases;
`-pedantic-errors' says to make them errors instead.  This does not
mean that _all_ non-ISO constructs get warnings or errors.

   *Note Options to Request or Suppress Warnings: Warning Options, for
more detail on these and related command-line options.


File: gcc.info,  Node: Bugs,  Next: Service,  Prev: Trouble,  Up: Top

11 Reporting Bugs
*****************

Your bug reports play an essential role in making GCC reliable.

   When you encounter a problem, the first thing to do is to see if it
is already known.  *Note Trouble::.  If it isn't known, then you should
report the problem.

   Reporting a bug may help you by bringing a solution to your problem,
or it may not.  (If it does not, look in the service directory; see
*Note Service::.)  In any case, the principal function of a bug report
is to help the entire community by making the next version of GCC work
better.  Bug reports are your contribution to the maintenance of GCC.

   Since the maintainers are very overloaded, we cannot respond to every
bug report.  However, if the bug has not been fixed, we are likely to
send you a patch and ask you to tell us whether it works.

   In order for a bug report to serve its purpose, you must include the
information that makes for fixing the bug.

* Menu:

* Criteria:  Bug Criteria.   Have you really found a bug?
* Where: Bug Lists.	     Where to send your bug report.
* Reporting: Bug Reporting.  How to report a bug effectively.
* GNATS: gccbug.             You can use a bug reporting tool.
* Known: Trouble.            Known problems.
* Help: Service.             Where to ask for help.


File: gcc.info,  Node: Bug Criteria,  Next: Bug Lists,  Up: Bugs

11.1 Have You Found a Bug?
==========================

If you are not sure whether you have found a bug, here are some
guidelines:

   * If the compiler gets a fatal signal, for any input whatever, that
     is a compiler bug.  Reliable compilers never crash.

   * If the compiler produces invalid assembly code, for any input
     whatever (except an `asm' statement), that is a compiler bug,
     unless the compiler reports errors (not just warnings) which would
     ordinarily prevent the assembler from being run.

   * If the compiler produces valid assembly code that does not
     correctly execute the input source code, that is a compiler bug.

     However, you must double-check to make sure, because you may have
     run into an incompatibility between GNU C and traditional C (*note
     Incompatibilities::).  These incompatibilities might be considered
     bugs, but they are inescapable consequences of valuable features.

     Or you may have a program whose behavior is undefined, which
     happened by chance to give the desired results with another C or
     C++ compiler.

     For example, in many nonoptimizing compilers, you can write `x;'
     at the end of a function instead of `return x;', with the same
     results.  But the value of the function is undefined if `return'
     is omitted; it is not a bug when GCC produces different results.

     Problems often result from expressions with two increment
     operators, as in `f (*p++, *p++)'.  Your previous compiler might
     have interpreted that expression the way you intended; GCC might
     interpret it another way.  Neither compiler is wrong.  The bug is
     in your code.

     After you have localized the error to a single source line, it
     should be easy to check for these things.  If your program is
     correct and well defined, you have found a compiler bug.

   * If the compiler produces an error message for valid input, that is
     a compiler bug.

   * If the compiler does not produce an error message for invalid
     input, that is a compiler bug.  However, you should note that your
     idea of "invalid input" might be my idea of "an extension" or
     "support for traditional practice".

   * If you are an experienced user of one of the languages GCC
     supports, your suggestions for improvement of GCC are welcome in
     any case.


File: gcc.info,  Node: Bug Lists,  Next: Bug Reporting,  Prev: Bug Criteria,  Up: Bugs

11.2 Where to Report Bugs
=========================

Send bug reports for the GNU Compiler Collection to
<gcc-bugs@gcc.gnu.org>.  In accordance with the GNU-wide convention, in
which bug reports for tool "foo" are sent to `bug-foo@gnu.org', the
address <bug-gcc@gnu.org> may also be used; it will forward to the
address given above.

   Please read `http://gcc.gnu.org/bugs.html' for additional and/or
more up-to-date bug reporting instructions before you post a bug report.


File: gcc.info,  Node: Bug Reporting,  Next: gccbug,  Prev: Bug Lists,  Up: Bugs

11.3 How to Report Bugs
=======================

The fundamental principle of reporting bugs usefully is this: *report
all the facts*.  If you are not sure whether to state a fact or leave
it out, state it!

   Often people omit facts because they think they know what causes the
problem and they conclude that some details don't matter.  Thus, you
might assume that the name of the variable you use in an example does
not matter.  Well, probably it doesn't, but one cannot be sure.
Perhaps the bug is a stray memory reference which happens to fetch from
the location where that name is stored in memory; perhaps, if the name
were different, the contents of that location would fool the compiler
into doing the right thing despite the bug.  Play it safe and give a
specific, complete example.  That is the easiest thing for you to do,
and the most helpful.

   Keep in mind that the purpose of a bug report is to enable someone to
fix the bug if it is not known.  It isn't very important what happens if
the bug is already known.  Therefore, always write your bug reports on
the assumption that the bug is not known.

   Sometimes people give a few sketchy facts and ask, "Does this ring a
bell?"  This cannot help us fix a bug, so it is basically useless.  We
respond by asking for enough details to enable us to investigate.  You
might as well expedite matters by sending them to begin with.

   Try to make your bug report self-contained.  If we have to ask you
for more information, it is best if you include all the previous
information in your response, as well as the information that was
missing.

   Please report each bug in a separate message.  This makes it easier
for us to track which bugs have been fixed and to forward your bugs
reports to the appropriate maintainer.

   To enable someone to investigate the bug, you should include all
these things:

   * The version of GCC.  You can get this by running it with the `-v'
     option.

     Without this, we won't know whether there is any point in looking
     for the bug in the current version of GCC.

   * A complete input file that will reproduce the bug.  If the bug is
     in the C preprocessor, send a source file and any header files
     that it requires.  If the bug is in the compiler proper (`cc1'),
     send the preprocessor output generated by adding `-save-temps' to
     the compilation command (*note Debugging Options::).  When you do
     this, use the same `-I', `-D' or `-U' options that you used in
     actual compilation.  Then send the INPUT.i or INPUT.ii files
     generated.

     A single statement is not enough of an example.  In order to
     compile it, it must be embedded in a complete file of compiler
     input; and the bug might depend on the details of how this is done.

     Without a real example one can compile, all anyone can do about
     your bug report is wish you luck.  It would be futile to try to
     guess how to provoke the bug.  For example, bugs in register
     allocation and reloading frequently depend on every little detail
     of the function they happen in.

     Even if the input file that fails comes from a GNU program, you
     should still send the complete test case.  Don't ask the GCC
     maintainers to do the extra work of obtaining the program in
     question--they are all overworked as it is.  Also, the problem may
     depend on what is in the header files on your system; it is
     unreliable for the GCC maintainers to try the problem with the
     header files available to them.  By sending CPP output, you can
     eliminate this source of uncertainty and save us a certain
     percentage of wild goose chases.

   * The command arguments you gave GCC to compile that example and
     observe the bug.  For example, did you use `-O'?  To guarantee you
     won't omit something important, list all the options.

     If we were to try to guess the arguments, we would probably guess
     wrong and then we would not encounter the bug.

   * The type of machine you are using, and the operating system name
     and version number.

   * The operands you gave to the `configure' command when you installed
     the compiler.

   * A complete list of any modifications you have made to the compiler
     source.  (We don't promise to investigate the bug unless it
     happens in an unmodified compiler.  But if you've made
     modifications and don't tell us, then you are sending us on a wild
     goose chase.)

     Be precise about these changes.  A description in English is not
     enough--send a context diff for them.

     Adding files of your own (such as a machine description for a
     machine we don't support) is a modification of the compiler source.

   * Details of any other deviations from the standard procedure for
     installing GCC.

   * A description of what behavior you observe that you believe is
     incorrect.  For example, "The compiler gets a fatal signal," or,
     "The assembler instruction at line 208 in the output is incorrect."

     Of course, if the bug is that the compiler gets a fatal signal,
     then one can't miss it.  But if the bug is incorrect output, the
     maintainer might not notice unless it is glaringly wrong.  None of
     us has time to study all the assembler code from a 50-line C
     program just on the chance that one instruction might be wrong.
     We need _you_ to do this part!

     Even if the problem you experience is a fatal signal, you should
     still say so explicitly.  Suppose something strange is going on,
     such as, your copy of the compiler is out of synch, or you have
     encountered a bug in the C library on your system.  (This has
     happened!)  Your copy might crash and the copy here would not.  If
     you said to expect a crash, then when the compiler here fails to
     crash, we would know that the bug was not happening.  If you don't
     say to expect a crash, then we would not know whether the bug was
     happening.  We would not be able to draw any conclusion from our
     observations.

     If the problem is a diagnostic when compiling GCC with some other
     compiler, say whether it is a warning or an error.

     Often the observed symptom is incorrect output when your program
     is run.  Sad to say, this is not enough information unless the
     program is short and simple.  None of us has time to study a large
     program to figure out how it would work if compiled correctly,
     much less which line of it was compiled wrong.  So you will have
     to do that.  Tell us which source line it is, and what incorrect
     result happens when that line is executed.  A person who
     understands the program can find this as easily as finding a bug
     in the program itself.

   * If you send examples of assembler code output from GCC, please use
     `-g' when you make them.  The debugging information includes
     source line numbers which are essential for correlating the output
     with the input.

   * If you wish to mention something in the GCC source, refer to it by
     context, not by line number.

     The line numbers in the development sources don't match those in
     your sources.  Your line numbers would convey no useful
     information to the maintainers.

   * Additional information from a debugger might enable someone to
     find a problem on a machine which he does not have available.
     However, you need to think when you collect this information if
     you want it to have any chance of being useful.

     For example, many people send just a backtrace, but that is never
     useful by itself.  A simple backtrace with arguments conveys little
     about GCC because the compiler is largely data-driven; the same
     functions are called over and over for different RTL insns, doing
     different things depending on the details of the insn.

     Most of the arguments listed in the backtrace are useless because
     they are pointers to RTL list structure.  The numeric values of the
     pointers, which the debugger prints in the backtrace, have no
     significance whatever; all that matters is the contents of the
     objects they point to (and most of the contents are other such
     pointers).

     In addition, most compiler passes consist of one or more loops that
     scan the RTL insn sequence.  The most vital piece of information
     about such a loop--which insn it has reached--is usually in a
     local variable, not in an argument.

     What you need to provide in addition to a backtrace are the values
     of the local variables for several stack frames up.  When a local
     variable or an argument is an RTX, first print its value and then
     use the GDB command `pr' to print the RTL expression that it points
     to.  (If GDB doesn't run on your machine, use your debugger to call
     the function `debug_rtx' with the RTX as an argument.)  In
     general, whenever a variable is a pointer, its value is no use
     without the data it points to.

   Here are some things that are not necessary:

   * A description of the envelope of the bug.

     Often people who encounter a bug spend a lot of time investigating
     which changes to the input file will make the bug go away and which
     changes will not affect it.

     This is often time consuming and not very useful, because the way
     we will find the bug is by running a single example under the
     debugger with breakpoints, not by pure deduction from a series of
     examples.  You might as well save your time for something else.

     Of course, if you can find a simpler example to report _instead_ of
     the original one, that is a convenience.  Errors in the output
     will be easier to spot, running under the debugger will take less
     time, etc.  Most GCC bugs involve just one function, so the most
     straightforward way to simplify an example is to delete all the
     function definitions except the one where the bug occurs.  Those
     earlier in the file may be replaced by external declarations if
     the crucial function depends on them.  (Exception: inline
     functions may affect compilation of functions defined later in the
     file.)

     However, simplification is not vital; if you don't want to do this,
     report the bug anyway and send the entire test case you used.

   * In particular, some people insert conditionals `#ifdef BUG' around
     a statement which, if removed, makes the bug not happen.  These
     are just clutter; we won't pay any attention to them anyway.
     Besides, you should send us cpp output, and that can't have
     conditionals.

   * A patch for the bug.

     A patch for the bug is useful if it is a good one.  But don't omit
     the necessary information, such as the test case, on the
     assumption that a patch is all we need.  We might see problems
     with your patch and decide to fix the problem another way, or we
     might not understand it at all.

     Sometimes with a program as complicated as GCC it is very hard to
     construct an example that will make the program follow a certain
     path through the code.  If you don't send the example, we won't be
     able to construct one, so we won't be able to verify that the bug
     is fixed.

     And if we can't understand what bug you are trying to fix, or why
     your patch should be an improvement, we won't install it.  A test
     case will help us to understand.

     See `http://gcc.gnu.org/contribute.html' for guidelines on how to
     make it easy for us to understand and install your patches.

   * A guess about what the bug is or what it depends on.

     Such guesses are usually wrong.  Even I can't guess right about
     such things without first using the debugger to find the facts.

   * A core dump file.

     We have no way of examining a core dump for your type of machine
     unless we have an identical system--and if we do have one, we
     should be able to reproduce the crash ourselves.


File: gcc.info,  Node: gccbug,  Prev: Bug Reporting,  Up: Bugs

11.4 The gccbug script
======================

To simplify creation of bug reports, and to allow better tracking of
reports, we use the GNATS bug tracking system.  Part of that system is
the `gccbug' script.  This is a Unix shell script, so you need a shell
to run it.  It is normally installed in the same directory where `gcc'
is installed.

   The gccbug script is derived from send-pr, *note Creating new
Problem Reports: (send-pr)using send-pr.  When invoked, it starts a
text editor so you can fill out the various fields of the report.  When
the you quit the editor, the report is automatically send to the bug
reporting address.

   A number of fields in this bug report form are specific to GCC, and
are explained at `http://gcc.gnu.org/gnats.html'.


File: gcc.info,  Node: Service,  Next: Contributing,  Prev: Bugs,  Up: Top

12 How To Get Help with GCC
***************************

If you need help installing, using or changing GCC, there are two ways
to find it:

   * Send a message to a suitable network mailing list.  First try
     <gcc-help@gcc.gnu.org> (for help installing or using GCC), and if
     that brings no response, try <gcc@gcc.gnu.org>.  For help changing
     GCC, ask <gcc@gcc.gnu.org>.  If you think you have found a bug in
     GCC, please report it following the instructions at *note Bug
     Reporting::.

   * Look in the service directory for someone who might help you for a
     fee.  The service directory is found at
     `http://www.gnu.org/prep/service.html'.


File: gcc.info,  Node: Contributing,  Next: VMS,  Prev: Service,  Up: Top

13 Contributing to GCC Development
**********************************

If you would like to help pretest GCC releases to assure they work well,
our current development sources are available by CVS (see
`http://gcc.gnu.org/cvs.html').  Source and binary snapshots are also
available for FTP; see `http://gcc.gnu.org/snapshots.html'.

   If you would like to work on improvements to GCC, please read the
advice at these URLs:

     `http://gcc.gnu.org/contribute.html'
     `http://gcc.gnu.org/contributewhy.html'

for information on how to make useful contributions and avoid
duplication of effort.  Suggested projects are listed at
`http://gcc.gnu.org/projects/'.


File: gcc.info,  Node: VMS,  Next: Funding,  Prev: Contributing,  Up: Top

14 Using GCC on VMS
*******************

Here is how to use GCC on VMS.

* Menu:

* Include Files and VMS::  Where the preprocessor looks for the include files.
* Global Declarations::    How to do globaldef, globalref and globalvalue with
                           GCC.
* VMS Misc::		   Misc information.


File: gcc.info,  Node: Include Files and VMS,  Next: Global Declarations,  Up: VMS

14.1 Include Files and VMS
==========================

Due to the differences between the filesystems of Unix and VMS, GCC
attempts to translate file names in `#include' into names that VMS will
understand.  The basic strategy is to prepend a prefix to the
specification of the include file, convert the whole filename to a VMS
filename, and then try to open the file.  GCC tries various prefixes
one by one until one of them succeeds:

  1. The first prefix is the `GNU_CC_INCLUDE:' logical name: this is
     where GNU C header files are traditionally stored.  If you wish to
     store header files in non-standard locations, then you can assign
     the logical `GNU_CC_INCLUDE' to be a search list, where each
     element of the list is suitable for use with a rooted logical.

  2. The next prefix tried is `SYS$SYSROOT:[SYSLIB.]'.  This is where
     VAX-C header files are traditionally stored.

  3. If the include file specification by itself is a valid VMS
     filename, the preprocessor then uses this name with no prefix in
     an attempt to open the include file.

  4. If the file specification is not a valid VMS filename (i.e. does
     not contain a device or a directory specifier, and contains a `/'
     character), the preprocessor tries to convert it from Unix syntax
     to VMS syntax.

     Conversion works like this: the first directory name becomes a
     device, and the rest of the directories are converted into
     VMS-format directory names.  For example, the name `X11/foobar.h'
     is translated to `X11:[000000]foobar.h' or `X11:foobar.h',
     whichever one can be opened.  This strategy allows you to assign a
     logical name to point to the actual location of the header files.

  5. If none of these strategies succeeds, the `#include' fails.

   Include directives of the form:

     #include foobar

are a common source of incompatibility between VAX-C and GCC.  VAX-C
treats this much like a standard `#include <foobar.h>' directive.  That
is incompatible with the ISO C behavior implemented by GCC: to expand
the name `foobar' as a macro.  Macro expansion should eventually yield
one of the two standard formats for `#include':

     #include "FILE"
     #include <FILE>

   If you have this problem, the best solution is to modify the source
to convert the `#include' directives to one of the two standard forms.
That will work with either compiler.  If you want a quick and dirty fix,
define the file names as macros with the proper expansion, like this:

     #define stdio <stdio.h>

This will work, as long as the name doesn't conflict with anything else
in the program.

   Another source of incompatibility is that VAX-C assumes that:

     #include "foobar"

is actually asking for the file `foobar.h'.  GCC does not make this
assumption, and instead takes what you ask for literally; it tries to
read the file `foobar'.  The best way to avoid this problem is to
always specify the desired file extension in your include directives.

   GCC for VMS is distributed with a set of include files that is
sufficient to compile most general purpose programs.  Even though the
GCC distribution does not contain header files to define constants and
structures for some VMS system-specific functions, there is no reason
why you cannot use GCC with any of these functions.  You first may have
to generate or create header files, either by using the public domain
utility `UNSDL' (which can be found on a DECUS tape), or by extracting
the relevant modules from one of the system macro libraries, and using
an editor to construct a C header file.

   A `#include' file name cannot contain a DECNET node name.  The
preprocessor reports an I/O error if you attempt to use a node name,
whether explicitly, or implicitly via a logical name.


File: gcc.info,  Node: Global Declarations,  Next: VMS Misc,  Prev: Include Files and VMS,  Up: VMS

14.2 Global Declarations and VMS
================================

GCC does not provide the `globalref', `globaldef' and `globalvalue'
keywords of VAX-C.  You can get the same effect with an obscure feature
of GAS, the GNU assembler.  (This requires GAS version 1.39 or later.)
The following macros allow you to use this feature in a fairly natural
way:

     #ifdef __GNUC__
     #define GLOBALREF(TYPE,NAME)                      \
       TYPE NAME                                       \
       asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
     #define GLOBALDEF(TYPE,NAME,VALUE)                \
       TYPE NAME                                       \
       asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
         = VALUE
     #define GLOBALVALUEREF(TYPE,NAME)                 \
       const TYPE NAME[1]                              \
       asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
     #define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
       const TYPE NAME[1]                              \
       asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
         = {VALUE}
     #else
     #define GLOBALREF(TYPE,NAME) \
       globalref TYPE NAME
     #define GLOBALDEF(TYPE,NAME,VALUE) \
       globaldef TYPE NAME = VALUE
     #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
       globalvalue TYPE NAME = VALUE
     #define GLOBALVALUEREF(TYPE,NAME) \
       globalvalue TYPE NAME
     #endif

(The `_$$PsectAttributes_GLOBALSYMBOL' prefix at the start of the name
is removed by the assembler, after it has modified the attributes of
the symbol).  These macros are provided in the VMS binaries
distribution in a header file `GNU_HACKS.H'.  An example of the usage
is:

     GLOBALREF (int, ijk);
     GLOBALDEF (int, jkl, 0);

   The macros `GLOBALREF' and `GLOBALDEF' cannot be used
straightforwardly for arrays, since there is no way to insert the array
dimension into the declaration at the right place.  However, you can
declare an array with these macros if you first define a typedef for the
array type, like this:

     typedef int intvector[10];
     GLOBALREF (intvector, foo);

   Array and structure initializers will also break the macros; you can
define the initializer to be a macro of its own, or you can expand the
`GLOBALDEF' macro by hand.  You may find a case where you wish to use
the `GLOBALDEF' macro with a large array, but you are not interested in
explicitly initializing each element of the array.  In such cases you
can use an initializer like: `{0,}', which will initialize the entire
array to `0'.

   A shortcoming of this implementation is that a variable declared with
`GLOBALVALUEREF' or `GLOBALVALUEDEF' is always an array.  For example,
the declaration:

     GLOBALVALUEREF(int, ijk);

declares the variable `ijk' as an array of type `int [1]'.  This is
done because a globalvalue is actually a constant; its "value" is what
the linker would normally consider an address.  That is not how an
integer value works in C, but it is how an array works.  So treating
the symbol as an array name gives consistent results--with the
exception that the value seems to have the wrong type.  *Don't try to
access an element of the array.*  It doesn't have any elements.  The
array "address" may not be the address of actual storage.

   The fact that the symbol is an array may lead to warnings where the
variable is used.  Insert type casts to avoid the warnings.  Here is an
example; it takes advantage of the ISO C feature allowing macros that
expand to use the same name as the macro itself.

     GLOBALVALUEREF (int, ss$_normal);
     GLOBALVALUEDEF (int, xyzzy,123);
     #ifdef __GNUC__
     #define ss$_normal ((int) ss$_normal)
     #define xyzzy ((int) xyzzy)
     #endif

   Don't use `globaldef' or `globalref' with a variable whose type is
an enumeration type; this is not implemented.  Instead, make the
variable an integer, and use a `globalvaluedef' for each of the
enumeration values.  An example of this would be:

     #ifdef __GNUC__
     GLOBALDEF (int, color, 0);
     GLOBALVALUEDEF (int, RED, 0);
     GLOBALVALUEDEF (int, BLUE, 1);
     GLOBALVALUEDEF (int, GREEN, 3);
     #else
     enum globaldef color {RED, BLUE, GREEN = 3};
     #endif


File: gcc.info,  Node: VMS Misc,  Prev: Global Declarations,  Up: VMS

14.3 Other VMS Issues
=====================

GCC automatically arranges for `main' to return 1 by default if you
fail to specify an explicit return value.  This will be interpreted by
VMS as a status code indicating a normal successful completion.
Version 1 of GCC did not provide this default.

   GCC on VMS works only with the GNU assembler, GAS.  You need version
1.37 or later of GAS in order to produce value debugging information for
the VMS debugger.  Use the ordinary VMS linker with the object files
produced by GAS.

   Under previous versions of GCC, the generated code would occasionally
give strange results when linked to the sharable `VAXCRTL' library.
Now this should work.

   A caveat for use of `const' global variables: the `const' modifier
must be specified in every external declaration of the variable in all
of the source files that use that variable.  Otherwise the linker will
issue warnings about conflicting attributes for the variable.  Your
program will still work despite the warnings, but the variable will be
placed in writable storage.

   Although the VMS linker does distinguish between upper and lower case
letters in global symbols, most VMS compilers convert all such symbols
into upper case and most run-time library routines also have upper case
names.  To be able to reliably call such routines, GCC (by means of the
assembler GAS) converts global symbols into upper case like other VMS
compilers.  However, since the usual practice in C is to distinguish
case, GCC (via GAS) tries to preserve usual C behavior by augmenting
each name that is not all lower case.  This means truncating the name
to at most 23 characters and then adding more characters at the end
which encode the case pattern of those 23.   Names which contain at
least one dollar sign are an exception; they are converted directly into
upper case without augmentation.

   Name augmentation yields bad results for programs that use
precompiled libraries (such as Xlib) which were generated by another
compiler.  You can use the compiler option `/NOCASE_HACK' to inhibit
augmentation; it makes external C functions and variables
case-independent as is usual on VMS.  Alternatively, you could write
all references to the functions and variables in such libraries using
lower case; this will work on VMS, but is not portable to other
systems.  The compiler option `/NAMES' also provides control over
global name handling.

   Function and variable names are handled somewhat differently with
G++.  The GNU C++ compiler performs "name mangling" on function names,
which means that it adds information to the function name to describe
the data types of the arguments that the function takes.  One result of
this is that the name of a function can become very long.  Since the
VMS linker only recognizes the first 31 characters in a name, special
action is taken to ensure that each function and variable has a unique
name that can be represented in 31 characters.

   If the name (plus a name augmentation, if required) is less than 32
characters in length, then no special action is performed.  If the name
is longer than 31 characters, the assembler (GAS) will generate a hash
string based upon the function name, truncate the function name to 23
characters, and append the hash string to the truncated name.  If the
`/VERBOSE' compiler option is used, the assembler will print both the
full and truncated names of each symbol that is truncated.

   The `/NOCASE_HACK' compiler option should not be used when you are
compiling programs that use libg++.  libg++ has several instances of
objects (i.e.  `Filebuf' and `filebuf') which become indistinguishable
in a case-insensitive environment.  This leads to cases where you need
to inhibit augmentation selectively (if you were using libg++ and Xlib
in the same program, for example).  There is no special feature for
doing this, but you can get the result by defining a macro for each
mixed case symbol for which you wish to inhibit augmentation.  The
macro should expand into the lower case equivalent of itself.  For
example:

     #define StuDlyCapS studlycaps

   These macro definitions can be placed in a header file to minimize
the number of changes to your source code.


File: gcc.info,  Node: Funding,  Next: GNU Project,  Prev: VMS,  Up: Top

Funding Free Software
*********************

If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development.  The most effective approach known is to encourage
commercial redistributors to donate.

   Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers--the Free Software Foundation, and others.

   The way to convince distributors to do this is to demand it and
expect it from them.  So when you compare distributors, judge them
partly by how much they give to free software development.  Show
distributors they must compete to be the one who gives the most.

   To make this approach work, you must insist on numbers that you can
compare, such as, "We will donate ten dollars to the Frobnitz project
for each disk sold."  Don't be satisfied with a vague promise, such as
"A portion of the profits are donated," since it doesn't give a basis
for comparison.

   Even a precise fraction "of the profits from this disk" is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably less
than a dollar; it might be a few cents, or nothing at all.

   Some redistributors do development work themselves.  This is useful
too; but to keep everyone honest, you need to inquire how much they do,
and what kind.  Some kinds of development make much more long-term
difference than others.  For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much.  Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU Compiler Collection
contribute more; major new features or packages contribute the most.

   By establishing the idea that supporting further development is "the
proper thing to do" when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.

     Copyright (C) 1994 Free Software Foundation, Inc.
     Verbatim copying and redistribution of this section is permitted
     without royalty; alteration is not permitted.


File: gcc.info,  Node: GNU Project,  Next: Copying,  Prev: Funding,  Up: Top

The GNU Project and GNU/Linux
*****************************

The GNU Project was launched in 1984 to develop a complete Unix-like
operating system which is free software: the GNU system.  (GNU is a
recursive acronym for "GNU's Not Unix"; it is pronounced "guh-NEW".)
Variants of the GNU operating system, which use the kernel Linux, are
now widely used; though these systems are often referred to as "Linux",
they are more accurately called GNU/Linux systems.

   For more information, see:
     `http://www.gnu.org/'
     `http://www.gnu.org/gnu/linux-and-gnu.html'


File: gcc.info,  Node: Copying,  Next: GNU Free Documentation License,  Prev: GNU Project,  Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

The licenses for most software are designed to take away your freedom
to share and change it.  By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY
 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
=============================================

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) YEAR  NAME OF AUTHOR

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.


File: gcc.info,  Node: GNU Free Documentation License,  Next: Contributors,  Prev: Copying,  Up: Top

GNU Free Documentation License
******************************

                        Version 1.1, March 2000

     Copyright (C) 2000 Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone
     the effective freedom to copy and redistribute it, with or without
     modifying it, either commercially or noncommercially.  Secondarily,
     this License preserves for the author and publisher a way to get
     credit for their work, while not being considered responsible for
     modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed
     under the terms of this License.  The "Document", below, refers to
     any such manual or work.  Any member of the public is a licensee,
     and is addressed as "you".

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter
     section of the Document that deals exclusively with the
     relationship of the publishers or authors of the Document to the
     Document's overall subject (or to related matters) and contains
     nothing that could fall directly within that overall subject.
     (For example, if the Document is in part a textbook of
     mathematics, a Secondary Section may not explain any mathematics.)
     The relationship could be a matter of historical connection with
     the subject or with related matters, or of legal, commercial,
     philosophical, ethical or political position regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, whose contents can be viewed and edited directly
     and straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup has been designed
     to thwart or discourage subsequent modification by readers is not
     Transparent.  A copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML designed for human modification.
     Opaque formats include PostScript, PDF, proprietary formats that
     can be read and edited only by proprietary word processors, SGML
     or XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you
     must enclose the copies in covers that carry, clearly and legibly,
     all these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a publicly-accessible
     computer-network location containing a complete Transparent copy
     of the Document, free of added material, which the general
     network-using public has access to download anonymously at no
     charge using public-standard network protocols.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has less than five).

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section entitled "History", and its title, and
          add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. In any section entitled "Acknowledgments" or "Dedications",
          preserve the section's title, and preserve in the section all
          the substance and tone of each of the contributor
          acknowledgments and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section as "Endorsements" or to
          conflict in title with any Invariant Section.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections entitled
     "History" in the various original documents, forming one section
     entitled "History"; likewise combine any sections entitled
     "Acknowledgments", and any sections entitled "Dedications".  You
     must delete all sections entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, does not as a whole count as a
     Modified Version of the Document, provided no compilation
     copyright is claimed for the compilation.  Such a compilation is
     called an "aggregate", and this License does not apply to the
     other self-contained works thus compiled with the Document, on
     account of their being thus compiled, if they are not themselves
     derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one
     quarter of the entire aggregate, the Document's Cover Texts may be
     placed on covers that surround only the Document within the
     aggregate.  Otherwise they must appear on covers around the whole
     aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License provided that you also include the
     original English version of this License.  In case of a
     disagreement between the translation and the original English
     version of this License, the original English version will prevail.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.1
       or any later version published by the Free Software Foundation;
       with the Invariant Sections being LIST THEIR TITLES, with the
       Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
       A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

