X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=gcc%2Fdoc%2Fgcc.info-3;h=06ace5031341bda99e856bede4ffc12961306cc0;hb=5a5369932a08c074943c94407697a5813002fd31;hp=82936afc94f1b098a4655e5d45419bee25e6e231;hpb=aaf7afc53d3ed4f6c811f6ec493d857ea0459573;p=msp430-gcc.git diff --git a/gcc/doc/gcc.info-3 b/gcc/doc/gcc.info-3 index 82936afc..06ace503 100644 --- a/gcc/doc/gcc.info-3 +++ b/gcc/doc/gcc.info-3 @@ -1,4 +1,4 @@ -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 @@ -33,764 +33,6093 @@ software. Copies published by the Free Software Foundation raise funds for GNU development.  -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. + + +File: gcc.info, Node: Target Builtins, Next: Pragmas, Prev: Other Builtins, Up: C Extensions + +5.45 Built-in Functions Specific to Particular Target Machines +============================================================== + +On some target machines, GCC supports many built-in functions specific +to those machines. Generally these generate calls to specific machine +instructions, but allow the compiler to schedule those calls. + +* Menu: + +* X86 Built-in Functions:: +* PowerPC AltiVec Built-in Functions:: + + +File: gcc.info, Node: X86 Built-in Functions, Next: PowerPC AltiVec Built-in Functions, Up: Target Builtins + +5.45.1 X86 Built-in Functions +----------------------------- + +These built-in functions are available for the i386 and x86-64 family +of computers, depending on the command-line switches used. + + The following machine modes are available for use with MMX built-in +functions (*note Vector Extensions::): `V2SI' for a vector of two +32-bit integers, `V4HI' for a vector of four 16-bit integers, and +`V8QI' for a vector of eight 8-bit integers. Some of the built-in +functions operate on MMX registers as a whole 64-bit entity, these use +`DI' as their mode. + + If 3Dnow extensions are enabled, `V2SF' is used as a mode for a +vector of two 32-bit floating point values. + + If SSE extensions are enabled, `V4SF' is used for a vector of four +32-bit floating point values. Some instructions use a vector of four +32-bit integers, these use `V4SI'. Finally, some instructions operate +on an entire vector register, interpreting it as a 128-bit integer, +these use mode `TI'. + + The following built-in functions are made available by `-mmmx'. All +of them generate the machine instruction that is part of the name. + + v8qi __builtin_ia32_paddb (v8qi, v8qi) + v4hi __builtin_ia32_paddw (v4hi, v4hi) + v2si __builtin_ia32_paddd (v2si, v2si) + v8qi __builtin_ia32_psubb (v8qi, v8qi) + v4hi __builtin_ia32_psubw (v4hi, v4hi) + v2si __builtin_ia32_psubd (v2si, v2si) + v8qi __builtin_ia32_paddsb (v8qi, v8qi) + v4hi __builtin_ia32_paddsw (v4hi, v4hi) + v8qi __builtin_ia32_psubsb (v8qi, v8qi) + v4hi __builtin_ia32_psubsw (v4hi, v4hi) + v8qi __builtin_ia32_paddusb (v8qi, v8qi) + v4hi __builtin_ia32_paddusw (v4hi, v4hi) + v8qi __builtin_ia32_psubusb (v8qi, v8qi) + v4hi __builtin_ia32_psubusw (v4hi, v4hi) + v4hi __builtin_ia32_pmullw (v4hi, v4hi) + v4hi __builtin_ia32_pmulhw (v4hi, v4hi) + di __builtin_ia32_pand (di, di) + di __builtin_ia32_pandn (di,di) + di __builtin_ia32_por (di, di) + di __builtin_ia32_pxor (di, di) + v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) + v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) + v2si __builtin_ia32_pcmpeqd (v2si, v2si) + v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) + v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) + v2si __builtin_ia32_pcmpgtd (v2si, v2si) + v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) + v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) + v2si __builtin_ia32_punpckhdq (v2si, v2si) + v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) + v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) + v2si __builtin_ia32_punpckldq (v2si, v2si) + v8qi __builtin_ia32_packsswb (v4hi, v4hi) + v4hi __builtin_ia32_packssdw (v2si, v2si) + v8qi __builtin_ia32_packuswb (v4hi, v4hi) + + The following built-in functions are made available either with +`-msse', or with a combination of `-m3dnow' and `-march=athlon'. All +of them generate the machine instruction that is part of the name. + + v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) + v8qi __builtin_ia32_pavgb (v8qi, v8qi) + v4hi __builtin_ia32_pavgw (v4hi, v4hi) + v4hi __builtin_ia32_psadbw (v8qi, v8qi) + v8qi __builtin_ia32_pmaxub (v8qi, v8qi) + v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) + v8qi __builtin_ia32_pminub (v8qi, v8qi) + v4hi __builtin_ia32_pminsw (v4hi, v4hi) + int __builtin_ia32_pextrw (v4hi, int) + v4hi __builtin_ia32_pinsrw (v4hi, int, int) + int __builtin_ia32_pmovmskb (v8qi) + void __builtin_ia32_maskmovq (v8qi, v8qi, char *) + void __builtin_ia32_movntq (di *, di) + void __builtin_ia32_sfence (void) + + The following built-in functions are available when `-msse' is used. +All of them generate the machine instruction that is part of the name. + + int __builtin_ia32_comieq (v4sf, v4sf) + int __builtin_ia32_comineq (v4sf, v4sf) + int __builtin_ia32_comilt (v4sf, v4sf) + int __builtin_ia32_comile (v4sf, v4sf) + int __builtin_ia32_comigt (v4sf, v4sf) + int __builtin_ia32_comige (v4sf, v4sf) + int __builtin_ia32_ucomieq (v4sf, v4sf) + int __builtin_ia32_ucomineq (v4sf, v4sf) + int __builtin_ia32_ucomilt (v4sf, v4sf) + int __builtin_ia32_ucomile (v4sf, v4sf) + int __builtin_ia32_ucomigt (v4sf, v4sf) + int __builtin_ia32_ucomige (v4sf, v4sf) + v4sf __builtin_ia32_addps (v4sf, v4sf) + v4sf __builtin_ia32_subps (v4sf, v4sf) + v4sf __builtin_ia32_mulps (v4sf, v4sf) + v4sf __builtin_ia32_divps (v4sf, v4sf) + v4sf __builtin_ia32_addss (v4sf, v4sf) + v4sf __builtin_ia32_subss (v4sf, v4sf) + v4sf __builtin_ia32_mulss (v4sf, v4sf) + v4sf __builtin_ia32_divss (v4sf, v4sf) + v4si __builtin_ia32_cmpeqps (v4sf, v4sf) + v4si __builtin_ia32_cmpltps (v4sf, v4sf) + v4si __builtin_ia32_cmpleps (v4sf, v4sf) + v4si __builtin_ia32_cmpgtps (v4sf, v4sf) + v4si __builtin_ia32_cmpgeps (v4sf, v4sf) + v4si __builtin_ia32_cmpunordps (v4sf, v4sf) + v4si __builtin_ia32_cmpneqps (v4sf, v4sf) + v4si __builtin_ia32_cmpnltps (v4sf, v4sf) + v4si __builtin_ia32_cmpnleps (v4sf, v4sf) + v4si __builtin_ia32_cmpngtps (v4sf, v4sf) + v4si __builtin_ia32_cmpngeps (v4sf, v4sf) + v4si __builtin_ia32_cmpordps (v4sf, v4sf) + v4si __builtin_ia32_cmpeqss (v4sf, v4sf) + v4si __builtin_ia32_cmpltss (v4sf, v4sf) + v4si __builtin_ia32_cmpless (v4sf, v4sf) + v4si __builtin_ia32_cmpgtss (v4sf, v4sf) + v4si __builtin_ia32_cmpgess (v4sf, v4sf) + v4si __builtin_ia32_cmpunordss (v4sf, v4sf) + v4si __builtin_ia32_cmpneqss (v4sf, v4sf) + v4si __builtin_ia32_cmpnlts (v4sf, v4sf) + v4si __builtin_ia32_cmpnless (v4sf, v4sf) + v4si __builtin_ia32_cmpngtss (v4sf, v4sf) + v4si __builtin_ia32_cmpngess (v4sf, v4sf) + v4si __builtin_ia32_cmpordss (v4sf, v4sf) + v4sf __builtin_ia32_maxps (v4sf, v4sf) + v4sf __builtin_ia32_maxss (v4sf, v4sf) + v4sf __builtin_ia32_minps (v4sf, v4sf) + v4sf __builtin_ia32_minss (v4sf, v4sf) + v4sf __builtin_ia32_andps (v4sf, v4sf) + v4sf __builtin_ia32_andnps (v4sf, v4sf) + v4sf __builtin_ia32_orps (v4sf, v4sf) + v4sf __builtin_ia32_xorps (v4sf, v4sf) + v4sf __builtin_ia32_movss (v4sf, v4sf) + v4sf __builtin_ia32_movhlps (v4sf, v4sf) + v4sf __builtin_ia32_movlhps (v4sf, v4sf) + v4sf __builtin_ia32_unpckhps (v4sf, v4sf) + v4sf __builtin_ia32_unpcklps (v4sf, v4sf) + v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) + v4sf __builtin_ia32_cvtsi2ss (v4sf, int) + v2si __builtin_ia32_cvtps2pi (v4sf) + int __builtin_ia32_cvtss2si (v4sf) + v2si __builtin_ia32_cvttps2pi (v4sf) + int __builtin_ia32_cvttss2si (v4sf) + v4sf __builtin_ia32_rcpps (v4sf) + v4sf __builtin_ia32_rsqrtps (v4sf) + v4sf __builtin_ia32_sqrtps (v4sf) + v4sf __builtin_ia32_rcpss (v4sf) + v4sf __builtin_ia32_rsqrtss (v4sf) + v4sf __builtin_ia32_sqrtss (v4sf) + v4sf __builtin_ia32_shufps (v4sf, v4sf, int) + void __builtin_ia32_movntps (float *, v4sf) + int __builtin_ia32_movmskps (v4sf) + + The following built-in functions are available when `-msse' is used. + +`v4sf __builtin_ia32_loadaps (float *)' + Generates the `movaps' machine instruction as a load from memory. + +`void __builtin_ia32_storeaps (float *, v4sf)' + Generates the `movaps' machine instruction as a store to memory. + +`v4sf __builtin_ia32_loadups (float *)' + Generates the `movups' machine instruction as a load from memory. + +`void __builtin_ia32_storeups (float *, v4sf)' + Generates the `movups' machine instruction as a store to memory. + +`v4sf __builtin_ia32_loadsss (float *)' + Generates the `movss' machine instruction as a load from memory. + +`void __builtin_ia32_storess (float *, v4sf)' + Generates the `movss' machine instruction as a store to memory. + +`v4sf __builtin_ia32_loadhps (v4sf, v2si *)' + Generates the `movhps' machine instruction as a load from memory. + +`v4sf __builtin_ia32_loadlps (v4sf, v2si *)' + Generates the `movlps' machine instruction as a load from memory + +`void __builtin_ia32_storehps (v4sf, v2si *)' + Generates the `movhps' machine instruction as a store to memory. + +`void __builtin_ia32_storelps (v4sf, v2si *)' + Generates the `movlps' machine instruction as a store to memory. + + The following built-in functions are available when `-m3dnow' is +used. All of them generate the machine instruction that is part of the +name. + + void __builtin_ia32_femms (void) + v8qi __builtin_ia32_pavgusb (v8qi, v8qi) + v2si __builtin_ia32_pf2id (v2sf) + v2sf __builtin_ia32_pfacc (v2sf, v2sf) + v2sf __builtin_ia32_pfadd (v2sf, v2sf) + v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) + v2si __builtin_ia32_pfcmpge (v2sf, v2sf) + v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) + v2sf __builtin_ia32_pfmax (v2sf, v2sf) + v2sf __builtin_ia32_pfmin (v2sf, v2sf) + v2sf __builtin_ia32_pfmul (v2sf, v2sf) + v2sf __builtin_ia32_pfrcp (v2sf) + v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) + v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) + v2sf __builtin_ia32_pfrsqrt (v2sf) + v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) + v2sf __builtin_ia32_pfsub (v2sf, v2sf) + v2sf __builtin_ia32_pfsubr (v2sf, v2sf) + v2sf __builtin_ia32_pi2fd (v2si) + v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) + + The following built-in functions are available when both `-m3dnow' +and `-march=athlon' are used. All of them generate the machine +instruction that is part of the name. + + v2si __builtin_ia32_pf2iw (v2sf) + v2sf __builtin_ia32_pfnacc (v2sf, v2sf) + v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) + v2sf __builtin_ia32_pi2fw (v2si) + v2sf __builtin_ia32_pswapdsf (v2sf) + v2si __builtin_ia32_pswapdsi (v2si) + + +File: gcc.info, Node: PowerPC AltiVec Built-in Functions, Prev: X86 Built-in Functions, Up: Target Builtins + +5.45.2 PowerPC AltiVec Built-in Functions +----------------------------------------- + +These built-in functions are available for the PowerPC family of +computers, depending on the command-line switches used. + + The following machine modes are available for use with AltiVec +built-in functions (*note Vector Extensions::): `V4SI' for a vector of +four 32-bit integers, `V4SF' for a vector of four 32-bit floating point +numbers, `V8HI' for a vector of eight 16-bit integers, and `V16QI' for +a vector of sixteen 8-bit integers. + + The following functions are made available by including +`' and using `-maltivec' and `-mabi=altivec'. The functions +implement the functionality described in Motorola's AltiVec Programming +Interface Manual. + + _Note:_ Only the `' interface is supported. Internally, +GCC uses built-in functions to achieve the functionality in the +aforementioned header file, but they are not supported and are subject +to change without notice. + + vector signed char vec_abs (vector signed char, vector signed char); + vector signed short vec_abs (vector signed short, vector signed short); + vector signed int vec_abs (vector signed int, vector signed int); + vector signed float vec_abs (vector signed float, vector signed float); + + vector signed char vec_abss (vector signed char, vector signed char); + vector signed short vec_abss (vector signed short, vector signed short); + + vector signed char vec_add (vector signed char, vector signed char); + vector unsigned char vec_add (vector signed char, vector unsigned char); + + vector unsigned char vec_add (vector unsigned char, vector signed char); + + vector unsigned char vec_add (vector unsigned char, + vector unsigned char); + vector signed short vec_add (vector signed short, vector signed short); + vector unsigned short vec_add (vector signed short, + vector unsigned short); + vector unsigned short vec_add (vector unsigned short, + vector signed short); + vector unsigned short vec_add (vector unsigned short, + vector unsigned short); + vector signed int vec_add (vector signed int, vector signed int); + vector unsigned int vec_add (vector signed int, vector unsigned int); + vector unsigned int vec_add (vector unsigned int, vector signed int); + vector unsigned int vec_add (vector unsigned int, vector unsigned int); + vector float vec_add (vector float, vector float); + + vector unsigned int vec_addc (vector unsigned int, vector unsigned int); + + vector unsigned char vec_adds (vector signed char, + vector unsigned char); + vector unsigned char vec_adds (vector unsigned char, + vector signed char); + vector unsigned char vec_adds (vector unsigned char, + vector unsigned char); + vector signed char vec_adds (vector signed char, vector signed char); + vector unsigned short vec_adds (vector signed short, + vector unsigned short); + vector unsigned short vec_adds (vector unsigned short, + vector signed short); + vector unsigned short vec_adds (vector unsigned short, + vector unsigned short); + vector signed short vec_adds (vector signed short, vector signed short); + + vector unsigned int vec_adds (vector signed int, vector unsigned int); + vector unsigned int vec_adds (vector unsigned int, vector signed int); + vector unsigned int vec_adds (vector unsigned int, vector unsigned int); + + vector signed int vec_adds (vector signed int, vector signed int); + + vector float vec_and (vector float, vector float); + vector float vec_and (vector float, vector signed int); + vector float vec_and (vector signed int, vector float); + vector signed int vec_and (vector signed int, vector signed int); + vector unsigned int vec_and (vector signed int, vector unsigned int); + vector unsigned int vec_and (vector unsigned int, vector signed int); + vector unsigned int vec_and (vector unsigned int, vector unsigned int); + vector signed short vec_and (vector signed short, vector signed short); + vector unsigned short vec_and (vector signed short, + vector unsigned short); + vector unsigned short vec_and (vector unsigned short, + vector signed short); + vector unsigned short vec_and (vector unsigned short, + vector unsigned short); + vector signed char vec_and (vector signed char, vector signed char); + vector unsigned char vec_and (vector signed char, vector unsigned char); + + vector unsigned char vec_and (vector unsigned char, vector signed char); + + vector unsigned char vec_and (vector unsigned char, + vector unsigned char); + + vector float vec_andc (vector float, vector float); + vector float vec_andc (vector float, vector signed int); + vector float vec_andc (vector signed int, vector float); + vector signed int vec_andc (vector signed int, vector signed int); + vector unsigned int vec_andc (vector signed int, vector unsigned int); + vector unsigned int vec_andc (vector unsigned int, vector signed int); + vector unsigned int vec_andc (vector unsigned int, vector unsigned int); + + vector signed short vec_andc (vector signed short, vector signed short); + + vector unsigned short vec_andc (vector signed short, + vector unsigned short); + vector unsigned short vec_andc (vector unsigned short, + vector signed short); + vector unsigned short vec_andc (vector unsigned short, + vector unsigned short); + vector signed char vec_andc (vector signed char, vector signed char); + vector unsigned char vec_andc (vector signed char, + vector unsigned char); + vector unsigned char vec_andc (vector unsigned char, + vector signed char); + vector unsigned char vec_andc (vector unsigned char, + vector unsigned char); + + vector unsigned char vec_avg (vector unsigned char, + vector unsigned char); + vector signed char vec_avg (vector signed char, vector signed char); + vector unsigned short vec_avg (vector unsigned short, + vector unsigned short); + vector signed short vec_avg (vector signed short, vector signed short); + vector unsigned int vec_avg (vector unsigned int, vector unsigned int); + vector signed int vec_avg (vector signed int, vector signed int); + + vector float vec_ceil (vector float); + + vector signed int vec_cmpb (vector float, vector float); + + vector signed char vec_cmpeq (vector signed char, vector signed char); + vector signed char vec_cmpeq (vector unsigned char, + vector unsigned char); + vector signed short vec_cmpeq (vector signed short, + vector signed short); + vector signed short vec_cmpeq (vector unsigned short, + vector unsigned short); + vector signed int vec_cmpeq (vector signed int, vector signed int); + vector signed int vec_cmpeq (vector unsigned int, vector unsigned int); + vector signed int vec_cmpeq (vector float, vector float); + + vector signed int vec_cmpge (vector float, vector float); + + vector signed char vec_cmpgt (vector unsigned char, + vector unsigned char); + vector signed char vec_cmpgt (vector signed char, vector signed char); + vector signed short vec_cmpgt (vector unsigned short, + vector unsigned short); + vector signed short vec_cmpgt (vector signed short, + vector signed short); + vector signed int vec_cmpgt (vector unsigned int, vector unsigned int); + vector signed int vec_cmpgt (vector signed int, vector signed int); + vector signed int vec_cmpgt (vector float, vector float); + + vector signed int vec_cmple (vector float, vector float); + + vector signed char vec_cmplt (vector unsigned char, + vector unsigned char); + vector signed char vec_cmplt (vector signed char, vector signed char); + vector signed short vec_cmplt (vector unsigned short, + vector unsigned short); + vector signed short vec_cmplt (vector signed short, + vector signed short); + vector signed int vec_cmplt (vector unsigned int, vector unsigned int); + vector signed int vec_cmplt (vector signed int, vector signed int); + vector signed int vec_cmplt (vector float, vector float); + + vector float vec_ctf (vector unsigned int, const char); + vector float vec_ctf (vector signed int, const char); + + vector signed int vec_cts (vector float, const char); + + vector unsigned int vec_ctu (vector float, const char); + + void vec_dss (const char); + + void vec_dssall (void); + + void vec_dst (void *, int, const char); + + void vec_dstst (void *, int, const char); + + void vec_dststt (void *, int, const char); + + void vec_dstt (void *, int, const char); + + vector float vec_expte (vector float, vector float); + + vector float vec_floor (vector float, vector float); + + vector float vec_ld (int, vector float *); + vector float vec_ld (int, float *): + vector signed int vec_ld (int, int *); + vector signed int vec_ld (int, vector signed int *); + vector unsigned int vec_ld (int, vector unsigned int *); + vector unsigned int vec_ld (int, unsigned int *); + vector signed short vec_ld (int, short *, vector signed short *); + vector unsigned short vec_ld (int, unsigned short *, + vector unsigned short *); + vector signed char vec_ld (int, signed char *); + vector signed char vec_ld (int, vector signed char *); + vector unsigned char vec_ld (int, unsigned char *); + vector unsigned char vec_ld (int, vector unsigned char *); + + vector signed char vec_lde (int, signed char *); + vector unsigned char vec_lde (int, unsigned char *); + vector signed short vec_lde (int, short *); + vector unsigned short vec_lde (int, unsigned short *); + vector float vec_lde (int, float *); + vector signed int vec_lde (int, int *); + vector unsigned int vec_lde (int, unsigned int *); + + void float vec_ldl (int, float *); + void float vec_ldl (int, vector float *); + void signed int vec_ldl (int, vector signed int *); + void signed int vec_ldl (int, int *); + void unsigned int vec_ldl (int, unsigned int *); + void unsigned int vec_ldl (int, vector unsigned int *); + void signed short vec_ldl (int, vector signed short *); + void signed short vec_ldl (int, short *); + void unsigned short vec_ldl (int, vector unsigned short *); + void unsigned short vec_ldl (int, unsigned short *); + void signed char vec_ldl (int, vector signed char *); + void signed char vec_ldl (int, signed char *); + void unsigned char vec_ldl (int, vector unsigned char *); + void unsigned char vec_ldl (int, unsigned char *); + + vector float vec_loge (vector float); + + vector unsigned char vec_lvsl (int, void *, int *); + + vector unsigned char vec_lvsr (int, void *, int *); + + vector float vec_madd (vector float, vector float, vector float); + + vector signed short vec_madds (vector signed short, vector signed short, + vector signed short); + + vector unsigned char vec_max (vector signed char, vector unsigned char); + + vector unsigned char vec_max (vector unsigned char, vector signed char); + + vector unsigned char vec_max (vector unsigned char, + vector unsigned char); + vector signed char vec_max (vector signed char, vector signed char); + vector unsigned short vec_max (vector signed short, + vector unsigned short); + vector unsigned short vec_max (vector unsigned short, + vector signed short); + vector unsigned short vec_max (vector unsigned short, + vector unsigned short); + vector signed short vec_max (vector signed short, vector signed short); + vector unsigned int vec_max (vector signed int, vector unsigned int); + vector unsigned int vec_max (vector unsigned int, vector signed int); + vector unsigned int vec_max (vector unsigned int, vector unsigned int); + vector signed int vec_max (vector signed int, vector signed int); + vector float vec_max (vector float, vector float); + + vector signed char vec_mergeh (vector signed char, vector signed char); + vector unsigned char vec_mergeh (vector unsigned char, + vector unsigned char); + vector signed short vec_mergeh (vector signed short, + vector signed short); + vector unsigned short vec_mergeh (vector unsigned short, + vector unsigned short); + vector float vec_mergeh (vector float, vector float); + vector signed int vec_mergeh (vector signed int, vector signed int); + vector unsigned int vec_mergeh (vector unsigned int, + vector unsigned int); + + vector signed char vec_mergel (vector signed char, vector signed char); + vector unsigned char vec_mergel (vector unsigned char, + vector unsigned char); + vector signed short vec_mergel (vector signed short, + vector signed short); + vector unsigned short vec_mergel (vector unsigned short, + vector unsigned short); + vector float vec_mergel (vector float, vector float); + vector signed int vec_mergel (vector signed int, vector signed int); + vector unsigned int vec_mergel (vector unsigned int, + vector unsigned int); + + vector unsigned short vec_mfvscr (void); + + vector unsigned char vec_min (vector signed char, vector unsigned char); + + vector unsigned char vec_min (vector unsigned char, vector signed char); + + vector unsigned char vec_min (vector unsigned char, + vector unsigned char); + vector signed char vec_min (vector signed char, vector signed char); + vector unsigned short vec_min (vector signed short, + vector unsigned short); + vector unsigned short vec_min (vector unsigned short, + vector signed short); + vector unsigned short vec_min (vector unsigned short, + vector unsigned short); + vector signed short vec_min (vector signed short, vector signed short); + vector unsigned int vec_min (vector signed int, vector unsigned int); + vector unsigned int vec_min (vector unsigned int, vector signed int); + vector unsigned int vec_min (vector unsigned int, vector unsigned int); + vector signed int vec_min (vector signed int, vector signed int); + vector float vec_min (vector float, vector float); + + vector signed short vec_mladd (vector signed short, vector signed short, + vector signed short); + vector signed short vec_mladd (vector signed short, + vector unsigned short, + vector unsigned short); + vector signed short vec_mladd (vector unsigned short, + vector signed short, + vector signed short); + vector unsigned short vec_mladd (vector unsigned short, + vector unsigned short, + vector unsigned short); + + vector signed short vec_mradds (vector signed short, + vector signed short, + vector signed short); + + vector unsigned int vec_msum (vector unsigned char, + vector unsigned char, + vector unsigned int); + vector signed int vec_msum (vector signed char, vector unsigned char, + vector signed int); + vector unsigned int vec_msum (vector unsigned short, + vector unsigned short, + vector unsigned int); + vector signed int vec_msum (vector signed short, vector signed short, + vector signed int); + + vector unsigned int vec_msums (vector unsigned short, + vector unsigned short, + vector unsigned int); + vector signed int vec_msums (vector signed short, vector signed short, + vector signed int); + + void vec_mtvscr (vector signed int); + void vec_mtvscr (vector unsigned int); + void vec_mtvscr (vector signed short); + void vec_mtvscr (vector unsigned short); + void vec_mtvscr (vector signed char); + void vec_mtvscr (vector unsigned char); + + vector unsigned short vec_mule (vector unsigned char, + vector unsigned char); + vector signed short vec_mule (vector signed char, vector signed char); + vector unsigned int vec_mule (vector unsigned short, + vector unsigned short); + vector signed int vec_mule (vector signed short, vector signed short); + + vector unsigned short vec_mulo (vector unsigned char, + vector unsigned char); + vector signed short vec_mulo (vector signed char, vector signed char); + vector unsigned int vec_mulo (vector unsigned short, + vector unsigned short); + vector signed int vec_mulo (vector signed short, vector signed short); + + vector float vec_nmsub (vector float, vector float, vector float); + + vector float vec_nor (vector float, vector float); + vector signed int vec_nor (vector signed int, vector signed int); + vector unsigned int vec_nor (vector unsigned int, vector unsigned int); + vector signed short vec_nor (vector signed short, vector signed short); + vector unsigned short vec_nor (vector unsigned short, + vector unsigned short); + vector signed char vec_nor (vector signed char, vector signed char); + vector unsigned char vec_nor (vector unsigned char, + vector unsigned char); + + vector float vec_or (vector float, vector float); + vector float vec_or (vector float, vector signed int); + vector float vec_or (vector signed int, vector float); + vector signed int vec_or (vector signed int, vector signed int); + vector unsigned int vec_or (vector signed int, vector unsigned int); + vector unsigned int vec_or (vector unsigned int, vector signed int); + vector unsigned int vec_or (vector unsigned int, vector unsigned int); + vector signed short vec_or (vector signed short, vector signed short); + vector unsigned short vec_or (vector signed short, + vector unsigned short); + vector unsigned short vec_or (vector unsigned short, + vector signed short); + vector unsigned short vec_or (vector unsigned short, + vector unsigned short); + vector signed char vec_or (vector signed char, vector signed char); + vector unsigned char vec_or (vector signed char, vector unsigned char); + vector unsigned char vec_or (vector unsigned char, vector signed char); + vector unsigned char vec_or (vector unsigned char, + vector unsigned char); + + vector signed char vec_pack (vector signed short, vector signed short); + vector unsigned char vec_pack (vector unsigned short, + vector unsigned short); + vector signed short vec_pack (vector signed int, vector signed int); + vector unsigned short vec_pack (vector unsigned int, + vector unsigned int); + + vector signed short vec_packpx (vector unsigned int, + vector unsigned int); + + vector unsigned char vec_packs (vector unsigned short, + vector unsigned short); + vector signed char vec_packs (vector signed short, vector signed short); + + vector unsigned short vec_packs (vector unsigned int, + vector unsigned int); + vector signed short vec_packs (vector signed int, vector signed int); + + vector unsigned char vec_packsu (vector unsigned short, + vector unsigned short); + vector unsigned char vec_packsu (vector signed short, + vector signed short); + vector unsigned short vec_packsu (vector unsigned int, + vector unsigned int); + vector unsigned short vec_packsu (vector signed int, vector signed int); + + vector float vec_perm (vector float, vector float, + vector unsigned char); + vector signed int vec_perm (vector signed int, vector signed int, + vector unsigned char); + vector unsigned int vec_perm (vector unsigned int, vector unsigned int, + vector unsigned char); + vector signed short vec_perm (vector signed short, vector signed short, + vector unsigned char); + vector unsigned short vec_perm (vector unsigned short, + vector unsigned short, + vector unsigned char); + vector signed char vec_perm (vector signed char, vector signed char, + vector unsigned char); + vector unsigned char vec_perm (vector unsigned char, + vector unsigned char, + vector unsigned char); + + vector float vec_re (vector float); + + vector signed char vec_rl (vector signed char, vector unsigned char); + vector unsigned char vec_rl (vector unsigned char, + vector unsigned char); + vector signed short vec_rl (vector signed short, vector unsigned short); + + vector unsigned short vec_rl (vector unsigned short, + vector unsigned short); + vector signed int vec_rl (vector signed int, vector unsigned int); + vector unsigned int vec_rl (vector unsigned int, vector unsigned int); + + vector float vec_round (vector float); + + vector float vec_rsqrte (vector float); + + vector float vec_sel (vector float, vector float, vector signed int); + vector float vec_sel (vector float, vector float, vector unsigned int); + vector signed int vec_sel (vector signed int, vector signed int, + vector signed int); + vector signed int vec_sel (vector signed int, vector signed int, + vector unsigned int); + vector unsigned int vec_sel (vector unsigned int, vector unsigned int, + vector signed int); + vector unsigned int vec_sel (vector unsigned int, vector unsigned int, + vector unsigned int); + vector signed short vec_sel (vector signed short, vector signed short, + vector signed short); + vector signed short vec_sel (vector signed short, vector signed short, + vector unsigned short); + vector unsigned short vec_sel (vector unsigned short, + vector unsigned short, + vector signed short); + vector unsigned short vec_sel (vector unsigned short, + vector unsigned short, + vector unsigned short); + vector signed char vec_sel (vector signed char, vector signed char, + vector signed char); + vector signed char vec_sel (vector signed char, vector signed char, + vector unsigned char); + vector unsigned char vec_sel (vector unsigned char, + vector unsigned char, + vector signed char); + vector unsigned char vec_sel (vector unsigned char, + vector unsigned char, + vector unsigned char); + + vector signed char vec_sl (vector signed char, vector unsigned char); + vector unsigned char vec_sl (vector unsigned char, + vector unsigned char); + vector signed short vec_sl (vector signed short, vector unsigned short); + + vector unsigned short vec_sl (vector unsigned short, + vector unsigned short); + vector signed int vec_sl (vector signed int, vector unsigned int); + vector unsigned int vec_sl (vector unsigned int, vector unsigned int); + + vector float vec_sld (vector float, vector float, const char); + vector signed int vec_sld (vector signed int, vector signed int, + const char); + vector unsigned int vec_sld (vector unsigned int, vector unsigned int, + const char); + vector signed short vec_sld (vector signed short, vector signed short, + const char); + vector unsigned short vec_sld (vector unsigned short, + vector unsigned short, const char); + vector signed char vec_sld (vector signed char, vector signed char, + const char); + vector unsigned char vec_sld (vector unsigned char, + vector unsigned char, + const char); + + vector signed int vec_sll (vector signed int, vector unsigned int); + vector signed int vec_sll (vector signed int, vector unsigned short); + vector signed int vec_sll (vector signed int, vector unsigned char); + vector unsigned int vec_sll (vector unsigned int, vector unsigned int); + vector unsigned int vec_sll (vector unsigned int, + vector unsigned short); + vector unsigned int vec_sll (vector unsigned int, vector unsigned char); + + vector signed short vec_sll (vector signed short, vector unsigned int); + vector signed short vec_sll (vector signed short, + vector unsigned short); + vector signed short vec_sll (vector signed short, vector unsigned char); + + vector unsigned short vec_sll (vector unsigned short, + vector unsigned int); + vector unsigned short vec_sll (vector unsigned short, + vector unsigned short); + vector unsigned short vec_sll (vector unsigned short, + vector unsigned char); + vector signed char vec_sll (vector signed char, vector unsigned int); + vector signed char vec_sll (vector signed char, vector unsigned short); + vector signed char vec_sll (vector signed char, vector unsigned char); + vector unsigned char vec_sll (vector unsigned char, + vector unsigned int); + vector unsigned char vec_sll (vector unsigned char, + vector unsigned short); + vector unsigned char vec_sll (vector unsigned char, + vector unsigned char); + + vector float vec_slo (vector float, vector signed char); + vector float vec_slo (vector float, vector unsigned char); + vector signed int vec_slo (vector signed int, vector signed char); + vector signed int vec_slo (vector signed int, vector unsigned char); + vector unsigned int vec_slo (vector unsigned int, vector signed char); + vector unsigned int vec_slo (vector unsigned int, vector unsigned char); + + vector signed short vec_slo (vector signed short, vector signed char); + vector signed short vec_slo (vector signed short, vector unsigned char); + + vector unsigned short vec_slo (vector unsigned short, + vector signed char); + vector unsigned short vec_slo (vector unsigned short, + vector unsigned char); + vector signed char vec_slo (vector signed char, vector signed char); + vector signed char vec_slo (vector signed char, vector unsigned char); + vector unsigned char vec_slo (vector unsigned char, vector signed char); + + vector unsigned char vec_slo (vector unsigned char, + vector unsigned char); + + vector signed char vec_splat (vector signed char, const char); + vector unsigned char vec_splat (vector unsigned char, const char); + vector signed short vec_splat (vector signed short, const char); + vector unsigned short vec_splat (vector unsigned short, const char); + vector float vec_splat (vector float, const char); + vector signed int vec_splat (vector signed int, const char); + vector unsigned int vec_splat (vector unsigned int, const char); + + vector signed char vec_splat_s8 (const char); + + vector signed short vec_splat_s16 (const char); + + vector signed int vec_splat_s32 (const char); + + vector unsigned char vec_splat_u8 (const char); + + vector unsigned short vec_splat_u16 (const char); + + vector unsigned int vec_splat_u32 (const char); + + vector signed char vec_sr (vector signed char, vector unsigned char); + vector unsigned char vec_sr (vector unsigned char, + vector unsigned char); + vector signed short vec_sr (vector signed short, vector unsigned short); + + vector unsigned short vec_sr (vector unsigned short, + vector unsigned short); + vector signed int vec_sr (vector signed int, vector unsigned int); + vector unsigned int vec_sr (vector unsigned int, vector unsigned int); + + vector signed char vec_sra (vector signed char, vector unsigned char); + vector unsigned char vec_sra (vector unsigned char, + vector unsigned char); + vector signed short vec_sra (vector signed short, + vector unsigned short); + vector unsigned short vec_sra (vector unsigned short, + vector unsigned short); + vector signed int vec_sra (vector signed int, vector unsigned int); + vector unsigned int vec_sra (vector unsigned int, vector unsigned int); + + vector signed int vec_srl (vector signed int, vector unsigned int); + vector signed int vec_srl (vector signed int, vector unsigned short); + vector signed int vec_srl (vector signed int, vector unsigned char); + vector unsigned int vec_srl (vector unsigned int, vector unsigned int); + vector unsigned int vec_srl (vector unsigned int, + vector unsigned short); + vector unsigned int vec_srl (vector unsigned int, vector unsigned char); + + vector signed short vec_srl (vector signed short, vector unsigned int); + vector signed short vec_srl (vector signed short, + vector unsigned short); + vector signed short vec_srl (vector signed short, vector unsigned char); + + vector unsigned short vec_srl (vector unsigned short, + vector unsigned int); + vector unsigned short vec_srl (vector unsigned short, + vector unsigned short); + vector unsigned short vec_srl (vector unsigned short, + vector unsigned char); + vector signed char vec_srl (vector signed char, vector unsigned int); + vector signed char vec_srl (vector signed char, vector unsigned short); + vector signed char vec_srl (vector signed char, vector unsigned char); + vector unsigned char vec_srl (vector unsigned char, + vector unsigned int); + vector unsigned char vec_srl (vector unsigned char, + vector unsigned short); + vector unsigned char vec_srl (vector unsigned char, + vector unsigned char); + + vector float vec_sro (vector float, vector signed char); + vector float vec_sro (vector float, vector unsigned char); + vector signed int vec_sro (vector signed int, vector signed char); + vector signed int vec_sro (vector signed int, vector unsigned char); + vector unsigned int vec_sro (vector unsigned int, vector signed char); + vector unsigned int vec_sro (vector unsigned int, vector unsigned char); + + vector signed short vec_sro (vector signed short, vector signed char); + vector signed short vec_sro (vector signed short, vector unsigned char); + + vector unsigned short vec_sro (vector unsigned short, + vector signed char); + vector unsigned short vec_sro (vector unsigned short, + vector unsigned char); + vector signed char vec_sro (vector signed char, vector signed char); + vector signed char vec_sro (vector signed char, vector unsigned char); + vector unsigned char vec_sro (vector unsigned char, vector signed char); + + vector unsigned char vec_sro (vector unsigned char, + vector unsigned char); + + void vec_st (vector float, int, float *); + void vec_st (vector float, int, vector float *); + void vec_st (vector signed int, int, int *); + void vec_st (vector signed int, int, unsigned int *); + void vec_st (vector unsigned int, int, unsigned int *); + void vec_st (vector unsigned int, int, vector unsigned int *); + void vec_st (vector signed short, int, short *); + void vec_st (vector signed short, int, vector unsigned short *); + void vec_st (vector signed short, int, vector signed short *); + void vec_st (vector unsigned short, int, unsigned short *); + void vec_st (vector unsigned short, int, vector unsigned short *); + void vec_st (vector signed char, int, signed char *); + void vec_st (vector signed char, int, unsigned char *); + void vec_st (vector signed char, int, vector signed char *); + void vec_st (vector unsigned char, int, unsigned char *); + void vec_st (vector unsigned char, int, vector unsigned char *); + + void vec_ste (vector signed char, int, unsigned char *); + void vec_ste (vector signed char, int, signed char *); + void vec_ste (vector unsigned char, int, unsigned char *); + void vec_ste (vector signed short, int, short *); + void vec_ste (vector signed short, int, unsigned short *); + void vec_ste (vector unsigned short, int, void *); + void vec_ste (vector signed int, int, unsigned int *); + void vec_ste (vector signed int, int, int *); + void vec_ste (vector unsigned int, int, unsigned int *); + void vec_ste (vector float, int, float *); + + void vec_stl (vector float, int, vector float *); + void vec_stl (vector float, int, float *); + void vec_stl (vector signed int, int, vector signed int *); + void vec_stl (vector signed int, int, int *); + void vec_stl (vector signed int, int, unsigned int *); + void vec_stl (vector unsigned int, int, vector unsigned int *); + void vec_stl (vector unsigned int, int, unsigned int *); + void vec_stl (vector signed short, int, short *); + void vec_stl (vector signed short, int, unsigned short *); + void vec_stl (vector signed short, int, vector signed short *); + void vec_stl (vector unsigned short, int, unsigned short *); + void vec_stl (vector unsigned short, int, vector signed short *); + void vec_stl (vector signed char, int, signed char *); + void vec_stl (vector signed char, int, unsigned char *); + void vec_stl (vector signed char, int, vector signed char *); + void vec_stl (vector unsigned char, int, unsigned char *); + void vec_stl (vector unsigned char, int, vector unsigned char *); + + vector signed char vec_sub (vector signed char, vector signed char); + vector unsigned char vec_sub (vector signed char, vector unsigned char); + + vector unsigned char vec_sub (vector unsigned char, vector signed char); + + vector unsigned char vec_sub (vector unsigned char, + vector unsigned char); + vector signed short vec_sub (vector signed short, vector signed short); + vector unsigned short vec_sub (vector signed short, + vector unsigned short); + vector unsigned short vec_sub (vector unsigned short, + vector signed short); + vector unsigned short vec_sub (vector unsigned short, + vector unsigned short); + vector signed int vec_sub (vector signed int, vector signed int); + vector unsigned int vec_sub (vector signed int, vector unsigned int); + vector unsigned int vec_sub (vector unsigned int, vector signed int); + vector unsigned int vec_sub (vector unsigned int, vector unsigned int); + vector float vec_sub (vector float, vector float); + + vector unsigned int vec_subc (vector unsigned int, vector unsigned int); + + vector unsigned char vec_subs (vector signed char, + vector unsigned char); + vector unsigned char vec_subs (vector unsigned char, + vector signed char); + vector unsigned char vec_subs (vector unsigned char, + vector unsigned char); + vector signed char vec_subs (vector signed char, vector signed char); + vector unsigned short vec_subs (vector signed short, + vector unsigned short); + vector unsigned short vec_subs (vector unsigned short, + vector signed short); + vector unsigned short vec_subs (vector unsigned short, + vector unsigned short); + vector signed short vec_subs (vector signed short, vector signed short); + + vector unsigned int vec_subs (vector signed int, vector unsigned int); + vector unsigned int vec_subs (vector unsigned int, vector signed int); + vector unsigned int vec_subs (vector unsigned int, vector unsigned int); + + vector signed int vec_subs (vector signed int, vector signed int); + + vector unsigned int vec_sum4s (vector unsigned char, + vector unsigned int); + vector signed int vec_sum4s (vector signed char, vector signed int); + vector signed int vec_sum4s (vector signed short, vector signed int); + + vector signed int vec_sum2s (vector signed int, vector signed int); + + vector signed int vec_sums (vector signed int, vector signed int); + + vector float vec_trunc (vector float); + + vector signed short vec_unpackh (vector signed char); + vector unsigned int vec_unpackh (vector signed short); + vector signed int vec_unpackh (vector signed short); + + vector signed short vec_unpackl (vector signed char); + vector unsigned int vec_unpackl (vector signed short); + vector signed int vec_unpackl (vector signed short); + + vector float vec_xor (vector float, vector float); + vector float vec_xor (vector float, vector signed int); + vector float vec_xor (vector signed int, vector float); + vector signed int vec_xor (vector signed int, vector signed int); + vector unsigned int vec_xor (vector signed int, vector unsigned int); + vector unsigned int vec_xor (vector unsigned int, vector signed int); + vector unsigned int vec_xor (vector unsigned int, vector unsigned int); + vector signed short vec_xor (vector signed short, vector signed short); + vector unsigned short vec_xor (vector signed short, + vector unsigned short); + vector unsigned short vec_xor (vector unsigned short, + vector signed short); + vector unsigned short vec_xor (vector unsigned short, + vector unsigned short); + vector signed char vec_xor (vector signed char, vector signed char); + vector unsigned char vec_xor (vector signed char, vector unsigned char); + + vector unsigned char vec_xor (vector unsigned char, vector signed char); + + vector unsigned char vec_xor (vector unsigned char, + vector unsigned char); + + vector signed int vec_all_eq (vector signed char, vector unsigned char); + + vector signed int vec_all_eq (vector signed char, vector signed char); + vector signed int vec_all_eq (vector unsigned char, vector signed char); + + vector signed int vec_all_eq (vector unsigned char, + vector unsigned char); + vector signed int vec_all_eq (vector signed short, + vector unsigned short); + vector signed int vec_all_eq (vector signed short, vector signed short); + + vector signed int vec_all_eq (vector unsigned short, + vector signed short); + vector signed int vec_all_eq (vector unsigned short, + vector unsigned short); + vector signed int vec_all_eq (vector signed int, vector unsigned int); + vector signed int vec_all_eq (vector signed int, vector signed int); + vector signed int vec_all_eq (vector unsigned int, vector signed int); + vector signed int vec_all_eq (vector unsigned int, vector unsigned int); + + vector signed int vec_all_eq (vector float, vector float); + + vector signed int vec_all_ge (vector signed char, vector unsigned char); + + vector signed int vec_all_ge (vector unsigned char, vector signed char); + + vector signed int vec_all_ge (vector unsigned char, + vector unsigned char); + vector signed int vec_all_ge (vector signed char, vector signed char); + vector signed int vec_all_ge (vector signed short, + vector unsigned short); + vector signed int vec_all_ge (vector unsigned short, + vector signed short); + vector signed int vec_all_ge (vector unsigned short, + vector unsigned short); + vector signed int vec_all_ge (vector signed short, vector signed short); + + vector signed int vec_all_ge (vector signed int, vector unsigned int); + vector signed int vec_all_ge (vector unsigned int, vector signed int); + vector signed int vec_all_ge (vector unsigned int, vector unsigned int); + + vector signed int vec_all_ge (vector signed int, vector signed int); + vector signed int vec_all_ge (vector float, vector float); + + vector signed int vec_all_gt (vector signed char, vector unsigned char); + + vector signed int vec_all_gt (vector unsigned char, vector signed char); + + vector signed int vec_all_gt (vector unsigned char, + vector unsigned char); + vector signed int vec_all_gt (vector signed char, vector signed char); + vector signed int vec_all_gt (vector signed short, + vector unsigned short); + vector signed int vec_all_gt (vector unsigned short, + vector signed short); + vector signed int vec_all_gt (vector unsigned short, + vector unsigned short); + vector signed int vec_all_gt (vector signed short, vector signed short); + + vector signed int vec_all_gt (vector signed int, vector unsigned int); + vector signed int vec_all_gt (vector unsigned int, vector signed int); + vector signed int vec_all_gt (vector unsigned int, vector unsigned int); + + vector signed int vec_all_gt (vector signed int, vector signed int); + vector signed int vec_all_gt (vector float, vector float); + + vector signed int vec_all_in (vector float, vector float); + + vector signed int vec_all_le (vector signed char, vector unsigned char); + + vector signed int vec_all_le (vector unsigned char, vector signed char); + + vector signed int vec_all_le (vector unsigned char, + vector unsigned char); + vector signed int vec_all_le (vector signed char, vector signed char); + vector signed int vec_all_le (vector signed short, + vector unsigned short); + vector signed int vec_all_le (vector unsigned short, + vector signed short); + vector signed int vec_all_le (vector unsigned short, + vector unsigned short); + vector signed int vec_all_le (vector signed short, vector signed short); + + vector signed int vec_all_le (vector signed int, vector unsigned int); + vector signed int vec_all_le (vector unsigned int, vector signed int); + vector signed int vec_all_le (vector unsigned int, vector unsigned int); + + vector signed int vec_all_le (vector signed int, vector signed int); + vector signed int vec_all_le (vector float, vector float); + + vector signed int vec_all_lt (vector signed char, vector unsigned char); + + vector signed int vec_all_lt (vector unsigned char, vector signed char); + + vector signed int vec_all_lt (vector unsigned char, + vector unsigned char); + vector signed int vec_all_lt (vector signed char, vector signed char); + vector signed int vec_all_lt (vector signed short, + vector unsigned short); + vector signed int vec_all_lt (vector unsigned short, + vector signed short); + vector signed int vec_all_lt (vector unsigned short, + vector unsigned short); + vector signed int vec_all_lt (vector signed short, vector signed short); + + vector signed int vec_all_lt (vector signed int, vector unsigned int); + vector signed int vec_all_lt (vector unsigned int, vector signed int); + vector signed int vec_all_lt (vector unsigned int, vector unsigned int); + + vector signed int vec_all_lt (vector signed int, vector signed int); + vector signed int vec_all_lt (vector float, vector float); + + vector signed int vec_all_nan (vector float); + + vector signed int vec_all_ne (vector signed char, vector unsigned char); + + vector signed int vec_all_ne (vector signed char, vector signed char); + vector signed int vec_all_ne (vector unsigned char, vector signed char); + + vector signed int vec_all_ne (vector unsigned char, + vector unsigned char); + vector signed int vec_all_ne (vector signed short, + vector unsigned short); + vector signed int vec_all_ne (vector signed short, vector signed short); + + vector signed int vec_all_ne (vector unsigned short, + vector signed short); + vector signed int vec_all_ne (vector unsigned short, + vector unsigned short); + vector signed int vec_all_ne (vector signed int, vector unsigned int); + vector signed int vec_all_ne (vector signed int, vector signed int); + vector signed int vec_all_ne (vector unsigned int, vector signed int); + vector signed int vec_all_ne (vector unsigned int, vector unsigned int); + + vector signed int vec_all_ne (vector float, vector float); + + vector signed int vec_all_nge (vector float, vector float); + + vector signed int vec_all_ngt (vector float, vector float); + + vector signed int vec_all_nle (vector float, vector float); + + vector signed int vec_all_nlt (vector float, vector float); + + vector signed int vec_all_numeric (vector float); + + vector signed int vec_any_eq (vector signed char, vector unsigned char); + + vector signed int vec_any_eq (vector signed char, vector signed char); + vector signed int vec_any_eq (vector unsigned char, vector signed char); + + vector signed int vec_any_eq (vector unsigned char, + vector unsigned char); + vector signed int vec_any_eq (vector signed short, + vector unsigned short); + vector signed int vec_any_eq (vector signed short, vector signed short); + + vector signed int vec_any_eq (vector unsigned short, + vector signed short); + vector signed int vec_any_eq (vector unsigned short, + vector unsigned short); + vector signed int vec_any_eq (vector signed int, vector unsigned int); + vector signed int vec_any_eq (vector signed int, vector signed int); + vector signed int vec_any_eq (vector unsigned int, vector signed int); + vector signed int vec_any_eq (vector unsigned int, vector unsigned int); + + vector signed int vec_any_eq (vector float, vector float); + + vector signed int vec_any_ge (vector signed char, vector unsigned char); + + vector signed int vec_any_ge (vector unsigned char, vector signed char); + + vector signed int vec_any_ge (vector unsigned char, + vector unsigned char); + vector signed int vec_any_ge (vector signed char, vector signed char); + vector signed int vec_any_ge (vector signed short, + vector unsigned short); + vector signed int vec_any_ge (vector unsigned short, + vector signed short); + vector signed int vec_any_ge (vector unsigned short, + vector unsigned short); + vector signed int vec_any_ge (vector signed short, vector signed short); + + vector signed int vec_any_ge (vector signed int, vector unsigned int); + vector signed int vec_any_ge (vector unsigned int, vector signed int); + vector signed int vec_any_ge (vector unsigned int, vector unsigned int); + + vector signed int vec_any_ge (vector signed int, vector signed int); + vector signed int vec_any_ge (vector float, vector float); + + vector signed int vec_any_gt (vector signed char, vector unsigned char); + + vector signed int vec_any_gt (vector unsigned char, vector signed char); + + vector signed int vec_any_gt (vector unsigned char, + vector unsigned char); + vector signed int vec_any_gt (vector signed char, vector signed char); + vector signed int vec_any_gt (vector signed short, + vector unsigned short); + vector signed int vec_any_gt (vector unsigned short, + vector signed short); + vector signed int vec_any_gt (vector unsigned short, + vector unsigned short); + vector signed int vec_any_gt (vector signed short, vector signed short); + + vector signed int vec_any_gt (vector signed int, vector unsigned int); + vector signed int vec_any_gt (vector unsigned int, vector signed int); + vector signed int vec_any_gt (vector unsigned int, vector unsigned int); + + vector signed int vec_any_gt (vector signed int, vector signed int); + vector signed int vec_any_gt (vector float, vector float); + + vector signed int vec_any_le (vector signed char, vector unsigned char); + + vector signed int vec_any_le (vector unsigned char, vector signed char); + + vector signed int vec_any_le (vector unsigned char, + vector unsigned char); + vector signed int vec_any_le (vector signed char, vector signed char); + vector signed int vec_any_le (vector signed short, + vector unsigned short); + vector signed int vec_any_le (vector unsigned short, + vector signed short); + vector signed int vec_any_le (vector unsigned short, + vector unsigned short); + vector signed int vec_any_le (vector signed short, vector signed short); + + vector signed int vec_any_le (vector signed int, vector unsigned int); + vector signed int vec_any_le (vector unsigned int, vector signed int); + vector signed int vec_any_le (vector unsigned int, vector unsigned int); + + vector signed int vec_any_le (vector signed int, vector signed int); + vector signed int vec_any_le (vector float, vector float); + + vector signed int vec_any_lt (vector signed char, vector unsigned char); + + vector signed int vec_any_lt (vector unsigned char, vector signed char); + + vector signed int vec_any_lt (vector unsigned char, + vector unsigned char); + vector signed int vec_any_lt (vector signed char, vector signed char); + vector signed int vec_any_lt (vector signed short, + vector unsigned short); + vector signed int vec_any_lt (vector unsigned short, + vector signed short); + vector signed int vec_any_lt (vector unsigned short, + vector unsigned short); + vector signed int vec_any_lt (vector signed short, vector signed short); + + vector signed int vec_any_lt (vector signed int, vector unsigned int); + vector signed int vec_any_lt (vector unsigned int, vector signed int); + vector signed int vec_any_lt (vector unsigned int, vector unsigned int); + + vector signed int vec_any_lt (vector signed int, vector signed int); + vector signed int vec_any_lt (vector float, vector float); + + vector signed int vec_any_nan (vector float); + + vector signed int vec_any_ne (vector signed char, vector unsigned char); + + vector signed int vec_any_ne (vector signed char, vector signed char); + vector signed int vec_any_ne (vector unsigned char, vector signed char); + + vector signed int vec_any_ne (vector unsigned char, + vector unsigned char); + vector signed int vec_any_ne (vector signed short, + vector unsigned short); + vector signed int vec_any_ne (vector signed short, vector signed short); + + vector signed int vec_any_ne (vector unsigned short, + vector signed short); + vector signed int vec_any_ne (vector unsigned short, + vector unsigned short); + vector signed int vec_any_ne (vector signed int, vector unsigned int); + vector signed int vec_any_ne (vector signed int, vector signed int); + vector signed int vec_any_ne (vector unsigned int, vector signed int); + vector signed int vec_any_ne (vector unsigned int, vector unsigned int); + + vector signed int vec_any_ne (vector float, vector float); + + vector signed int vec_any_nge (vector float, vector float); + + vector signed int vec_any_ngt (vector float, vector float); + + vector signed int vec_any_nle (vector float, vector float); + + vector signed int vec_any_nlt (vector float, vector float); + + vector signed int vec_any_numeric (vector float); + + vector signed int vec_any_out (vector float, vector float); + + +File: gcc.info, Node: Pragmas, Next: Unnamed Fields, Prev: Target Builtins, Up: C Extensions + +5.46 Pragmas Accepted by GCC +============================ + +GCC supports several types of pragmas, primarily in order to compile +code originally written for other compilers. Note that in general we +do not recommend the use of pragmas; *Note Function Attributes::, for +further explanation. + +* Menu: + +* ARM Pragmas:: +* Darwin Pragmas:: +* Solaris Pragmas:: +* Tru64 Pragmas:: + + +File: gcc.info, Node: ARM Pragmas, Next: Darwin Pragmas, Up: Pragmas + +5.46.1 ARM Pragmas +------------------ + +The ARM target defines pragmas for controlling the default addition of +`long_call' and `short_call' attributes to functions. *Note Function +Attributes::, for information about the effects of these attributes. + +`long_calls' + Set all subsequent functions to have the `long_call' attribute. + +`no_long_calls' + Set all subsequent functions to have the `short_call' attribute. + +`long_calls_off' + Do not affect the `long_call' or `short_call' attributes of + subsequent functions. + + +File: gcc.info, Node: Darwin Pragmas, Next: Solaris Pragmas, Prev: ARM Pragmas, Up: Pragmas + +5.46.2 Darwin Pragmas +--------------------- + +The following pragmas are available for all architectures running the +Darwin operating system. These are useful for compatibility with other +MacOS compilers. + +`mark TOKENS...' + This pragma is accepted, but has no effect. + +`options align=ALIGNMENT' + This pragma sets the alignment of fields in structures. The + values of ALIGNMENT may be `mac68k', to emulate m68k alignment, or + `power', to emulate PowerPC alignment. Uses of this pragma nest + properly; to restore the previous setting, use `reset' for the + ALIGNMENT. + +`segment TOKENS...' + This pragma is accepted, but has no effect. + +`unused (VAR [, VAR]...)' + This pragma declares variables to be possibly unused. GCC will not + produce warnings for the listed variables. The effect is similar + to that of the `unused' attribute, except that this pragma may + appear anywhere within the variables' scopes. + + +File: gcc.info, Node: Solaris Pragmas, Next: Tru64 Pragmas, Prev: Darwin Pragmas, Up: Pragmas + +5.46.3 Solaris Pragmas +---------------------- + +For compatibility with the SunPRO compiler, the following pragma is +supported. + +`redefine_extname OLDNAME NEWNAME' + This pragma gives the C function OLDNAME the assembler label + NEWNAME. The pragma must appear before the function declaration. + This pragma is equivalent to the asm labels extension (*note Asm + Labels::). The preprocessor defines `__PRAGMA_REDEFINE_EXTNAME' + if the pragma is available. + + +File: gcc.info, Node: Tru64 Pragmas, Prev: Solaris Pragmas, Up: Pragmas + +5.46.4 Tru64 Pragmas +-------------------- + +For compatibility with the Compaq C compiler, the following pragma is +supported. + +`extern_prefix STRING' + This pragma renames all subsequent function and variable + declarations such that STRING is prepended to the name. This + effect may be terminated by using another `extern_prefix' pragma + with the empty string. + + This pragma is similar in intent to to the asm labels extension + (*note Asm Labels::) in that the system programmer wants to change + the assembly-level ABI without changing the source-level API. The + preprocessor defines `__PRAGMA_EXTERN_PREFIX' if the pragma is + available. + + +File: gcc.info, Node: Unnamed Fields, Prev: Pragmas, Up: C Extensions + +5.47 Unnamed struct/union fields within structs/unions. +======================================================= + +For compatibility with other compilers, GCC allows you to define a +structure or union that contains, as fields, structures and unions +without names. For example: + + struct { + int a; + union { + int b; + float c; + }; + int d; + } foo; + + In this example, the user would be able to access members of the +unnamed union with code like `foo.b'. Note that only unnamed structs +and unions are allowed, you may not have, for example, an unnamed `int'. + + You must never create such structures that cause ambiguous field +definitions. For example, this structure: + + struct { + int a; + struct { + int a; + }; + } foo; + + It is ambiguous which `a' is being referred to with `foo.a'. Such +constructs are not supported and must be avoided. In the future, such +constructs may be detected and treated as compilation errors. + + +File: gcc.info, Node: C++ Extensions, Next: Objective-C, Prev: C Extensions, Up: Top + +6 Extensions to the C++ Language +******************************** + +The GNU compiler provides these extensions to the C++ language (and you +can also use most of the C language extensions in your C++ programs). +If you want to write code that checks whether these features are +available, you can test for the GNU compiler the same way as for C +programs: check for a predefined macro `__GNUC__'. You can also use +`__GNUG__' to test specifically for GNU C++ (*note Standard Predefined +Macros: (cpp.info)Standard Predefined.). + +* Menu: + +* Min and Max:: C++ Minimum and maximum operators. +* Volatiles:: What constitutes an access to a volatile object. +* Restricted Pointers:: C99 restricted pointers and references. +* Vague Linkage:: Where G++ puts inlines, vtables and such. +* C++ Interface:: You can use a single C++ header file for both + declarations and definitions. +* Template Instantiation:: Methods for ensuring that exactly one copy of + each needed template instantiation is emitted. +* Bound member functions:: You can extract a function pointer to the + method denoted by a `->*' or `.*' expression. +* C++ Attributes:: Variable, function, and type attributes for C++ only. +* Java Exceptions:: Tweaking exception handling to work with Java. +* Deprecated Features:: Things might disappear from g++. +* Backwards Compatibility:: Compatibilities with earlier definitions of C++. + + +File: gcc.info, Node: Min and Max, Next: Volatiles, Up: C++ Extensions + +6.1 Minimum and Maximum Operators in C++ +======================================== + +It is very convenient to have operators which return the "minimum" or +the "maximum" of two arguments. In GNU C++ (but not in GNU C), + +`A ? B' + is the "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 ?' are built into the compiler, they properly +handle expressions with side-effects; `int min = i++ (*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 (); - } + +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. + + +File: gcc.info, Node: Vague Linkage, Next: C++ Interface, Prev: Restricted Pointers, Up: C++ Extensions + +6.4 Vague Linkage +================= + +There are several constructs in C++ which require space in the object +file but are not clearly tied to a single translation unit. We say that +these constructs have "vague linkage". Typically such constructs are +emitted wherever they are needed, though sometimes we can be more +clever. + +Inline Functions + Inline functions are typically defined in a header file which can + be included in many different compilations. Hopefully they can + usually be inlined, but sometimes an out-of-line copy is + necessary, if the address of the function is taken or if inlining + fails. In general, we emit an out-of-line copy in all translation + units where one is needed. As an exception, we only emit inline + virtual functions with the vtable, since it will always require a + copy. + + Local static variables and string constants used in an inline + function are also considered to have vague linkage, since they + must be shared between all inlined and out-of-line instances of + the function. + +VTables + C++ virtual functions are implemented in most compilers using a + lookup table, known as a vtable. The vtable contains pointers to + the virtual functions provided by a class, and each object of the + class contains a pointer to its vtable (or vtables, in some + multiple-inheritance situations). If the class declares any + non-inline, non-pure virtual functions, the first one is chosen as + the "key method" for the class, and the vtable is only emitted in + the translation unit where the key method is defined. + + _Note:_ If the chosen key method is later defined as inline, the + vtable will still be emitted in every translation unit which + defines it. Make sure that any inline virtuals are declared + inline in the class body, even if they are not defined there. + +type_info objects + C++ requires information about types to be written out in order to + implement `dynamic_cast', `typeid' and exception handling. For + polymorphic classes (classes with virtual functions), the type_info + object is written out along with the vtable so that `dynamic_cast' + can determine the dynamic type of a class object at runtime. For + all other types, we write out the type_info object when it is + used: when applying `typeid' to an expression, throwing an object, + or referring to a type in a catch clause or exception + specification. + +Template Instantiations + Most everything in this section also applies to template + instantiations, but there are other options as well. *Note + Where's the Template?: Template Instantiation. + + + When used with GNU ld version 2.8 or later on an ELF system such as +Linux/GNU or Solaris 2, or on Microsoft Windows, duplicate copies of +these constructs will be discarded at link time. This is known as +COMDAT support. + + On targets that don't support COMDAT, but do support weak symbols, +GCC will use them. This way one copy will override all the others, but +the unused copies will still take up space in the executable. + + For targets which do not support either COMDAT or weak symbols, most +entities with vague linkage will be emitted as local symbols to avoid +duplicate definition errors from the linker. This will not happen for +local statics in inlines, however, as having multiple copies will +almost certainly break things. + + *Note Declarations and Definitions in One Header: C++ Interface, for +another way to control placement of these constructs. + + +File: gcc.info, Node: C++ Interface, Next: Template Instantiation, Prev: Vague Linkage, Up: C++ Extensions + +6.5 Declarations and Definitions in One Header +============================================== + +C++ object definitions can be quite complex. In principle, your source +code will need two kinds of things for each object that you use across +more than one source file. First, you need an "interface" +specification, describing its structure with type declarations and +function prototypes. Second, you need the "implementation" itself. It +can be tedious to maintain a separate interface description in a header +file, in parallel to the actual implementation. It is also dangerous, +since separate interface and implementation definitions may not remain +parallel. + + With GNU C++, you can use a single header file for both purposes. + + _Warning:_ The mechanism to specify this is in transition. For the + nonce, you must use one of two `#pragma' commands; in a future + release of GNU C++, an alternative mechanism will make these + `#pragma' commands unnecessary. + + The header file contains the full definitions, but is marked with +`#pragma interface' in the source code. This allows the compiler to +use the header file only as an interface specification when ordinary +source files incorporate it with `#include'. In the single source file +where the full implementation belongs, you can use either a naming +convention or `#pragma implementation' to indicate this alternate use +of the header file. + +`#pragma interface' +`#pragma interface "SUBDIR/OBJECTS.h"' + Use this directive in _header files_ that define object classes, + to save space in most of the object files that use those classes. + Normally, local copies of certain information (backup copies of + inline member functions, debugging information, and the internal + tables that implement virtual functions) must be kept in each + object file that includes class definitions. You can use this + pragma to avoid such duplication. When a header file containing + `#pragma interface' is included in a compilation, this auxiliary + information will not be generated (unless the main input source + file itself uses `#pragma implementation'). Instead, the object + files will contain references to be resolved at link time. + + The second form of this directive is useful for the case where you + have multiple headers with the same name in different directories. + If you use this form, you must specify the same string to `#pragma + implementation'. + +`#pragma implementation' +`#pragma implementation "OBJECTS.h"' + Use this pragma in a _main input file_, when you want full output + from included header files to be generated (and made globally + visible). The included header file, in turn, should use `#pragma + interface'. Backup copies of inline member functions, debugging + information, and the internal tables used to implement virtual + functions are all generated in implementation files. + + If you use `#pragma implementation' with no argument, it applies to + an include file with the same basename(1) as your source file. + For example, in `allclass.cc', giving just `#pragma implementation' + by itself is equivalent to `#pragma implementation "allclass.h"'. + + In versions of GNU C++ prior to 2.6.0 `allclass.h' was treated as + an implementation file whenever you would include it from + `allclass.cc' even if you never specified `#pragma + implementation'. This was deemed to be more trouble than it was + worth, however, and disabled. + + If you use an explicit `#pragma implementation', it must appear in + your source file _before_ you include the affected header files. + + Use the string argument if you want a single implementation file to + include code from multiple header files. (You must also use + `#include' to include the header file; `#pragma implementation' + only specifies how to use the file--it doesn't actually include + it.) + + There is no way to split up the contents of a single header file + into multiple implementation files. + + `#pragma implementation' and `#pragma interface' also have an effect +on function inlining. + + If you define a class in a header file marked with `#pragma +interface', the effect on a function defined in that class is similar to +an explicit `extern' declaration--the compiler emits no code at all to +define an independent version of the function. Its definition is used +only for inlining with its callers. + + Conversely, when you include the same header file in a main source +file that declares it as `#pragma implementation', the compiler emits +code for the function itself; this defines a version of the function +that can be found via pointers (or by callers compiled without +inlining). If all calls to the function can be inlined, you can avoid +emitting the function by compiling with `-fno-implement-inlines'. If +any calls were not inlined, you will get linker errors. + + ---------- Footnotes ---------- + + (1) A file's "basename" was the name stripped of all leading path +information and of trailing suffixes, such as `.h' or `.C' or `.cc'. + + +File: gcc.info, Node: Template Instantiation, Next: Bound member functions, Prev: C++ Interface, Up: C++ Extensions + +6.6 Where's the Template? +========================= + +C++ templates are the first language feature to require more +intelligence from the environment than one usually finds on a UNIX +system. Somehow the compiler and linker have to make sure that each +template instance occurs exactly once in the executable if it is needed, +and not at all otherwise. There are two basic approaches to this +problem, which I will refer to as the Borland model and the Cfront +model. + +Borland model + Borland C++ solved the template instantiation problem by adding + the code equivalent of common blocks to their linker; the compiler + emits template instances in each translation unit that uses them, + and the linker collapses them together. The advantage of this + model is that the linker only has to consider the object files + themselves; there is no external complexity to worry about. This + disadvantage is that compilation time is increased because the + template code is being compiled repeatedly. Code written for this + model tends to include definitions of all templates in the header + file, since they must be seen to be instantiated. + +Cfront model + The AT&T C++ translator, Cfront, solved the template instantiation + problem by creating the notion of a template repository, an + automatically maintained place where template instances are + stored. A more modern version of the repository works as follows: + As individual object files are built, the compiler places any + template definitions and instantiations encountered in the + repository. At link time, the link wrapper adds in the objects in + the repository and compiles any needed instances that were not + previously emitted. The advantages of this model are more optimal + compilation speed and the ability to use the system linker; to + implement the Borland model a compiler vendor also needs to + replace the linker. The disadvantages are vastly increased + complexity, and thus potential for error; for some code this can be + just as transparent, but in practice it can been very difficult to + build multiple programs in one directory and one program in + multiple directories. Code written for this model tends to + separate definitions of non-inline member templates into a + separate file, which should be compiled separately. + + When used with GNU ld version 2.8 or later on an ELF system such as +Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the +Borland model. On other systems, g++ implements neither automatic +model. + + A future version of g++ will support a hybrid model whereby the +compiler will emit any instantiations for which the template definition +is included in the compile, and store template definitions and +instantiation context information into the object file for the rest. +The link wrapper will extract that information as necessary and invoke +the compiler to produce the remaining instantiations. The linker will +then combine duplicate instantiations. + + In the mean time, you have the following options for dealing with +template instantiations: + + 1. Compile your template-using code with `-frepo'. The compiler will + generate files with the extension `.rpo' listing all of the + template instantiations used in the corresponding object files + which could be instantiated there; the link wrapper, `collect2', + will then update the `.rpo' files to tell the compiler where to + place those instantiations and rebuild any affected object files. + The link-time overhead is negligible after the first pass, as the + compiler will continue to place the instantiations in the same + files. + + This is your best option for application code written for the + Borland model, as it will just work. Code written for the Cfront + model will need to be modified so that the template definitions + are available at one or more points of instantiation; usually this + is as simple as adding `#include ' 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; + template ostream& operator << + (ostream&, const Foo&); + + 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; + static template class Foo; + + 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; + template ostream& operator << (ostream&, const A&); + + This strategy will work with code written for either model. If + you are using code written for the Cfront model, the file + containing a class template and the file containing its member + templates should be implemented in the same translation unit. + + 5. A slight variation on this approach is to use the flag + `-falt-external-templates' instead. This flag causes template + instances to be emitted in the translation unit that implements the + header where they are first instantiated, rather than the one which + implements the file where the templates are defined. This header + must be the same in all translation units, or things are likely to + break. + + *Note Declarations and Definitions in One Header: C++ Interface, + for more discussion of these pragmas. + + +File: gcc.info, Node: Bound member functions, Next: C++ Attributes, Prev: Template Instantiation, Up: C++ Extensions + +6.7 Extracting the function pointer from a bound pointer to member function +=========================================================================== + +In C++, pointer to member functions (PMFs) are implemented using a wide +pointer of sorts to handle all the possible call mechanisms; the PMF +needs to store information about how to adjust the `this' pointer, and +if the function pointed to is virtual, where to find the vtable, and +where in the vtable to look for the member function. If you are using +PMFs in an inner loop, you should really reconsider that decision. If +that is not an option, you can extract the pointer to the function that +would be called for a given object/PMF pair and call it directly inside +the inner loop, to save a bit of time. + + Note that you will still be paying the penalty for the call through a +function pointer; on most modern architectures, such a call defeats the +branch prediction features of the CPU. This is also true of normal +virtual function calls. + + The syntax for this extension is + + extern A a; + extern int (A::*fp)(); + typedef int (*fptr)(A *); + + fptr p = (fptr)(a.*fp); + + For PMF constants (i.e. expressions of the form `&Klasse::Member'), +no object is needed to obtain the address of the function. They can be +converted to function pointers directly: + + fptr p1 = (fptr)(&A::foo); + + You must specify `-Wno-pmf-conversions' to use this extension. + + +File: gcc.info, Node: C++ Attributes, Next: Java Exceptions, Prev: Bound member functions, Up: C++ Extensions + +6.8 C++-Specific Variable, Function, and Type Attributes +======================================================== + +Some attributes only make sense for C++ programs. + +`init_priority (PRIORITY)' + In Standard C++, objects defined at namespace scope are guaranteed + to be initialized in an order in strict accordance with that of + their definitions _in a given translation unit_. No guarantee is + made for initializations across translation units. However, GNU + C++ allows users to control the order of initialization of objects + defined at namespace scope with the `init_priority' attribute by + specifying a relative PRIORITY, a constant integral expression + currently bounded between 101 and 65535 inclusive. Lower numbers + indicate a higher priority. + + In the following example, `A' would normally be created before + `B', but the `init_priority' attribute has reversed that order: + + Some_Class A __attribute__ ((init_priority (2000))); + Some_Class B __attribute__ ((init_priority (543))); + + Note that the particular values of PRIORITY do not matter; only + their relative ordering. + +`java_interface' + This type attribute informs C++ that the class is a Java + interface. It may only be applied to classes declared within an + `extern "Java"' block. Calls to methods declared in this + interface will be dispatched using GCJ's interface table + mechanism, instead of regular virtual table dispatch. + + + +File: gcc.info, Node: Java Exceptions, Next: Deprecated Features, Prev: C++ Attributes, Up: C++ Extensions + +6.9 Java Exceptions +=================== + +The Java language uses a slightly different exception handling model +from C++. Normally, GNU C++ will automatically detect when you are +writing C++ code that uses Java exceptions, and handle them +appropriately. However, if C++ code only needs to execute destructors +when Java exceptions are thrown through it, GCC will guess incorrectly. +Sample problematic code is: + + struct S { ~S(); }; + extern void bar(); // is written in Java, and may throw exceptions + void foo() + { + S s; + bar(); + } + +The usual effect of an incorrect guess is a link failure, complaining of +a missing routine called `__gxx_personality_v0'. + + You can inform the compiler that Java exceptions are to be used in a +translation unit, irrespective of what it might think, by writing +`#pragma GCC java_exceptions' at the head of the file. This `#pragma' +must appear before any functions that throw or catch exceptions, or run +destructors when exceptions are thrown through them. + + You cannot mix Java and C++ exceptions in the same translation unit. +It is believed to be safe to throw a C++ exception from one file through +another file compiled for the Java exception model, or vice versa, but +there may be bugs in this area. + + +File: gcc.info, Node: Deprecated Features, Next: Backwards Compatibility, Prev: Java Exceptions, Up: C++ Extensions + +6.10 Deprecated Features +======================== + +In the past, the GNU C++ compiler was extended to experiment with new +features, at a time when the C++ language was still evolving. Now that +the C++ standard is complete, some of those features are superseded by +superior alternatives. Using the old features might cause a warning in +some cases that the feature will be dropped in the future. In other +cases, the feature might be gone already. + + While the list below is not exhaustive, it documents some of the +options that are now deprecated: + +`-fexternal-templates' +`-falt-external-templates' + These are two of the many ways for g++ to implement template + instantiation. *Note Template Instantiation::. The C++ standard + clearly defines how template definitions have to be organized + across implementation units. g++ has an implicit instantiation + mechanism that should work just fine for standard-conforming code. + +`-fstrict-prototype' +`-fno-strict-prototype' + Previously it was possible to use an empty prototype parameter + list to indicate an unspecified number of parameters (like C), + rather than no parameters, as C++ demands. This feature has been + removed, except where it is required for backwards compatibility + *Note Backwards Compatibility::. + + The named return value extension has been deprecated, and is now +removed from g++. + + The use of initializer lists with new expressions has been +deprecated, and is now removed from g++. + + Floating and complex non-type template parameters have been +deprecated, and are now removed from g++. + + The implicit typename extension has been deprecated and will be +removed from g++ at some point. In some cases g++ determines that a +dependant type such as `TPL::X' is a type without needing a +`typename' keyword, contrary to the standard. + + +File: gcc.info, Node: Backwards Compatibility, Prev: Deprecated Features, Up: C++ Extensions + +6.11 Backwards Compatibility +============================ + +Now that there is a definitive ISO standard C++, G++ has a specification +to adhere to. The C++ language evolved over time, and features that +used to be acceptable in previous drafts of the standard, such as the +ARM [Annotated C++ Reference Manual], are no longer accepted. In order +to allow compilation of C++ written to such drafts, G++ contains some +backwards compatibilities. _All such backwards compatibility features +are liable to disappear in future versions of G++._ They should be +considered deprecated *Note Deprecated Features::. + +`For scope' + If a variable is declared at for scope, it used to remain in scope + until the end of the scope which contained the for statement + (rather than just within the for scope). G++ retains this, but + issues a warning, if such a variable is accessed outside the for + scope. + +`Implicit C language' + Old C system header files did not contain an `extern "C" {...}' + scope to set the language. On such systems, all header files are + implicitly scoped inside a C language scope. Also, an empty + prototype `()' will be treated as an unspecified number of + arguments, rather than no arguments, as C++ demands. + + +File: gcc.info, Node: Objective-C, Next: Compatibility, Prev: C++ Extensions, Up: Top + +7 GNU Objective-C runtime features +********************************** + +This document is meant to describe some of the GNU Objective-C runtime +features. It is not intended to teach you Objective-C, there are +several resources on the Internet that present the language. Questions +and comments about this document to Ovidiu Predescu . + +* Menu: + +* Executing code before main:: +* Type encoding:: +* Garbage Collection:: +* Constant string objects:: +* compatibility_alias:: + + +File: gcc.info, Node: Executing code before main, Next: Type encoding, Prev: Objective-C, Up: Objective-C + +7.1 `+load': Executing code before main +======================================= + +The GNU Objective-C runtime provides a way that allows you to execute +code before the execution of the program enters the `main' function. +The code is executed on a per-class and a per-category basis, through a +special class method `+load'. + + This facility is very useful if you want to initialize global +variables which can be accessed by the program directly, without +sending a message to the class first. The usual way to initialize +global variables, in the `+initialize' method, might not be useful +because `+initialize' is only called when the first message is sent to a +class object, which in some cases could be too late. + + Suppose for example you have a `FileStream' class that declares +`Stdin', `Stdout' and `Stderr' as global variables, like below: + + + FileStream *Stdin = nil; + FileStream *Stdout = nil; + FileStream *Stderr = nil; + + @implementation FileStream + + + (void)initialize + { + Stdin = [[FileStream new] initWithFd:0]; + Stdout = [[FileStream new] initWithFd:1]; + Stderr = [[FileStream new] initWithFd:2]; + } + + /* Other methods here */ + @end + + In this example, the initialization of `Stdin', `Stdout' and +`Stderr' in `+initialize' occurs too late. The programmer can send a +message to one of these objects before the variables are actually +initialized, thus sending messages to the `nil' object. The +`+initialize' method which actually initializes the global variables is +not invoked until the first message is sent to the class object. The +solution would require these variables to be initialized just before +entering `main'. + + The correct solution of the above problem is to use the `+load' +method instead of `+initialize': + + + @implementation FileStream + + + (void)load + { + Stdin = [[FileStream new] initWithFd:0]; + Stdout = [[FileStream new] initWithFd:1]; + Stderr = [[FileStream new] initWithFd:2]; + } + + /* Other methods here */ + @end + + The `+load' is a method that is not overridden by categories. If a +class and a category of it both implement `+load', both methods are +invoked. This allows some additional initializations to be performed in +a category. + + This mechanism is not intended to be a replacement for `+initialize'. +You should be aware of its limitations when you decide to use it +instead of `+initialize'. + +* Menu: + +* What you can and what you cannot do in +load:: + + +File: gcc.info, Node: What you can and what you cannot do in +load, Prev: Executing code before main, Up: Executing code before main + +7.1.1 What you can and what you cannot do in `+load' +---------------------------------------------------- + +The `+load' implementation in the GNU runtime guarantees you the +following things: + + * you can write whatever C code you like; + + * you can send messages to Objective-C constant strings (`@"this is a + constant string"'); + + * you can allocate and send messages to objects whose class is + implemented in the same file; + + * the `+load' implementation of all super classes of a class are + executed before the `+load' of that class is executed; + + * the `+load' implementation of a class is executed before the + `+load' implementation of any category. + + + In particular, the following things, even if they can work in a +particular case, are not guaranteed: + + * allocation of or sending messages to arbitrary objects; + + * allocation of or sending messages to objects whose classes have a + category implemented in the same file; + + + You should make no assumptions about receiving `+load' in sibling +classes when you write `+load' of a class. The order in which sibling +classes receive `+load' is not guaranteed. + + The order in which `+load' and `+initialize' are called could be +problematic if this matters. If you don't allocate objects inside +`+load', it is guaranteed that `+load' is called before `+initialize'. +If you create an object inside `+load' the `+initialize' method of +object's class is invoked even if `+load' was not invoked. Note if you +explicitly call `+load' on a class, `+initialize' will be called first. +To avoid possible problems try to implement only one of these methods. + + The `+load' method is also invoked when a bundle is dynamically +loaded into your running program. This happens automatically without +any intervening operation from you. When you write bundles and you +need to write `+load' you can safely create and send messages to +objects whose classes already exist in the running program. The same +restrictions as above apply to classes defined in bundle. + + +File: gcc.info, Node: Type encoding, Next: Garbage Collection, Prev: Executing code before main, Up: Objective-C + +7.2 Type encoding +================= + +The Objective-C compiler generates type encodings for all the types. +These type encodings are used at runtime to find out information about +selectors and methods and about objects and classes. + + The types are encoded in the following way: + +`char' `c' +`unsigned char' `C' +`short' `s' +`unsigned short' `S' +`int' `i' +`unsigned int' `I' +`long' `l' +`unsigned long' `L' +`long long' `q' +`unsigned long `Q' +long' +`float' `f' +`double' `d' +`void' `v' +`id' `@' +`Class' `#' +`SEL' `:' +`char*' `*' +unknown type `?' +bit-fields `b' followed by the starting position of the + bit-field, the type of the bit-field and the size of + the bit-field (the bit-fields encoding was changed + from the NeXT's compiler encoding, see below) + + The encoding of bit-fields has changed to allow bit-fields to be +properly handled by the runtime functions that compute sizes and +alignments of types that contain bit-fields. The previous encoding +contained only the size of the bit-field. Using only this information +it is not possible to reliably compute the size occupied by the +bit-field. This is very important in the presence of the Boehm's +garbage collector because the objects are allocated using the typed +memory facility available in this collector. The typed memory +allocation requires information about where the pointers are located +inside the object. + + The position in the bit-field is the position, counting in bits, of +the bit closest to the beginning of the structure. + + The non-atomic types are encoded as follows: + +pointers `^' followed by the pointed type. +arrays `[' followed by the number of elements in the array + followed by the type of the elements followed by `]' +structures `{' followed by the name of the structure (or `?' if the + structure is unnamed), the `=' sign, the type of the + members and by `}' +unions `(' followed by the name of the structure (or `?' if the + union is unnamed), the `=' sign, the type of the members + followed by `)' + + Here are some types and their encodings, as they are generated by the +compiler on an i386 machine: + + +Objective-C type Compiler encoding + int a[10]; `[10i]' + struct { `{?=i[3f]b128i3b131i2c}' + int i; + float f[3]; + int a:3; + int b:2; + char c; + } + + + In addition to the types the compiler also encodes the type +specifiers. The table below describes the encoding of the current +Objective-C type specifiers: + + +Specifier Encoding +`const' `r' +`in' `n' +`inout' `N' +`out' `o' +`bycopy' `O' +`oneway' `V' + + + The type specifiers are encoded just before the type. Unlike types +however, the type specifiers are only encoded when they appear in method +argument types. + + +File: gcc.info, Node: Garbage Collection, Next: Constant string objects, Prev: Type encoding, Up: Objective-C + +7.3 Garbage Collection +====================== + +Support for a new memory management policy has been added by using a +powerful conservative garbage collector, known as the +Boehm-Demers-Weiser conservative garbage collector. It is available +from `http://www.hpl.hp.com/personal/Hans_Boehm/gc/'. + + To enable the support for it you have to configure the compiler +using an additional argument, `--enable-objc-gc'. You need to have +garbage collector installed before building the compiler. This will +build an additional runtime library which has several enhancements to +support the garbage collector. The new library has a new name, +`libobjc_gc.a' to not conflict with the non-garbage-collected library. + + When the garbage collector is used, the objects are allocated using +the so-called typed memory allocation mechanism available in the +Boehm-Demers-Weiser collector. This mode requires precise information +on where pointers are located inside objects. This information is +computed once per class, immediately after the class has been +initialized. + + There is a new runtime function `class_ivar_set_gcinvisible()' which +can be used to declare a so-called "weak pointer" reference. Such a +pointer is basically hidden for the garbage collector; this can be +useful in certain situations, especially when you want to keep track of +the allocated objects, yet allow them to be collected. This kind of +pointers can only be members of objects, you cannot declare a global +pointer as a weak reference. Every type which is a pointer type can be +declared a weak pointer, including `id', `Class' and `SEL'. + + Here is an example of how to use this feature. Suppose you want to +implement a class whose instances hold a weak pointer reference; the +following class does this: + + + @interface WeakPointer : Object + { + const void* weakPointer; + } + + - initWithPointer:(const void*)p; + - (const void*)weakPointer; + @end + + + @implementation WeakPointer + + + (void)initialize + { + class_ivar_set_gcinvisible (self, "weakPointer", YES); + } + + - initWithPointer:(const void*)p + { + weakPointer = p; + return self; + } + + - (const void*)weakPointer + { + return weakPointer; + } + + @end + + Weak pointers are supported through a new type character specifier +represented by the `!' character. The `class_ivar_set_gcinvisible()' +function adds or removes this specifier to the string type description +of the instance variable named as argument. + + +File: gcc.info, Node: Constant string objects, Next: compatibility_alias, Prev: Garbage Collection, Up: Objective-C + +7.4 Constant string objects +=========================== + +GNU Objective-C provides constant string objects that are generated +directly by the compiler. You declare a constant string object by +prefixing a C constant string with the character `@': + + id myString = @"this is a constant string object"; + + The constant string objects are usually instances of the +`NXConstantString' class which is provided by the GNU Objective-C +runtime. To get the definition of this class you must include the +`objc/NXConstStr.h' header file. -`-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. + + +File: gcc.info, Node: compatibility_alias, Prev: Constant string objects, Up: Objective-C + +7.5 compatibility_alias +======================= + +This is a feature of the Objective-C compiler rather than of the +runtime, anyway since it is documented nowhere and its existence was +forgotten, we are documenting it here. + + The keyword `@compatibility_alias' allows you to define a class name +as equivalent to another class name. For example: + + @compatibility_alias WOApplication GSWApplication; + + tells the compiler that each time it encounters `WOApplication' as a +class name, it should replace it with `GSWApplication' (that is, +`WOApplication' is just an alias for `GSWApplication'). + + There are some constraints on how this can be used-- + + * `WOApplication' (the alias) must not be an existing class; + + * `GSWApplication' (the real class) must be an existing class. + + + +File: gcc.info, Node: Compatibility, Next: Gcov, Prev: Objective-C, Up: Top + +8 Binary Compatibility +********************** + +Binary compatibility encompasses several related concepts: + +"application binary interface (ABI)" + The set of runtime conventions followed by all of the tools that + deal with binary representations of a program, including + compilers, assemblers, linkers, and language runtime support. + Some ABIs are formal with a written specification, possibly + designed by multiple interested parties. Others are simply the + way things are actually done by a particular set of tools. + +"ABI conformance" + A compiler conforms to an ABI if it generates code that follows + all of the specifications enumerated by that ABI. A library + conforms to an ABI if it is implemented according to that ABI. An + application conforms to an ABI if it is built using tools that + conform to that ABI and does not contain source code that + specifically changes behavior specified by the ABI. + +"calling conventions" + Calling conventions are a subset of an ABI that specify of how + arguments are passed and function results are returned. + +"interoperability" + Different sets of tools are interoperable if they generate files + that can be used in the same program. The set of tools includes + compilers, assemblers, linkers, libraries, header files, startup + files, and debuggers. Binaries produced by different sets of + tools are not interoperable unless they implement the same ABI. + This applies to different versions of the same tools as well as + tools from different vendors. + +"intercallability" + Whether a function in a binary built by one set of tools can call a + function in a binary built by a different set of tools is a subset + of interoperability. + +"implementation-defined features" + Language standards include lists of implementation-defined + features whose behavior can vary from one implementation to + another. Some of these features are normally covered by a + platform's ABI and others are not. The features that are not + covered by an ABI generally affect how a program behaves, but not + intercallability. + +"compatibility" + Conformance to the same ABI and the same behavior of + implementation-defined features are both relevant for + compatibility. + + The application binary interface implemented by a C or C++ compiler +affects code generation and runtime support for: + + * size and alignment of data types + + * layout of structured types + + * calling conventions + + * register usage conventions + + * interfaces for runtime arithmetic support + + * object file formats + + In addition, the application binary interface implemented by a C++ +compiler affects code generation and runtime support for: + * name mangling + + * exception handling + + * invoking constructors and destructors + + * layout, alignment, and padding of classes + + * layout and alignment of virtual tables + + Some GCC compilation options cause the compiler to generate code that +does not conform to the platform's default ABI. Other options cause +different program behavior for implementation-defined features that are +not covered by an ABI. These options are provided for consistency with +other compilers that do not follow the platform's default ABI or the +usual behavior of implementation-defined features for the platform. Be +very careful about using such options. + + Most platforms have a well-defined ABI that covers C code, but ABIs +that cover C++ functionality are not yet common. + + Starting with GCC 3.2, GCC binary conventions for C++ are based on a +written, vendor-neutral C++ ABI that was designed to be specific to +64-bit Itanium but also includes generic specifications that apply to +any platform. This C++ ABI is also implemented by other compiler +vendors on some platforms, notably GNU/Linux and BSD systems. We have +tried hard to provide a stable ABI that will be compatible with future +GCC releases, but it is possible that we will encounter problems that +make this difficult. Such problems could include different +interpretations of the C++ ABI by different vendors, bugs in the ABI, or +bugs in the implementation of the ABI in different compilers. GCC's +`-Wabi' switch warns when G++ generates code that is probably not +compatible with the C++ ABI. + + The C++ library used with a C++ compiler includes the Standard C++ +Library, with functionality defined in the C++ Standard, plus language +runtime support. The runtime support is included in a C++ ABI, but +there is no formal ABI for the Standard C++ Library. Two +implementations of that library are interoperable if one follows the +de-facto ABI of the other and if they are both built with the same +compiler, or with compilers that conform to the same ABI for C++ +compiler and runtime support. + + When G++ and another C++ compiler conform to the same C++ ABI, but +the implementations of the Standard C++ Library that they normally use +do not follow the same ABI for the Standard C++ Library, object files +built with those compilers can be used in the same program only if they +use the same C++ library. This requires specifying the location of the +C++ library header files when invoking the compiler whose usual library +is not being used. The location of GCC's C++ header files depends on +how the GCC build was configured, but can be seen by using the G++ `-v' +option. With default configuration options for G++ 3.2 the compile +line for a different C++ compiler needs to include + + -IGCC_INSTALL_DIRECTORY/include/c++/3.2 + + Similarly, compiling code with G++ that must use a C++ library other +than the GNU C++ library requires specifying the location of the header +files for that other library. + + The most straightforward way to link a program to use a particular +C++ library is to use a C++ driver that specifies that C++ library by +default. The `g++' driver, for example, tells the linker where to find +GCC's C++ library (`libstdc++') plus the other libraries and startup +files it needs, in the proper order. + + If a program must use a different C++ library and it's not possible +to do the final link using a C++ driver that uses that library by +default, it is necessary to tell `g++' the location and name of that +library. It might also be necessary to specify different startup files +and other runtime support libraries, and to suppress the use of GCC's +support libraries with one or more of the options `-nostdlib', +`-nostartfiles', and `-nodefaultlibs'. + + +File: gcc.info, Node: Gcov, Next: Trouble, Prev: Compatibility, Up: Top + +9 `gcov'--a Test Coverage Program +********************************* + +`gcov' is a tool you can use in conjunction with GCC to test code +coverage in your programs. + +* Menu: + +* Gcov Intro:: Introduction to gcov. +* Invoking Gcov:: How to use gcov. +* Gcov and Optimization:: Using gcov with GCC optimization. +* Gcov Data Files:: The files used by gcov. + + +File: gcc.info, Node: Gcov Intro, Next: Invoking Gcov, Up: Gcov + +9.1 Introduction to `gcov' +========================== + +`gcov' is a test coverage program. Use it in concert with GCC to +analyze your programs to help create more efficient, faster running +code. You can use `gcov' as a profiling tool to help discover where +your optimization efforts will best affect your code. You can also use +`gcov' along with the other profiling tool, `gprof', to assess which +parts of your code use the greatest amount of computing time. + + Profiling tools help you analyze your code's performance. Using a +profiler such as `gcov' or `gprof', you can find out some basic +performance statistics, such as: + + * how often each line of code executes + + * what lines of code are actually executed + + * how much computing time each section of code uses + + Once you know these things about how your code works when compiled, +you can look at each module to see which modules should be optimized. +`gcov' helps you determine where to work on optimization. + + Software developers also use coverage testing in concert with +testsuites, to make sure software is actually good enough for a release. +Testsuites can verify that a program works as expected; a coverage +program tests to see how much of the program is exercised by the +testsuite. Developers can then determine what kinds of test cases need +to be added to the testsuites to create both better testing and a better +final product. + + You should compile your code without optimization if you plan to use +`gcov' because the optimization, by combining some lines of code into +one function, may not give you as much information as you need to look +for `hot spots' where the code is using a great deal of computer time. +Likewise, because `gcov' accumulates statistics by line (at the lowest +resolution), it works best with a programming style that places only +one statement on each line. If you use complicated macros that expand +to loops or to other control structures, the statistics are less +helpful--they only report on the line where the macro call appears. If +your complex macros behave like functions, you can replace them with +inline functions to solve this problem. + + `gcov' creates a logfile called `SOURCEFILE.gcov' which indicates +how many times each line of a source file `SOURCEFILE.c' has executed. +You can use these logfiles along with `gprof' to aid in fine-tuning the +performance of your programs. `gprof' gives timing information you can +use along with the information you get from `gcov'. + + `gcov' works only on code compiled with GCC. It is not compatible +with any other profiling or test coverage mechanism. + + +File: gcc.info, Node: Invoking Gcov, Next: Gcov and Optimization, Prev: Gcov Intro, Up: Gcov + +9.2 Invoking gcov +================= + + gcov [OPTIONS] SOURCEFILE + + `gcov' accepts the following options: + +`-h' +`--help' + Display help about using `gcov' (on the standard output), and exit + without doing any further processing. + +`-v' +`--version' + Display the `gcov' version number (on the standard output), and + exit without doing any further processing. + +`-b' +`--branch-probabilities' + Write branch frequencies to the output file, and write branch + summary info to the standard output. This option allows you to + see how often each branch in your program was taken. + +`-c' +`--branch-counts' + Write branch frequencies as the number of branches taken, rather + than the percentage of branches taken. + +`-n' +`--no-output' + Do not create the `gcov' output file. + +`-l' +`--long-file-names' + Create long file names for included source files. For example, if + the header file `x.h' contains code, and was included in the file + `a.c', then running `gcov' on the file `a.c' will produce an + output file called `a.c.x.h.gcov' instead of `x.h.gcov'. This can + be useful if `x.h' is included in multiple source files. + +`-f' +`--function-summaries' + Output summaries for each function in addition to the file level + summary. + +`-o DIRECTORY' +`--object-directory DIRECTORY' + The directory where the object files live. Gcov will search for + `.bb', `.bbg', and `.da' files in this directory. + + When using `gcov', you must first compile your program with two +special GCC options: `-fprofile-arcs -ftest-coverage'. This tells the +compiler to generate additional information needed by gcov (basically a +flow graph of the program) and also includes additional code in the +object files for generating the extra profiling information needed by +gcov. These additional files are placed in the directory where the +source code is located. + + Running the program will cause profile output to be generated. For +each source file compiled with `-fprofile-arcs', an accompanying `.da' +file will be placed in the source directory. + + Running `gcov' with your program's source file names as arguments +will now produce a listing of the code along with frequency of execution +for each line. For example, if your program is called `tmp.c', this is +what you see when you use the basic `gcov' facility: + + $ gcc -fprofile-arcs -ftest-coverage tmp.c + $ a.out + $ gcov tmp.c + 87.50% of 8 source lines executed in file tmp.c + Creating tmp.c.gcov. + + The file `tmp.c.gcov' contains output from `gcov'. Here is a sample: + + main() + { + 1 int i, total; + + 1 total = 0; + + 11 for (i = 0; i < 10; i++) + 10 total += i; + + 1 if (total != 45) + ###### printf ("Failure\n"); + else + 1 printf ("Success\n"); + 1 } + + When you use the `-b' option, your output looks like this: + + $ gcov -b tmp.c + 87.50% of 8 source lines executed in file tmp.c + 80.00% of 5 branches executed in file tmp.c + 80.00% of 5 branches taken at least once in file tmp.c + 50.00% of 2 calls executed in file tmp.c + Creating tmp.c.gcov. + + Here is a sample of a resulting `tmp.c.gcov' file: + + main() + { + 1 int i, total; + + 1 total = 0; + + 11 for (i = 0; i < 10; i++) + branch 0 taken = 91% + branch 1 taken = 100% + branch 2 taken = 100% + 10 total += i; + + 1 if (total != 45) + branch 0 taken = 100% + ###### printf ("Failure\n"); + call 0 never executed + branch 1 never executed + else + 1 printf ("Success\n"); + call 0 returns = 100% + 1 } + + For each basic block, a line is printed after the last line of the +basic block describing the branch or call that ends the basic block. +There can be multiple branches and calls listed for a single source +line if there are multiple basic blocks that end on that line. In this +case, the branches and calls are each given a number. There is no +simple way to map these branches and calls back to source constructs. +In general, though, the lowest numbered branch or call will correspond +to the leftmost construct on the source line. + + For a branch, if it was executed at least once, then a percentage +indicating the number of times the branch was taken divided by the +number of times the branch was executed will be printed. Otherwise, the +message "never executed" is printed. + + For a call, if it was executed at least once, then a percentage +indicating the number of times the call returned divided by the number +of times the call was executed will be printed. This will usually be +100%, but may be less for functions call `exit' or `longjmp', and thus +may not return every time they are called. + + The execution counts are cumulative. If the example program were +executed again without removing the `.da' file, the count for the +number of times each line in the source was executed would be added to +the results of the previous run(s). This is potentially useful in +several ways. For example, it could be used to accumulate data over a +number of program runs as part of a test verification suite, or to +provide more accurate long-term information over a large number of +program runs. + + The data in the `.da' files is saved immediately before the program +exits. For each source file compiled with `-fprofile-arcs', the +profiling code first attempts to read in an existing `.da' file; if the +file doesn't match the executable (differing number of basic block +counts) it will ignore the contents of the file. It then adds in the +new execution counts and finally writes the data to the file. + + +File: gcc.info, Node: Gcov and Optimization, Next: Gcov Data Files, Prev: Invoking Gcov, Up: Gcov + +9.3 Using `gcov' with GCC Optimization +====================================== + +If you plan to use `gcov' to help optimize your code, you must first +compile your program with two special GCC options: `-fprofile-arcs +-ftest-coverage'. Aside from that, you can use any other GCC options; +but if you want to prove that every single line in your program was +executed, you should not compile with optimization at the same time. +On some machines the optimizer can eliminate some simple code lines by +combining them with other lines. For example, code like this: + + if (a != b) + c = 1; + else + c = 0; + +can be compiled into one instruction on some machines. In this case, +there is no way for `gcov' to calculate separate execution counts for +each line because there isn't separate code for each line. Hence the +`gcov' output looks like this if you compiled the program with +optimization: + + 100 if (a != b) + 100 c = 1; + 100 else + 100 c = 0; + + The output shows that this block of code, combined by optimization, +executed 100 times. In one sense this result is correct, because there +was only one instruction representing all four of these lines. However, +the output does not indicate how many times the result was 0 and how +many times the result was 1. + + +File: gcc.info, Node: Gcov Data Files, Prev: Gcov and Optimization, Up: Gcov + +9.4 Brief description of `gcov' data files +========================================== + +`gcov' uses three files for doing profiling. The names of these files +are derived from the original _source_ file by substituting the file +suffix with either `.bb', `.bbg', or `.da'. All of these files are +placed in the same directory as the source file, and contain data +stored in a platform-independent method. + + The `.bb' and `.bbg' files are generated when the source file is +compiled with the GCC `-ftest-coverage' option. The `.bb' file +contains a list of source files (including headers), functions within +those files, and line numbers corresponding to each basic block in the +source file. + + The `.bb' file format consists of several lists of 4-byte integers +which correspond to the line numbers of each basic block in the file. +Each list is terminated by a line number of 0. A line number of -1 is +used to designate that the source file name (padded to a 4-byte +boundary and followed by another -1) follows. In addition, a line +number of -2 is used to designate that the name of a function (also +padded to a 4-byte boundary and followed by a -2) follows. + + The `.bbg' file is used to reconstruct the program flow graph for +the source file. It contains a list of the program flow arcs (possible +branches taken from one basic block to another) for each function which, +in combination with the `.bb' file, enables gcov to reconstruct the +program flow. + + In the `.bbg' file, the format is: + number of basic blocks for function #0 (4-byte number) + total number of arcs for function #0 (4-byte number) + count of arcs in basic block #0 (4-byte number) + destination basic block of arc #0 (4-byte number) + flag bits (4-byte number) + destination basic block of arc #1 (4-byte number) + flag bits (4-byte number) + ... + destination basic block of arc #N (4-byte number) + flag bits (4-byte number) + count of arcs in basic block #1 (4-byte number) + destination basic block of arc #0 (4-byte number) + flag bits (4-byte number) + ... + + A -1 (stored as a 4-byte number) is used to separate each function's +list of basic blocks, and to verify that the file has been read +correctly. + + The `.da' file is generated when a program containing object files +built with the GCC `-fprofile-arcs' option is executed. A separate +`.da' file is created for each source file compiled with this option, +and the name of the `.da' file is stored as an absolute pathname in the +resulting object file. This path name is derived from the source file +name by substituting a `.da' suffix. + + The format of the `.da' file is fairly simple. The first 8-byte +number is the number of counts in the file, followed by the counts +(stored as 8-byte numbers). Each count corresponds to the number of +times each arc in the program is executed. The counts are cumulative; +each time the program is executed, it attempts to combine the existing +`.da' files with the new counts for this invocation of the program. It +ignores the contents of any `.da' files whose number of arcs doesn't +correspond to the current program, and merely overwrites them instead. + + All three of these files use the functions in `gcov-io.h' to store +integers; the functions in this header provide a machine-independent +mechanism for storing and retrieving data from a stream. + + +File: gcc.info, Node: Trouble, Next: Bugs, Prev: Gcov, Up: Top + +10 Known Causes of Trouble with GCC +*********************************** + +This section describes known problems that affect users of GCC. Most +of these are not GCC bugs per se--if they were, we would fix them. But +the result for a user may be like the result of a bug. + + Some of these problems are due to bugs in other software, some are +missing features that are too much work to add, and some are places +where people's opinions differ as to what is best. + +* Menu: + +* Actual Bugs:: Bugs we will fix later. +* Cross-Compiler Problems:: Common problems of cross compiling with GCC. +* Interoperation:: Problems using GCC with other compilers, + and with certain linkers, assemblers and debuggers. +* External Bugs:: Problems compiling certain programs. +* Incompatibilities:: GCC is incompatible with traditional C. +* Fixed Headers:: GCC uses corrected versions of system header files. + This is necessary, but doesn't always work smoothly. +* Standard Libraries:: GCC uses the system C library, which might not be + compliant with the ISO C standard. +* Disappointments:: Regrettable things we can't change, but not quite bugs. +* C++ Misunderstandings:: Common misunderstandings with GNU C++. +* Protoize Caveats:: Things to watch out for when using `protoize'. +* Non-bugs:: Things we think are right, but some others disagree. +* Warnings and Errors:: Which problems in your code get warnings, + and which get errors. + + +File: gcc.info, Node: Actual Bugs, Next: Cross-Compiler Problems, Up: Trouble + +10.1 Actual Bugs We Haven't Fixed Yet +===================================== + + * The `fixincludes' script interacts badly with automounters; if the + directory of system header files is automounted, it tends to be + unmounted while `fixincludes' is running. This would seem to be a + bug in the automounter. We don't know any good way to work around + it. + + * The `fixproto' script will sometimes add prototypes for the + `sigsetjmp' and `siglongjmp' functions that reference the + `jmp_buf' type before that type is defined. To work around this, + edit the offending file and place the typedef in front of the + prototypes. + + * When `-pedantic-errors' is specified, GCC will incorrectly give an + error message when a function name is specified in an expression + involving the comma operator. + + +File: gcc.info, Node: Cross-Compiler Problems, Next: Interoperation, Prev: Actual Bugs, Up: Trouble + +10.2 Cross-Compiler Problems +============================ + +You may run into problems with cross compilation on certain machines, +for several reasons. + + * Cross compilation can run into trouble for certain machines because + some target machines' assemblers require floating point numbers to + be written as _integer_ constants in certain contexts. + + The compiler writes these integer constants by examining the + floating point value as an integer and printing that integer, + because this is simple to write and independent of the details of + the floating point representation. But this does not work if the + compiler is running on a different machine with an incompatible + floating point format, or even a different byte-ordering. + + In addition, correct constant folding of floating point values + requires representing them in the target machine's format. (The C + standard does not quite require this, but in practice it is the + only way to win.) + + It is now possible to overcome these problems by defining macros + such as `REAL_VALUE_TYPE'. But doing so is a substantial amount of + work for each target machine. *Note Cross Compilation and + Floating Point: (gccint)Cross-compilation. + + * At present, the program `mips-tfile' which adds debug support to + object files on MIPS systems does not work in a cross compile + environment. + + +File: gcc.info, Node: Interoperation, Next: External Bugs, Prev: Cross-Compiler Problems, Up: Trouble + +10.3 Interoperation +=================== + +This section lists various difficulties encountered in using GCC +together with other compilers or with the assemblers, linkers, +libraries and debuggers on certain systems. + + * On many platforms, GCC supports a different ABI for C++ than do + other compilers, so the object files compiled by GCC cannot be + used with object files generated by another C++ compiler. + + An area where the difference is most apparent is name mangling. + The use of different name mangling is intentional, to protect you + from more subtle problems. Compilers differ as to many internal + details of C++ implementation, including: how class instances are + laid out, how multiple inheritance is implemented, and how virtual + function calls are handled. If the name encoding were made the + same, your programs would link against libraries provided from + other compilers--but the programs would then crash when run. + Incompatible libraries are then detected at link time, rather than + at run time. + + * Older GDB versions sometimes fail to read the output of GCC version + 2. If you have trouble, get GDB version 4.4 or later. + + * DBX rejects some files produced by GCC, though it accepts similar + constructs in output from PCC. Until someone can supply a coherent + description of what is valid DBX input and what is not, there is + nothing I can do about these problems. You are on your own. + + * The GNU assembler (GAS) does not support PIC. To generate PIC + code, you must use some other assembler, such as `/bin/as'. + + * On some BSD systems, including some versions of Ultrix, use of + profiling causes static variable destructors (currently used only + in C++) not to be run. + + * On some SGI systems, when you use `-lgl_s' as an option, it gets + translated magically to `-lgl_s -lX11_s -lc_s'. Naturally, this + does not happen when you use GCC. You must specify all three + options explicitly. + + * On a Sparc, GCC aligns all values of type `double' on an 8-byte + boundary, and it expects every `double' to be so aligned. The Sun + compiler usually gives `double' values 8-byte alignment, with one + exception: function arguments of type `double' may not be aligned. + + As a result, if a function compiled with Sun CC takes the address + of an argument of type `double' and passes this pointer of type + `double *' to a function compiled with GCC, dereferencing the + pointer may cause a fatal signal. + + One way to solve this problem is to compile your entire program + with GCC. Another solution is to modify the function that is + compiled with Sun CC to copy the argument into a local variable; + local variables are always properly aligned. A third solution is + to modify the function that uses the pointer to dereference it via + the following function `access_double' instead of directly with + `*': + + inline double + access_double (double *unaligned_ptr) { - 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'. + +File: gcc.info, Node: External Bugs, Next: Incompatibilities, Prev: Interoperation, Up: Trouble + +10.4 Problems Compiling Certain Programs +======================================== + +Certain programs have problems compiling. + + * Parse errors may occur compiling X11 on a Decstation running + Ultrix 4.2 because of problems in DEC's versions of the X11 header + files `X11/Xlib.h' and `X11/Xutil.h'. People recommend adding + `-I/usr/include/mit' to use the MIT versions of the header files, + using the `-traditional' switch to turn off ISO C, or fixing the + header files by adding this: + + #ifdef __STDC__ + #define NeedFunctionPrototypes 0 + #endif + + * On various 386 Unix systems derived from System V, including SCO, + ISC, and ESIX, you may get error messages about running out of + virtual memory while compiling certain programs. + + You can prevent this problem by linking GCC with the GNU malloc + (which thus replaces the malloc that comes with the system). GNU + malloc is available as a separate package, and also in the file + `src/gmalloc.c' in the GNU Emacs 19 distribution. + + If you have installed GNU malloc as a separate library package, + use this option when you relink GCC: + + MALLOC=/usr/local/lib/libgmalloc.a + + Alternatively, if you have compiled `gmalloc.c' from Emacs 19, copy + the object file to `gmalloc.o' and use this option when you relink + GCC: + + MALLOC=gmalloc.o + + +File: gcc.info, Node: Incompatibilities, Next: Fixed Headers, Prev: External Bugs, Up: Trouble + +10.5 Incompatibilities of GCC +============================= + +There are several noteworthy incompatibilities between GNU C and K&R +(non-ISO) versions of C. The `-traditional' option eliminates many of +these incompatibilities, _but not all_, by telling GCC to behave like a +K&R C compiler. + + * GCC normally makes string constants read-only. If several + identical-looking string constants are used, GCC stores only one + copy of the string. + + One consequence is that you cannot call `mktemp' with a string + constant argument. The function `mktemp' always alters the string + its argument points to. + + Another consequence is that `sscanf' does not work on some systems + when passed a string constant as its format control string or + input. This is because `sscanf' incorrectly tries to write into + the string constant. Likewise `fscanf' and `scanf'. + + The best solution to these problems is to change the program to use + `char'-array variables with initialization strings for these + purposes instead of string constants. But if this is not possible, + you can use the `-fwritable-strings' flag, which directs GCC to + handle string constants the same way most C compilers do. + `-traditional' also has this effect, among others. + + * `-2147483648' is positive. + + This is because 2147483648 cannot fit in the type `int', so + (following the ISO C rules) its data type is `unsigned long int'. + Negating this value yields 2147483648 again. + + * GCC does not substitute macro arguments when they appear inside of + string constants. For example, the following macro in GCC + + #define foo(a) "a" + + will produce output `"a"' regardless of what the argument A is. + + The `-traditional' option directs GCC to handle such cases (among + others) in the old-fashioned (non-ISO) fashion. + + * When you use `setjmp' and `longjmp', the only automatic variables + guaranteed to remain valid are those declared `volatile'. This is + a consequence of automatic register allocation. Consider this + function: + + jmp_buf j; + + foo () { - int 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 `'. 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 (`' on systems with ISO C headers) and not to + declare `time' if the system header files declare it, or failing + that to use `time_t' as the return type of `time'. + + * When compiling functions that return `float', PCC converts it to a + double. GCC actually returns a `float'. If you are concerned + with PCC compatibility, you should declare your functions to return + `double'; you might as well say what you mean. + + * When compiling functions that return structures or unions, GCC + output code normally uses a method different from that used on most + versions of Unix. As a result, code compiled with GCC cannot call + a structure-returning function compiled with PCC, and vice versa. + + The method used by GCC is as follows: a structure or union which is + 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or + union with any other size is stored into an address supplied by + the caller (usually in a special, fixed register, but on some + machines it is passed on the stack). The machine-description + macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE' tell GCC where + to pass this address. + + By contrast, PCC on most target machines returns structures and + unions of any size by copying the data into an area of static + storage, and then returning the address of that storage as if it + were a pointer value. The caller must copy the data from that + memory area to the place where the value is wanted. GCC does not + use this method because it is slower and nonreentrant. + + On some newer machines, PCC uses a reentrant convention for all + structure and union returning. GCC on most of these machines uses + a compatible convention when returning structures and unions in + memory, but still returns small structures and unions in registers. + + You can tell GCC to use a compatible convention for all structure + and union returning with the option `-fpcc-struct-return'. + + * GCC complains about program fragments such as `0x74ae-0x4000' + which appear to be two hexadecimal constants separated by the minus + operator. Actually, this string is a single "preprocessing token". + Each such token must correspond to one token in C. Since this + does not, GCC prints an error message. Although it may appear + obvious that what is meant is an operator and two values, the ISO + C standard specifically requires that this be treated as erroneous. + + A "preprocessing token" is a "preprocessing number" if it begins + with a digit and is followed by letters, underscores, digits, + periods and `e+', `e-', `E+', `E-', `p+', `p-', `P+', or `P-' + character sequences. (In strict C89 mode, the sequences `p+', + `p-', `P+' and `P-' cannot appear in preprocessing numbers.) + + To make the above program fragment valid, place whitespace in + front of the minus sign. This whitespace will end the + preprocessing number. + + +File: gcc.info, Node: Fixed Headers, Next: Standard Libraries, Prev: Incompatibilities, Up: Trouble + +10.6 Fixed Header Files +======================= + +GCC needs to install corrected versions of some system header files. +This is because most target systems have some header files that won't +work with GCC unless they are changed. Some have bugs, some are +incompatible with ISO C, and some depend on special features of other +compilers. + + Installing GCC automatically creates and installs the fixed header +files, by running a program called `fixincludes' (or for certain +targets an alternative such as `fixinc.svr4'). Normally, you don't +need to pay attention to this. But there are cases where it doesn't do +the right thing automatically. + + * If you update the system's header files, such as by installing a + new system version, the fixed header files of GCC are not + automatically updated. The easiest way to update them is to + reinstall GCC. (If you want to be clever, look in the makefile + and you can find a shortcut.) + + * On some systems, in particular SunOS 4, header file directories + contain machine-specific symbolic links in certain places. This + makes it possible to share most of the header files among hosts + running the same version of SunOS 4 on different machine models. + + The programs that fix the header files do not understand this + special way of using symbolic links; therefore, the directory of + fixed header files is good only for the machine model used to + build it. + + In SunOS 4, only programs that look inside the kernel will notice + the difference between machine models. Therefore, for most + purposes, you need not be concerned about this. + + It is possible to make separate sets of fixed header files for the + different machine models, and arrange a structure of symbolic + links so as to use the proper set, but you'll have to do this by + hand. + + * On Lynxos, GCC by default does not fix the header files. This is + because bugs in the shell cause the `fixincludes' script to fail. + + This means you will encounter problems due to bugs in the system + header files. It may be no comfort that they aren't GCC's fault, + but it does mean that there's nothing for us to do about them. + + +File: gcc.info, Node: Standard Libraries, Next: Disappointments, Prev: Fixed Headers, Up: Trouble + +10.7 Standard Libraries +======================= + +GCC by itself attempts to be a conforming freestanding implementation. +*Note Language Standards Supported by GCC: Standards, for details of +what this means. Beyond the library facilities required of such an +implementation, the rest of the C library is supplied by the vendor of +the operating system. If that C library doesn't conform to the C +standards, then your programs might get warnings (especially when using +`-Wall') that you don't expect. + + For example, the `sprintf' function on SunOS 4.1.3 returns `char *' +while the C standard says that `sprintf' returns an `int'. The +`fixincludes' program could make the prototype for this function match +the Standard, but that would be wrong, since the function will still +return `char *'. + + If you need a Standard compliant library, then you need to find one, +as GCC does not provide one. The GNU C library (called `glibc') +provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for +GNU/Linux and HURD-based GNU systems; no recent version of it supports +other systems, though some very old versions did. Version 2.2 of the +GNU C library includes nearly complete C99 support. You could also ask +your operating system vendor if newer libraries are available. + + +File: gcc.info, Node: Disappointments, Next: C++ Misunderstandings, Prev: Standard Libraries, Up: Trouble + +10.8 Disappointments and Misunderstandings +========================================== + +These problems are perhaps regrettable, but we don't know any practical +way around them. + + * Certain local variables aren't recognized by debuggers when you + compile with optimization. + + This occurs because sometimes GCC optimizes the variable out of + existence. There is no way to tell the debugger how to compute the + value such a variable "would have had", and it is not clear that + would be desirable anyway. So GCC simply does not mention the + eliminated variable when it writes debugging information. + + You have to expect a certain amount of disagreement between the + executable and your source code, when you use optimization. + + * Users often think it is a bug when GCC reports an error for code + like this: + + int foo (struct mumble *); + + struct mumble { ... }; + + int foo (struct mumble *x) + { ... } + + This code really is erroneous, because the scope of `struct + mumble' in the prototype is limited to the argument list + containing it. It does not refer to the `struct mumble' defined + with file scope immediately below--they are two unrelated types + with similar names in different scopes. + + But in the definition of `foo', the file-scope type is used + because that is available to be inherited. Thus, the definition + and the prototype do not match, and you get an error. + + This behavior may seem silly, but it's what the ISO standard + specifies. It is easy enough for you to make your code work by + moving the definition of `struct mumble' above the prototype. + It's not worth being incompatible with ISO C just to avoid an + error for the example shown above. + + * Accesses to bit-fields even in volatile objects works by accessing + larger objects, such as a byte or a word. You cannot rely on what + size of object is accessed in order to read or write the + bit-field; it may even vary for a given bit-field according to the + precise usage. + + If you care about controlling the amount of memory that is + accessed, use volatile but do not use bit-fields. + + * GCC comes with shell scripts to fix certain known problems in + system header files. They install corrected copies of various + header files in a special directory where only GCC will normally + look for them. The scripts adapt to various systems by searching + all the system header files for the problem cases that we know + about. + + If new system header files are installed, nothing automatically + arranges to update the corrected header files. You will have to + reinstall GCC to fix the new header files. More specifically, go + to the build directory and delete the files `stmp-fixinc' and + `stmp-headers', and the subdirectory `include'; then do `make + install' again. + + * On 68000 and x86 systems, for instance, you can get paradoxical + results if you test the precise values of floating point numbers. + For example, you can find that a floating point value which is not + a NaN is not equal to itself. This results from the fact that the + floating point registers hold a few more bits of precision than + fit in a `double' in memory. Compiled code moves values between + memory and floating point registers at its convenience, and moving + them into memory truncates them. + + You can partially avoid this problem by using the `-ffloat-store' + option (*note Optimize Options::). + + * On the MIPS, variable argument functions using `varargs.h' cannot + have a floating point value for the first argument. The reason + for this is that in the absence of a prototype in scope, if the + first argument is a floating point, it is passed in a floating + point register, rather than an integer register. + + If the code is rewritten to use the ISO standard `stdarg.h' method + of variable arguments, and the prototype is in scope at the time + of the call, everything will work fine. + + * On the H8/300 and H8/300H, variable argument functions must be + implemented using the ISO standard `stdarg.h' method of variable + arguments. Furthermore, calls to functions using `stdarg.h' + variable arguments must have a prototype for the called function + in scope at the time of the call. + + * On AIX and other platforms without weak symbol support, templates + need to be instantiated explicitly and symbols for static members + of templates will not be generated. + + +File: gcc.info, Node: C++ Misunderstandings, Next: Protoize Caveats, Prev: Disappointments, Up: Trouble -`-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 + + +File: gcc.info, Node: Static Definitions, Next: Temporaries, Up: C++ Misunderstandings + +10.9.1 Declare _and_ Define Static Members +------------------------------------------ + +When a class has static data members, it is not enough to _declare_ the +static member; you must also _define_ it. For example: + + class Foo + { + ... + void method(); + static int bar; + }; + + This declaration only establishes that the class `Foo' has an `int' +named `Foo::bar', and a member function named `Foo::method'. But you +still need to define _both_ `method' and `bar' elsewhere. According to +the ISO standard, you must supply an initializer in one (and only one) +source file, such as: + + int Foo::bar = 0; + + Other C++ compilers may not correctly implement the standard +behavior. As a result, when you switch to `g++' from one of these +compilers, you may discover that a program that appeared to work +correctly in fact does not conform to the standard: `g++' reports as +undefined symbols any static data members that lack definitions. + + +File: gcc.info, Node: Temporaries, Next: Copy Assignment, Prev: Static Definitions, Up: C++ Misunderstandings + +10.9.2 Temporaries May Vanish Before You Expect +----------------------------------------------- + +It is dangerous to use pointers or references to _portions_ of a +temporary object. The compiler may very well delete the object before +you expect it to, leaving a pointer to garbage. The most common place +where this problem crops up is in classes like string classes, +especially ones that define a conversion function to type `char *' or +`const char *'--which is one reason why the standard `string' class +requires you to call the `c_str' member function. However, any class +that returns a pointer to some internal structure is potentially +subject to this problem. + + For example, a program may use a function `strfunc' that returns +`string' objects, and another function `charfunc' that operates on +pointers to `char': + + string strfunc (); + void charfunc (const char *); + + void + f () + { + const char *p = strfunc().c_str(); + ... + charfunc (p); + ... + charfunc (p); + } + +In this situation, it may seem reasonable to save a pointer to the C +string returned by the `c_str' member function and use that rather than +call `c_str' repeatedly. However, the temporary string created by the +call to `strfunc' is destroyed after `p' is initialized, at which point +`p' is left pointing to freed memory. + + Code like this may run successfully under some other compilers, +particularly obsolete cfront-based compilers that delete temporaries +along with normal local variables. However, the GNU C++ behavior is +standard-conforming, so if your program depends on late destruction of +temporaries it is not portable. + + The safe way to write such code is to give the temporary a name, +which forces it to remain until the end of the scope of the name. For +example: + + string& tmp = strfunc (); + charfunc (tmp.c_str ()); + + +File: gcc.info, Node: Copy Assignment, Prev: Temporaries, Up: C++ Misunderstandings + +10.9.3 Implicit Copy-Assignment for Virtual Bases +------------------------------------------------- + +When a base class is virtual, only one subobject of the base class +belongs to each full object. Also, the constructors and destructors are +invoked only once, and called from the most-derived class. However, +such objects behave unspecified when being assigned. For example: + + struct Base{ + char *name; + Base(char *n) : name(strdup(n)){} + Base& operator= (const Base& other){ + free (name); + name = strdup (other.name); + } + }; + + struct A:virtual Base{ + int val; + A():Base("A"){} + }; + + struct B:virtual Base{ + int bval; + B():Base("B"){} + }; + + struct Derived:public A, public B{ + Derived():Base("Derived"){} + }; + + void func(Derived &d1, Derived &d2) + { + d1 = d2; + } + + The C++ standard specifies that `Base::Base' is only called once +when constructing or copy-constructing a Derived object. It is +unspecified whether `Base::operator=' is called more than once when the +implicit copy-assignment for Derived objects is invoked (as it is +inside `func' in the example). + + g++ implements the "intuitive" algorithm for copy-assignment: assign +all direct bases, then assign all members. In that algorithm, the +virtual base subobject can be encountered many times. In the example, +copying proceeds in the following order: `val', `name' (via `strdup'), +`bval', and `name' again. + + If application code relies on copy-assignment, a user-defined +copy-assignment operator removes any uncertainties. With such an +operator, the application can define whether and how the virtual base +subobject is assigned. + + +File: gcc.info, Node: Protoize Caveats, Next: Non-bugs, Prev: C++ Misunderstandings, Up: Trouble + +10.10 Caveats of using `protoize' +================================= + +The conversion programs `protoize' and `unprotoize' can sometimes +change a source file in a way that won't work unless you rearrange it. + + * `protoize' can insert references to a type name or type tag before + the definition, or in a file where they are not defined. + + If this happens, compiler error messages should show you where the + new references are, so fixing the file by hand is straightforward. + + * There are some C constructs which `protoize' cannot figure out. + For example, it can't determine argument types for declaring a + pointer-to-function variable; this you must do by hand. `protoize' + inserts a comment containing `???' each time it finds such a + variable; so you can find all such variables by searching for this + string. ISO C does not require declaring the argument types of + pointer-to-function types. + + * Using `unprotoize' can easily introduce bugs. If the program + relied on prototypes to bring about conversion of arguments, these + conversions will not take place in the program without prototypes. + One case in which you can be sure `unprotoize' is safe is when you + are removing prototypes that were made with `protoize'; if the + program worked before without any prototypes, it will work again + without them. + + You can find all the places where this problem might occur by + compiling the program with the `-Wconversion' option. It prints a + warning whenever an argument is converted. + + * Both conversion programs can be confused if there are macro calls + in and around the text to be converted. In other words, the + standard syntax for a declaration or definition must not result + from expanding a macro. This problem is inherent in the design of + C and cannot be fixed. If only a few functions have confusing + macro calls, you can easily convert them manually. + + * `protoize' cannot get the argument types for a function whose + definition was not actually compiled due to preprocessing + conditionals. When this happens, `protoize' changes nothing in + regard to such a function. `protoize' tries to detect such + instances and warn about them. + + You can generally work around this problem by using `protoize' step + by step, each time specifying a different set of `-D' options for + compilation, until all of the functions have been converted. + There is no automatic way to verify that you have got them all, + however. + + * Confusion may result if there is an occasion to convert a function + declaration or definition in a region of source code where there + is more than one formal parameter list present. Thus, attempts to + convert code containing multiple (conditionally compiled) versions + of a single function header (in the same vicinity) may not produce + the desired (or expected) results. + + If you plan on converting source files which contain such code, it + is recommended that you first make sure that each conditionally + compiled region of source code which contains an alternative + function header also contains at least one additional follower + token (past the final right parenthesis of the function header). + This should circumvent the problem. + + * `unprotoize' can become confused when trying to convert a function + definition or declaration which contains a declaration for a + pointer-to-function formal argument which has the same name as the + function being defined or declared. We recommend you avoid such + choices of formal parameter names. + + * You might also want to correct some of the indentation by hand and + break long lines. (The conversion programs don't write lines + longer than eighty characters in any case.) + + +File: gcc.info, Node: Non-bugs, Next: Warnings and Errors, Prev: Protoize Caveats, Up: Trouble + +10.11 Certain Changes We Don't Want to Make +=========================================== + +This section lists changes that people frequently request, but which we +do not make because we think GCC is better without them. + + * Checking the number and type of arguments to a function which has + an old-fashioned definition and no prototype. + + Such a feature would work only occasionally--only for calls that + appear in the same file as the called function, following the + definition. The only way to check all calls reliably is to add a + prototype for the function. But adding a prototype eliminates the + motivation for this feature. So the feature is not worthwhile. + + * Warning about using an expression whose type is signed as a shift + count. + + Shift count operands are probably signed more often than unsigned. + Warning about this would cause far more annoyance than good. + + * Warning about assigning a signed value to an unsigned variable. + + Such assignments must be very common; warning about them would + cause more annoyance than good. + + * Warning when a non-void function value is ignored. + + Coming as I do from a Lisp background, I balk at the idea that + there is something dangerous about discarding a value. There are + functions that return values which some callers may find useful; + it makes no sense to clutter the program with a cast to `void' + whenever the value isn't useful. + + * Making `-fshort-enums' the default. + + This would cause storage layout to be incompatible with most other + C compilers. And it doesn't seem very important, given that you + can get the same result in other ways. The case where it matters + most is when the enumeration-valued object is inside a structure, + and in that case you can specify a field width explicitly. + + * Making bit-fields unsigned by default on particular machines where + "the ABI standard" says to do so. + + The ISO C standard leaves it up to the implementation whether a + bit-field declared plain `int' is signed or not. This in effect + creates two alternative dialects of C. + + The GNU C compiler supports both dialects; you can specify the + signed dialect with `-fsigned-bitfields' and the unsigned dialect + with `-funsigned-bitfields'. However, this leaves open the + question of which dialect to use by default. + + Currently, the preferred dialect makes plain bit-fields signed, + because this is simplest. Since `int' is the same as `signed int' + in every other context, it is cleanest for them to be the same in + bit-fields as well. + + Some computer manufacturers have published Application Binary + Interface standards which specify that plain bit-fields should be + unsigned. It is a mistake, however, to say anything about this + issue in an ABI. This is because the handling of plain bit-fields + distinguishes two dialects of C. Both dialects are meaningful on + every type of machine. Whether a particular object file was + compiled using signed bit-fields or unsigned is of no concern to + other object files, even if they access the same bit-fields in the + same data structures. + + A given program is written in one or the other of these two + dialects. The program stands a chance to work on most any machine + if it is compiled with the proper dialect. It is unlikely to work + at all if compiled with the wrong dialect. + + Many users appreciate the GNU C compiler because it provides an + environment that is uniform across machines. These users would be + inconvenienced if the compiler treated plain bit-fields + differently on certain machines. + + Occasionally users write programs intended only for a particular + machine type. On these occasions, the users would benefit if the + GNU C compiler were to support by default the same dialect as the + other compilers on that machine. But such applications are rare. + And users writing a program to run on more than one type of + machine cannot possibly benefit from this kind of compatibility. + + This is why GCC does and will treat plain bit-fields in the same + fashion on all types of machines (by default). + + There are some arguments for making bit-fields unsigned by default + on all machines. If, for example, this becomes a universal de + facto standard, it would make sense for GCC to go along with it. + This is something to be considered in the future. + + (Of course, users strongly concerned about portability should + indicate explicitly in each bit-field whether it is signed or not. + In this way, they write programs which have the same meaning in + both C dialects.) + + * Undefining `__STDC__' when `-ansi' is not used. + + Currently, GCC defines `__STDC__' as long as you don't use + `-traditional'. This provides good results in practice. + + Programmers normally use conditionals on `__STDC__' to ask whether + it is safe to use certain features of ISO C, such as function + prototypes or ISO token concatenation. Since plain `gcc' supports + all the features of ISO C, the correct answer to these questions is + "yes". + + Some users try to use `__STDC__' to check for the availability of + certain library facilities. This is actually incorrect usage in + an ISO C program, because the ISO C standard says that a conforming + freestanding implementation should define `__STDC__' even though it + does not have the library facilities. `gcc -ansi -pedantic' is a + conforming freestanding implementation, and it is therefore + required to define `__STDC__', even though it does not come with + an ISO C library. + + Sometimes people say that defining `__STDC__' in a compiler that + does not completely conform to the ISO C standard somehow violates + the standard. This is illogical. The standard is a standard for + compilers that claim to support ISO C, such as `gcc -ansi'--not + for other compilers such as plain `gcc'. Whatever the ISO C + standard says is relevant to the design of plain `gcc' without + `-ansi' only for pragmatic reasons, not as a requirement. + + GCC normally defines `__STDC__' to be 1, and in addition defines + `__STRICT_ANSI__' if you specify the `-ansi' option, or a `-std' + option for strict conformance to some version of ISO C. On some + hosts, system include files use a different convention, where + `__STDC__' is normally 0, but is 1 if the user specifies strict + conformance to the C Standard. GCC follows the host convention + when processing system include files, but when processing user + files it follows the usual GNU C convention. + + * Undefining `__STDC__' in C++. + + Programs written to compile with C++-to-C translators get the + value of `__STDC__' that goes with the C compiler that is + subsequently used. These programs must test `__STDC__' to + determine what kind of C preprocessor that compiler uses: whether + they should concatenate tokens in the ISO C fashion or in the + traditional fashion. + + These programs work properly with GNU C++ if `__STDC__' is defined. + They would not work otherwise. + + In addition, many header files are written to provide prototypes + in ISO C but not in traditional C. Many of these header files can + work without change in C++ provided `__STDC__' is defined. If + `__STDC__' is not defined, they will all fail, and will all need + to be changed to test explicitly for C++ as well. + + * Deleting "empty" loops. + + Historically, GCC has not deleted "empty" loops under the + assumption that the most likely reason you would put one in a + program is to have a delay, so deleting them will not make real + programs run any faster. + + However, the rationale here is that optimization of a nonempty loop + cannot produce an empty one, which holds for C but is not always + the case for C++. + + Moreover, with `-funroll-loops' small "empty" loops are already + removed, so the current behavior is both sub-optimal and + inconsistent and will change in the future. + + * Making side effects happen in the same order as in some other + compiler. + + It is never safe to depend on the order of evaluation of side + effects. For example, a function call like this may very well + behave differently from one compiler to another: + + void func (int, int); + + int i = 2; + func (i++, i++); + + There is no guarantee (in either the C or the C++ standard language + definitions) that the increments will be evaluated in any + particular order. Either increment might happen first. `func' + might get the arguments `2, 3', or it might get `3, 2', or even + `2, 2'. + + * Not allowing structures with volatile fields in registers. + + Strictly speaking, there is no prohibition in the ISO C standard + against allowing structures with volatile fields in registers, but + it does not seem to make any sense and is probably not what you + wanted to do. So the compiler will give an error message in this + case. + + * Making certain warnings into errors by default. + + Some ISO C testsuites report failure when the compiler does not + produce an error message for a certain program. + + ISO C requires a "diagnostic" message for certain kinds of invalid + programs, but a warning is defined by GCC to count as a + diagnostic. If GCC produces a warning but not an error, that is + correct ISO C support. If test suites call this "failure", they + should be run with the GCC option `-pedantic-errors', which will + turn these warnings into errors. + + + +File: gcc.info, Node: Warnings and Errors, Prev: Non-bugs, Up: Trouble + +10.12 Warning Messages and Error Messages +========================================= + +The GNU compiler can produce two kinds of diagnostics: errors and +warnings. Each kind has a different purpose: + + "Errors" report problems that make it impossible to compile your + program. GCC reports errors with the source file name and line + number where the problem is apparent. + + "Warnings" report other unusual conditions in your code that _may_ + indicate a problem, although compilation can (and does) proceed. + Warning messages also report the source file name and line number, + but include the text `warning:' to distinguish them from error + messages. + + Warnings may indicate danger points where you should check to make +sure that your program really does what you intend; or the use of +obsolete features; or the use of nonstandard features of GNU C or C++. +Many warnings are issued only if you ask for them, with one of the `-W' +options (for instance, `-Wall' requests a variety of useful warnings). + + GCC always tries to compile your program if possible; it never +gratuitously rejects a program whose meaning is clear merely because +(for instance) it fails to conform to a standard. In some cases, +however, the C and C++ standards specify that certain extensions are +forbidden, and a diagnostic _must_ be issued by a conforming compiler. +The `-pedantic' option tells GCC to issue warnings in such cases; +`-pedantic-errors' says to make them errors instead. This does not +mean that _all_ non-ISO constructs get warnings or errors. + + *Note Options to Request or Suppress Warnings: Warning Options, for +more detail on these and related command-line options. + + +File: gcc.info, Node: Bugs, Next: Service, Prev: Trouble, Up: Top + +11 Reporting Bugs +***************** + +Your bug reports play an essential role in making GCC reliable. + + When you encounter a problem, the first thing to do is to see if it +is already known. *Note Trouble::. If it isn't known, then you should +report the problem. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. (If it does not, look in the service directory; see +*note Service::.) In any case, the principal function of a bug report +is to help the entire community by making the next version of GCC work +better. Bug reports are your contribution to the maintenance of GCC. + + Since the maintainers are very overloaded, we cannot respond to every +bug report. However, if the bug has not been fixed, we are likely to +send you a patch and ask you to tell us whether it works. + + In order for a bug report to serve its purpose, you must include the +information that makes for fixing the bug. + +* Menu: + +* Criteria: Bug Criteria. Have you really found a bug? +* Where: Bug Lists. Where to send your bug report. +* Reporting: Bug Reporting. How to report a bug effectively. +* GNATS: gccbug. You can use a bug reporting tool. +* Known: Trouble. Known problems. +* Help: Service. Where to ask for help. + + +File: gcc.info, Node: Bug Criteria, Next: Bug Lists, Up: Bugs + +11.1 Have You Found a Bug? +========================== + +If you are not sure whether you have found a bug, here are some +guidelines: + + * If the compiler gets a fatal signal, for any input whatever, that + is a compiler bug. Reliable compilers never crash. + + * If the compiler produces invalid assembly code, for any input + whatever (except an `asm' statement), that is a compiler bug, + unless the compiler reports errors (not just warnings) which would + ordinarily prevent the assembler from being run. + + * If the compiler produces valid assembly code that does not + correctly execute the input source code, that is a compiler bug. + + However, you must double-check to make sure, because you may have + run into an incompatibility between GNU C and traditional C (*note + Incompatibilities::). These incompatibilities might be considered + bugs, but they are inescapable consequences of valuable features. + + Or you may have a program whose behavior is undefined, which + happened by chance to give the desired results with another C or + C++ compiler. + + For example, in many nonoptimizing compilers, you can write `x;' + at the end of a function instead of `return x;', with the same + results. But the value of the function is undefined if `return' + is omitted; it is not a bug when GCC produces different results. + + Problems often result from expressions with two increment + operators, as in `f (*p++, *p++)'. Your previous compiler might + have interpreted that expression the way you intended; GCC might + interpret it another way. Neither compiler is wrong. The bug is + in your code. + + After you have localized the error to a single source line, it + should be easy to check for these things. If your program is + correct and well defined, you have found a compiler bug. + + * If the compiler produces an error message for valid input, that is + a compiler bug. + + * If the compiler does not produce an error message for invalid + input, that is a compiler bug. However, you should note that your + idea of "invalid input" might be my idea of "an extension" or + "support for traditional practice". + + * If you are an experienced user of one of the languages GCC + supports, your suggestions for improvement of GCC are welcome in + any case. + + +File: gcc.info, Node: Bug Lists, Next: Bug Reporting, Prev: Bug Criteria, Up: Bugs + +11.2 Where to Report Bugs +========================= + +Send bug reports for the GNU Compiler Collection to +. In accordance with the GNU-wide convention, in +which bug reports for tool "foo" are sent to `bug-foo@gnu.org', the +address may also be used; it will forward to the +address given above. + + Please read `http://gcc.gnu.org/bugs.html' for additional and/or +more up-to-date bug reporting instructions before you post a bug report. + + +File: gcc.info, Node: Bug Reporting, Next: gccbug, Prev: Bug Lists, Up: Bugs + +11.3 How to Report Bugs +======================= + +The fundamental principle of reporting bugs usefully is this: *report +all the facts*. If you are not sure whether to state a fact or leave +it out, state it! + + Often people omit facts because they think they know what causes the +problem and they conclude that some details don't matter. Thus, you +might assume that the name of the variable you use in an example does +not matter. Well, probably it doesn't, but one cannot be sure. +Perhaps the bug is a stray memory reference which happens to fetch from +the location where that name is stored in memory; perhaps, if the name +were different, the contents of that location would fool the compiler +into doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. + + Keep in mind that the purpose of a bug report is to enable someone to +fix the bug if it is not known. It isn't very important what happens if +the bug is already known. Therefore, always write your bug reports on +the assumption that the bug is not known. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. You +might as well expedite matters by sending them to begin with. + + Try to make your bug report self-contained. If we have to ask you +for more information, it is best if you include all the previous +information in your response, as well as the information that was +missing. + + Please report each bug in a separate message. This makes it easier +for us to track which bugs have been fixed and to forward your bugs +reports to the appropriate maintainer. + + To enable someone to investigate the bug, you should include all +these things: + + * The version of GCC. You can get this by running it with the `-v' + option. + + Without this, we won't know whether there is any point in looking + for the bug in the current version of GCC. + + * A complete input file that will reproduce the bug. If the bug is + in the C preprocessor, send a source file and any header files + that it requires. If the bug is in the compiler proper (`cc1'), + send the preprocessor output generated by adding `-save-temps' to + the compilation command (*note Debugging Options::). When you do + this, use the same `-I', `-D' or `-U' options that you used in + actual compilation. Then send the INPUT.i or INPUT.ii files + generated. + + A single statement is not enough of an example. In order to + compile it, it must be embedded in a complete file of compiler + input; and the bug might depend on the details of how this is done. + + Without a real example one can compile, all anyone can do about + your bug report is wish you luck. It would be futile to try to + guess how to provoke the bug. For example, bugs in register + allocation and reloading frequently depend on every little detail + of the function they happen in. + + Even if the input file that fails comes from a GNU program, you + should still send the complete test case. Don't ask the GCC + maintainers to do the extra work of obtaining the program in + question--they are all overworked as it is. Also, the problem may + depend on what is in the header files on your system; it is + unreliable for the GCC maintainers to try the problem with the + header files available to them. By sending CPP output, you can + eliminate this source of uncertainty and save us a certain + percentage of wild goose chases. + + * The command arguments you gave GCC to compile that example and + observe the bug. For example, did you use `-O'? To guarantee you + won't omit something important, list all the options. + + If we were to try to guess the arguments, we would probably guess + wrong and then we would not encounter the bug. + + * The type of machine you are using, and the operating system name + and version number. + + * The operands you gave to the `configure' command when you installed + the compiler. + + * A complete list of any modifications you have made to the compiler + source. (We don't promise to investigate the bug unless it + happens in an unmodified compiler. But if you've made + modifications and don't tell us, then you are sending us on a wild + goose chase.) + + Be precise about these changes. A description in English is not + enough--send a context diff for them. + + Adding files of your own (such as a machine description for a + machine we don't support) is a modification of the compiler source. + + * Details of any other deviations from the standard procedure for + installing GCC. + + * A description of what behavior you observe that you believe is + incorrect. For example, "The compiler gets a fatal signal," or, + "The assembler instruction at line 208 in the output is incorrect." + + Of course, if the bug is that the compiler gets a fatal signal, + then one can't miss it. But if the bug is incorrect output, the + maintainer might not notice unless it is glaringly wrong. None of + us has time to study all the assembler code from a 50-line C + program just on the chance that one instruction might be wrong. + We need _you_ to do this part! + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of the compiler is out of synch, or you have + encountered a bug in the C library on your system. (This has + happened!) Your copy might crash and the copy here would not. If + you said to expect a crash, then when the compiler here fails to + crash, we would know that the bug was not happening. If you don't + say to expect a crash, then we would not know whether the bug was + happening. We would not be able to draw any conclusion from our + observations. + + If the problem is a diagnostic when compiling GCC with some other + compiler, say whether it is a warning or an error. + + Often the observed symptom is incorrect output when your program + is run. Sad to say, this is not enough information unless the + program is short and simple. None of us has time to study a large + program to figure out how it would work if compiled correctly, + much less which line of it was compiled wrong. So you will have + to do that. Tell us which source line it is, and what incorrect + result happens when that line is executed. A person who + understands the program can find this as easily as finding a bug + in the program itself. + + * If you send examples of assembler code output from GCC, please use + `-g' when you make them. The debugging information includes + source line numbers which are essential for correlating the output + with the input. + + * If you wish to mention something in the GCC source, refer to it by + context, not by line number. + + The line numbers in the development sources don't match those in + your sources. Your line numbers would convey no useful + information to the maintainers. + + * Additional information from a debugger might enable someone to + find a problem on a machine which he does not have available. + However, you need to think when you collect this information if + you want it to have any chance of being useful. + + For example, many people send just a backtrace, but that is never + useful by itself. A simple backtrace with arguments conveys little + about GCC because the compiler is largely data-driven; the same + functions are called over and over for different RTL insns, doing + different things depending on the details of the insn. + + Most of the arguments listed in the backtrace are useless because + they are pointers to RTL list structure. The numeric values of the + pointers, which the debugger prints in the backtrace, have no + significance whatever; all that matters is the contents of the + objects they point to (and most of the contents are other such + pointers). + + In addition, most compiler passes consist of one or more loops that + scan the RTL insn sequence. The most vital piece of information + about such a loop--which insn it has reached--is usually in a + local variable, not in an argument. + + What you need to provide in addition to a backtrace are the values + of the local variables for several stack frames up. When a local + variable or an argument is an RTX, first print its value and then + use the GDB command `pr' to print the RTL expression that it points + to. (If GDB doesn't run on your machine, use your debugger to call + the function `debug_rtx' with the RTX as an argument.) In + general, whenever a variable is a pointer, its value is no use + without the data it points to. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. You might as well save your time for something else. + + Of course, if you can find a simpler example to report _instead_ of + the original one, that is a convenience. Errors in the output + will be easier to spot, running under the debugger will take less + time, etc. Most GCC bugs involve just one function, so the most + straightforward way to simplify an example is to delete all the + function definitions except the one where the bug occurs. Those + earlier in the file may be replaced by external declarations if + the crucial function depends on them. (Exception: inline + functions may affect compilation of functions defined later in the + file.) + + However, simplification is not vital; if you don't want to do this, + report the bug anyway and send the entire test case you used. + + * In particular, some people insert conditionals `#ifdef BUG' around + a statement which, if removed, makes the bug not happen. These + are just clutter; we won't pay any attention to them anyway. + Besides, you should send us cpp output, and that can't have + conditionals. + + * A patch for the bug. + + A patch for the bug is useful if it is a good one. But don't omit + the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems + with your patch and decide to fix the problem another way, or we + might not understand it at all. + + Sometimes with a program as complicated as GCC it is very hard to + construct an example that will make the program follow a certain + path through the code. If you don't send the example, we won't be + able to construct one, so we won't be able to verify that the bug + is fixed. + + And if we can't understand what bug you are trying to fix, or why + your patch should be an improvement, we won't install it. A test + case will help us to understand. + + See `http://gcc.gnu.org/contribute.html' for guidelines on how to + make it easy for us to understand and install your patches. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even I can't guess right about + such things without first using the debugger to find the facts. + + * A core dump file. + + We have no way of examining a core dump for your type of machine + unless we have an identical system--and if we do have one, we + should be able to reproduce the crash ourselves. + + +File: gcc.info, Node: gccbug, Prev: Bug Reporting, Up: Bugs + +11.4 The gccbug script +====================== + +To simplify creation of bug reports, and to allow better tracking of +reports, we use the GNATS bug tracking system. Part of that system is +the `gccbug' script. This is a Unix shell script, so you need a shell +to run it. It is normally installed in the same directory where `gcc' +is installed. + + The gccbug script is derived from send-pr, *note Creating new +Problem Reports: (send-pr)using send-pr. When invoked, it starts a +text editor so you can fill out the various fields of the report. When +the you quit the editor, the report is automatically send to the bug +reporting address. + + A number of fields in this bug report form are specific to GCC, and +are explained at `http://gcc.gnu.org/gnats.html'. + + +File: gcc.info, Node: Service, Next: Contributing, Prev: Bugs, Up: Top + +12 How To Get Help with GCC +*************************** + +If you need help installing, using or changing GCC, there are two ways +to find it: + + * Send a message to a suitable network mailing list. First try + (for help installing or using GCC), and if + that brings no response, try . For help changing + GCC, ask . If you think you have found a bug in + GCC, please report it following the instructions at *note Bug + Reporting::. + + * Look in the service directory for someone who might help you for a + fee. The service directory is found at + `http://www.gnu.org/prep/service.html'. + + +File: gcc.info, Node: Contributing, Next: VMS, Prev: Service, Up: Top + +13 Contributing to GCC Development +********************************** + +If you would like to help pretest GCC releases to assure they work well, +our current development sources are available by CVS (see +`http://gcc.gnu.org/cvs.html'). Source and binary snapshots are also +available for FTP; see `http://gcc.gnu.org/snapshots.html'. + + If you would like to work on improvements to GCC, please read the +advice at these URLs: + + `http://gcc.gnu.org/contribute.html' + `http://gcc.gnu.org/contributewhy.html' + +for information on how to make useful contributions and avoid +duplication of effort. Suggested projects are listed at +`http://gcc.gnu.org/projects/'. + + +File: gcc.info, Node: VMS, Next: Funding, Prev: Contributing, Up: Top + +14 Using GCC on VMS +******************* + +Here is how to use GCC on VMS. + +* Menu: + +* Include Files and VMS:: Where the preprocessor looks for the include files. +* Global Declarations:: How to do globaldef, globalref and globalvalue with + GCC. +* VMS Misc:: Misc information. + + +File: gcc.info, Node: Include Files and VMS, Next: Global Declarations, Up: VMS + +14.1 Include Files and VMS +========================== + +Due to the differences between the filesystems of Unix and VMS, GCC +attempts to translate file names in `#include' into names that VMS will +understand. The basic strategy is to prepend a prefix to the +specification of the include file, convert the whole filename to a VMS +filename, and then try to open the file. GCC tries various prefixes +one by one until one of them succeeds: + + 1. The first prefix is the `GNU_CC_INCLUDE:' logical name: this is + where GNU C header files are traditionally stored. If you wish to + store header files in non-standard locations, then you can assign + the logical `GNU_CC_INCLUDE' to be a search list, where each + element of the list is suitable for use with a rooted logical. + + 2. The next prefix tried is `SYS$SYSROOT:[SYSLIB.]'. This is where + VAX-C header files are traditionally stored. + + 3. If the include file specification by itself is a valid VMS + filename, the preprocessor then uses this name with no prefix in + an attempt to open the include file. + + 4. If the file specification is not a valid VMS filename (i.e. does + not contain a device or a directory specifier, and contains a `/' + character), the preprocessor tries to convert it from Unix syntax + to VMS syntax. + + Conversion works like this: the first directory name becomes a + device, and the rest of the directories are converted into + VMS-format directory names. For example, the name `X11/foobar.h' + is translated to `X11:[000000]foobar.h' or `X11:foobar.h', + whichever one can be opened. This strategy allows you to assign a + logical name to point to the actual location of the header files. + + 5. If none of these strategies succeeds, the `#include' fails. + + Include directives of the form: + + #include foobar + +are a common source of incompatibility between VAX-C and GCC. VAX-C +treats this much like a standard `#include ' 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 + + 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 + +This will work, as long as the name doesn't conflict with anything else +in the program. + + Another source of incompatibility is that VAX-C assumes that: + + #include "foobar" + +is actually asking for the file `foobar.h'. GCC does not make this +assumption, and instead takes what you ask for literally; it tries to +read the file `foobar'. The best way to avoid this problem is to +always specify the desired file extension in your include directives. + + GCC for VMS is distributed with a set of include files that is +sufficient to compile most general purpose programs. Even though the +GCC distribution does not contain header files to define constants and +structures for some VMS system-specific functions, there is no reason +why you cannot use GCC with any of these functions. You first may have +to generate or create header files, either by using the public domain +utility `UNSDL' (which can be found on a DECUS tape), or by extracting +the relevant modules from one of the system macro libraries, and using +an editor to construct a C header file. + + A `#include' file name cannot contain a DECNET node name. The +preprocessor reports an I/O error if you attempt to use a node name, +whether explicitly, or implicitly via a logical name. + + +File: gcc.info, Node: Global Declarations, Next: VMS Misc, Prev: Include Files and VMS, Up: VMS + +14.2 Global Declarations and VMS +================================ + +GCC does not provide the `globalref', `globaldef' and `globalvalue' +keywords of VAX-C. You can get the same effect with an obscure feature +of GAS, the GNU assembler. (This requires GAS version 1.39 or later.) +The following macros allow you to use this feature in a fairly natural +way: + + #ifdef __GNUC__ + #define GLOBALREF(TYPE,NAME) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) + #define GLOBALDEF(TYPE,NAME,VALUE) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ + = VALUE + #define GLOBALVALUEREF(TYPE,NAME) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) + #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ + = {VALUE} + #else + #define GLOBALREF(TYPE,NAME) \ + globalref TYPE NAME + #define GLOBALDEF(TYPE,NAME,VALUE) \ + globaldef TYPE NAME = VALUE + #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + globalvalue TYPE NAME = VALUE + #define GLOBALVALUEREF(TYPE,NAME) \ + globalvalue TYPE NAME + #endif + +(The `_$$PsectAttributes_GLOBALSYMBOL' prefix at the start of the name +is removed by the assembler, after it has modified the attributes of +the symbol). These macros are provided in the VMS binaries +distribution in a header file `GNU_HACKS.H'. An example of the usage +is: + + GLOBALREF (int, ijk); + GLOBALDEF (int, jkl, 0); + + The macros `GLOBALREF' and `GLOBALDEF' cannot be used +straightforwardly for arrays, since there is no way to insert the array +dimension into the declaration at the right place. However, you can +declare an array with these macros if you first define a typedef for the +array type, like this: + + typedef int intvector[10]; + GLOBALREF (intvector, foo); + + Array and structure initializers will also break the macros; you can +define the initializer to be a macro of its own, or you can expand the +`GLOBALDEF' macro by hand. You may find a case where you wish to use +the `GLOBALDEF' macro with a large array, but you are not interested in +explicitly initializing each element of the array. In such cases you +can use an initializer like: `{0,}', which will initialize the entire +array to `0'. + + A shortcoming of this implementation is that a variable declared with +`GLOBALVALUEREF' or `GLOBALVALUEDEF' is always an array. For example, +the declaration: + + GLOBALVALUEREF(int, ijk); + +declares the variable `ijk' as an array of type `int [1]'. This is +done because a globalvalue is actually a constant; its "value" is what +the linker would normally consider an address. That is not how an +integer value works in C, but it is how an array works. So treating +the symbol as an array name gives consistent results--with the +exception that the value seems to have the wrong type. *Don't try to +access an element of the array.* It doesn't have any elements. The +array "address" may not be the address of actual storage. + + The fact that the symbol is an array may lead to warnings where the +variable is used. Insert type casts to avoid the warnings. Here is an +example; it takes advantage of the ISO C feature allowing macros that +expand to use the same name as the macro itself. + + GLOBALVALUEREF (int, ss$_normal); + GLOBALVALUEDEF (int, xyzzy,123); + #ifdef __GNUC__ + #define ss$_normal ((int) ss$_normal) + #define xyzzy ((int) xyzzy) + #endif + + Don't use `globaldef' or `globalref' with a variable whose type is +an enumeration type; this is not implemented. Instead, make the +variable an integer, and use a `globalvaluedef' for each of the +enumeration values. An example of this would be: + + #ifdef __GNUC__ + GLOBALDEF (int, color, 0); + GLOBALVALUEDEF (int, RED, 0); + GLOBALVALUEDEF (int, BLUE, 1); + GLOBALVALUEDEF (int, GREEN, 3); + #else + enum globaldef color {RED, BLUE, GREEN = 3}; + #endif + + +File: gcc.info, Node: VMS Misc, Prev: Global Declarations, Up: VMS + +14.3 Other VMS Issues +===================== + +GCC automatically arranges for `main' to return 1 by default if you +fail to specify an explicit return value. This will be interpreted by +VMS as a status code indicating a normal successful completion. +Version 1 of GCC did not provide this default. + + GCC on VMS works only with the GNU assembler, GAS. You need version +1.37 or later of GAS in order to produce value debugging information for +the VMS debugger. Use the ordinary VMS linker with the object files +produced by GAS. + + Under previous versions of GCC, the generated code would occasionally +give strange results when linked to the sharable `VAXCRTL' library. +Now this should work. + + A caveat for use of `const' global variables: the `const' modifier +must be specified in every external declaration of the variable in all +of the source files that use that variable. Otherwise the linker will +issue warnings about conflicting attributes for the variable. Your +program will still work despite the warnings, but the variable will be +placed in writable storage. + + Although the VMS linker does distinguish between upper and lower case +letters in global symbols, most VMS compilers convert all such symbols +into upper case and most run-time library routines also have upper case +names. To be able to reliably call such routines, GCC (by means of the +assembler GAS) converts global symbols into upper case like other VMS +compilers. However, since the usual practice in C is to distinguish +case, GCC (via GAS) tries to preserve usual C behavior by augmenting +each name that is not all lower case. This means truncating the name +to at most 23 characters and then adding more characters at the end +which encode the case pattern of those 23. Names which contain at +least one dollar sign are an exception; they are converted directly into +upper case without augmentation. + + Name augmentation yields bad results for programs that use +precompiled libraries (such as Xlib) which were generated by another +compiler. You can use the compiler option `/NOCASE_HACK' to inhibit +augmentation; it makes external C functions and variables +case-independent as is usual on VMS. Alternatively, you could write +all references to the functions and variables in such libraries using +lower case; this will work on VMS, but is not portable to other +systems. The compiler option `/NAMES' also provides control over +global name handling. + + Function and variable names are handled somewhat differently with +G++. The GNU C++ compiler performs "name mangling" on function names, +which means that it adds information to the function name to describe +the data types of the arguments that the function takes. One result of +this is that the name of a function can become very long. Since the +VMS linker only recognizes the first 31 characters in a name, special +action is taken to ensure that each function and variable has a unique +name that can be represented in 31 characters. + + If the name (plus a name augmentation, if required) is less than 32 +characters in length, then no special action is performed. If the name +is longer than 31 characters, the assembler (GAS) will generate a hash +string based upon the function name, truncate the function name to 23 +characters, and append the hash string to the truncated name. If the +`/VERBOSE' compiler option is used, the assembler will print both the +full and truncated names of each symbol that is truncated. + + The `/NOCASE_HACK' compiler option should not be used when you are +compiling programs that use libg++. libg++ has several instances of +objects (i.e. `Filebuf' and `filebuf') which become indistinguishable +in a case-insensitive environment. This leads to cases where you need +to inhibit augmentation selectively (if you were using libg++ and Xlib +in the same program, for example). There is no special feature for +doing this, but you can get the result by defining a macro for each +mixed case symbol for which you wish to inhibit augmentation. The +macro should expand into the lower case equivalent of itself. For +example: + + #define StuDlyCapS studlycaps + + These macro definitions can be placed in a header file to minimize +the number of changes to your source code. + + +File: gcc.info, Node: Funding, Next: GNU Project, Prev: VMS, Up: Top + +Funding Free Software +********************* + +If you want to have more free software a few years from now, it makes +sense for you to help encourage people to contribute funds for its +development. The most effective approach known is to encourage +commercial redistributors to donate. + + Users of free software systems can boost the pace of development by +encouraging for-a-fee distributors to donate part of their selling price +to free software developers--the Free Software Foundation, and others. + + The way to convince distributors to do this is to demand it and +expect it from them. So when you compare distributors, judge them +partly by how much they give to free software development. Show +distributors they must compete to be the one who gives the most. + + To make this approach work, you must insist on numbers that you can +compare, such as, "We will donate ten dollars to the Frobnitz project +for each disk sold." Don't be satisfied with a vague promise, such as +"A portion of the profits are donated," since it doesn't give a basis +for comparison. + + Even a precise fraction "of the profits from this disk" is not very +meaningful, since creative accounting and unrelated business decisions +can greatly alter what fraction of the sales price counts as profit. +If the price you pay is $50, ten percent of the profit is probably less +than a dollar; it might be a few cents, or nothing at all. + + Some redistributors do development work themselves. This is useful +too; but to keep everyone honest, you need to inquire how much they do, +and what kind. Some kinds of development make much more long-term +difference than others. For example, maintaining a separate version of +a program contributes very little; maintaining the standard version of a +program for the whole community contributes much. Easy new ports +contribute little, since someone else would surely do them; difficult +ports such as adding a new CPU to the GNU Compiler Collection +contribute more; major new features or packages contribute the most. + + By establishing the idea that supporting further development is "the +proper thing to do" when distributing free software for a fee, we can +assure a steady flow of resources into making more free software. + + Copyright (C) 1994 Free Software Foundation, Inc. + Verbatim copying and redistribution of this section is permitted + without royalty; alteration is not permitted. + + +File: gcc.info, Node: GNU Project, Next: Copying, Prev: Funding, Up: Top + +The GNU Project and GNU/Linux +***************************** + +The GNU Project was launched in 1984 to develop a complete Unix-like +operating system which is free software: the GNU system. (GNU is a +recursive acronym for "GNU's Not Unix"; it is pronounced "guh-NEW".) +Variants of the GNU operating system, which use the kernel Linux, are +now widely used; though these systems are often referred to as "Linux", +they are more accurately called GNU/Linux systems. + + For more information, see: + `http://www.gnu.org/' + `http://www.gnu.org/gnu/linux-and-gnu.html' + + +File: gcc.info, Node: Copying, Next: GNU Free Documentation License, Prev: GNU Project, Up: Top + +GNU GENERAL PUBLIC LICENSE +************************** + + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +Preamble +======== + +The licenses for most software are designed to take away your freedom +to share and change it. By contrast, the GNU General Public License is +intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it in +new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, +and (2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + 0. This License applies to any program or other work which contains a + notice placed by the copyright holder saying it may be distributed + under the terms of this General Public License. The "Program", + below, refers to any such program or work, and a "work based on + the Program" means either the Program or any derivative work under + copyright law: that is to say, a work containing the Program or a + portion of it, either verbatim or with modifications and/or + translated into another language. (Hereinafter, translation is + included without limitation in the term "modification".) Each + licensee is addressed as "you". + + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running the Program is not restricted, and the output from the + Program is covered only if its contents constitute a work based on + the Program (independent of having been made by running the + Program). Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's + source code as you receive it, in any medium, provided that you + conspicuously and appropriately publish on each copy an appropriate + copyright notice and disclaimer of warranty; keep intact all the + notices that refer to this License and to the absence of any + warranty; and give any other recipients of the Program a copy of + this License along with the Program. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange + for a fee. + + 2. You may modify your copy or copies of the Program or any portion + of it, thus forming a work based on the Program, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b. You must cause any work that you distribute or publish, that + in whole or in part contains or is derived from the Program + or any part thereof, to be licensed as a whole at no charge + to all third parties under the terms of this License. + + c. If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display + an announcement including an appropriate copyright notice and + a notice that there is no warranty (or else, saying that you + provide a warranty) and that users may redistribute the + program under these conditions, and telling the user how to + view a copy of this License. (Exception: if the Program + itself is interactive but does not normally print such an + announcement, your work based on the Program is not required + to print an announcement.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Program, and can be reasonably considered independent and separate + works in themselves, then this License, and its terms, do not + apply to those sections when you distribute them as separate + works. But when you distribute the same sections as part of a + whole which is a work based on the Program, the distribution of + the whole must be on the terms of this License, whose permissions + for other licensees extend to the entire whole, and thus to each + and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Program. + + In addition, mere aggregation of another work not based on the + Program with the Program (or with a work based on the Program) on + a volume of a storage or distribution medium does not bring the + other work under the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, + under Section 2) in object code or executable form under the terms + of Sections 1 and 2 above provided that you also do one of the + following: + + a. Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of + Sections 1 and 2 above on a medium customarily used for + software interchange; or, + + b. Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a + medium customarily used for software interchange; or, + + c. Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with + such an offer, in accord with Subsection b above.) + + The source code for a work means the preferred form of the work for + making modifications to it. For an executable work, complete + source code means all the source code for all modules it contains, + plus any associated interface definition files, plus the scripts + used to control compilation and installation of the executable. + However, as a special exception, the source code distributed need + not include anything that is normally distributed (in either + source or binary form) with the major components (compiler, + kernel, and so on) of the operating system on which the executable + runs, unless that component itself accompanies the executable. + + If distribution of executable or object code is made by offering + access to copy from a designated place, then offering equivalent + access to copy the source code from the same place counts as + distribution of the source code, even though third parties are not + compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense or distribute the Program is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 5. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify + or distribute the Program or its derivative works. These actions + are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Program (or any work + based on the Program), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the + Program), the recipient automatically receives a license from the + original licensor to copy, distribute or modify the Program + subject to these terms and conditions. You may not impose any + further restrictions on the recipients' exercise of the rights + granted herein. You are not responsible for enforcing compliance + by third parties to this License. + + 7. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent + issues), conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy simultaneously + your obligations under this License and any other pertinent + obligations, then as a consequence you may not distribute the + Program at all. For example, if a patent license would not permit + royalty-free redistribution of the Program by all those who + receive copies directly or indirectly through you, then the only + way you could satisfy both it and this License would be to refrain + entirely from distribution of the Program. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of + any such claims; this section has the sole purpose of protecting + the integrity of the free software distribution system, which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Program under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only + in or among countries not thus excluded. In such case, this + License incorporates the limitation as if written in the body of + this License. + + 9. The Free Software Foundation may publish revised and/or new + versions of the General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the Program + does not specify a version number of this License, you may choose + any version ever published by the Free Software Foundation. + + 10. If you wish to incorporate parts of the Program into other free + programs whose distribution conditions are different, write to the + author to ask for permission. For software which is copyrighted + by the Free Software Foundation, write to the Free Software + Foundation; we sometimes make exceptions for this. Our decision + will be guided by the two goals of preserving the free status of + all derivatives of our free software and of promoting the sharing + and reuse of software generally. + + NO WARRANTY + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT + NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE + PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU + OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY + OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + + Also add information on how to contact you by electronic and paper +mail. + + If the program is interactive, make it output a short notice like +this when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details + type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + + The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, the +commands you use may be called something other than `show w' and `show +c'; they could even be mouse-clicks or menu items--whatever suits your +program. + + You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the program, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + SIGNATURE OF TY COON, 1 April 1989 + Ty Coon, President of Vice + + This General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Library General Public License instead of this License. + + +File: gcc.info, Node: GNU Free Documentation License, Next: Contributors, Prev: Copying, Up: Top + +GNU Free Documentation License +****************************** + + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + written document "free" in the sense of freedom: to assure everyone + the effective freedom to copy and redistribute it, with or without + modifying it, either commercially or noncommercially. Secondarily, + this License preserves for the author and publisher a way to get + credit for their work, while not being considered responsible for + modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work that contains a + notice placed by the copyright holder saying it can be distributed + under the terms of this License. The "Document", below, refers to + any such manual or work. Any member of the public is a licensee, + and is addressed as "you". + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter + section of the Document that deals exclusively with the + relationship of the publishers or authors of the Document to the + Document's overall subject (or to related matters) and contains + nothing that could fall directly within that overall subject. + (For example, if the Document is in part a textbook of + mathematics, a Secondary Section may not explain any mathematics.) + The relationship could be a matter of historical connection with + the subject or with related matters, or of legal, commercial, + philosophical, ethical or political position regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, whose contents can be viewed and edited directly + and straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup has been designed + to thwart or discourage subsequent modification by readers is not + Transparent. A copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML designed for human modification. + Opaque formats include PostScript, PDF, proprietary formats that + can be read and edited only by proprietary word processors, SGML + or XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies of the Document numbering more than + 100, and the Document's license notice requires Cover Texts, you + must enclose the copies in covers that carry, clearly and legibly, + all these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a publicly-accessible + computer-network location containing a complete Transparent copy + of the Document, free of added material, which the general + network-using public has access to download anonymously at no + charge using public-standard network protocols. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has less than five). + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section entitled "History", and its title, and + add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. In any section entitled "Acknowledgments" or "Dedications", + preserve the section's title, and preserve in the section all + the substance and tone of each of the contributor + acknowledgments and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section as "Endorsements" or to + conflict in title with any Invariant Section. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections entitled + "History" in the various original documents, forming one section + entitled "History"; likewise combine any sections entitled + "Acknowledgments", and any sections entitled "Dedications". You + must delete all sections entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, does not as a whole count as a + Modified Version of the Document, provided no compilation + copyright is claimed for the compilation. Such a compilation is + called an "aggregate", and this License does not apply to the + other self-contained works thus compiled with the Document, on + account of their being thus compiled, if they are not themselves + derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one + quarter of the entire aggregate, the Document's Cover Texts may be + placed on covers that surround only the Document within the + aggregate. Otherwise they must appear on covers around the whole + aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License provided that you also include the + original English version of this License. In case of a + disagreement between the translation and the original English + version of this License, the original English version will prevail. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no Front-Cover +Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being +LIST"; likewise for Back-Cover Texts. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software.