This is gcc.info, produced by makeinfo version 7.1 from gcc.texi. This file documents the use of the GNU compilers. Copyright © 1988-2024 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "Funding Free Software", the Front-Cover Texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Front-Cover Text is: A GNU Manual (b) The FSF's Back-Cover Text is: You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development. INFO-DIR-SECTION Software development START-INFO-DIR-ENTRY * gcc: (gcc). The GNU Compiler Collection. * g++: (gcc). The GNU C++ compiler. * gcov: (gcc) Gcov. ‘gcov’--a test coverage program. * gcov-tool: (gcc) Gcov-tool. ‘gcov-tool’--an offline gcda profile processing program. * gcov-dump: (gcc) Gcov-dump. ‘gcov-dump’--an offline gcda and gcno profile dump tool. * lto-dump: (gcc) lto-dump. ‘lto-dump’--Tool for dumping LTO object files. END-INFO-DIR-ENTRY This file documents the use of the GNU compilers. Copyright © 1988-2024 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "Funding Free Software", the Front-Cover Texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Front-Cover Text is: A GNU Manual (b) The FSF's Back-Cover Text is: You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.  File: gcc.info, Node: x86 transactional memory intrinsics, Next: x86 control-flow protection intrinsics, Prev: x86 Built-in Functions, Up: Target Builtins 6.62.40 x86 Transactional Memory Intrinsics ------------------------------------------- These hardware transactional memory intrinsics for x86 allow you to use memory transactions with RTM (Restricted Transactional Memory). This support is enabled with the ‘-mrtm’ option. For using HLE (Hardware Lock Elision) see *note x86 specific memory model extensions for transactional memory:: instead. A memory transaction commits all changes to memory in an atomic way, as visible to other threads. If the transaction fails it is rolled back and all side effects discarded. Generally there is no guarantee that a memory transaction ever succeeds and suitable fallback code always needs to be supplied. -- RTM Function: unsigned _xbegin () Start a RTM (Restricted Transactional Memory) transaction. Returns ‘_XBEGIN_STARTED’ when the transaction started successfully (note this is not 0, so the constant has to be explicitly tested). If the transaction aborts, all side effects are undone and an abort code encoded as a bit mask is returned. The following macros are defined: -- Macro: _XABORT_EXPLICIT Transaction was explicitly aborted with ‘_xabort’. The parameter passed to ‘_xabort’ is available with ‘_XABORT_CODE(status)’. -- Macro: _XABORT_RETRY Transaction retry is possible. -- Macro: _XABORT_CONFLICT Transaction abort due to a memory conflict with another thread. -- Macro: _XABORT_CAPACITY Transaction abort due to the transaction using too much memory. -- Macro: _XABORT_DEBUG Transaction abort due to a debug trap. -- Macro: _XABORT_NESTED Transaction abort in an inner nested transaction. There is no guarantee any transaction ever succeeds, so there always needs to be a valid fallback path. -- RTM Function: void _xend () Commit the current transaction. When no transaction is active this faults. All memory side effects of the transaction become visible to other threads in an atomic manner. -- RTM Function: int _xtest () Return a nonzero value if a transaction is currently active, otherwise 0. -- RTM Function: void _xabort (status) Abort the current transaction. When no transaction is active this is a no-op. The STATUS is an 8-bit constant; its value is encoded in the return value from ‘_xbegin’. Here is an example showing handling for ‘_XABORT_RETRY’ and a fallback path for other failures: #include int n_tries, max_tries; unsigned status = _XABORT_EXPLICIT; ... for (n_tries = 0; n_tries < max_tries; n_tries++) { status = _xbegin (); if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) break; } if (status == _XBEGIN_STARTED) { ... transaction code... _xend (); } else { ... non-transactional fallback path... } Note that, in most cases, the transactional and non-transactional code must synchronize together to ensure consistency.  File: gcc.info, Node: x86 control-flow protection intrinsics, Prev: x86 transactional memory intrinsics, Up: Target Builtins 6.62.41 x86 Control-Flow Protection Intrinsics ---------------------------------------------- -- CET Function: ret_type _get_ssp (void) Get the current value of shadow stack pointer if shadow stack support from Intel CET is enabled in the hardware or ‘0’ otherwise. The ‘ret_type’ is ‘unsigned long long’ for 64-bit targets and ‘unsigned int’ for 32-bit targets. -- CET Function: void _inc_ssp (unsigned int) Increment the current shadow stack pointer by the size specified by the function argument. The argument is masked to a byte value for security reasons, so to increment by more than 255 bytes you must call the function multiple times. The shadow stack unwind code looks like: #include /* Unwind the shadow stack for EH. */ #define _Unwind_Frames_Extra(x) \ do \ { \ _Unwind_Word ssp = _get_ssp (); \ if (ssp != 0) \ { \ _Unwind_Word tmp = (x); \ while (tmp > 255) \ { \ _inc_ssp (tmp); \ tmp -= 255; \ } \ _inc_ssp (tmp); \ } \ } \ while (0) This code runs unconditionally on all 64-bit processors. For 32-bit processors the code runs on those that support multi-byte NOP instructions.  File: gcc.info, Node: Target Format Checks, Next: Pragmas, Prev: Target Builtins, Up: C Extensions 6.63 Format Checks Specific to Particular Target Machines ========================================================= For some target machines, GCC supports additional options to the format attribute (*note Declaring Attributes of Functions: Function Attributes.). * Menu: * Solaris Format Checks:: * Darwin Format Checks::  File: gcc.info, Node: Solaris Format Checks, Next: Darwin Format Checks, Up: Target Format Checks 6.63.1 Solaris Format Checks ---------------------------- Solaris targets support the ‘cmn_err’ (or ‘__cmn_err__’) format check. ‘cmn_err’ accepts a subset of the standard ‘printf’ conversions, and the two-argument ‘%b’ conversion for displaying bit-fields. See the Solaris man page for ‘cmn_err’ for more information.  File: gcc.info, Node: Darwin Format Checks, Prev: Solaris Format Checks, Up: Target Format Checks 6.63.2 Darwin Format Checks --------------------------- In addition to the full set of format archetypes (attribute format style arguments such as ‘printf’, ‘scanf’, ‘strftime’, and ‘strfmon’), Darwin targets also support the ‘CFString’ (or ‘__CFString__’) archetype in the ‘format’ attribute. Declarations with this archetype are parsed for correct syntax and argument types. However, parsing of the format string itself and validating arguments against it in calls to such functions is currently not performed. Additionally, ‘CFStringRefs’ (defined by the ‘CoreFoundation’ headers) may also be used as format arguments. Note that the relevant headers are only likely to be available on Darwin (OSX) installations. On such installations, the XCode and system documentation provide descriptions of ‘CFString’, ‘CFStringRefs’ and associated functions.  File: gcc.info, Node: Pragmas, Next: Unnamed Fields, Prev: Target Format Checks, Up: C Extensions 6.64 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. The GNU C preprocessor recognizes several pragmas in addition to the compiler pragmas documented here. Refer to the CPP manual for more information. * Menu: * AArch64 Pragmas:: * ARM Pragmas:: * M32C Pragmas:: * PRU Pragmas:: * RS/6000 and PowerPC Pragmas:: * S/390 Pragmas:: * Darwin Pragmas:: * Solaris Pragmas:: * Symbol-Renaming Pragmas:: * Structure-Layout Pragmas:: * Weak Pragmas:: * Diagnostic Pragmas:: * Visibility Pragmas:: * Push/Pop Macro Pragmas:: * Function Specific Option Pragmas:: * Loop-Specific Pragmas::  File: gcc.info, Node: AArch64 Pragmas, Next: ARM Pragmas, Up: Pragmas 6.64.1 AArch64 Pragmas ---------------------- The pragmas defined by the AArch64 target correspond to the AArch64 target function attributes. They can be specified as below: #pragma GCC target("string") where ‘STRING’ can be any string accepted as an AArch64 target attribute. *Note AArch64 Function Attributes::, for more details on the permissible values of ‘string’.  File: gcc.info, Node: ARM Pragmas, Next: M32C Pragmas, Prev: AArch64 Pragmas, Up: Pragmas 6.64.2 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: M32C Pragmas, Next: PRU Pragmas, Prev: ARM Pragmas, Up: Pragmas 6.64.3 M32C Pragmas ------------------- ‘GCC memregs NUMBER’ Overrides the command-line option ‘-memregs=’ for the current file. Use with care! This pragma must be before any function in the file, and mixing different memregs values in different objects may make them incompatible. This pragma is useful when a performance-critical function uses a memreg for temporary values, as it may allow you to reduce the number of memregs used. ‘ADDRESS NAME ADDRESS’ For any declared symbols matching NAME, this does three things to that symbol: it forces the symbol to be located at the given address (a number), it forces the symbol to be volatile, and it changes the symbol's scope to be static. This pragma exists for compatibility with other compilers, but note that the common ‘1234H’ numeric syntax is not supported (use ‘0x1234’ instead). Example: #pragma ADDRESS port3 0x103 char port3;  File: gcc.info, Node: PRU Pragmas, Next: RS/6000 and PowerPC Pragmas, Prev: M32C Pragmas, Up: Pragmas 6.64.4 PRU Pragmas ------------------ ‘ctable_entry INDEX CONSTANT_ADDRESS’ Specifies that the PRU CTABLE entry given by INDEX has the value CONSTANT_ADDRESS. This enables GCC to emit LBCO/SBCO instructions when the load/store address is known and can be addressed with some CTABLE entry. For example: /* will compile to "sbco Rx, 2, 0x10, 4" */ #pragma ctable_entry 2 0x4802a000 *(unsigned int *)0x4802a010 = val;  File: gcc.info, Node: RS/6000 and PowerPC Pragmas, Next: S/390 Pragmas, Prev: PRU Pragmas, Up: Pragmas 6.64.5 RS/6000 and PowerPC Pragmas ---------------------------------- The RS/6000 and PowerPC targets define one pragma for controlling whether or not the ‘longcall’ attribute is added to function declarations by default. This pragma overrides the ‘-mlongcall’ option, but not the ‘longcall’ and ‘shortcall’ attributes. *Note RS/6000 and PowerPC Options::, for more information about when long calls are and are not necessary. ‘longcall (1)’ Apply the ‘longcall’ attribute to all subsequent function declarations. ‘longcall (0)’ Do not apply the ‘longcall’ attribute to subsequent function declarations.  File: gcc.info, Node: S/390 Pragmas, Next: Darwin Pragmas, Prev: RS/6000 and PowerPC Pragmas, Up: Pragmas 6.64.6 S/390 Pragmas -------------------- The pragmas defined by the S/390 target correspond to the S/390 target function attributes and some the additional options: ‘zvector’ ‘no-zvector’ Note that options of the pragma, unlike options of the target attribute, do change the value of preprocessor macros like ‘__VEC__’. They can be specified as below: #pragma GCC target("string[,string]...") #pragma GCC target("string"[,"string"]...)  File: gcc.info, Node: Darwin Pragmas, Next: Solaris Pragmas, Prev: S/390 Pragmas, Up: Pragmas 6.64.7 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 does 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: Symbol-Renaming Pragmas, Prev: Darwin Pragmas, Up: Pragmas 6.64.8 Solaris Pragmas ---------------------- The Solaris target supports ‘#pragma redefine_extname’ (*note Symbol-Renaming Pragmas::). It also supports additional ‘#pragma’ directives for compatibility with the system compiler. ‘align ALIGNMENT (VARIABLE [, VARIABLE]...)’ Increase the minimum alignment of each VARIABLE to ALIGNMENT. This is the same as GCC's ‘aligned’ attribute *note Variable Attributes::). Macro expansion occurs on the arguments to this pragma when compiling C and Objective-C. It does not currently occur when compiling C++, but this is a bug which may be fixed in a future release. ‘fini (FUNCTION [, FUNCTION]...)’ This pragma causes each listed FUNCTION to be called after main, or during shared module unloading, by adding a call to the ‘.fini’ section. ‘init (FUNCTION [, FUNCTION]...)’ This pragma causes each listed FUNCTION to be called during initialization (before ‘main’) or during shared module loading, by adding a call to the ‘.init’ section.  File: gcc.info, Node: Symbol-Renaming Pragmas, Next: Structure-Layout Pragmas, Prev: Solaris Pragmas, Up: Pragmas 6.64.9 Symbol-Renaming Pragmas ------------------------------ GCC supports a ‘#pragma’ directive that changes the name used in assembly for a given declaration. While this pragma is supported on all platforms, it is intended primarily to provide compatibility with the Solaris system headers. This effect can also be achieved using the asm labels extension (*note Asm Labels::). ‘redefine_extname OLDNAME NEWNAME’ This pragma gives the C function OLDNAME the assembly symbol NEWNAME. The preprocessor macro ‘__PRAGMA_REDEFINE_EXTNAME’ is defined if this pragma is available (currently on all platforms). This pragma and the ‘asm’ labels extension interact in a complicated manner. Here are some corner cases you may want to be aware of: 1. This pragma silently applies only to declarations with external linkage. The ‘asm’ label feature does not have this restriction. 2. In C++, this pragma silently applies only to declarations with "C" linkage. Again, ‘asm’ labels do not have this restriction. 3. If either of the ways of changing the assembly name of a declaration are applied to a declaration whose assembly name has already been determined (either by a previous use of one of these features, or because the compiler needed the assembly name in order to generate code), and the new name is different, a warning issues and the name does not change. 4. The OLDNAME used by ‘#pragma redefine_extname’ is always the C-language name.  File: gcc.info, Node: Structure-Layout Pragmas, Next: Weak Pragmas, Prev: Symbol-Renaming Pragmas, Up: Pragmas 6.64.10 Structure-Layout Pragmas -------------------------------- For compatibility with Microsoft Windows compilers, GCC supports a set of ‘#pragma’ directives that change the maximum alignment of members of structures (other than zero-width bit-fields), unions, and classes subsequently defined. The N value below always is required to be a small power of two and specifies the new alignment in bytes. 1. ‘#pragma pack(N)’ simply sets the new alignment. 2. ‘#pragma pack()’ sets the alignment to the one that was in effect when compilation started (see also command-line option ‘-fpack-struct[=N]’ *note Code Gen Options::). 3. ‘#pragma pack(push[,N])’ pushes the current alignment setting on an internal stack and then optionally sets the new alignment. 4. ‘#pragma pack(pop)’ restores the alignment setting to the one saved at the top of the internal stack (and removes that stack entry). Note that ‘#pragma pack([N])’ does not influence this internal stack; thus it is possible to have ‘#pragma pack(push)’ followed by multiple ‘#pragma pack(N)’ instances and finalized by a single ‘#pragma pack(pop)’. Some targets, e.g. x86 and PowerPC, support the ‘#pragma ms_struct’ directive which lays out structures and unions subsequently defined as the documented ‘__attribute__ ((ms_struct))’. 1. ‘#pragma ms_struct on’ turns on the Microsoft layout. 2. ‘#pragma ms_struct off’ turns off the Microsoft layout. 3. ‘#pragma ms_struct reset’ goes back to the default layout. Most targets also support the ‘#pragma scalar_storage_order’ directive which lays out structures and unions subsequently defined as the documented ‘__attribute__ ((scalar_storage_order))’. 1. ‘#pragma scalar_storage_order big-endian’ sets the storage order of the scalar fields to big-endian. 2. ‘#pragma scalar_storage_order little-endian’ sets the storage order of the scalar fields to little-endian. 3. ‘#pragma scalar_storage_order default’ goes back to the endianness that was in effect when compilation started (see also command-line option ‘-fsso-struct=ENDIANNESS’ *note C Dialect Options::).  File: gcc.info, Node: Weak Pragmas, Next: Diagnostic Pragmas, Prev: Structure-Layout Pragmas, Up: Pragmas 6.64.11 Weak Pragmas -------------------- For compatibility with SVR4, GCC supports a set of ‘#pragma’ directives for declaring symbols to be weak, and defining weak aliases. ‘#pragma weak SYMBOL’ This pragma declares SYMBOL to be weak, as if the declaration had the attribute of the same name. The pragma may appear before or after the declaration of SYMBOL. It is not an error for SYMBOL to never be defined at all. ‘#pragma weak SYMBOL1 = SYMBOL2’ This pragma declares SYMBOL1 to be a weak alias of SYMBOL2. It is an error if SYMBOL2 is not defined in the current translation unit.  File: gcc.info, Node: Diagnostic Pragmas, Next: Visibility Pragmas, Prev: Weak Pragmas, Up: Pragmas 6.64.12 Diagnostic Pragmas -------------------------- GCC allows the user to selectively enable or disable certain types of diagnostics, and change the kind of the diagnostic. For example, a project's policy might require that all sources compile with ‘-Werror’ but certain files might have exceptions allowing specific types of warnings. Or, a project might selectively enable diagnostics and treat them as errors depending on which preprocessor macros are defined. ‘#pragma GCC diagnostic KIND OPTION’ Modifies the disposition of a diagnostic. Note that not all diagnostics are modifiable; at the moment only warnings (normally controlled by ‘-W...’) can be controlled, and not all of them. Use ‘-fdiagnostics-show-option’ to determine which diagnostics are controllable and which option controls them. KIND is ‘error’ to treat this diagnostic as an error, ‘warning’ to treat it like a warning (even if ‘-Werror’ is in effect), or ‘ignored’ if the diagnostic is to be ignored. OPTION is a double quoted string that matches the command-line option. #pragma GCC diagnostic warning "-Wformat" #pragma GCC diagnostic error "-Wformat" #pragma GCC diagnostic ignored "-Wformat" Note that these pragmas override any command-line options. GCC keeps track of the location of each pragma, and issues diagnostics according to the state as of that point in the source file. Thus, pragmas occurring after a line do not affect diagnostics caused by that line. ‘#pragma GCC diagnostic push’ ‘#pragma GCC diagnostic pop’ Causes GCC to remember the state of the diagnostics as of each ‘push’, and restore to that point at each ‘pop’. If a ‘pop’ has no matching ‘push’, the command-line options are restored. #pragma GCC diagnostic error "-Wuninitialized" foo(a); /* error is given for this one */ #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wuninitialized" foo(b); /* no diagnostic for this one */ #pragma GCC diagnostic pop foo(c); /* error is given for this one */ #pragma GCC diagnostic pop foo(d); /* depends on command-line options */ ‘#pragma GCC diagnostic ignored_attributes’ Similarly to ‘-Wno-attributes=’, this pragma allows users to suppress warnings about unknown scoped attributes (in C++11 and C23). For example, ‘#pragma GCC diagnostic ignored_attributes "vendor::attr"’ disables warning about the following declaration: [[vendor::attr]] void f(); whereas ‘#pragma GCC diagnostic ignored_attributes "vendor::"’ prevents warning about both of these declarations: [[vendor::safe]] void f(); [[vendor::unsafe]] void f2(); GCC also offers a simple mechanism for printing messages during compilation. ‘#pragma message STRING’ Prints STRING as a compiler message on compilation. The message is informational only, and is neither a compilation warning nor an error. Newlines can be included in the string by using the ‘\n’ escape sequence. #pragma message "Compiling " __FILE__ "..." STRING may be parenthesized, and is printed with location information. For example, #define DO_PRAGMA(x) _Pragma (#x) #define TODO(x) DO_PRAGMA(message ("TODO - " #x)) TODO(Remember to fix this) prints ‘/tmp/file.c:4: note: #pragma message: TODO - Remember to fix this’. ‘#pragma GCC error MESSAGE’ Generates an error message. This pragma _is_ considered to indicate an error in the compilation, and it will be treated as such. Newlines can be included in the string by using the ‘\n’ escape sequence. They will be displayed as newlines even if the ‘-fmessage-length’ option is set to zero. The error is only generated if the pragma is present in the code after pre-processing has been completed. It does not matter however if the code containing the pragma is unreachable: #if 0 #pragma GCC error "this error is not seen" #endif void foo (void) { return; #pragma GCC error "this error is seen" } ‘#pragma GCC warning MESSAGE’ This is just like ‘pragma GCC error’ except that a warning message is issued instead of an error message. Unless ‘-Werror’ is in effect, in which case this pragma will generate an error as well.  File: gcc.info, Node: Visibility Pragmas, Next: Push/Pop Macro Pragmas, Prev: Diagnostic Pragmas, Up: Pragmas 6.64.13 Visibility Pragmas -------------------------- ‘#pragma GCC visibility push(VISIBILITY)’ ‘#pragma GCC visibility pop’ This pragma allows the user to set the visibility for multiple declarations without having to give each a visibility attribute (*note Function Attributes::). In C++, ‘#pragma GCC visibility’ affects only namespace-scope declarations. Class members and template specializations are not affected; if you want to override the visibility for a particular member or instantiation, you must use an attribute.  File: gcc.info, Node: Push/Pop Macro Pragmas, Next: Function Specific Option Pragmas, Prev: Visibility Pragmas, Up: Pragmas 6.64.14 Push/Pop Macro Pragmas ------------------------------ For compatibility with Microsoft Windows compilers, GCC supports ‘#pragma push_macro("MACRO_NAME")’ and ‘#pragma pop_macro("MACRO_NAME")’. ‘#pragma push_macro("MACRO_NAME")’ This pragma saves the value of the macro named as MACRO_NAME to the top of the stack for this macro. ‘#pragma pop_macro("MACRO_NAME")’ This pragma sets the value of the macro named as MACRO_NAME to the value on top of the stack for this macro. If the stack for MACRO_NAME is empty, the value of the macro remains unchanged. For example: #define X 1 #pragma push_macro("X") #undef X #define X -1 #pragma pop_macro("X") int x [X]; In this example, the definition of X as 1 is saved by ‘#pragma push_macro’ and restored by ‘#pragma pop_macro’.  File: gcc.info, Node: Function Specific Option Pragmas, Next: Loop-Specific Pragmas, Prev: Push/Pop Macro Pragmas, Up: Pragmas 6.64.15 Function Specific Option Pragmas ---------------------------------------- ‘#pragma GCC target (STRING, ...)’ This pragma allows you to set target-specific options for functions defined later in the source file. One or more strings can be specified. Each function that is defined after this point is treated as if it had been declared with one ‘target(’STRING‘)’ attribute for each STRING argument. The parentheses around the strings in the pragma are optional. *Note Function Attributes::, for more information about the ‘target’ attribute and the attribute syntax. The ‘#pragma GCC target’ pragma is presently implemented for x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. ‘#pragma GCC optimize (STRING, ...)’ This pragma allows you to set global optimization options for functions defined later in the source file. One or more strings can be specified. Each function that is defined after this point is treated as if it had been declared with one ‘optimize(’STRING‘)’ attribute for each STRING argument. The parentheses around the strings in the pragma are optional. *Note Function Attributes::, for more information about the ‘optimize’ attribute and the attribute syntax. ‘#pragma GCC push_options’ ‘#pragma GCC pop_options’ These pragmas maintain a stack of the current target and optimization options. It is intended for include files where you temporarily want to switch to using a different ‘#pragma GCC target’ or ‘#pragma GCC optimize’ and then to pop back to the previous options. ‘#pragma GCC reset_options’ This pragma clears the current ‘#pragma GCC target’ and ‘#pragma GCC optimize’ to use the default switches as specified on the command line.  File: gcc.info, Node: Loop-Specific Pragmas, Prev: Function Specific Option Pragmas, Up: Pragmas 6.64.16 Loop-Specific Pragmas ----------------------------- ‘#pragma GCC ivdep’ With this pragma, the programmer asserts that there are no loop-carried dependencies which would prevent consecutive iterations of the following loop from executing concurrently with SIMD (single instruction multiple data) instructions. For example, the compiler can only unconditionally vectorize the following loop with the pragma: void foo (int n, int *a, int *b, int *c) { int i, j; #pragma GCC ivdep for (i = 0; i < n; ++i) a[i] = b[i] + c[i]; } In this example, using the ‘restrict’ qualifier had the same effect. In the following example, that would not be possible. Assume k < -m or k >= m. Only with the pragma, the compiler knows that it can unconditionally vectorize the following loop: void ignore_vec_dep (int *a, int k, int c, int m) { #pragma GCC ivdep for (int i = 0; i < m; i++) a[i] = a[i + k] * c; } ‘#pragma GCC novector’ With this pragma, the programmer asserts that the following loop should be prevented from executing concurrently with SIMD (single instruction multiple data) instructions. For example, the compiler cannot vectorize the following loop with the pragma: void foo (int n, int *a, int *b, int *c) { int i, j; #pragma GCC novector for (i = 0; i < n; ++i) a[i] = b[i] + c[i]; } ‘#pragma GCC unroll N’ You can use this pragma to control how many times a loop should be unrolled. It must be placed immediately before a ‘for’, ‘while’ or ‘do’ loop or a ‘#pragma GCC ivdep’, and applies only to the loop that follows. N is an integer constant expression specifying the unrolling factor. The values of 0 and 1 block any unrolling of the loop.  File: gcc.info, Node: Unnamed Fields, Next: Thread-Local, Prev: Pragmas, Up: C Extensions 6.65 Unnamed Structure and Union Fields ======================================= As permitted by ISO C11 and 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, you are 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, in this structure: struct { int a; struct { int a; }; } foo; it is ambiguous which ‘a’ is being referred to with ‘foo.a’. The compiler gives errors for such constructs. Unless ‘-fms-extensions’ is used, the unnamed field must be a structure or union definition without a tag (for example, ‘struct { int a; };’). If ‘-fms-extensions’ is used, the field may also be a definition with a tag such as ‘struct foo { int a; };’, a reference to a previously defined structure or union such as ‘struct foo;’, or a reference to a ‘typedef’ name for a previously defined structure or union type. The option ‘-fplan9-extensions’ enables ‘-fms-extensions’ as well as two other extensions. First, a pointer to a structure is automatically converted to a pointer to an anonymous field for assignments and function calls. For example: struct s1 { int a; }; struct s2 { struct s1; }; extern void f1 (struct s1 *); void f2 (struct s2 *p) { f1 (p); } In the call to ‘f1’ inside ‘f2’, the pointer ‘p’ is converted into a pointer to the anonymous field. Second, when the type of an anonymous field is a ‘typedef’ for a ‘struct’ or ‘union’, code may refer to the field using the name of the ‘typedef’. typedef struct { int a; } s1; struct s2 { s1; }; s1 f1 (struct s2 *p) { return p->s1; } These usages are only permitted when they are not ambiguous.  File: gcc.info, Node: Thread-Local, Next: Binary constants, Prev: Unnamed Fields, Up: C Extensions 6.66 Thread-Local Storage ========================= Thread-local storage (TLS) is a mechanism by which variables are allocated such that there is one instance of the variable per extant thread. The runtime model GCC uses to implement this originates in the IA-64 processor-specific ABI, but has since been migrated to other processors as well. It requires significant support from the linker (‘ld’), dynamic linker (‘ld.so’), and system libraries (‘libc.so’ and ‘libpthread.so’), so it is not available everywhere. At the user level, the extension is visible with a new storage class keyword: ‘__thread’. For example: __thread int i; extern __thread struct state s; static __thread char *p; The ‘__thread’ specifier may be used alone, with the ‘extern’ or ‘static’ specifiers, but with no other storage class specifier. When used with ‘extern’ or ‘static’, ‘__thread’ must appear immediately after the other storage class specifier. The ‘__thread’ specifier may be applied to any global, file-scoped static, function-scoped static, or static data member of a class. It may not be applied to block-scoped automatic or non-static data member. When the address-of operator is applied to a thread-local variable, it is evaluated at run time and returns the address of the current thread's instance of that variable. An address so obtained may be used by any thread. When a thread terminates, any pointers to thread-local variables in that thread become invalid. No static initialization may refer to the address of a thread-local variable. In C++, if an initializer is present for a thread-local variable, it must be a CONSTANT-EXPRESSION, as defined in 5.19.2 of the ANSI/ISO C++ standard. See ELF Handling For Thread-Local Storage (https://www.akkadia.org/drepper/tls.pdf) for a detailed explanation of the four thread-local storage addressing models, and how the runtime is expected to function. * Menu: * C99 Thread-Local Edits:: * C++98 Thread-Local Edits::  File: gcc.info, Node: C99 Thread-Local Edits, Next: C++98 Thread-Local Edits, Up: Thread-Local 6.66.1 ISO/IEC 9899:1999 Edits for Thread-Local Storage ------------------------------------------------------- The following are a set of changes to ISO/IEC 9899:1999 (aka C99) that document the exact semantics of the language extension. • ‘5.1.2 Execution environments’ Add new text after paragraph 1 Within either execution environment, a “thread” is a flow of control within a program. It is implementation defined whether or not there may be more than one thread associated with a program. It is implementation defined how threads beyond the first are created, the name and type of the function called at thread startup, and how threads may be terminated. However, objects with thread storage duration shall be initialized before thread startup. • ‘6.2.4 Storage durations of objects’ Add new text before paragraph 3 An object whose identifier is declared with the storage-class specifier ‘__thread’ has “thread storage duration”. Its lifetime is the entire execution of the thread, and its stored value is initialized only once, prior to thread startup. • ‘6.4.1 Keywords’ Add ‘__thread’. • ‘6.7.1 Storage-class specifiers’ Add ‘__thread’ to the list of storage class specifiers in paragraph 1. Change paragraph 2 to With the exception of ‘__thread’, at most one storage-class specifier may be given [...]. The ‘__thread’ specifier may be used alone, or immediately following ‘extern’ or ‘static’. Add new text after paragraph 6 The declaration of an identifier for a variable that has block scope that specifies ‘__thread’ shall also specify either ‘extern’ or ‘static’. The ‘__thread’ specifier shall be used only with variables.  File: gcc.info, Node: C++98 Thread-Local Edits, Prev: C99 Thread-Local Edits, Up: Thread-Local 6.66.2 ISO/IEC 14882:1998 Edits for Thread-Local Storage -------------------------------------------------------- The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) that document the exact semantics of the language extension. • [intro.execution] New text after paragraph 4 A “thread” is a flow of control within the abstract machine. It is implementation defined whether or not there may be more than one thread. New text after paragraph 7 It is unspecified whether additional action must be taken to ensure when and whether side effects are visible to other threads. • [lex.key] Add ‘__thread’. • [basic.start.main] Add after paragraph 5 The thread that begins execution at the ‘main’ function is called the “main thread”. It is implementation defined how functions beginning threads other than the main thread are designated or typed. A function so designated, as well as the ‘main’ function, is called a “thread startup function”. It is implementation defined what happens if a thread startup function returns. It is implementation defined what happens to other threads when any thread calls ‘exit’. • [basic.start.init] Add after paragraph 4 The storage for an object of thread storage duration shall be statically initialized before the first statement of the thread startup function. An object of thread storage duration shall not require dynamic initialization. • [basic.start.term] Add after paragraph 3 The type of an object with thread storage duration shall not have a non-trivial destructor, nor shall it be an array type whose elements (directly or indirectly) have non-trivial destructors. • [basic.stc] Add "thread storage duration" to the list in paragraph 1. Change paragraph 2 Thread, static, and automatic storage durations are associated with objects introduced by declarations [...]. Add ‘__thread’ to the list of specifiers in paragraph 3. • [basic.stc.thread] New section before [basic.stc.static] The keyword ‘__thread’ applied to a non-local object gives the object thread storage duration. A local variable or class data member declared both ‘static’ and ‘__thread’ gives the variable or member thread storage duration. • [basic.stc.static] Change paragraph 1 All objects that have neither thread storage duration, dynamic storage duration nor are local [...]. • [dcl.stc] Add ‘__thread’ to the list in paragraph 1. Change paragraph 1 With the exception of ‘__thread’, at most one STORAGE-CLASS-SPECIFIER shall appear in a given DECL-SPECIFIER-SEQ. The ‘__thread’ specifier may be used alone, or immediately following the ‘extern’ or ‘static’ specifiers. [...] Add after paragraph 5 The ‘__thread’ specifier can be applied only to the names of objects and to anonymous unions. • [class.mem] Add after paragraph 6 Non-‘static’ members shall not be ‘__thread’.  File: gcc.info, Node: Binary constants, Prev: Thread-Local, Up: C Extensions 6.67 Binary Constants using the ‘0b’ Prefix =========================================== Integer constants can be written as binary constants, consisting of a sequence of ‘0’ and ‘1’ digits, prefixed by ‘0b’ or ‘0B’. This is particularly useful in environments that operate a lot on the bit level (like microcontrollers). The following statements are identical: i = 42; i = 0x2a; i = 052; i = 0b101010; The type of these constants follows the same rules as for octal or hexadecimal integer constants, so suffixes like ‘L’ or ‘UL’ can be applied.  File: gcc.info, Node: C++ Extensions, Next: Objective-C, Prev: C Extensions, Up: Top 7 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 Predefined Macros: (cpp)Common Predefined Macros.). * Menu: * C++ 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. * Function Multiversioning:: Declaring multiple function versions. * Type Traits:: Compiler support for type traits. * C++ Concepts:: Improved support for generic programming. * Deprecated Features:: Things will disappear from G++. * Backwards Compatibility:: Compatibilities with earlier definitions of C++.  File: gcc.info, Node: C++ Volatiles, Next: Restricted Pointers, Up: C++ Extensions 7.1 When is a Volatile C++ Object Accessed? =========================================== The C++ standard differs from the C standard in its treatment of volatile objects. It fails to specify what constitutes a volatile access, except to say that C++ should behave in a similar manner to C with respect to volatiles, where possible. However, the different lvalueness of expressions between C and C++ complicate the behavior. G++ behaves the same as GCC for volatile access, *Note Volatiles: C Extensions, for a description of GCC's behavior. The C and C++ language specifications differ when an object is accessed in a void context: volatile int *src = SOMEVALUE; *src; The C++ standard specifies that such expressions do not undergo lvalue to rvalue conversion, and that the type of the dereferenced object may be incomplete. The C++ standard does not specify explicitly that it is lvalue to rvalue conversion that is responsible for causing an access. There is reason to believe that it is, because otherwise certain simple expressions become undefined. However, because it would surprise most programmers, G++ treats dereferencing a pointer to volatile object of complete type as GCC would do for an equivalent type in C. When the object has incomplete type, G++ issues a warning; if you wish to force an error, you must force a conversion to rvalue with, for instance, a static cast. 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. G++ implements the same behavior as GCC does when assigning to a volatile object--there is no reread of the assigned-to object, the assigned rvalue is reused. Note that in C++ assignment expressions are lvalues, and if used as an lvalue, the volatile object is referred to. For instance, VREF refers to VOBJ, as expected, in the following example: volatile int vobj; volatile int &vref = vobj = SOMETHING;  File: gcc.info, Node: Restricted Pointers, Next: Vague Linkage, Prev: C++ Volatiles, Up: C++ Extensions 7.2 Restricting Pointer Aliasing ================================ As with the C front end, 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 has 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 that 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 7.3 Vague Linkage ================= There are several constructs in C++ that 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 always requires 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 is still emitted in every translation unit that 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 run time. 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 GNU/Linux 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 uses them. This way one copy overrides all the others, but the unused copies still take up space in the executable. For targets that do not support either COMDAT or weak symbols, most entities with vague linkage are emitted as local symbols to avoid duplicate definition errors from the linker. This does not happen for local statics in inlines, however, as having multiple copies almost certainly breaks 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 7.4 C++ Interface and Implementation Pragmas ============================================ ‘#pragma interface’ and ‘#pragma implementation’ provide the user with a way of explicitly directing the compiler to emit entities with vague linkage (and debugging information) in a particular translation unit. _Note:_ These ‘#pragma’s have been superceded as of GCC 2.7.2 by COMDAT support and the "key method" heuristic mentioned in *note Vague Linkage::. Using them can actually cause your program to grow due to unnecessary out-of-line copies of inline functions. ‘#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 is not generated (unless the main input source file itself uses ‘#pragma implementation’). Instead, the object files 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"’. 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 an inline 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 are not inlined, you will get linker errors. ---------- Footnotes ---------- (1) A file's “basename” is 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 7.5 Where's the Template? ========================= C++ templates were the first language feature to require more intelligence from the environment than was traditionally found 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 are referred 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. The 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. G++ implements the Borland model on targets where the linker supports it, including ELF targets (such as GNU/Linux), macOS and Microsoft Windows. Otherwise G++ implements neither automatic model. You have the following options for dealing with template instantiations: 1. Do nothing. Code written for the Borland model works fine, but each translation unit contains instances of each of the templates it uses. The duplicate instances will be discarded by the linker, but in a large program, this can lead to an unacceptable amount of code duplication in object files or shared libraries. Duplicate instances of a template can be avoided by defining an explicit instantiation in one object file, and preventing the compiler from doing implicit instantiations in any other object files by using an explicit instantiation declaration, using the ‘extern template’ syntax: extern template int max (int, int); This syntax is defined in the C++ 2011 standard, but has been supported by G++ and other compilers since well before 2011. Explicit instantiations can be used for the largest or most frequently duplicated instances, without having to know exactly which other instances are used in the rest of the program. 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. This is the simplest option, but also offers flexibility and fine-grained control when necessary. It is also the most portable alternative and programs using this approach will work with most modern compilers. 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 if you want to ensure that only the intended instances are used. 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. In addition to forward declaration of explicit instantiations (with ‘extern’), G++ has extended the template instantiation syntax to support 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’): inline template class Foo; static template class Foo;  File: gcc.info, Node: Bound member functions, Next: C++ Attributes, Prev: Template Instantiation, Up: C++ Extensions 7.6 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 still pay 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: Function Multiversioning, Prev: Bound member functions, Up: C++ Extensions 7.7 C++-Specific Variable, Function, and Type Attributes ======================================================== Some attributes only make sense for C++ programs. ‘abi_tag ("TAG", ...)’ The ‘abi_tag’ attribute can be applied to a function, variable, or class declaration. It modifies the mangled name of the entity to incorporate the tag name, in order to distinguish the function or class from an earlier version with a different ABI; perhaps the class has changed size, or the function has a different return type that is not encoded in the mangled name. The attribute can also be applied to an inline namespace, but does not affect the mangled name of the namespace; in this case it is only used for ‘-Wabi-tag’ warnings and automatic tagging of functions and variables. Tagging inline namespaces is generally preferable to tagging individual declarations, but the latter is sometimes necessary, such as when only certain members of a class need to be tagged. The argument can be a list of strings of arbitrary length. The strings are sorted on output, so the order of the list is unimportant. A redeclaration of an entity must not add new ABI tags, since doing so would change the mangled name. The ABI tags apply to a name, so all instantiations and specializations of a template have the same tags. The attribute will be ignored if applied to an explicit specialization or instantiation. The ‘-Wabi-tag’ flag enables a warning about a class which does not have all the ABI tags used by its subobjects and virtual functions; for users with code that needs to coexist with an earlier ABI, using this option can help to find all affected types that need to be tagged. When a type involving an ABI tag is used as the type of a variable or return type of a function where that tag is not already present in the signature of the function, the tag is automatically applied to the variable or function. ‘-Wabi-tag’ also warns about this situation; this warning can be avoided by explicitly tagging the variable or function or moving it into a tagged inline namespace. ‘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 reverses 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. ‘warn_unused’ For C++ types with non-trivial constructors and/or destructors it is impossible for the compiler to determine whether a variable of this type is truly unused if it is not referenced. This type attribute informs the compiler that variables of this type should be warned about if they appear to be unused, just like variables of fundamental types. This attribute is appropriate for types which just represent a value, such as ‘std::string’; it is not appropriate for types which control a resource, such as ‘std::lock_guard’. This attribute is also accepted in C, but it is unnecessary because C does not have constructors or destructors. ‘cold’ In addition to functions and labels, GNU C++ allows the ‘cold’ attribute to be used on C++ classes, structs, or unions. Applying the ‘cold’ attribute on a type has the effect of treating every member function of the type, including implicit special member functions, as cold. If a member function is marked with the ‘hot’ function attribute, the ‘hot’ attribute takes precedence and the ‘cold’ attribute is not propagated. For the effects of the ‘cold’ attribute on functions, see *note Common Function Attributes::. ‘hot’ In addition to functions and labels, GNU C++ allows the ‘hot’ attribute to be used on C++ classes, structs, or unions. Applying the ‘hot’ attribute on a type has the effect of treating every member function of the type, including implicit special member functions, as hot. If a member function is marked with the ‘cold’ function attribute, the ‘cold’ attribute takes precedence and the ‘hot’ attribute is not propagated. For the effects of the ‘hot’ attribute on functions, see *note Common Function Attributes::.  File: gcc.info, Node: Function Multiversioning, Next: Type Traits, Prev: C++ Attributes, Up: C++ Extensions 7.8 Function Multiversioning ============================ With the GNU C++ front end, for x86 targets, you may specify multiple versions of a function, where each function is specialized for a specific target feature. At runtime, the appropriate version of the function is automatically executed depending on the characteristics of the execution platform. Here is an example. __attribute__ ((target ("default"))) int foo () { // The default version of foo. return 0; } __attribute__ ((target ("sse4.2"))) int foo () { // foo version for SSE4.2 return 1; } __attribute__ ((target ("arch=atom"))) int foo () { // foo version for the Intel ATOM processor return 2; } __attribute__ ((target ("arch=amdfam10"))) int foo () { // foo version for the AMD Family 0x10 processors. return 3; } int main () { int (*p)() = &foo; assert ((*p) () == foo ()); return 0; } In the above example, four versions of function foo are created. The first version of foo with the target attribute "default" is the default version. This version gets executed when no other target specific version qualifies for execution on a particular platform. A new version of foo is created by using the same function signature but with a different target string. Function foo is called or a pointer to it is taken just like a regular function. GCC takes care of doing the dispatching to call the right version at runtime. Refer to the GCC wiki on Function Multiversioning (https://gcc.gnu.org/wiki/FunctionMultiVersioning) for more details.  File: gcc.info, Node: Type Traits, Next: C++ Concepts, Prev: Function Multiversioning, Up: C++ Extensions 7.9 Type Traits =============== The C++ front end implements syntactic extensions that allow compile-time determination of various characteristics of a type (or of a pair of types). -- Built-in Function: bool __has_nothrow_assign (TYPE) If TYPE is ‘const’-qualified or is a reference type then the trait is ‘false’. Otherwise if ‘__has_trivial_assign (type)’ is ‘true’ then the trait is ‘true’, else if TYPE is a cv-qualified class or union type with copy assignment operators that are known not to throw an exception then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __has_nothrow_copy (TYPE) If ‘__has_trivial_copy (type)’ is ‘true’ then the trait is ‘true’, else if TYPE is a cv-qualified class or union type with copy constructors that are known not to throw an exception then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __has_nothrow_constructor (TYPE) If ‘__has_trivial_constructor (type)’ is ‘true’ then the trait is ‘true’, else if TYPE is a cv class or union type (or array thereof) with a default constructor that is known not to throw an exception then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __has_trivial_assign (TYPE) If TYPE is ‘const’- qualified or is a reference type then the trait is ‘false’. Otherwise if ‘__is_trivial (type)’ is ‘true’ then the trait is ‘true’, else if TYPE is a cv-qualified class or union type with a trivial copy assignment ([class.copy]) then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __has_trivial_copy (TYPE) If ‘__is_trivial (type)’ is ‘true’ or TYPE is a reference type then the trait is ‘true’, else if TYPE is a cv class or union type with a trivial copy constructor ([class.copy]) then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __has_trivial_constructor (TYPE) If ‘__is_trivial (type)’ is ‘true’ then the trait is ‘true’, else if TYPE is a cv-qualified class or union type (or array thereof) with a trivial default constructor ([class.ctor]) then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __has_trivial_destructor (TYPE) If ‘__is_trivial (type)’ is ‘true’ or TYPE is a reference type then the trait is ‘true’, else if TYPE is a cv class or union type (or array thereof) with a trivial destructor ([class.dtor]) then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __has_virtual_destructor (TYPE) If TYPE is a class type with a virtual destructor ([class.dtor]) then the trait is ‘true’, else it is ‘false’. Requires: If TYPE is a non-union class type, it shall be a complete type. -- Built-in Function: bool __is_abstract (TYPE) If TYPE is an abstract class ([class.abstract]) then the trait is ‘true’, else it is ‘false’. Requires: If TYPE is a non-union class type, it shall be a complete type. -- Built-in Function: bool __is_aggregate (TYPE) If TYPE is an aggregate type ([dcl.init.aggr]) the trait is ‘true’, else it is ‘false’. Requires: If TYPE is a class type, it shall be a complete type. -- Built-in Function: bool __is_base_of (BASE_TYPE, DERIVED_TYPE) If BASE_TYPE is a base class of DERIVED_TYPE ([class.derived]) then the trait is ‘true’, otherwise it is ‘false’. Top-level cv-qualifications of BASE_TYPE and DERIVED_TYPE are ignored. For the purposes of this trait, a class type is considered is own base. Requires: if ‘__is_class (base_type)’ and ‘__is_class (derived_type)’ are ‘true’ and BASE_TYPE and DERIVED_TYPE are not the same type (disregarding cv-qualifiers), DERIVED_TYPE shall be a complete type. A diagnostic is produced if this requirement is not met. -- Built-in Function: bool __is_class (TYPE) If TYPE is a cv-qualified class type, and not a union type ([basic.compound]) the trait is ‘true’, else it is ‘false’. -- Built-in Function: bool __is_empty (TYPE) If ‘__is_class (type)’ is ‘false’ then the trait is ‘false’. Otherwise TYPE is considered empty if and only if: TYPE has no non-static data members, or all non-static data members, if any, are bit-fields of length 0, and TYPE has no virtual members, and TYPE has no virtual base classes, and TYPE has no base classes BASE_TYPE for which ‘__is_empty (base_type)’ is ‘false’. Requires: If TYPE is a non-union class type, it shall be a complete type. -- Built-in Function: bool __is_enum (TYPE) If TYPE is a cv enumeration type ([basic.compound]) the trait is ‘true’, else it is ‘false’. -- Built-in Function: bool __is_final (TYPE) If TYPE is a class or union type marked ‘final’, then the trait is ‘true’, else it is ‘false’. Requires: If TYPE is a class type, it shall be a complete type. -- Built-in Function: bool __is_literal_type (TYPE) If TYPE is a literal type ([basic.types]) the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __is_pod (TYPE) If TYPE is a cv POD type ([basic.types]) then the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, (possibly cv-qualified) ‘void’, or an array of unknown bound. -- Built-in Function: bool __is_polymorphic (TYPE) If TYPE is a polymorphic class ([class.virtual]) then the trait is ‘true’, else it is ‘false’. Requires: If TYPE is a non-union class type, it shall be a complete type. -- Built-in Function: bool __is_standard_layout (TYPE) If TYPE is a standard-layout type ([basic.types]) the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, an array of complete types, or (possibly cv-qualified) ‘void’. -- Built-in Function: bool __is_trivial (TYPE) If TYPE is a trivial type ([basic.types]) the trait is ‘true’, else it is ‘false’. Requires: TYPE shall be a complete type, an array of complete types, or (possibly cv-qualified) ‘void’. -- Built-in Function: bool __is_union (TYPE) If TYPE is a cv union type ([basic.compound]) the trait is ‘true’, else it is ‘false’. -- Built-in Function: bool __underlying_type (TYPE) The underlying type of TYPE. Requires: TYPE shall be an enumeration type ([dcl.enum]). -- Built-in Function: bool __integer_pack (LENGTH) When used as the pattern of a pack expansion within a template definition, expands to a template argument pack containing integers from ‘0’ to ‘LENGTH-1’. This is provided for efficient implementation of ‘std::make_integer_sequence’.  File: gcc.info, Node: C++ Concepts, Next: Deprecated Features, Prev: Type Traits, Up: C++ Extensions 7.10 C++ Concepts ================= C++ concepts provide much-improved support for generic programming. In particular, they allow the specification of constraints on template arguments. The constraints are used to extend the usual overloading and partial specialization capabilities of the language, allowing generic data structures and algorithms to be "refined" based on their properties rather than their type names. The following keywords are reserved for concepts. ‘assumes’ States an expression as an assumption, and if possible, verifies that the assumption is valid. For example, ‘assume(n > 0)’. ‘axiom’ Introduces an axiom definition. Axioms introduce requirements on values. ‘forall’ Introduces a universally quantified object in an axiom. For example, ‘forall (int n) n + 0 == n’. ‘concept’ Introduces a concept definition. Concepts are sets of syntactic and semantic requirements on types and their values. ‘requires’ Introduces constraints on template arguments or requirements for a member function of a class template. The front end also exposes a number of internal mechanism that can be used to simplify the writing of type traits. Note that some of these traits are likely to be removed in the future. -- Built-in Function: bool __is_same (TYPE1, TYPE2) A binary type trait: ‘true’ whenever the TYPE1 and TYPE2 refer to the same type.  File: gcc.info, Node: Deprecated Features, Next: Backwards Compatibility, Prev: C++ Concepts, Up: C++ Extensions 7.11 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. G++ allows a virtual function returning ‘void *’ to be overridden by one returning a different pointer type. This extension to the covariant return type rules is now deprecated and will be removed from a future version. The use of default arguments in function pointers, function typedefs and other places where they are not permitted by the standard is deprecated and will be removed from a future version of G++. G++ allows floating-point literals to appear in integral constant expressions, e.g. ‘ enum E { e = int(2.2 * 3.7) } ’ This extension is deprecated and will be removed from a future version. G++ allows static data members of const floating-point type to be declared with an initializer in a class definition. The standard only allows initializers for static members of const integral types and const enumeration types so this extension has been deprecated and will be removed from a future version. G++ allows attributes to follow a parenthesized direct initializer, e.g. ‘ int f (0) __attribute__ ((something)); ’ This extension has been ignored since G++ 3.3 and is deprecated. G++ allows anonymous structs and unions to have members that are not public non-static data members (i.e. fields). These extensions are deprecated.  File: gcc.info, Node: Backwards Compatibility, Prev: Deprecated Features, Up: C++ Extensions 7.12 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::. ‘Implicit C language’ Old C system header files did not contain an ‘extern "C" {...}’ scope to set the language. On such systems, all system header files are implicitly scoped inside a C language scope. Such headers must correctly prototype function argument types, there is no leeway for ‘()’ to indicate an unspecified set of arguments.  File: gcc.info, Node: Objective-C, Next: Compatibility, Prev: C++ Extensions, Up: Top 8 GNU Objective-C Features ************************** This document is meant to describe some of the GNU Objective-C features. It is not intended to teach you Objective-C. There are several resources on the Internet that present the language. * Menu: * GNU Objective-C runtime API:: * Executing code before main:: * Type encoding:: * Garbage Collection:: * Constant string objects:: * compatibility_alias:: * Exceptions:: * Synchronization:: * Fast enumeration:: * Messaging with the GNU Objective-C runtime::  File: gcc.info, Node: GNU Objective-C runtime API, Next: Executing code before main, Up: Objective-C 8.1 GNU Objective-C Runtime API =============================== This section is specific for the GNU Objective-C runtime. If you are using a different runtime, you can skip it. The GNU Objective-C runtime provides an API that allows you to interact with the Objective-C runtime system, querying the live runtime structures and even manipulating them. This allows you for example to inspect and navigate classes, methods and protocols; to define new classes or new methods, and even to modify existing classes or protocols. If you are using a "Foundation" library such as GNUstep-Base, this library will provide you with a rich set of functionality to do most of the inspection tasks, and you probably will only need direct access to the GNU Objective-C runtime API to define new classes or methods. * Menu: * Modern GNU Objective-C runtime API:: * Traditional GNU Objective-C runtime API::  File: gcc.info, Node: Modern GNU Objective-C runtime API, Next: Traditional GNU Objective-C runtime API, Up: GNU Objective-C runtime API 8.1.1 Modern GNU Objective-C Runtime API ---------------------------------------- The GNU Objective-C runtime provides an API which is similar to the one provided by the "Objective-C 2.0" Apple/NeXT Objective-C runtime. The API is documented in the public header files of the GNU Objective-C runtime: • ‘objc/objc.h’: this is the basic Objective-C header file, defining the basic Objective-C types such as ‘id’, ‘Class’ and ‘BOOL’. You have to include this header to do almost anything with Objective-C. • ‘objc/runtime.h’: this header declares most of the public runtime API functions allowing you to inspect and manipulate the Objective-C runtime data structures. These functions are fairly standardized across Objective-C runtimes and are almost identical to the Apple/NeXT Objective-C runtime ones. It does not declare functions in some specialized areas (constructing and forwarding message invocations, threading) which are in the other headers below. You have to include ‘objc/objc.h’ and ‘objc/runtime.h’ to use any of the functions, such as ‘class_getName()’, declared in ‘objc/runtime.h’. • ‘objc/message.h’: this header declares public functions used to construct, deconstruct and forward message invocations. Because messaging is done in quite a different way on different runtimes, functions in this header are specific to the GNU Objective-C runtime implementation. • ‘objc/objc-exception.h’: this header declares some public functions related to Objective-C exceptions. For example functions in this header allow you to throw an Objective-C exception from plain C/C++ code. • ‘objc/objc-sync.h’: this header declares some public functions related to the Objective-C ‘@synchronized()’ syntax, allowing you to emulate an Objective-C ‘@synchronized()’ block in plain C/C++ code. • ‘objc/thr.h’: this header declares a public runtime API threading layer that is only provided by the GNU Objective-C runtime. It declares functions such as ‘objc_mutex_lock()’, which provide a platform-independent set of threading functions. The header files contain detailed documentation for each function in the GNU Objective-C runtime API.  File: gcc.info, Node: Traditional GNU Objective-C runtime API, Prev: Modern GNU Objective-C runtime API, Up: GNU Objective-C runtime API 8.1.2 Traditional GNU Objective-C Runtime API --------------------------------------------- The GNU Objective-C runtime used to provide a different API, which we call the "traditional" GNU Objective-C runtime API. Functions belonging to this API are easy to recognize because they use a different naming convention, such as ‘class_get_super_class()’ (traditional API) instead of ‘class_getSuperclass()’ (modern API). Software using this API includes the file ‘objc/objc-api.h’ where it is declared. Starting with GCC 4.7.0, the traditional GNU runtime API is no longer available.  File: gcc.info, Node: Executing code before main, Next: Type encoding, Prev: GNU Objective-C runtime API, Up: Objective-C 8.2 ‘+load’: Executing Code before ‘main’ ========================================= This section is specific for the GNU Objective-C runtime. If you are using a different runtime, you can skip it. 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, Up: Executing code before main 8.2.1 What You Can and Cannot Do in ‘+load’ ------------------------------------------- ‘+load’ is to be used only as a last resort. Because it is executed very early, most of the Objective-C runtime machinery will not be ready when ‘+load’ is executed; hence ‘+load’ works best for executing C code that is independent on the Objective-C runtime. The ‘+load’ implementation in the GNU runtime guarantees you the following things: • you can write whatever C code you like; • 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; • sending messages to Objective-C constant strings (‘@"this is a constant string"’); 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 8.3 Type Encoding ================= This is an advanced section. Type encodings are used extensively by the compiler and by the runtime, but you generally do not need to know about them to use Objective-C. 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: ‘_Bool’ ‘B’ ‘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’ ‘long double’ ‘D’ ‘void’ ‘v’ ‘id’ ‘@’ ‘Class’ ‘#’ ‘SEL’ ‘:’ ‘char*’ ‘*’ ‘enum’ an ‘enum’ is encoded exactly as the integer type that the compiler uses for it, which depends on the enumeration values. Often the compiler users ‘unsigned int’, which is then encoded as ‘I’. unknown type ‘?’ Complex types ‘j’ followed by the inner type. For example ‘_Complex double’ is encoded as "jd". 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 ‘)’ vectors ‘![’ followed by the vector_size (the number of bytes composing the vector) followed by a comma, followed by the alignment (in bytes) of the vector, followed by the type of the elements 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; } int a __attribute__ ((vector_size (16)));‘![16,16i]’ (alignment depends on the machine) 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’ ‘byref’ ‘R’ ‘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. Note how ‘const’ interacts with pointers: Objective-C type Compiler encoding -------------------------------------------------------------------------- const int ‘ri’ const int* ‘^ri’ int *const ‘r^i’ ‘const int*’ is a pointer to a ‘const int’, and so is encoded as ‘^ri’. ‘int* const’, instead, is a ‘const’ pointer to an ‘int’, and so is encoded as ‘r^i’. Finally, there is a complication when encoding ‘const char *’ versus ‘char * const’. Because ‘char *’ is encoded as ‘*’ and not as ‘^c’, there is no way to express the fact that ‘r’ applies to the pointer or to the pointee. Hence, it is assumed as a convention that ‘r*’ means ‘const char *’ (since it is what is most often meant), and there is no way to encode ‘char *const’. ‘char *const’ would simply be encoded as ‘*’, and the ‘const’ is lost. * Menu: * Legacy type encoding:: * @encode:: * Method signatures::  File: gcc.info, Node: Legacy type encoding, Next: @encode, Up: Type encoding 8.3.1 Legacy Type Encoding -------------------------- Unfortunately, historically GCC used to have a number of bugs in its encoding code. The NeXT runtime expects GCC to emit type encodings in this historical format (compatible with GCC-3.3), so when using the NeXT runtime, GCC will introduce on purpose a number of incorrect encodings: • the read-only qualifier of the pointee gets emitted before the '^'. The read-only qualifier of the pointer itself gets ignored, unless it is a typedef. Also, the 'r' is only emitted for the outermost type. • 32-bit longs are encoded as 'l' or 'L', but not always. For typedefs, the compiler uses 'i' or 'I' instead if encoding a struct field or a pointer. • ‘enum’s are always encoded as 'i' (int) even if they are actually unsigned or long. In addition to that, the NeXT runtime uses a different encoding for bitfields. It encodes them as ‘b’ followed by the size, without a bit offset or the underlying field type.  File: gcc.info, Node: @encode, Next: Method signatures, Prev: Legacy type encoding, Up: Type encoding 8.3.2 ‘@encode’ --------------- GNU Objective-C supports the ‘@encode’ syntax that allows you to create a type encoding from a C/Objective-C type. For example, ‘@encode(int)’ is compiled by the compiler into ‘"i"’. ‘@encode’ does not support type qualifiers other than ‘const’. For example, ‘@encode(const char*)’ is valid and is compiled into ‘"r*"’, while ‘@encode(bycopy char *)’ is invalid and will cause a compilation error.  File: gcc.info, Node: Method signatures, Prev: @encode, Up: Type encoding 8.3.3 Method Signatures ----------------------- This section documents the encoding of method types, which is rarely needed to use Objective-C. You should skip it at a first reading; the runtime provides functions that will work on methods and can walk through the list of parameters and interpret them for you. These functions are part of the public "API" and are the preferred way to interact with method signatures from user code. But if you need to debug a problem with method signatures and need to know how they are implemented (i.e., the "ABI"), read on. Methods have their "signature" encoded and made available to the runtime. The "signature" encodes all the information required to dynamically build invocations of the method at runtime: return type and arguments. The "signature" is a null-terminated string, composed of the following: • The return type, including type qualifiers. For example, a method returning ‘int’ would have ‘i’ here. • The total size (in bytes) required to pass all the parameters. This includes the two hidden parameters (the object ‘self’ and the method selector ‘_cmd’). • Each argument, with the type encoding, followed by the offset (in bytes) of the argument in the list of parameters. For example, a method with no arguments and returning ‘int’ would have the signature ‘i8@0:4’ if the size of a pointer is 4. The signature is interpreted as follows: the ‘i’ is the return type (an ‘int’), the ‘8’ is the total size of the parameters in bytes (two pointers each of size 4), the ‘@0’ is the first parameter (an object at byte offset ‘0’) and ‘:4’ is the second parameter (a ‘SEL’ at byte offset ‘4’). You can easily find more examples by running the "strings" program on an Objective-C object file compiled by GCC. You'll see a lot of strings that look very much like ‘i8@0:4’. They are signatures of Objective-C methods.  File: gcc.info, Node: Garbage Collection, Next: Constant string objects, Prev: Type encoding, Up: Objective-C 8.4 Garbage Collection ====================== This section is specific for the GNU Objective-C runtime. If you are using a different runtime, you can skip it. Support for garbage collection with the GNU runtime has been added by using a powerful conservative garbage collector, known as the Boehm-Demers-Weiser conservative garbage collector. To enable the support for it you have to configure the compiler using an additional argument, ‘--enable-objc-gc’. This will build the boehm-gc library, and 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 { if (self == objc_lookUpClass ("WeakPointer")) 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 8.5 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 by default instances of the ‘NXConstantString’ class which is provided by the GNU Objective-C runtime. To get the definition of this class you must include the ‘objc/NXConstStr.h’ header file. User defined libraries may want to implement their own constant string class. To be able to support them, the GNU Objective-C compiler provides a new command line options ‘-fconstant-string-class=CLASS-NAME’. The provided class should adhere to a strict structure, the same as ‘NXConstantString’'s structure: @interface MyConstantStringClass { Class isa; char *c_string; unsigned int len; } @end ‘NXConstantString’ inherits from ‘Object’; 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, but the final ivar layout of the class must be the compatible with the given structure. When the compiler creates the statically allocated constant string object, the ‘c_string’ field will be filled by the compiler with the string; the ‘length’ field will be filled by the compiler with the string length; the ‘isa’ pointer will be filled with ‘NULL’ by the compiler, and it will later be fixed up automatically at runtime by the GNU Objective-C runtime library to point to the class which was set by the ‘-fconstant-string-class’ option when the object file is loaded (if you wonder how it works behind the scenes, the name of the class to use, and the list of static objects to fixup, are stored by the compiler in the object file in a place where the GNU runtime library will find them at runtime). As a result, 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, Next: Exceptions, Prev: Constant string objects, Up: Objective-C 8.6 ‘compatibility_alias’ ========================= 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: Exceptions, Next: Synchronization, Prev: compatibility_alias, Up: Objective-C 8.7 Exceptions ============== GNU Objective-C provides exception support built into the language, as in the following example: @try { ... @throw expr; ... } @catch (AnObjCClass *exc) { ... @throw expr; ... @throw; ... } @catch (AnotherClass *exc) { ... } @catch (id allOthers) { ... } @finally { ... @throw expr; ... } The ‘@throw’ statement may appear anywhere in an Objective-C or Objective-C++ program; when used inside of a ‘@catch’ block, the ‘@throw’ may appear without an argument (as shown above), in which case the object caught by the ‘@catch’ will be rethrown. Note that only (pointers to) Objective-C objects may be thrown and caught using this scheme. When an object is thrown, it will be caught by the nearest ‘@catch’ clause capable of handling objects of that type, analogously to how ‘catch’ blocks work in C++ and Java. A ‘@catch(id ...)’ clause (as shown above) may also be provided to catch any and all Objective-C exceptions not caught by previous ‘@catch’ clauses (if any). The ‘@finally’ clause, if present, will be executed upon exit from the immediately preceding ‘@try ... @catch’ section. This will happen regardless of whether any exceptions are thrown, caught or rethrown inside the ‘@try ... @catch’ section, analogously to the behavior of the ‘finally’ clause in Java. There are several caveats to using the new exception mechanism: • The ‘-fobjc-exceptions’ command line option must be used when compiling Objective-C files that use exceptions. • With the GNU runtime, exceptions are always implemented as "native" exceptions and it is recommended that the ‘-fexceptions’ and ‘-shared-libgcc’ options are used when linking. • With the NeXT runtime, although currently designed to be binary compatible with ‘NS_HANDLER’-style idioms provided by the ‘NSException’ class, the new exceptions can only be used on Mac OS X 10.3 (Panther) and later systems, due to additional functionality needed in the NeXT Objective-C runtime. • As mentioned above, the new exceptions do not support handling types other than Objective-C objects. Furthermore, when used from Objective-C++, the Objective-C exception model does not interoperate with C++ exceptions at this time. This means you cannot ‘@throw’ an exception from Objective-C and ‘catch’ it in C++, or vice versa (i.e., ‘throw ... @catch’).  File: gcc.info, Node: Synchronization, Next: Fast enumeration, Prev: Exceptions, Up: Objective-C 8.8 Synchronization =================== GNU Objective-C provides support for synchronized blocks: @synchronized (ObjCClass *guard) { ... } Upon entering the ‘@synchronized’ block, a thread of execution shall first check whether a lock has been placed on the corresponding ‘guard’ object by another thread. If it has, the current thread shall wait until the other thread relinquishes its lock. Once ‘guard’ becomes available, the current thread will place its own lock on it, execute the code contained in the ‘@synchronized’ block, and finally relinquish the lock (thereby making ‘guard’ available to other threads). Unlike Java, Objective-C does not allow for entire methods to be marked ‘@synchronized’. Note that throwing exceptions out of ‘@synchronized’ blocks is allowed, and will cause the guarding object to be unlocked properly. Because of the interactions between synchronization and exception handling, you can only use ‘@synchronized’ when compiling with exceptions enabled, that is with the command line option ‘-fobjc-exceptions’.  File: gcc.info, Node: Fast enumeration, Next: Messaging with the GNU Objective-C runtime, Prev: Synchronization, Up: Objective-C 8.9 Fast Enumeration ==================== * Menu: * Using fast enumeration:: * c99-like fast enumeration syntax:: * Fast enumeration details:: * Fast enumeration protocol::  File: gcc.info, Node: Using fast enumeration, Next: c99-like fast enumeration syntax, Up: Fast enumeration 8.9.1 Using Fast Enumeration ---------------------------- GNU Objective-C provides support for the fast enumeration syntax: id array = ...; id object; for (object in array) { /* Do something with 'object' */ } ‘array’ needs to be an Objective-C object (usually a collection object, for example an array, a dictionary or a set) which implements the "Fast Enumeration Protocol" (see below). If you are using a Foundation library such as GNUstep Base or Apple Cocoa Foundation, all collection objects in the library implement this protocol and can be used in this way. The code above would iterate over all objects in ‘array’. For each of them, it assigns it to ‘object’, then executes the ‘Do something with 'object'’ statements. Here is a fully worked-out example using a Foundation library (which provides the implementation of ‘NSArray’, ‘NSString’ and ‘NSLog’): NSArray *array = [NSArray arrayWithObjects: @"1", @"2", @"3", nil]; NSString *object; for (object in array) NSLog (@"Iterating over %@", object);  File: gcc.info, Node: c99-like fast enumeration syntax, Next: Fast enumeration details, Prev: Using fast enumeration, Up: Fast enumeration 8.9.2 C99-Like Fast Enumeration Syntax -------------------------------------- A c99-like declaration syntax is also allowed: id array = ...; for (id object in array) { /* Do something with 'object' */ } this is completely equivalent to: id array = ...; { id object; for (object in array) { /* Do something with 'object' */ } } but can save some typing. Note that the option ‘-std=c99’ is not required to allow this syntax in Objective-C.  File: gcc.info, Node: Fast enumeration details, Next: Fast enumeration protocol, Prev: c99-like fast enumeration syntax, Up: Fast enumeration 8.9.3 Fast Enumeration Details ------------------------------ Here is a more technical description with the gory details. Consider the code for (OBJECT EXPRESSION in COLLECTION EXPRESSION) { STATEMENTS } here is what happens when you run it: • ‘COLLECTION EXPRESSION’ is evaluated exactly once and the result is used as the collection object to iterate over. This means it is safe to write code such as ‘for (object in [NSDictionary keyEnumerator]) ...’. • the iteration is implemented by the compiler by repeatedly getting batches of objects from the collection object using the fast enumeration protocol (see below), then iterating over all objects in the batch. This is faster than a normal enumeration where objects are retrieved one by one (hence the name "fast enumeration"). • if there are no objects in the collection, then ‘OBJECT EXPRESSION’ is set to ‘nil’ and the loop immediately terminates. • if there are objects in the collection, then for each object in the collection (in the order they are returned) ‘OBJECT EXPRESSION’ is set to the object, then ‘STATEMENTS’ are executed. • ‘STATEMENTS’ can contain ‘break’ and ‘continue’ commands, which will abort the iteration or skip to the next loop iteration as expected. • when the iteration ends because there are no more objects to iterate over, ‘OBJECT EXPRESSION’ is set to ‘nil’. This allows you to determine whether the iteration finished because a ‘break’ command was used (in which case ‘OBJECT EXPRESSION’ will remain set to the last object that was iterated over) or because it iterated over all the objects (in which case ‘OBJECT EXPRESSION’ will be set to ‘nil’). • ‘STATEMENTS’ must not make any changes to the collection object; if they do, it is a hard error and the fast enumeration terminates by invoking ‘objc_enumerationMutation’, a runtime function that normally aborts the program but which can be customized by Foundation libraries via ‘objc_set_mutation_handler’ to do something different, such as raising an exception.  File: gcc.info, Node: Fast enumeration protocol, Prev: Fast enumeration details, Up: Fast enumeration 8.9.4 Fast Enumeration Protocol ------------------------------- If you want your own collection object to be usable with fast enumeration, you need to have it implement the method - (unsigned long) countByEnumeratingWithState: (NSFastEnumerationState *)state objects: (id *)objects count: (unsigned long)len; where ‘NSFastEnumerationState’ must be defined in your code as follows: typedef struct { unsigned long state; id *itemsPtr; unsigned long *mutationsPtr; unsigned long extra[5]; } NSFastEnumerationState; If no ‘NSFastEnumerationState’ is defined in your code, the compiler will automatically replace ‘NSFastEnumerationState *’ with ‘struct __objcFastEnumerationState *’, where that type is silently defined by the compiler in an identical way. This can be confusing and we recommend that you define ‘NSFastEnumerationState’ (as shown above) instead. The method is called repeatedly during a fast enumeration to retrieve batches of objects. Each invocation of the method should retrieve the next batch of objects. The return value of the method is the number of objects in the current batch; this should not exceed ‘len’, which is the maximum size of a batch as requested by the caller. The batch itself is returned in the ‘itemsPtr’ field of the ‘NSFastEnumerationState’ struct. To help with returning the objects, the ‘objects’ array is a C array preallocated by the caller (on the stack) of size ‘len’. In many cases you can put the objects you want to return in that ‘objects’ array, then do ‘itemsPtr = objects’. But you don't have to; if your collection already has the objects to return in some form of C array, it could return them from there instead. The ‘state’ and ‘extra’ fields of the ‘NSFastEnumerationState’ structure allows your collection object to keep track of the state of the enumeration. In a simple array implementation, ‘state’ may keep track of the index of the last object that was returned, and ‘extra’ may be unused. The ‘mutationsPtr’ field of the ‘NSFastEnumerationState’ is used to keep track of mutations. It should point to a number; before working on each object, the fast enumeration loop will check that this number has not changed. If it has, a mutation has happened and the fast enumeration will abort. So, ‘mutationsPtr’ could be set to point to some sort of version number of your collection, which is increased by one every time there is a change (for example when an object is added or removed). Or, if you are content with less strict mutation checks, it could point to the number of objects in your collection or some other value that can be checked to perform an approximate check that the collection has not been mutated. Finally, note how we declared the ‘len’ argument and the return value to be of type ‘unsigned long’. They could also be declared to be of type ‘unsigned int’ and everything would still work.  File: gcc.info, Node: Messaging with the GNU Objective-C runtime, Prev: Fast enumeration, Up: Objective-C 8.10 Messaging with the GNU Objective-C Runtime =============================================== This section is specific for the GNU Objective-C runtime. If you are using a different runtime, you can skip it. The implementation of messaging in the GNU Objective-C runtime is designed to be portable, and so is based on standard C. Sending a message in the GNU Objective-C runtime is composed of two separate steps. First, there is a call to the lookup function, ‘objc_msg_lookup ()’ (or, in the case of messages to super, ‘objc_msg_lookup_super ()’). This runtime function takes as argument the receiver and the selector of the method to be called; it returns the ‘IMP’, that is a pointer to the function implementing the method. The second step of method invocation consists of casting this pointer function to the appropriate function pointer type, and calling the function pointed to it with the right arguments. For example, when the compiler encounters a method invocation such as ‘[object init]’, it compiles it into a call to ‘objc_msg_lookup (object, @selector(init))’ followed by a cast of the returned value to the appropriate function pointer type, and then it calls it. * Menu: * Dynamically registering methods:: * Forwarding hook::  File: gcc.info, Node: Dynamically registering methods, Next: Forwarding hook, Up: Messaging with the GNU Objective-C runtime 8.10.1 Dynamically Registering Methods -------------------------------------- If ‘objc_msg_lookup()’ does not find a suitable method implementation, because the receiver does not implement the required method, it tries to see if the class can dynamically register the method. To do so, the runtime checks if the class of the receiver implements the method + (BOOL) resolveInstanceMethod: (SEL)selector; in the case of an instance method, or + (BOOL) resolveClassMethod: (SEL)selector; in the case of a class method. If the class implements it, the runtime invokes it, passing as argument the selector of the original method, and if it returns ‘YES’, the runtime tries the lookup again, which could now succeed if a matching method was added dynamically by ‘+resolveInstanceMethod:’ or ‘+resolveClassMethod:’. This allows classes to dynamically register methods (by adding them to the class using ‘class_addMethod’) when they are first called. To do so, a class should implement ‘+resolveInstanceMethod:’ (or, depending on the case, ‘+resolveClassMethod:’) and have it recognize the selectors of methods that can be registered dynamically at runtime, register them, and return ‘YES’. It should return ‘NO’ for methods that it does not dynamically registered at runtime. If ‘+resolveInstanceMethod:’ (or ‘+resolveClassMethod:’) is not implemented or returns ‘NO’, the runtime then tries the forwarding hook. Support for ‘+resolveInstanceMethod:’ and ‘resolveClassMethod:’ was added to the GNU Objective-C runtime in GCC version 4.6.  File: gcc.info, Node: Forwarding hook, Prev: Dynamically registering methods, Up: Messaging with the GNU Objective-C runtime 8.10.2 Forwarding Hook ---------------------- The GNU Objective-C runtime provides a hook, called ‘__objc_msg_forward2’, which is called by ‘objc_msg_lookup()’ when it cannot find a method implementation in the runtime tables and after calling ‘+resolveInstanceMethod:’ and ‘+resolveClassMethod:’ has been attempted and did not succeed in dynamically registering the method. To configure the hook, you set the global variable ‘__objc_msg_forward2’ to a function with the same argument and return types of ‘objc_msg_lookup()’. When ‘objc_msg_lookup()’ cannot find a method implementation, it invokes the hook function you provided to get a method implementation to return. So, in practice ‘__objc_msg_forward2’ allows you to extend ‘objc_msg_lookup()’ by adding some custom code that is called to do a further lookup when no standard method implementation can be found using the normal lookup. This hook is generally reserved for "Foundation" libraries such as GNUstep Base, which use it to implement their high-level method forwarding API, typically based around the ‘forwardInvocation:’ method. So, unless you are implementing your own "Foundation" library, you should not set this hook. In a typical forwarding implementation, the ‘__objc_msg_forward2’ hook function determines the argument and return type of the method that is being looked up, and then creates a function that takes these arguments and has that return type, and returns it to the caller. Creating this function is non-trivial and is typically performed using a dedicated library such as ‘libffi’. The forwarding method implementation thus created is returned by ‘objc_msg_lookup()’ and is executed as if it was a normal method implementation. When the forwarding method implementation is called, it is usually expected to pack all arguments into some sort of object (typically, an ‘NSInvocation’ in a "Foundation" library), and hand it over to the programmer (‘forwardInvocation:’) who is then allowed to manipulate the method invocation using a high-level API provided by the "Foundation" library. For example, the programmer may want to examine the method invocation arguments and name and potentially change them before forwarding the method invocation to one or more local objects (‘performInvocation:’) or even to remote objects (by using Distributed Objects or some other mechanism). When all this completes, the return value is passed back and must be returned correctly to the original caller. Note that the GNU Objective-C runtime currently provides no support for method forwarding or method invocations other than the ‘__objc_msg_forward2’ hook. If the forwarding hook does not exist or returns ‘NULL’, the runtime currently attempts forwarding using an older, deprecated API, and if that fails, it aborts the program. In future versions of the GNU Objective-C runtime, the runtime will immediately abort.  File: gcc.info, Node: Compatibility, Next: Gcov, Prev: Objective-C, Up: Top 9 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.3 the compile line for a different C++ compiler needs to include -IGCC_INSTALL_DIRECTORY/include/c++/3.3 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: Gcov-tool, Prev: Compatibility, Up: Top 10 ‘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. * Cross-profiling:: Data file relocation. * Freestanding Environments:: How to use profiling and test coverage in freestanding environments.  File: gcc.info, Node: Gcov Intro, Next: Invoking Gcov, Up: Gcov 10.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 and to discover untested parts of your program. 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 10.2 Invoking ‘gcov’ ==================== gcov [OPTIONS] FILES ‘gcov’ accepts the following options: ‘-a’ ‘--all-blocks’ Write individual execution counts for every basic block. Normally gcov outputs execution counts only for the main blocks of a line. With this option you can determine if blocks within a single line are not being executed. ‘-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. Unconditional branches will not be shown, unless the ‘-u’ option is given. ‘-c’ ‘--branch-counts’ Write branch frequencies as the number of branches taken, rather than the percentage of branches taken. ‘-d’ ‘--display-progress’ Display the progress on the standard output. ‘-f’ ‘--function-summaries’ Output summaries for each function in addition to the file level summary. ‘-h’ ‘--help’ Display help about using ‘gcov’ (on the standard output), and exit without doing any further processing. ‘-j’ ‘--json-format’ Output gcov file in an easy-to-parse JSON intermediate format which does not require source code for generation. The JSON file is compressed with gzip compression algorithm and the files have ‘.gcov.json.gz’ extension. Structure of the JSON is following: { "current_working_directory": "foo/bar", "data_file": "a.out", "format_version": "2", "gcc_version": "11.1.1 20210510" "files": ["$file"] } Fields of the root element have following semantics: • CURRENT_WORKING_DIRECTORY: working directory where a compilation unit was compiled • DATA_FILE: name of the data file (GCDA) • FORMAT_VERSION: semantic version of the format Changes in version _2_: • CALLS: information about function calls is added • GCC_VERSION: version of the GCC compiler Each FILE has the following form: { "file": "a.c", "functions": ["$function"], "lines": ["$line"] } Fields of the FILE element have following semantics: • FILE_NAME: name of the source file Each FUNCTION has the following form: { "blocks": 2, "blocks_executed": 2, "demangled_name": "foo", "end_column": 1, "end_line": 4, "execution_count": 1, "name": "foo", "start_column": 5, "start_line": 1 } Fields of the FUNCTION element have following semantics: • BLOCKS: number of blocks that are in the function • BLOCKS_EXECUTED: number of executed blocks of the function • DEMANGLED_NAME: demangled name of the function • END_COLUMN: column in the source file where the function ends • END_LINE: line in the source file where the function ends • EXECUTION_COUNT: number of executions of the function • NAME: name of the function • START_COLUMN: column in the source file where the function begins • START_LINE: line in the source file where the function begins Note that line numbers and column numbers number from 1. In the current implementation, START_LINE and START_COLUMN do not include any template parameters and the leading return type but that this is likely to be fixed in the future. Each LINE has the following form: { "block_ids": ["$block_id"], "branches": ["$branch"], "calls": ["$call"], "count": 2, "line_number": 15, "unexecuted_block": false, "function_name": "foo", } Branches and calls are present only with -B option. Fields of the LINE element have following semantics: • BLOCK_IDS: IDs of basic blocks that belong to the line • COUNT: number of executions of the line • LINE_NUMBER: line number • UNEXECUTED_BLOCK: flag whether the line contains an unexecuted block (not all statements on the line are executed) • FUNCTION_NAME: a name of a function this LINE belongs to (for a line with an inlined statements can be not set) Each BRANCH has the following form: { "count": 11, "destination_block_id": 17, "fallthrough": true, "source_block_id": 13, "throw": false } Fields of the BRANCH element have following semantics: • COUNT: number of executions of the branch • FALLTHROUGH: true when the branch is a fall through branch • THROW: true when the branch is an exceptional branch • ISOURCE_BLOCK_ID: ID of the basic block where this branch happens • DESTINATION_BLOCK_ID: ID of the basic block this branch jumps to Each CALL has the following form: { "destination_block_id": 1, "returned": 11, "source_block_id": 13 } Fields of the CALL element have following semantics: • RETURNED: number of times a function call returned (call count is equal to LINE::COUNT) • ISOURCE_BLOCK_ID: ID of the basic block where this call happens • DESTINATION_BLOCK_ID: ID of the basic block this calls continues after return ‘-H’ ‘--human-readable’ Write counts in human readable format (like 24.6k). ‘-k’ ‘--use-colors’ Use colors for lines of code that have zero coverage. We use red color for non-exceptional lines and cyan for exceptional. Same colors are used for basic blocks with ‘-a’ option. ‘-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 and you want to see the individual contributions. If you use the ‘-p’ option, both the including and included file names will be complete path names. ‘-m’ ‘--demangled-names’ Display demangled function names in output. The default is to show mangled function names. ‘-n’ ‘--no-output’ Do not create the ‘gcov’ output file. ‘-o DIRECTORY|FILE’ ‘--object-directory DIRECTORY’ ‘--object-file FILE’ Specify either the directory containing the gcov data files, or the object path name. The ‘.gcno’, and ‘.gcda’ data files are searched for using this option. If a directory is specified, the data files are in that directory and named after the input file name, without its extension. If a file is specified here, the data files are named after that file, without its extension. ‘-p’ ‘--preserve-paths’ Preserve complete path information in the names of generated ‘.gcov’ files. Without this option, just the filename component is used. With this option, all directories are used, with ‘/’ characters translated to ‘#’ characters, ‘.’ directory components removed and unremoveable ‘..’ components renamed to ‘^’. This is useful if sourcefiles are in several different directories. ‘-q’ ‘--use-hotness-colors’ Emit perf-like colored output for hot lines. Legend of the color scale is printed at the very beginning of the output file. ‘-r’ ‘--relative-only’ Only output information about source files with a relative pathname (after source prefix elision). Absolute paths are usually system header files and coverage of any inline functions therein is normally uninteresting. ‘-s DIRECTORY’ ‘--source-prefix DIRECTORY’ A prefix for source file names to remove when generating the output coverage files. This option is useful when building in a separate directory, and the pathname to the source directory is not wanted when determining the output file names. Note that this prefix detection is applied before determining whether the source file is absolute. ‘-t’ ‘--stdout’ Output to standard output instead of output files. ‘-u’ ‘--unconditional-branches’ When branch probabilities are given, include those of unconditional branches. Unconditional branches are normally not interesting. ‘-v’ ‘--version’ Display the ‘gcov’ version number (on the standard output), and exit without doing any further processing. ‘-w’ ‘--verbose’ Print verbose informations related to basic blocks and arcs. ‘-x’ ‘--hash-filenames’ When using -PRESERVE-PATHS, gcov uses the full pathname of the source files to create an output filename. This can lead to long filenames that can overflow filesystem limits. This option creates names of the form ‘SOURCE-FILE##MD5.gcov’, where the SOURCE-FILE component is the final filename part and the MD5 component is calculated from the full mangled name that would have been used otherwise. The option is an alternative to the -PRESERVE-PATHS on systems which have a filesystem limit. ‘gcov’ should be run with the current directory the same as that when you invoked the compiler. Otherwise it will not be able to locate the source files. ‘gcov’ produces files called ‘MANGLEDNAME.gcov’ in the current directory. These contain the coverage information of the source file they correspond to. One ‘.gcov’ file is produced for each source (or header) file containing code, which was compiled to produce the data files. The MANGLEDNAME part of the output file name is usually simply the source file name, but can be something more complicated if the ‘-l’ or ‘-p’ options are given. Refer to those options for details. If you invoke ‘gcov’ with multiple input files, the contributions from each input file are summed. Typically you would invoke it with the same list of files as the final link of your executable. The ‘.gcov’ files contain the ‘:’ separated fields along with program source code. The format is EXECUTION_COUNT:LINE_NUMBER:SOURCE LINE TEXT Additional block information may succeed each line, when requested by command line option. The EXECUTION_COUNT is ‘-’ for lines containing no code. Unexecuted lines are marked ‘#####’ or ‘=====’, depending on whether they are reachable by non-exceptional paths or only exceptional paths such as C++ exception handlers, respectively. Given the ‘-a’ option, unexecuted blocks are marked ‘$$$$$’ or ‘%%%%%’, depending on whether a basic block is reachable via non-exceptional or exceptional paths. Executed basic blocks having a statement with zero EXECUTION_COUNT end with ‘*’ character and are colored with magenta color with the ‘-k’ option. This functionality is not supported in Ada. Note that GCC can completely remove the bodies of functions that are not needed - for instance if they are inlined everywhere. Such functions are marked with ‘-’, which can be confusing. Use the ‘-fkeep-inline-functions’ and ‘-fkeep-static-functions’ options to retain these functions and allow gcov to properly show their EXECUTION_COUNT. Some lines of information at the start have LINE_NUMBER of zero. These preamble lines are of the form -:0:TAG:VALUE The ordering and number of these preamble lines will be augmented as ‘gcov’ development progresses -- do not rely on them remaining unchanged. Use TAG to locate a particular preamble line. The additional block information is of the form TAG INFORMATION The INFORMATION is human readable, but designed to be simple enough for machine parsing too. When printing percentages, 0% and 100% are only printed when the values are _exactly_ 0% and 100% respectively. Other values which would conventionally be rounded to 0% or 100% are instead printed as the nearest non-boundary value. When using ‘gcov’, you must first compile your program with a special GCC option ‘--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 object file is located. Running the program will cause profile output to be generated. For each source file compiled with ‘-fprofile-arcs’, an accompanying ‘.gcda’ file will be placed in the object file 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.cpp’, this is what you see when you use the basic ‘gcov’ facility: $ g++ --coverage tmp.cpp -c $ g++ --coverage tmp.o $ a.out $ gcov tmp.cpp -m File 'tmp.cpp' Lines executed:92.86% of 14 Creating 'tmp.cpp.gcov' The file ‘tmp.cpp.gcov’ contains output from ‘gcov’. Here is a sample: -: 0:Source:tmp.cpp -: 0:Working directory:/home/gcc/testcase -: 0:Graph:tmp.gcno -: 0:Data:tmp.gcda -: 0:Runs:1 -: 0:Programs:1 -: 1:#include -: 2: -: 3:template -: 4:class Foo -: 5:{ -: 6: public: 1*: 7: Foo(): b (1000) {} ------------------ Foo::Foo(): #####: 7: Foo(): b (1000) {} ------------------ Foo::Foo(): 1: 7: Foo(): b (1000) {} ------------------ 2*: 8: void inc () { b++; } ------------------ Foo::inc(): #####: 8: void inc () { b++; } ------------------ Foo::inc(): 2: 8: void inc () { b++; } ------------------ -: 9: -: 10: private: -: 11: int b; -: 12:}; -: 13: -: 14:template class Foo; -: 15:template class Foo; -: 16: -: 17:int 1: 18:main (void) -: 19:{ -: 20: int i, total; 1: 21: Foo counter; -: 22: 1: 23: counter.inc(); 1: 24: counter.inc(); 1: 25: total = 0; -: 26: 11: 27: for (i = 0; i < 10; i++) 10: 28: total += i; -: 29: 1*: 30: int v = total > 100 ? 1 : 2; -: 31: 1: 32: if (total != 45) #####: 33: printf ("Failure\n"); -: 34: else 1: 35: printf ("Success\n"); 1: 36: return 0; -: 37:} Note that line 7 is shown in the report multiple times. First occurrence presents total number of execution of the line and the next two belong to instances of class Foo constructors. As you can also see, line 30 contains some unexecuted basic blocks and thus execution count has asterisk symbol. When you use the ‘-a’ option, you will get individual block counts, and the output looks like this: -: 0:Source:tmp.cpp -: 0:Working directory:/home/gcc/testcase -: 0:Graph:tmp.gcno -: 0:Data:tmp.gcda -: 0:Runs:1 -: 0:Programs:1 -: 1:#include -: 2: -: 3:template -: 4:class Foo -: 5:{ -: 6: public: 1*: 7: Foo(): b (1000) {} ------------------ Foo::Foo(): #####: 7: Foo(): b (1000) {} ------------------ Foo::Foo(): 1: 7: Foo(): b (1000) {} ------------------ 2*: 8: void inc () { b++; } ------------------ Foo::inc(): #####: 8: void inc () { b++; } ------------------ Foo::inc(): 2: 8: void inc () { b++; } ------------------ -: 9: -: 10: private: -: 11: int b; -: 12:}; -: 13: -: 14:template class Foo; -: 15:template class Foo; -: 16: -: 17:int 1: 18:main (void) -: 19:{ -: 20: int i, total; 1: 21: Foo counter; 1: 21-block 0 -: 22: 1: 23: counter.inc(); 1: 23-block 0 1: 24: counter.inc(); 1: 24-block 0 1: 25: total = 0; -: 26: 11: 27: for (i = 0; i < 10; i++) 1: 27-block 0 11: 27-block 1 10: 28: total += i; 10: 28-block 0 -: 29: 1*: 30: int v = total > 100 ? 1 : 2; 1: 30-block 0 %%%%%: 30-block 1 1: 30-block 2 -: 31: 1: 32: if (total != 45) 1: 32-block 0 #####: 33: printf ("Failure\n"); %%%%%: 33-block 0 -: 34: else 1: 35: printf ("Success\n"); 1: 35-block 0 1: 36: return 0; 1: 36-block 0 -: 37:} In this mode, each basic block is only shown on one line - the last line of the block. A multi-line block will only contribute to the execution count of that last line, and other lines will not be shown to contain code, unless previous blocks end on those lines. The total execution count of a line is shown and subsequent lines show the execution counts for individual blocks that end on that line. After each block, the branch and call counts of the block will be shown, if the ‘-b’ option is given. Because of the way GCC instruments calls, a call count can be shown after a line with no individual blocks. As you can see, line 33 contains a basic block that was not executed. When you use the ‘-b’ option, your output looks like this: -: 0:Source:tmp.cpp -: 0:Working directory:/home/gcc/testcase -: 0:Graph:tmp.gcno -: 0:Data:tmp.gcda -: 0:Runs:1 -: 0:Programs:1 -: 1:#include -: 2: -: 3:template -: 4:class Foo -: 5:{ -: 6: public: 1*: 7: Foo(): b (1000) {} ------------------ Foo::Foo(): function Foo::Foo() called 0 returned 0% blocks executed 0% #####: 7: Foo(): b (1000) {} ------------------ Foo::Foo(): function Foo::Foo() called 1 returned 100% blocks executed 100% 1: 7: Foo(): b (1000) {} ------------------ 2*: 8: void inc () { b++; } ------------------ Foo::inc(): function Foo::inc() called 0 returned 0% blocks executed 0% #####: 8: void inc () { b++; } ------------------ Foo::inc(): function Foo::inc() called 2 returned 100% blocks executed 100% 2: 8: void inc () { b++; } ------------------ -: 9: -: 10: private: -: 11: int b; -: 12:}; -: 13: -: 14:template class Foo; -: 15:template class Foo; -: 16: -: 17:int function main called 1 returned 100% blocks executed 81% 1: 18:main (void) -: 19:{ -: 20: int i, total; 1: 21: Foo counter; call 0 returned 100% branch 1 taken 100% (fallthrough) branch 2 taken 0% (throw) -: 22: 1: 23: counter.inc(); call 0 returned 100% branch 1 taken 100% (fallthrough) branch 2 taken 0% (throw) 1: 24: counter.inc(); call 0 returned 100% branch 1 taken 100% (fallthrough) branch 2 taken 0% (throw) 1: 25: total = 0; -: 26: 11: 27: for (i = 0; i < 10; i++) branch 0 taken 91% (fallthrough) branch 1 taken 9% 10: 28: total += i; -: 29: 1*: 30: int v = total > 100 ? 1 : 2; branch 0 taken 0% (fallthrough) branch 1 taken 100% -: 31: 1: 32: if (total != 45) branch 0 taken 0% (fallthrough) branch 1 taken 100% #####: 33: printf ("Failure\n"); call 0 never executed branch 1 never executed branch 2 never executed -: 34: else 1: 35: printf ("Success\n"); call 0 returned 100% branch 1 taken 100% (fallthrough) branch 2 taken 0% (throw) 1: 36: return 0; -: 37:} For each function, a line is printed showing how many times the function is called, how many times it returns and what percentage of the function's blocks were executed. 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 that 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 ‘.gcda’ 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 ‘.gcda’ 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 ‘.gcda’ 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 10.3 Using ‘gcov’ with GCC Optimization ======================================= If you plan to use ‘gcov’ to help optimize your code, you must first compile your program with a special GCC option ‘--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: 12:if (a != b) 100: 13: c = 1; 100: 14:else 100: 15: 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. Inlineable functions can create unexpected line counts. Line counts are shown for the source code of the inlineable function, but what is shown depends on where the function is inlined, or if it is not inlined at all. If the function is not inlined, the compiler must emit an out of line copy of the function, in any object file that needs it. If ‘fileA.o’ and ‘fileB.o’ both contain out of line bodies of a particular inlineable function, they will also both contain coverage counts for that function. When ‘fileA.o’ and ‘fileB.o’ are linked together, the linker will, on many systems, select one of those out of line bodies for all calls to that function, and remove or ignore the other. Unfortunately, it will not remove the coverage counters for the unused function body. Hence when instrumented, all but one use of that function will show zero counts. If the function is inlined in several places, the block structure in each location might not be the same. For instance, a condition might now be calculable at compile time in some instances. Because the coverage of all the uses of the inline function will be shown for the same source lines, the line counts themselves might seem inconsistent. Long-running applications can use the ‘__gcov_reset’ and ‘__gcov_dump’ facilities to restrict profile collection to the program region of interest. Calling ‘__gcov_reset(void)’ will clear all run-time profile counters to zero, and calling ‘__gcov_dump(void)’ will cause the profile information collected at that point to be dumped to ‘.gcda’ output files. Instrumented applications use a static destructor with priority 99 to invoke the ‘__gcov_dump’ function. Thus ‘__gcov_dump’ is executed after all user defined static destructors, as well as handlers registered with ‘atexit’. If an executable loads a dynamic shared object via dlopen functionality, ‘-Wl,--dynamic-list-data’ is needed to dump all profile data. Profiling run-time library reports various errors related to profile manipulation and profile saving. Errors are printed into standard error output or ‘GCOV_ERROR_FILE’ file, if environment variable is used. In order to terminate immediately after an errors occurs set ‘GCOV_EXIT_AT_ERROR’ environment variable. That can help users to find profile clashing which leads to a misleading profile.  File: gcc.info, Node: Gcov Data Files, Next: Cross-profiling, Prev: Gcov and Optimization, Up: Gcov 10.4 Brief Description of ‘gcov’ Data Files =========================================== ‘gcov’ uses two files for profiling. The names of these files are derived from the original _object_ file by substituting the file suffix with either ‘.gcno’, or ‘.gcda’. The files contain coverage and profile data stored in a platform-independent format. The ‘.gcno’ files are placed in the same directory as the object file. By default, the ‘.gcda’ files are also stored in the same directory as the object file, but the GCC ‘-fprofile-dir’ option may be used to store the ‘.gcda’ files in a separate directory. The ‘.gcno’ notes file is generated when the source file is compiled with the GCC ‘-ftest-coverage’ option. It contains information to reconstruct the basic block graphs and assign source line numbers to blocks. The ‘.gcda’ count data file is generated when a program containing object files built with the GCC ‘-fprofile-arcs’ option is executed. A separate ‘.gcda’ file is created for each object file compiled with this option. It contains arc transition counts, value profile counts, and some summary information. It is not recommended to access the coverage files directly. Consumers should use the intermediate format that is provided by ‘gcov’ tool via ‘--json-format’ option.  File: gcc.info, Node: Cross-profiling, Next: Freestanding Environments, Prev: Gcov Data Files, Up: Gcov 10.5 Data File Relocation to Support Cross-Profiling ==================================================== Running the program will cause profile output to be generated. For each source file compiled with ‘-fprofile-arcs’, an accompanying ‘.gcda’ file will be placed in the object file directory. That implicitly requires running the program on the same system as it was built or having the same absolute directory structure on the target system. The program will try to create the needed directory structure, if it is not already present. To support cross-profiling, a program compiled with ‘-fprofile-arcs’ can relocate the data files based on two environment variables: • GCOV_PREFIX contains the prefix to add to the absolute paths in the object file. Prefix can be absolute, or relative. The default is no prefix. • GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off the hardwired absolute paths. Default value is 0. _Note:_ If GCOV_PREFIX_STRIP is set without GCOV_PREFIX is undefined, then a relative path is made out of the hardwired absolute paths. For example, if the object file ‘/user/build/foo.o’ was built with ‘-fprofile-arcs’, the final executable will try to create the data file ‘/user/build/foo.gcda’ when running on the target system. This will fail if the corresponding directory does not exist and it is unable to create it. This can be overcome by, for example, setting the environment as ‘GCOV_PREFIX=/target/run’ and ‘GCOV_PREFIX_STRIP=1’. Such a setting will name the data file ‘/target/run/build/foo.gcda’. You must move the data files to the expected directory tree in order to use them for profile directed optimizations (‘-fprofile-use’), or to use the ‘gcov’ tool.  File: gcc.info, Node: Freestanding Environments, Prev: Cross-profiling, Up: Gcov 10.6 Profiling and Test Coverage in Freestanding Environments ============================================================= In case your application runs in a hosted environment such as GNU/Linux, then this section is likely not relevant to you. This section is intended for application developers targeting freestanding environments (for example embedded systems) with limited resources. In particular, systems or test cases which do not support constructors/destructors or the C library file I/O. In this section, the “target system” runs your application instrumented for profiling or test coverage. You develop and analyze your application on the “host system”. We now provide an overview how profiling and test coverage can be obtained in this scenario followed by a tutorial which can be exercised on the host system. Finally, some system initialization caveats are listed. 10.6.1 Overview --------------- For an application instrumented for profiling or test coverage, the compiler generates some global data structures which are updated by instrumentation code while the application runs. These data structures are called the “gcov information”. Normally, when the application exits, the gcov information is stored to ‘.gcda’ files. There is one file per translation unit instrumented for profiling or test coverage. The function ‘__gcov_exit()’, which stores the gcov information to a file, is called by a global destructor function for each translation unit instrumented for profiling or test coverage. It runs at process exit. In a global constructor function, the ‘__gcov_init()’ function is called to register the gcov information of a translation unit in a global list. In some situations, this procedure does not work. Firstly, if you want to profile the global constructor or exit processing of an operating system, the compiler generated functions may conflict with the test objectives. Secondly, you may want to test early parts of the system initialization or abnormal program behaviour which do not allow a global constructor or exit processing. Thirdly, you need a filesystem to store the files. The ‘-fprofile-info-section’ GCC option enables you to use profiling and test coverage in freestanding environments. This option disables the use of global constructors and destructors for the gcov information. Instead, a pointer to the gcov information is stored in a special linker input section for each translation unit which is compiled with this option. By default, the section name is ‘.gcov_info’. The gcov information is statically initialized. The pointers to the gcov information from all translation units of an executable can be collected by the linker in a contiguous memory block. For the GNU linker, the below linker script output section definition can be used to achieve this: .gcov_info : { PROVIDE (__gcov_info_start = .); KEEP (*(.gcov_info)) PROVIDE (__gcov_info_end = .); } The linker will provide two global symbols, ‘__gcov_info_start’ and ‘__gcov_info_end’, which define the start and end of the array of pointers to gcov information blocks, respectively. The ‘KEEP ()’ directive is required to prevent a garbage collection of the pointers. They are not directly referenced by anything in the executable. The section may be placed in a read-only memory area. In order to transfer the profiling and test coverage data from the target to the host system, the application has to provide a function to produce a reliable in order byte stream from the target to the host. The byte stream may be compressed and encoded using error detection and correction codes to meet application-specific requirements. The GCC provided ‘libgcov’ target library provides two functions, ‘__gcov_info_to_gcda()’ and ‘__gcov_filename_to_gcfn()’, to generate a byte stream from a gcov information bock. The functions are declared in ‘#include ’. The byte stream can be deserialized by the ‘merge-stream’ subcommand of the ‘gcov-tool’ to create or update ‘.gcda’ files in the host filesystem for the instrumented application. 10.6.2 Tutorial --------------- This tutorial should be exercised on the host system. We will build a program instrumented for test coverage. The program runs an application and dumps the gcov information to ‘stderr’ encoded as a printable character stream. The application simply decodes such character streams from ‘stdin’ and writes the decoded character stream to ‘stdout’ (warning: this is binary data). The decoded character stream is consumed by the ‘merge-stream’ subcommand of the ‘gcov-tool’ to create or update the ‘.gcda’ files. To get started, create an empty directory. Change into the new directory. Then you will create the following three files in this directory 1. ‘app.h’ - a header file included by ‘app.c’ and ‘main.c’, 2. ‘app.c’ - a source file which contains an example application, and 3. ‘main.c’ - a source file which contains the program main function and code to dump the gcov information. Firstly, create the header file ‘app.h’ with the following content: static const unsigned char a = 'a'; static inline unsigned char * encode (unsigned char c, unsigned char buf[2]) { buf[0] = c % 16 + a; buf[1] = (c / 16) % 16 + a; return buf; } extern void application (void); Secondly, create the source file ‘app.c’ with the following content: #include "app.h" #include /* The application reads a character stream encoded by encode() from stdin, decodes it, and writes the decoded characters to stdout. Characters other than the 16 characters 'a' to 'p' are ignored. */ static int can_decode (unsigned char c) { return (unsigned char)(c - a) < 16; } void application (void) { int first = 1; int i; unsigned char c; while ((i = fgetc (stdin)) != EOF) { unsigned char x = (unsigned char)i; if (can_decode (x)) { if (first) c = x - a; else fputc (c + 16 * (x - a), stdout); first = !first; } else first = 1; } } Thirdly, create the source file ‘main.c’ with the following content: #include "app.h" #include #include #include /* The start and end symbols are provided by the linker script. We use the array notation to avoid issues with a potential small-data area. */ extern const struct gcov_info *const __gcov_info_start[]; extern const struct gcov_info *const __gcov_info_end[]; /* This function shall produce a reliable in order byte stream to transfer the gcov information from the target to the host system. */ static void dump (const void *d, unsigned n, void *arg) { (void)arg; const unsigned char *c = d; unsigned char buf[2]; for (unsigned i = 0; i < n; ++i) fwrite (encode (c[i], buf), sizeof (buf), 1, stderr); } /* The filename is serialized to a gcfn data stream by the __gcov_filename_to_gcfn() function. The gcfn data is used by the "merge-stream" subcommand of the "gcov-tool" to figure out the filename associated with the gcov information. */ static void filename (const char *f, void *arg) { __gcov_filename_to_gcfn (f, dump, arg); } /* The __gcov_info_to_gcda() function may have to allocate memory under certain conditions. Simply try it out if it is needed for your application or not. */ static void * allocate (unsigned length, void *arg) { (void)arg; return malloc (length); } /* Dump the gcov information of all translation units. */ static void dump_gcov_info (void) { const struct gcov_info *const *info = __gcov_info_start; const struct gcov_info *const *end = __gcov_info_end; /* Obfuscate variable to prevent compiler optimizations. */ __asm__ ("" : "+r" (info)); while (info != end) { void *arg = NULL; __gcov_info_to_gcda (*info, filename, dump, allocate, arg); fputc ('\n', stderr); ++info; } } /* The main() function just runs the application and then dumps the gcov information to stderr. */ int main (void) { application (); dump_gcov_info (); return 0; } If we compile ‘app.c’ with test coverage and no extra profiling options, then a global constructor (‘_sub_I_00100_0’ here, it may have a different name in your environment) and destructor (‘_sub_D_00100_1’) is used to register and dump the gcov information, respectively. We also see undefined references to ‘__gcov_init’ and ‘__gcov_exit’: $ gcc --coverage -c app.c $ nm app.o 0000000000000000 r a 0000000000000030 T application 0000000000000000 t can_decode U fgetc U fputc 0000000000000000 b __gcov0.application 0000000000000038 b __gcov0.can_decode 0000000000000000 d __gcov_.application 00000000000000c0 d __gcov_.can_decode U __gcov_exit U __gcov_init U __gcov_merge_add U stdin U stdout 0000000000000161 t _sub_D_00100_1 0000000000000151 t _sub_I_00100_0 Compile ‘app.c’ and ‘main.c’ with test coverage and ‘-fprofile-info-section’. Now, a read-only pointer size object is present in the ‘.gcov_info’ section and there are no undefined references to ‘__gcov_init’ and ‘__gcov_exit’: $ gcc --coverage -fprofile-info-section -c main.c $ gcc --coverage -fprofile-info-section -c app.c $ objdump -h app.o app.o: file format elf64-x86-64 Sections: Idx Name Size VMA LMA File off Algn 0 .text 00000151 0000000000000000 0000000000000000 00000040 2**0 CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE 1 .data 00000100 0000000000000000 0000000000000000 000001a0 2**5 CONTENTS, ALLOC, LOAD, RELOC, DATA 2 .bss 00000040 0000000000000000 0000000000000000 000002a0 2**5 ALLOC 3 .rodata 0000003c 0000000000000000 0000000000000000 000002a0 2**3 CONTENTS, ALLOC, LOAD, READONLY, DATA 4 .gcov_info 00000008 0000000000000000 0000000000000000 000002e0 2**3 CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA 5 .comment 0000004e 0000000000000000 0000000000000000 000002e8 2**0 CONTENTS, READONLY 6 .note.GNU-stack 00000000 0000000000000000 0000000000000000 00000336 2**0 CONTENTS, READONLY 7 .eh_frame 00000058 0000000000000000 0000000000000000 00000338 2**3 CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA We have to customize the program link procedure so that all the ‘.gcov_info’ linker input sections are placed in a contiguous memory block with a begin and end symbol. Firstly, get the default linker script using the following commands (we assume a GNU linker): $ ld --verbose | sed '1,/^===/d' | sed '/^===/d' > linkcmds Secondly, open the file ‘linkcmds’ with a text editor and place the linker output section definition from the overview after the ‘.rodata’ section definition. Link the program executable using the customized linker script: $ gcc --coverage main.o app.o -T linkcmds -Wl,-Map,app.map In the linker map file ‘app.map’, we see that the linker placed the read-only pointer size objects of our objects files ‘main.o’ and ‘app.o’ into a contiguous memory block and provided the symbols ‘__gcov_info_start’ and ‘__gcov_info_end’: $ grep -C 1 "\.gcov_info" app.map .gcov_info 0x0000000000403ac0 0x10 0x0000000000403ac0 PROVIDE (__gcov_info_start = .) *(.gcov_info) .gcov_info 0x0000000000403ac0 0x8 main.o .gcov_info 0x0000000000403ac8 0x8 app.o 0x0000000000403ad0 PROVIDE (__gcov_info_end = .) Make sure no ‘.gcda’ files are present. Run the program with nothing to decode and dump ‘stderr’ to the file ‘gcda-0.txt’ (first run). Run the program to decode ‘gcda-0.txt’ and send it to the ‘gcov-tool’ using the ‘merge-stream’ subcommand to create the ‘.gcda’ files (second run). Run ‘gcov’ to produce a report for ‘app.c’. We see that the first run with nothing to decode results in a partially covered application: $ rm -f app.gcda main.gcda $ echo "" | ./a.out 2>gcda-0.txt $ ./a.out gcda-1.txt | gcov-tool merge-stream $ gcov -bc app.c File 'app.c' Lines executed:69.23% of 13 Branches executed:66.67% of 6 Taken at least once:50.00% of 6 Calls executed:66.67% of 3 Creating 'app.c.gcov' Lines executed:69.23% of 13 Run the program to decode ‘gcda-1.txt’ and send it to the ‘gcov-tool’ using the ‘merge-stream’ subcommand to update the ‘.gcda’ files. Run ‘gcov’ to produce a report for ‘app.c’. Since the second run decoded the gcov information of the first run, we have now a fully covered application: $ ./a.out gcda-2.txt | gcov-tool merge-stream $ gcov -bc app.c File 'app.c' Lines executed:100.00% of 13 Branches executed:100.00% of 6 Taken at least once:100.00% of 6 Calls executed:100.00% of 3 Creating 'app.c.gcov' Lines executed:100.00% of 13 10.6.3 System Initialization Caveats ------------------------------------ The gcov information of a translation unit consists of several global data structures. For example, the instrumented code may update program flow graph edge counters in a zero-initialized data structure. It is safe to run instrumented code before the zero-initialized data is cleared to zero. The coverage information obtained before the zero-initialized data is cleared to zero is unusable. Dumping the gcov information using ‘__gcov_info_to_gcda()’ before the zero-initialized data is cleared to zero or the initialized data is loaded, is undefined behaviour. Clearing the zero-initialized data to zero through a function instrumented for profiling or test coverage is undefined behaviour, since it may produce inconsistent program flow graph edge counters for example.  File: gcc.info, Node: Gcov-tool, Next: Gcov-dump, Prev: Gcov, Up: Top 11 ‘gcov-tool’--an Offline Gcda Profile Processing Tool ******************************************************* ‘gcov-tool’ is a tool you can use in conjunction with GCC to manipulate or process gcda profile files offline. * Menu: * Gcov-tool Intro:: Introduction to gcov-tool. * Invoking Gcov-tool:: How to use gcov-tool.  File: gcc.info, Node: Gcov-tool Intro, Next: Invoking Gcov-tool, Up: Gcov-tool 11.1 Introduction to ‘gcov-tool’ ================================ ‘gcov-tool’ is an offline tool to process gcc's gcda profile files. Current gcov-tool supports the following functionalities: • merge two sets of profiles with weights. • read a stream of profiles with associated filenames and merge it with a set of profiles with weights. • read one set of profile and rewrite profile contents. One can scale or normalize the count values. Examples of the use cases for this tool are: • Collect the profiles for different set of inputs, and use this tool to merge them. One can specify the weight to factor in the relative importance of each input. • Collect profiles from target systems without a filesystem (freestanding environments). Merge the collected profiles with associated profiles present on the host system. One can specify the weight to factor in the relative importance of each input. • Rewrite the profile after removing a subset of the gcda files, while maintaining the consistency of the summary and the histogram. • It can also be used to debug or libgcov code as the tools shares the majority code as the runtime library. Note that for the merging operation, this profile generated offline may contain slight different values from the online merged profile. Here are a list of typical differences: • histogram difference: This offline tool recomputes the histogram after merging the counters. The resulting histogram, therefore, is precise. The online merging does not have this capability - the histogram is merged from two histograms and the result is an approximation. • summary checksum difference: Summary checksum uses a CRC32 operation. The value depends on the link list order of gcov-info objects. This order is different in gcov-tool from that in the online merge. It's expected to have different summary checksums. It does not really matter as the compiler does not use this checksum anywhere. • value profile counter values difference: Some counter values for value profile are runtime dependent, like heap addresses. It's normal to see some difference in these kind of counters.  File: gcc.info, Node: Invoking Gcov-tool, Prev: Gcov-tool Intro, Up: Gcov-tool 11.2 Invoking ‘gcov-tool’ ========================= gcov-tool [GLOBAL-OPTIONS] SUB_COMMAND [SUB_COMMAND-OPTIONS] PROFILE_DIR ‘gcov-tool’ accepts the following options: ‘-h’ ‘--help’ Display help about using ‘gcov-tool’ (on the standard output), and exit without doing any further processing. ‘-v’ ‘--version’ Display the ‘gcov-tool’ version number (on the standard output), and exit without doing any further processing. ‘merge’ Merge two profile directories. ‘-o DIRECTORY’ ‘--output DIRECTORY’ Set the output profile directory. Default output directory name is MERGED_PROFILE. ‘-v’ ‘--verbose’ Set the verbose mode. ‘-w W1,W2’ ‘--weight W1,W2’ Set the merge weights of the DIRECTORY1 and DIRECTORY2, respectively. The default weights are 1 for both. ‘merge-stream’ Collect profiles with associated filenames from a _gcfn_ and _gcda_ data stream. Read the stream from the file specified by FILE or from ‘stdin’. Merge the profiles with associated profiles in the host filesystem. Apply the optional weights while merging profiles. For the generation of a _gcfn_ and _gcda_ data stream on the target system, please have a look at the ‘__gcov_filename_to_gcfn()’ and ‘__gcov_info_to_gcda()’ functions declared in ‘#include ’. ‘-v’ ‘--verbose’ Set the verbose mode. ‘-w W1,W2’ ‘--weight W1,W2’ Set the merge weights of the profiles from the _gcfn_ and _gcda_ data stream and the associated profiles in the host filesystem, respectively. The default weights are 1 for both. ‘rewrite’ Read the specified profile directory and rewrite to a new directory. ‘-n LONG_LONG_VALUE’ ‘--normalize ’ Normalize the profile. The specified value is the max counter value in the new profile. ‘-o DIRECTORY’ ‘--output DIRECTORY’ Set the output profile directory. Default output name is REWRITE_PROFILE. ‘-s FLOAT_OR_SIMPLE-FRAC_VALUE’ ‘--scale FLOAT_OR_SIMPLE-FRAC_VALUE’ Scale the profile counters. The specified value can be in floating point value, or simple fraction value form, such 1, 2, 2/3, and 5/3. ‘-v’ ‘--verbose’ Set the verbose mode. ‘overlap’ Compute the overlap score between the two specified profile directories. The overlap score is computed based on the arc profiles. It is defined as the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all), for all arc counter i, where p1_counter[i] and p2_counter[i] are two matched counters and p1_sum_all and p2_sum_all are the sum of counter values in profile 1 and profile 2, respectively. ‘-f’ ‘--function’ Print function level overlap score. ‘-F’ ‘--fullname’ Print full gcda filename. ‘-h’ ‘--hotonly’ Only print info for hot objects/functions. ‘-o’ ‘--object’ Print object level overlap score. ‘-t FLOAT’ ‘--hot_threshold ’ Set the threshold for hot counter value. ‘-v’ ‘--verbose’ Set the verbose mode.  File: gcc.info, Node: Gcov-dump, Next: lto-dump, Prev: Gcov-tool, Up: Top 12 ‘gcov-dump’--an Offline Gcda and Gcno Profile Dump Tool ********************************************************** * Menu: * Gcov-dump Intro:: Introduction to gcov-dump. * Invoking Gcov-dump:: How to use gcov-dump.  File: gcc.info, Node: Gcov-dump Intro, Next: Invoking Gcov-dump, Up: Gcov-dump 12.1 Introduction to ‘gcov-dump’ ================================ ‘gcov-dump’ is a tool you can use in conjunction with GCC to dump content of gcda and gcno profile files offline.  File: gcc.info, Node: Invoking Gcov-dump, Prev: Gcov-dump Intro, Up: Gcov-dump 12.2 Invoking ‘gcov-dump’ ========================= Usage: gcov-dump [OPTION] ... GCOVFILES ‘gcov-dump’ accepts the following options: ‘-h’ ‘--help’ Display help about using ‘gcov-dump’ (on the standard output), and exit without doing any further processing. ‘-l’ ‘--long’ Dump content of records. ‘-p’ ‘--positions’ Dump positions of records. ‘-r’ ‘--raw’ Print content records in raw format. ‘-s’ ‘--stable’ Print content in stable format usable for comparison. ‘-v’ ‘--version’ Display the ‘gcov-dump’ version number (on the standard output), and exit without doing any further processing.  File: gcc.info, Node: lto-dump, Next: Trouble, Prev: Gcov-dump, Up: Top 13 ‘lto-dump’--Tool for dumping LTO object files. ************************************************* * Menu: * lto-dump Intro:: Introduction to lto-dump. * Invoking lto-dump:: How to use lto-dump.  File: gcc.info, Node: lto-dump Intro, Next: Invoking lto-dump, Up: lto-dump 13.1 Introduction to ‘lto-dump’ =============================== ‘lto-dump’ is a tool you can use in conjunction with GCC to dump link time optimization object files.  File: gcc.info, Node: Invoking lto-dump, Prev: lto-dump Intro, Up: lto-dump 13.2 Invoking ‘lto-dump’ ======================== Usage: lto-dump [OPTION] ... OBJFILES ‘lto-dump’ accepts the following options: ‘-list’ Dumps list of details of functions and variables. ‘-demangle’ Dump the demangled output. ‘-defined-only’ Dump only the defined symbols. ‘-print-value’ Dump initial values of the variables. ‘-name-sort’ Sort the symbols alphabetically. ‘-size-sort’ Sort the symbols according to size. ‘-reverse-sort’ Dump the symbols in reverse order. ‘-no-sort’ Dump the symbols in order of occurrence. ‘-symbol=’ Dump the details of specific symbol. ‘-objects’ Dump the details of LTO objects. ‘-type-stats’ Dump the statistics of tree types. ‘-tree-stats’ Dump the statistics of trees. ‘-gimple-stats’ Dump the statistics of gimple statements. ‘-dump-level=’ For deciding the optimization level of body. ‘-dump-body=’ Dump the specific gimple body. ‘-help’ Display the dump tool help.  File: gcc.info, Node: Trouble, Next: Bugs, Prev: lto-dump, Up: Top 14 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. * Interoperation:: Problems using GCC with other compilers, and with certain linkers, assemblers and debuggers. * 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 cannot change, but not quite bugs. * C++ Misunderstandings:: Common misunderstandings with GNU C++. * 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: Interoperation, Up: Trouble 14.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.  File: gcc.info, Node: Interoperation, Next: Incompatibilities, Prev: Actual Bugs, Up: Trouble 14.2 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. • 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 a SPARC, GCC aligns all values of type ‘double’ on an 8-byte boundary, and it expects every ‘double’ to be so aligned. The Sun compiler usually gives ‘double’ values 8-byte alignment, with one exception: function arguments of type ‘double’ may not be aligned. As a result, if a function compiled with Sun CC takes the address of an argument of type ‘double’ and passes this pointer of type ‘double *’ to a function compiled with GCC, dereferencing the pointer may cause a fatal signal. One way to solve this problem is to compile your entire program with GCC. Another solution is to modify the function that is compiled with Sun CC to copy the argument into a local variable; local variables are always properly aligned. A third solution is to modify the function that uses the pointer to dereference it via the following function ‘access_double’ instead of directly with ‘*’: inline double access_double (double *unaligned_ptr) { union d2i { double d; int i[2]; }; union d2i *p = (union d2i *) unaligned_ptr; union d2i u; u.i[0] = p->i[0]; u.i[1] = p->i[1]; return u.d; } Storing into the pointer can be done likewise with the same union. • On Solaris, the ‘malloc’ function in the ‘libmalloc.a’ library may allocate memory that is only 4 byte aligned. Since GCC on the SPARC assumes that doubles are 8 byte aligned, this may result in a fatal signal if doubles are stored in memory allocated by the ‘libmalloc.a’ library. The solution is to not use the ‘libmalloc.a’ library. Use instead ‘malloc’ and related functions from ‘libc.a’; they do not have this problem. • 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. • 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.  File: gcc.info, Node: Incompatibilities, Next: Fixed Headers, Prev: Interoperation, Up: Trouble 14.3 Incompatibilities of GCC ============================= There are several noteworthy incompatibilities between GNU C and K&R (non-ISO) versions of C. • 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 very old 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 solution to these problems is to change the program to use ‘char’-array variables with initialization strings for these purposes instead of string constants. • ‘-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. • When you use ‘setjmp’ and ‘longjmp’, the only automatic variables guaranteed to remain valid are those declared ‘volatile’. This is a consequence of automatic register allocation. Consider this function: jmp_buf j; foo () { int a, b; a = fun1 (); if (setjmp (j)) return a; a = fun2 (); /* ‘longjmp (j)’ may occur in ‘fun3’. */ return a + fun3 (); } Here ‘a’ may or may not be restored to its first value when the ‘longjmp’ occurs. If ‘a’ is allocated in a register, then its first value is restored; otherwise, it keeps the last value stored in it. If you use the ‘-W’ option with the ‘-O’ option, you will get a warning when GCC thinks such a problem might be possible. • 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. • K&R compilers allow comments to cross over an inclusion boundary (i.e. started in an include file and ended in the including file). • 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, an ‘extern’ declaration affects all the rest of the file even if it happens within a block. • 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’. • PCC allows typedef names to be used as function parameters. • Traditional C 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. 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. • 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 ‘/*...*/’. • 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 target hook ‘TARGET_STRUCT_VALUE_RTX’ tells 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 C90 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 14.4 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’. 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. They can be updated using the ‘mkheaders’ script installed in ‘LIBEXECDIR/gcc/TARGET/VERSION/install-tools/’. • On some systems, 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 the system 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. 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.  File: gcc.info, Node: Standard Libraries, Next: Disappointments, Prev: Fixed Headers, Up: Trouble 14.5 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 14.6 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. They can be updated using the ‘mkheaders’ script installed in ‘LIBEXECDIR/gcc/TARGET/VERSION/install-tools/’. • 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 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. • On AIX, GCC scans object files and library archives for static constructors and destructors when linking an application before the linker prunes unreferenced symbols. This is necessary to prevent the AIX linker from mistakenly assuming that static constructor or destructor are unused and removing them before the scanning can occur. All static constructors and destructors found will be referenced even though the modules in which they occur may not be used by the program. This may lead to both increased executable size and unexpected symbol references.  File: gcc.info, Node: C++ Misunderstandings, Next: Non-bugs, Prev: Disappointments, Up: Trouble 14.7 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 * Name lookup:: Name lookup, templates, and accessing members of base classes * Temporaries:: Temporaries may vanish before you expect * Copy Assignment:: Copy Assignment operators copy virtual bases twice  File: gcc.info, Node: Static Definitions, Next: Name lookup, Up: C++ Misunderstandings 14.7.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: Name lookup, Next: Temporaries, Prev: Static Definitions, Up: C++ Misunderstandings 14.7.2 Name Lookup, Templates, and Accessing Members of Base Classes -------------------------------------------------------------------- The C++ standard prescribes that all names that are not dependent on template parameters are bound to their present definitions when parsing a template function or class.(1) Only names that are dependent are looked up at the point of instantiation. For example, consider void foo(double); struct A { template void f () { foo (1); // 1 int i = N; // 2 T t; t.bar(); // 3 foo (t); // 4 } static const int N; }; Here, the names ‘foo’ and ‘N’ appear in a context that does not depend on the type of ‘T’. The compiler will thus require that they are defined in the context of use in the template, not only before the point of instantiation, and will here use ‘::foo(double)’ and ‘A::N’, respectively. In particular, it will convert the integer value to a ‘double’ when passing it to ‘::foo(double)’. Conversely, ‘bar’ and the call to ‘foo’ in the fourth marked line are used in contexts that do depend on the type of ‘T’, so they are only looked up at the point of instantiation, and you can provide declarations for them after declaring the template, but before instantiating it. In particular, if you instantiate ‘A::f’, the last line will call an overloaded ‘::foo(int)’ if one was provided, even if after the declaration of ‘struct A’. This distinction between lookup of dependent and non-dependent names is called two-stage (or dependent) name lookup. G++ implements it since version 3.4. Two-stage name lookup sometimes leads to situations with behavior different from non-template codes. The most common is probably this: template struct Base { int i; }; template struct Derived : public Base { int get_i() { return i; } }; In ‘get_i()’, ‘i’ is not used in a dependent context, so the compiler will look for a name declared at the enclosing namespace scope (which is the global scope here). It will not look into the base class, since that is dependent and you may declare specializations of ‘Base’ even after declaring ‘Derived’, so the compiler cannot really know what ‘i’ would refer to. If there is no global variable ‘i’, then you will get an error message. In order to make it clear that you want the member of the base class, you need to defer lookup until instantiation time, at which the base class is known. For this, you need to access ‘i’ in a dependent context, by either using ‘this->i’ (remember that ‘this’ is of type ‘Derived*’, so is obviously dependent), or using ‘Base::i’. Alternatively, ‘Base::i’ might be brought into scope by a ‘using’-declaration. Another, similar example involves calling member functions of a base class: template struct Base { int f(); }; template struct Derived : Base { int g() { return f(); }; }; Again, the call to ‘f()’ is not dependent on template arguments (there are no arguments that depend on the type ‘T’, and it is also not otherwise specified that the call should be in a dependent context). Thus a global declaration of such a function must be available, since the one in the base class is not visible until instantiation time. The compiler will consequently produce the following error message: x.cc: In member function `int Derived::g()': x.cc:6: error: there are no arguments to `f' that depend on a template parameter, so a declaration of `f' must be available x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but allowing the use of an undeclared name is deprecated) To make the code valid either use ‘this->f()’, or ‘Base::f()’. Using the ‘-fpermissive’ flag will also let the compiler accept the code, by marking all function calls for which no declaration is visible at the time of definition of the template for later lookup at instantiation time, as if it were a dependent call. We do not recommend using ‘-fpermissive’ to work around invalid code, and it will also only catch cases where functions in base classes are called, not where variables in base classes are used (as in the example above). Note that some compilers (including G++ versions prior to 3.4) get these examples wrong and accept above code without an error. Those compilers do not implement two-stage name lookup correctly. ---------- Footnotes ---------- (1) The C++ standard just uses the term "dependent" for names that depend on the type or value of template parameters. This shorter term will also be used in the rest of this section.  File: gcc.info, Node: Temporaries, Next: Copy Assignment, Prev: Name lookup, Up: C++ Misunderstandings 14.7.3 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: const string& tmp = strfunc (); charfunc (tmp.c_str ());  File: gcc.info, Node: Copy Assignment, Prev: Temporaries, Up: C++ Misunderstandings 14.7.4 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(const char *n) : name(strdup(n)){} Base& operator= (const Base& other){ free (name); name = strdup (other.name); return *this; } }; 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 more than once. In the example, copying proceeds in the following order: ‘name’ (via ‘strdup’), ‘val’, ‘name’ again, and ‘bval’. 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: Non-bugs, Next: Warnings and Errors, Prev: C++ Misunderstandings, Up: Trouble 14.8 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. C contains many standard functions that return a value that most programs choose to ignore. One obvious example is ‘printf’. Warning about this practice only leads the defensive programmer to clutter programs with dozens of casts to ‘void’. Such casts are required so frequently that they become visual noise. Writing those casts becomes so automatic that they no longer convey useful information about the intentions of the programmer. For functions where the return value should never be ignored, use the ‘warn_unused_result’ function attribute (*note Function Attributes::). • 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__’ unconditionally. 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. This held for carefully written C compiled with less powerful optimizers but is not always the case for carefully written C++ or with more powerful optimizers. Thus GCC will remove operations from loops whenever it can determine those operations are not externally visible (apart from the time taken to execute them, of course). In case the loop can be proved to be finite, GCC will also remove the loop itself. Be aware of this when performing timing tests, for instance the following loop can be completely removed, provided ‘some_expression’ can provably not change any global state. { int sum = 0; int ix; for (ix = 0; ix != 10000; ix++) sum += some_expression; } Even though ‘sum’ is accumulated in the loop, no use is made of that summation, so the accumulation can be removed. • 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’. • 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 testsuites 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 14.9 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 15 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. * Menu: * Criteria: Bug Criteria. Have you really found a bug? * Reporting: Bug Reporting. How to report a bug effectively.  File: gcc.info, Node: Bug Criteria, Next: Bug Reporting, Up: Bugs 15.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 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 someone else's 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 Reporting, Prev: Bug Criteria, Up: Bugs 15.2 How and Where to Report Bugs ================================= Bugs should be reported to the bug database at .  File: gcc.info, Node: Service, Next: Contributing, Prev: Bugs, Up: Top 16 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 . For further information, see .  File: gcc.info, Node: Contributing, Next: Funding, Prev: Service, Up: Top 17 Contributing to GCC Development ********************************** If you would like to help pretest GCC releases to assure they work well, current development sources are available via Git (see ). Source and binary snapshots are also available for FTP; see . If you would like to work on improvements to GCC, please read the advice at these URLs: for information on how to make useful contributions and avoid duplication of effort. Suggested projects are listed at .  File: gcc.info, Node: Funding, Next: GNU Project, Prev: Contributing, 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 © 1994 Free Software Foundation, Inc. Verbatim copying and redistribution of this section is permitted without royalty; alteration is not permitted.