-This is doc/gcc.info, produced by makeinfo version 4.5 from
+This is doc/gcc.info, produced by makeinfo version 4.11 from
doc/gcc.texi.
INFO-DIR-SECTION Programming
funds for GNU development.
\1f
-File: gcc.info, Node: Warning Options, Next: Debugging Options, Prev: Language Independent Options, Up: Invoking GCC
+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.
+
+\1f
+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::
+
+\1f
+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)
+
+\1f
+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);
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 `__PRAGMA_EXTERN_PREFIX' if the pragma is
+ available.
+
+\1f
+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.
+
+\1f
+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++.
+
+\1f
+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.
-Options to Request or Suppress Warnings
+ 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.
+
+\1f
+File: gcc.info, Node: Volatiles, Next: Restricted Pointers, Prev: Min and Max, Up: C++ Extensions
+
+6.2 When is a Volatile Object Accessed?
=======================================
- Warnings are diagnostic messages that report constructions which are
-not inherently erroneous but which are risky or suggest there may have
-been an error.
-
- You can request many specific warnings with options beginning `-W',
-for example `-Wimplicit' to request warnings on implicit declarations.
-Each of these specific warning options also has a negative form
-beginning `-Wno-' to turn off warnings; for example, `-Wno-implicit'.
-This manual lists only one of the two forms, whichever is not the
-default.
-
- The following options control the amount and kinds of warnings
-produced by GCC; for further, language-specific options also refer to
-*Note C++ Dialect Options:: and *Note Objective-C Dialect Options::.
-
-`-fsyntax-only'
- Check the code for syntax errors, but don't do anything beyond
- that.
-
-`-pedantic'
- Issue all the warnings demanded by strict ISO C and ISO C++;
- reject all programs that use forbidden extensions, and some other
- programs that do not follow ISO C and ISO C++. For ISO C, follows
- the version of the ISO C standard specified by any `-std' option
- used.
-
- Valid ISO C and ISO C++ programs should compile properly with or
- without this option (though a rare few will require `-ansi' or a
- `-std' option specifying the required version of ISO C). However,
- without this option, certain GNU extensions and traditional C and
- C++ features are supported as well. With this option, they are
- rejected.
-
- `-pedantic' does not cause warning messages for use of the
- alternate keywords whose names begin and end with `__'. Pedantic
- warnings are also disabled in the expression that follows
- `__extension__'. However, only system header files should use
- these escape routes; application programs should avoid them.
- *Note Alternate Keywords::.
-
- Some users try to use `-pedantic' to check programs for strict ISO
- C conformance. They soon find that it does not do quite what they
- want: it finds some non-ISO practices, but not all--only those for
- which ISO C _requires_ a diagnostic, and some others for which
- diagnostics have been added.
-
- A feature to report any failure to conform to ISO C might be
- useful in some instances, but would require considerable
- additional work and would be quite different from `-pedantic'. We
- don't have plans to support such a feature in the near future.
-
- Where the standard specified with `-std' represents a GNU extended
- dialect of C, such as `gnu89' or `gnu99', there is a corresponding
- "base standard", the version of ISO C on which the GNU extended
- dialect is based. Warnings from `-pedantic' are given where they
- are required by the base standard. (It would not make sense for
- such warnings to be given only for features not in the specified
- GNU C dialect, since by definition the GNU dialects of C include
- all features the compiler supports with the given option, and
- there would be nothing to warn about.)
-
-`-pedantic-errors'
- Like `-pedantic', except that errors are produced rather than
- warnings.
-
-`-w'
- Inhibit all warning messages.
-
-`-Wno-import'
- Inhibit warning messages about the use of `#import'.
-
-`-Wchar-subscripts'
- Warn if an array subscript has type `char'. This is a common cause
- of error, as programmers often forget that this type is signed on
- some machines.
-
-`-Wcomment'
- Warn whenever a comment-start sequence `/*' appears in a `/*'
- comment, or whenever a Backslash-Newline appears in a `//' comment.
-
-`-Wformat'
- Check calls to `printf' and `scanf', etc., to make sure that the
- arguments supplied have types appropriate to the format string
- specified, and that the conversions specified in the format string
- make sense. This includes standard functions, and others
- specified by format attributes (*note Function Attributes::), in
- the `printf', `scanf', `strftime' and `strfmon' (an X/Open
- extension, not in the C standard) families.
-
- The formats are checked against the format features supported by
- GNU libc version 2.2. These include all ISO C89 and C99 features,
- as well as features from the Single Unix Specification and some
- BSD and GNU extensions. Other library implementations may not
- support all these features; GCC does not support warning about
- features that go beyond a particular library's limitations.
- However, if `-pedantic' is used with `-Wformat', warnings will be
- given about format features not in the selected standard version
- (but not for `strfmon' formats, since those are not in any version
- of the C standard). *Note Options Controlling C Dialect: C
- Dialect Options.
-
- `-Wformat' is included in `-Wall'. For more control over some
- aspects of format checking, the options `-Wno-format-y2k',
- `-Wno-format-extra-args', `-Wformat-nonliteral',
- `-Wformat-security' and `-Wformat=2' are available, but are not
- included in `-Wall'.
-
-`-Wno-format-y2k'
- If `-Wformat' is specified, do not warn about `strftime' formats
- which may yield only a two-digit year.
-
-`-Wno-format-extra-args'
- If `-Wformat' is specified, do not warn about excess arguments to a
- `printf' or `scanf' format function. The C standard specifies
- that such arguments are ignored.
-
- Where the unused arguments lie between used arguments that are
- specified with `$' operand number specifications, normally
- warnings are still given, since the implementation could not know
- what type to pass to `va_arg' to skip the unused arguments.
- However, in the case of `scanf' formats, this option will suppress
- the warning if the unused arguments are all pointers, since the
- Single Unix Specification says that such unused arguments are
- allowed.
-
-`-Wformat-nonliteral'
- If `-Wformat' is specified, also warn if the format string is not a
- string literal and so cannot be checked, unless the format function
- takes its format arguments as a `va_list'.
-
-`-Wformat-security'
- If `-Wformat' is specified, also warn about uses of format
- functions that represent possible security problems. At present,
- this warns about calls to `printf' and `scanf' functions where the
- format string is not a string literal and there are no format
- arguments, as in `printf (foo);'. This may be a security hole if
- the format string came from untrusted input and contains `%n'.
- (This is currently a subset of what `-Wformat-nonliteral' warns
- about, but in future warnings may be added to `-Wformat-security'
- that are not included in `-Wformat-nonliteral'.)
-
-`-Wformat=2'
- Enable `-Wformat' plus format checks not included in `-Wformat'.
- Currently equivalent to `-Wformat -Wformat-nonliteral
- -Wformat-security'.
-
-`-Wimplicit-int'
- Warn when a declaration does not specify a type.
-
-`-Wimplicit-function-declaration'
-`-Werror-implicit-function-declaration'
- Give a warning (or error) whenever a function is used before being
- declared.
-
-`-Wimplicit'
- Same as `-Wimplicit-int' and `-Wimplicit-function-declaration'.
-
-`-Wmain'
- Warn if the type of `main' is suspicious. `main' should be a
- function with external linkage, returning int, taking either zero
- arguments, two, or three arguments of appropriate types.
-
-`-Wmissing-braces'
- Warn if an aggregate or union initializer is not fully bracketed.
- In the following example, the initializer for `a' is not fully
- bracketed, but that for `b' is fully bracketed.
-
- int a[2][2] = { 0, 1, 2, 3 };
- int b[2][2] = { { 0, 1 }, { 2, 3 } };
-
-`-Wparentheses'
- Warn if parentheses are omitted in certain contexts, such as when
- there is an assignment in a context where a truth value is
- expected, or when operators are nested whose precedence people
- often get confused about.
-
- Also warn about constructions where there may be confusion to which
- `if' statement an `else' branch belongs. Here is an example of
- such a case:
+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.
- {
- if (a)
- if (b)
- foo ();
- else
- bar ();
- }
+\1f
+File: gcc.info, Node: Restricted Pointers, Next: Vague Linkage, Prev: Volatiles, Up: C++ Extensions
- In C, every `else' branch belongs to the innermost possible `if'
- statement, which in this example is `if (b)'. This is often not
- what the programmer expected, as illustrated in the above example
- by indentation the programmer chose. When there is the potential
- for this confusion, GCC will issue a warning when this flag is
- specified. To eliminate the warning, add explicit braces around
- the innermost `if' statement so there is no way the `else' could
- belong to the enclosing `if'. The resulting code would look like
- this:
+6.3 Restricting Pointer Aliasing
+================================
- {
- if (a)
- {
- if (b)
- foo ();
- else
- bar ();
- }
- }
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
-`-Wsequence-point'
- Warn about code that may have undefined semantics because of
- violations of sequence point rules in the C standard.
-
- The C standard defines the order in which expressions in a C
- program are evaluated in terms of "sequence points", which
- represent a partial ordering between the execution of parts of the
- program: those executed before the sequence point, and those
- executed after it. These occur after the evaluation of a full
- expression (one which is not part of a larger expression), after
- the evaluation of the first operand of a `&&', `||', `? :' or `,'
- (comma) operator, before a function is called (but after the
- evaluation of its arguments and the expression denoting the called
- function), and in certain other places. Other than as expressed
- by the sequence point rules, the order of evaluation of
- subexpressions of an expression is not specified. All these rules
- describe only a partial order rather than a total order, since,
- for example, if two functions are called within one expression
- with no sequence point between them, the order in which the
- functions are called is not specified. However, the standards
- committee have ruled that function calls do not overlap.
-
- It is not specified when between sequence points modifications to
- the values of objects take effect. Programs whose behavior
- depends on this have undefined behavior; the C standard specifies
- that "Between the previous and next sequence point an object shall
- have its stored value modified at most once by the evaluation of
- an expression. Furthermore, the prior value shall be read only to
- determine the value to be stored.". If a program breaks these
- rules, the results on any particular implementation are entirely
- unpredictable.
-
- Examples of code with undefined behavior are `a = a++;', `a[n] =
- b[n++]' and `a[i++] = i;'. Some more complicated cases are not
- diagnosed by this option, and it may give an occasional false
- positive result, but in general it has been found fairly effective
- at detecting this sort of problem in programs.
-
- The present implementation of this option only works for C
- programs. A future implementation may also work for C++ programs.
-
- The C standard is worded confusingly, therefore there is some
- debate over the precise meaning of the sequence point rules in
- subtle cases. Links to discussions of the problem, including
- proposed formal definitions, may be found on our readings page, at
- `http://gcc.gnu.org/readings.html'.
-
-`-Wreturn-type'
- Warn whenever a function is defined with a return-type that
- defaults to `int'. Also warn about any `return' statement with no
- return-value in a function whose return-type is not `void'.
-
- For C++, a function without return type always produces a
- diagnostic message, even when `-Wno-return-type' is specified.
- The only exceptions are `main' and functions defined in system
- headers.
-
-`-Wswitch'
- Warn whenever a `switch' statement has an index of enumeral type
- and lacks a `case' for one or more of the named codes of that
- enumeration. (The presence of a `default' label prevents this
- warning.) `case' labels outside the enumeration range also
- provoke warnings when this option is used.
-
-`-Wtrigraphs'
- Warn if any trigraphs are encountered that might change the
- meaning of the program (trigraphs within comments are not warned
- about).
-
-`-Wunused-function'
- Warn whenever a static function is declared but not defined or a
- non\-inline static function is unused.
-
-`-Wunused-label'
- Warn whenever a label is declared but not used.
-
- To suppress this warning use the `unused' attribute (*note
- Variable Attributes::).
-
-`-Wunused-parameter'
- Warn whenever a function parameter is unused aside from its
- declaration.
-
- To suppress this warning use the `unused' attribute (*note
- Variable Attributes::).
-
-`-Wunused-variable'
- Warn whenever a local variable or non-constant static variable is
- unused aside from its declaration
-
- To suppress this warning use the `unused' attribute (*note
- Variable Attributes::).
-
-`-Wunused-value'
- Warn whenever a statement computes a result that is explicitly not
- used.
-
- To suppress this warning cast the expression to `void'.
-
-`-Wunused'
- All all the above `-Wunused' options combined.
-
- In order to get a warning about an unused function parameter, you
- must either specify `-W -Wunused' or separately specify
- `-Wunused-parameter'.
-
-`-Wuninitialized'
- Warn if an automatic variable is used without first being
- initialized or if a variable may be clobbered by a `setjmp' call.
-
- These warnings are possible only in optimizing compilation,
- because they require data flow information that is computed only
- when optimizing. If you don't specify `-O', you simply won't get
- these warnings.
-
- These warnings occur only for variables that are candidates for
- register allocation. Therefore, they do not occur for a variable
- that is declared `volatile', or whose address is taken, or whose
- size is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
- structures, unions or arrays, even when they are in registers.
-
- Note that there may be no warning about a variable that is used
- only to compute a value that itself is never used, because such
- computations may be deleted by data flow analysis before the
- warnings are printed.
-
- These warnings are made optional because GCC is not smart enough
- to see all the reasons why the code might be correct despite
- appearing to have an error. Here is one example of how this can
- happen:
+ 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.
+
+\1f
+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.
+
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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)
{
- int x;
- switch (y)
- {
- case 1: x = 1;
- break;
- case 2: x = 4;
- break;
- case 3: x = 5;
- }
- foo (x);
+ 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;
}
- If the value of `y' is always 1, 2 or 3, then `x' is always
- initialized, but GCC doesn't know this. Here is another common
- case:
+ 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'.
+\1f
+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
+
+\1f
+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 save_y;
- if (change_y) save_y = y, y = new_y;
- ...
- if (change_y) y = save_y;
+ int a, b;
+
+ a = fun1 ();
+ if (setjmp (j))
+ return a;
+
+ a = fun2 ();
+ /* `longjmp (j)' may occur in `fun3'. */
+ return a + fun3 ();
}
- This has no bug because `save_y' is used only if it is set.
-
- This option also warns when a non-volatile automatic variable
- might be changed by a call to `longjmp'. These warnings as well
- are possible only in optimizing compilation.
-
- The compiler sees only the calls to `setjmp'. It cannot know
- where `longjmp' will be called; in fact, a signal handler could
- call it at any point in the code. As a result, you may get a
- warning even when there is in fact no problem because `longjmp'
- cannot in fact be called at the place which would cause a problem.
-
- Some spurious warnings can be avoided if you declare all the
- functions you use that never return as `noreturn'. *Note Function
- Attributes::.
-
-`-Wreorder (C++ only)'
- Warn when the order of member initializers given in the code does
- not match the order in which they must be executed. For instance:
-
-`-Wunknown-pragmas'
- Warn when a #pragma directive is encountered which is not
- understood by GCC. If this command line option is used, warnings
- will even be issued for unknown pragmas in system header files.
- This is not the case if the warnings were only enabled by the
- `-Wall' command line option.
-
-`-Wall'
- All of the above `-W' options combined. This enables all the
- warnings about constructions that some users consider
- questionable, and that are easy to avoid (or modify to prevent the
- warning), even in conjunction with macros.
-
-`-Wdiv-by-zero'
- Warn about compile-time integer division by zero. This is
- default. To inhibit the warning messages, use `-Wno-div-by-zero'.
- Floating point division by zero is not warned about, as it can be
- a legitimate way of obtaining infinities and NaNs.
-
-`-Wmultichar'
- Warn if a multicharacter constant (`'FOOF'') is used. This is
- default. To inhibit the warning messages, use `-Wno-multichar'.
- Usually they indicate a typo in the user's code, as they have
- implementation-defined values, and should not be used in portable
- code.
-
-`-Wsystem-headers'
- Print warning messages for constructs found in system header files.
- Warnings from system headers are normally suppressed, on the
- assumption that they usually do not indicate real problems and
- would only make the compiler output harder to read. Using this
- command line option tells GCC to emit warnings from system headers
- as if they occurred in user code. However, note that using
- `-Wall' in conjunction with this option will _not_ warn about
- unknown pragmas in system headers--for that, `-Wunknown-pragmas'
- must also be used.
-
- The following `-W...' options are not implied by `-Wall'. Some of
-them warn about constructions that users generally do not consider
-questionable, but which occasionally you might wish to check for;
-others warn about constructions that are necessary or hard to avoid in
-some cases, and there is no simple way to modify the code to suppress
-the warning.
-
-`-W'
- Print extra warning messages for these events:
-
- * A function can return either with or without a value.
- (Falling off the end of the function body is considered
- returning without a value.) For example, this function would
- evoke such a warning:
-
- foo (a)
- {
- if (a > 0)
- return a;
- }
-
- * An expression-statement or the left-hand side of a comma
- expression contains no side effects. To suppress the
- warning, cast the unused expression to void. For example, an
- expression such as `x[i,j]' will cause a warning, but
- `x[(void)i,j]' will not.
-
- * An unsigned value is compared against zero with `<' or `<='.
-
- * A comparison like `x<=y<=z' appears; this is equivalent to
- `(x<=y ? 1 : 0) <= z', which is a different interpretation
- from that of ordinary mathematical notation.
-
- * Storage-class specifiers like `static' are not the first
- things in a declaration. According to the C Standard, this
- usage is obsolescent.
-
- * The return type of a function has a type qualifier such as
- `const'. Such a type qualifier has no effect, since the
- value returned by a function is not an lvalue. (But don't
- warn about the GNU extension of `volatile void' return types.
- That extension will be warned about if `-pedantic' is
- specified.)
-
- * If `-Wall' or `-Wunused' is also specified, warn about unused
- arguments.
-
- * A comparison between signed and unsigned values could produce
- an incorrect result when the signed value is converted to
- unsigned. (But don't warn if `-Wno-sign-compare' is also
- specified.)
-
- * An aggregate has a partly bracketed initializer. For
- example, the following code would evoke such a warning,
- because braces are missing around the initializer for `x.h':
-
- struct s { int f, g; };
- struct t { struct s h; int i; };
- struct t x = { 1, 2, 3 };
-
- * An aggregate has an initializer which does not initialize all
- members. For example, the following code would cause such a
- warning, because `x.h' would be implicitly initialized to
- zero:
-
- struct s { int f, g, h; };
- struct s x = { 3, 4 };
-
-`-Wfloat-equal'
- Warn if floating point values are used in equality comparisons.
-
- The idea behind this is that sometimes it is convenient (for the
- programmer) to consider floating-point values as approximations to
- infinitely precise real numbers. If you are doing this, then you
- need to compute (by analysing the code, or in some other way) the
- maximum or likely maximum error that the computation introduces,
- and allow for it when performing comparisons (and when producing
- output, but that's a different problem). In particular, instead
- of testing for equality, you would check to see whether the two
- values have ranges that overlap; and this is done with the
- relational operators, so equality comparisons are probably
- mistaken.
-
-`-Wtraditional (C only)'
- Warn about certain constructs that behave differently in
- traditional and ISO C. Also warn about ISO C constructs that have
- no traditional C equivalent, and/or problematic constructs which
- should be avoided.
-
- * Macro parameters that appear within string literals in the
- macro body. In traditional C macro replacement takes place
- within string literals, but does not in ISO C.
-
- * In traditional C, some preprocessor directives did not exist.
- Traditional preprocessors would only consider a line to be a
- directive if the `#' appeared in column 1 on the line.
- Therefore `-Wtraditional' warns about directives that
- traditional C understands but would ignore because the `#'
- does not appear as the first character on the line. It also
- suggests you hide directives like `#pragma' not understood by
- traditional C by indenting them. Some traditional
- implementations would not recognize `#elif', so it suggests
- avoiding it altogether.
-
- * A function-like macro that appears without arguments.
-
- * The unary plus operator.
-
- * The `U' integer constant suffix, or the `F' or `L' floating
- point constant suffixes. (Traditional C does support the `L'
- suffix on integer constants.) Note, these suffixes appear in
- macros defined in the system headers of most modern systems,
- e.g. the `_MIN'/`_MAX' macros in `<limits.h>'. Use of these
- macros in user code might normally lead to spurious warnings,
- however gcc's integrated preprocessor has enough context to
- avoid warning in these cases.
-
- * A function declared external in one block and then used after
- the end of the block.
-
- * A `switch' statement has an operand of type `long'.
-
- * A non-`static' function declaration follows a `static' one.
- This construct is not accepted by some traditional C
- compilers.
-
- * The ISO type of an integer constant has a different width or
- signedness from its traditional type. This warning is only
- issued if the base of the constant is ten. I.e. hexadecimal
- or octal values, which typically represent bit patterns, are
- not warned about.
-
- * Usage of ISO string concatenation is detected.
-
- * Initialization of automatic aggregates.
-
- * Identifier conflicts with labels. Traditional C lacks a
- separate namespace for labels.
-
- * Initialization of unions. If the initializer is zero, the
- warning is omitted. This is done under the assumption that
- the zero initializer in user code appears conditioned on e.g.
- `__STDC__' to avoid missing initializer warnings and relies
- on default initialization to zero in the traditional C case.
-
- * Conversions by prototypes between fixed/floating point values
- and vice versa. The absence of these prototypes when
- compiling with traditional C would cause serious problems.
- This is a subset of the possible conversion warnings, for the
- full set use `-Wconversion'.
-
-`-Wundef'
- Warn if an undefined identifier is evaluated in an `#if' directive.
-
-`-Wshadow'
- Warn whenever a local variable shadows another local variable,
- parameter or global variable or whenever a built-in function is
- shadowed.
-
-`-Wlarger-than-LEN'
- Warn whenever an object of larger than LEN bytes is defined.
-
-`-Wpointer-arith'
- Warn about anything that depends on the "size of" a function type
- or of `void'. GNU C assigns these types a size of 1, for
- convenience in calculations with `void *' pointers and pointers to
- functions.
-
-`-Wbad-function-cast (C only)'
- Warn whenever a function call is cast to a non-matching type. For
- example, warn if `int malloc()' is cast to `anything *'.
-
-`-Wcast-qual'
- Warn whenever a pointer is cast so as to remove a type qualifier
- from the target type. For example, warn if a `const char *' is
- cast to an ordinary `char *'.
-
-`-Wcast-align'
- Warn whenever a pointer is cast such that the required alignment
- of the target is increased. For example, warn if a `char *' is
- cast to an `int *' on machines where integers can only be accessed
- at two- or four-byte boundaries.
-
-`-Wwrite-strings'
- When compiling C, give string constants the type `const
- char[LENGTH]' so that copying the address of one into a
- non-`const' `char *' pointer will get a warning; when compiling
- C++, warn about the deprecated conversion from string constants to
- `char *'. These warnings will help you find at compile time code
- that can try to write into a string constant, but only if you have
- been very careful about using `const' in declarations and
- prototypes. Otherwise, it will just be a nuisance; this is why we
- did not make `-Wall' request these warnings.
-
-`-Wconversion'
- Warn if a prototype causes a type conversion that is different
- from what would happen to the same argument in the absence of a
- prototype. This includes conversions of fixed point to floating
- and vice versa, and conversions changing the width or signedness
- of a fixed point argument except when the same as the default
- promotion.
-
- Also, warn if a negative integer constant expression is implicitly
- converted to an unsigned type. For example, warn about the
- assignment `x = -1' if `x' is unsigned. But do not warn about
- explicit casts like `(unsigned) -1'.
-
-`-Wsign-compare'
- Warn when a comparison between signed and unsigned values could
- produce an incorrect result when the signed value is converted to
- unsigned. This warning is also enabled by `-W'; to get the other
- warnings of `-W' without this warning, use `-W -Wno-sign-compare'.
-
-`-Waggregate-return'
- Warn if any functions that return structures or unions are defined
- or called. (In languages where you can return an array, this also
- elicits a warning.)
-
-`-Wstrict-prototypes (C only)'
- Warn if a function is declared or defined without specifying the
- argument types. (An old-style function definition is permitted
- without a warning if preceded by a declaration which specifies the
- argument types.)
-
-`-Wmissing-prototypes (C only)'
- Warn if a global function is defined without a previous prototype
- declaration. This warning is issued even if the definition itself
- provides a prototype. The aim is to detect global functions that
- fail to be declared in header files.
-
-`-Wmissing-declarations'
- Warn if a global function is defined without a previous
- declaration. Do so even if the definition itself provides a
- prototype. Use this option to detect global functions that are
- not declared in header files.
-
-`-Wmissing-noreturn'
- Warn about functions which might be candidates for attribute
- `noreturn'. Note these are only possible candidates, not absolute
- ones. Care should be taken to manually verify functions actually
- do not ever return before adding the `noreturn' attribute,
- otherwise subtle code generation bugs could be introduced. You
- will not get a warning for `main' in hosted C environments.
-
-`-Wmissing-format-attribute'
- If `-Wformat' is enabled, also warn about functions which might be
- candidates for `format' attributes. Note these are only possible
- candidates, not absolute ones. GCC will guess that `format'
- attributes might be appropriate for any function that calls a
- function like `vprintf' or `vscanf', but this might not always be
- the case, and some functions for which `format' attributes are
- appropriate may not be detected. This option has no effect unless
- `-Wformat' is enabled (possibly by `-Wall').
-
-`-Wno-deprecated-declarations'
- Do not warn about uses of functions, variables, and types marked as
- deprecated by using the `deprecated' attribute. (*note Function
- Attributes::, *note Variable Attributes::, *note Type
- Attributes::.)
-
-`-Wpacked'
- Warn if a structure is given the packed attribute, but the packed
- attribute has no effect on the layout or size of the structure.
- Such structures may be mis-aligned for little benefit. For
- instance, in this code, the variable `f.x' in `struct bar' will be
- misaligned even though `struct bar' does not itself have the
- packed attribute:
-
- struct foo {
- int x;
- char a, b, c, d;
- } __attribute__((packed));
- struct bar {
- char z;
- struct foo f;
- };
+ 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: gcc.info, Node: C++ Misunderstandings, Next: Protoize Caveats, Prev: Disappointments, Up: Trouble
-`-Wpadded'
- Warn if padding is included in a structure, either to align an
- element of the structure or to align the whole structure.
- Sometimes when this happens it is possible to rearrange the fields
- of the structure to reduce the padding and so make the structure
- smaller.
-
-`-Wredundant-decls'
- Warn if anything is declared more than once in the same scope,
- even in cases where multiple declaration is valid and changes
- nothing.
-
-`-Wnested-externs (C only)'
- Warn if an `extern' declaration is encountered within a function.
-
-`-Wunreachable-code'
- Warn if the compiler detects that code will never be executed.
-
- This option is intended to warn when the compiler detects that at
- least a whole line of source code will never be executed, because
- some condition is never satisfied or because it is after a
- procedure that never returns.
-
- It is possible for this option to produce a warning even though
- there are circumstances under which part of the affected line can
- be executed, so care should be taken when removing
- apparently-unreachable code.
-
- For instance, when a function is inlined, a warning may mean that
- the line is unreachable in only one inlined copy of the function.
-
- This option is not made part of `-Wall' because in a debugging
- version of a program there is often substantial code which checks
- correct functioning of the program and is, hopefully, unreachable
- because the program does work. Another common use of unreachable
- code is to provide behavior which is selectable at compile-time.
-
-`-Winline'
- Warn if a function can not be inlined and it was declared as
- inline.
-
-`-Wlong-long'
- Warn if `long long' type is used. This is default. To inhibit
- the warning messages, use `-Wno-long-long'. Flags `-Wlong-long'
- and `-Wno-long-long' are taken into account only when `-pedantic'
- flag is used.
-
-`-Wdisabled-optimization'
- Warn if a requested optimization pass is disabled. This warning
- does not generally indicate that there is anything wrong with your
- code; it merely indicates that GCC's optimizers were unable to
- handle the code effectively. Often, the problem is that your code
- is too big or too complex; GCC will refuse to optimize programs
- when the optimization itself is likely to take inordinate amounts
- of time.
-
-`-Werror'
- Make all warnings into errors.
+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
+
+\1f
+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.
+
+\1f
+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 ());
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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.
+
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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/'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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.
projects / msp430-gcc.git / blobdiff