GCC supports a number of command-line options that control adding run-time instrumentation to the code it normally generates. For example, one purpose of instrumentation is collect profiling statistics for use in finding program hot spots, code coverage analysis, or profile-guided optimizations. Another class of program instrumentation is adding run-time checking to detect programming errors like invalid pointer dereferences or out-of-bounds array accesses, as well as deliberately hostile attacks such as stack smashing or C++ vtable hijacking. There is also a general hook which can be used to implement other forms of tracing or function-level instrumentation for debug or program analysis purposes.
-pprof. You must use this option when compiling the source files you want data about, and you must also use it when linking.
-pggprof. You must use this option when compiling the source files you want data about, and you must also use it when linking. -fprofile-arcs-fbranch-probabilities), or for test coverage analysis (-ftest-coverage). Each object file's auxname is generated from the name of the output file, if explicitly specified and it is not the final executable, otherwise it is the basename of the source file. In both cases any suffix is removed (e.g. foo.gcda for input file dir/foo.c, or dir/foo.gcda for output file specified as -o dir/foo.o). See Cross-profiling.
--coverage-fprofile-arcs -ftest-coverage (when compiling) and -lgcov (when linking). See the documentation for those options for more details. -fprofile-arcs plus optimization and code generation options. For test coverage analysis, use the additional -ftest-coverage option. You do not need to profile every source file in a program. -lgcov or -fprofile-arcs (the latter implies the former). fork calls are detected and correctly handled (double counting will not happen). -fbranch-probabilities (see Options that Control Optimization). gcov to produce human readable information from the .gcno and .gcda files. Refer to the gcov documentation for further information. With -fprofile-arcs, for each function of your program GCC creates a program flow graph, then finds a spanning tree for the graph. Only arcs that are not on the spanning tree have to be instrumented: the compiler adds code to count the number of times that these arcs are executed. When an arc is the only exit or only entrance to a block, the instrumentation code can be added to the block; otherwise, a new basic block must be created to hold the instrumentation code.
-ftest-coveragegcov code-coverage utility (see gcov—a Test Coverage Program) can use to show program coverage. Each source file's note file is called auxname.gcno. Refer to the -fprofile-arcs option above for a description of auxname and instructions on how to generate test coverage data. Coverage data matches the source files more closely if you do not optimize. -fprofile-dir=path
-fprofile-generate, -ftest-coverage, -fprofile-arcs and used by -fprofile-use and -fbranch-probabilities and its related options. Both absolute and relative paths can be used. By default, GCC uses the current directory as path, thus the profile data file appears in the same directory as the object file. -fprofile-generate-fprofile-generate=path
-fprofile-generate both when compiling and when linking your program. The following options are enabled: -fprofile-arcs, -fprofile-values, -fvpt.
If path is specified, GCC looks at the path to find the profile feedback data files. See -fprofile-dir.
To optimize the program based on the collected profile information, use -fprofile-use. See Optimize Options, for more information.
-fsanitize=addressASAN_OPTIONS environment variable. When set to help=1, the available options are shown at startup of the instrumented program. See https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags for a list of supported options. -fsanitize=kernel-address-fsanitize=threadTSAN_OPTIONS environment variable; see https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags for a list of supported options. -fsanitize=leak-fsanitize=address nor -fsanitize=thread is used. In that case the executable is linked against a library that overrides malloc and other allocator functions. See https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer for more details. The run-time behavior can be influenced using the LSAN_OPTIONS environment variable. -fsanitize=undefined-fsanitize=shift-fsanitize=integer-divide-by-zeroINT_MIN / -1 division. -fsanitize=unreachable__builtin_unreachable call into a diagnostics message call instead. When reaching the __builtin_unreachable call, the behavior is undefined. -fsanitize=vla-bound-fsanitize=null-fsanitize=return-fsanitize=signed-integer-overflow+, *, and both unary and binary - does not overflow in the signed arithmetics. Note, integer promotion rules must be taken into account. That is, the following is not an overflow: signed char a = SCHAR_MAX; a++;
-fsanitize=bounds-fsanitize=bounds-strict-fsanitize=alignment-fsanitize=object-size__builtin_object_size function. Various out of bounds pointer accesses are detected. -fsanitize=float-divide-by-zero-fsanitize=float-divide-by-zero is not enabled by -fsanitize=undefined, since floating-point division by zero can be a legitimate way of obtaining infinities and NaNs. -fsanitize=float-cast-overflow-fsanitize=float-cast-overflow is not enabled by -fsanitize=undefined. This option does not work well with FE_INVALID exceptions enabled. -fsanitize=nonnull-attributenonnull function attribute. -fsanitize=returns-nonnull-attributereturns_nonnull function attribute, to detect returning of null values from such functions. -fsanitize=bool-fsanitize=enum-fsanitize=vptrWhile -ftrapv causes traps for signed overflows to be emitted, -fsanitize=undefined gives a diagnostic message. This currently works only for the C family of languages.
-fno-sanitize=all-fsanitize=all is not allowed, as some sanitizers cannot be used together. -fasan-shadow-offset=number
-fsanitize-sections=s1,s2,...
-fsanitize-recover[=opts]
-fsanitize-recover= controls error recovery mode for sanitizers mentioned in comma-separated list of opts. Enabling this option for a sanitizer component causes it to attempt to continue running the program as if no error happened. This means multiple runtime errors can be reported in a single program run, and the exit code of the program may indicate success even when errors have been reported. The -fno-sanitize-recover= option can be used to alter this behavior: only the first detected error is reported and program then exits with a non-zero exit code. Currently this feature only works for -fsanitize=undefined (and its suboptions except for -fsanitize=unreachable and -fsanitize=return), -fsanitize=float-cast-overflow, -fsanitize=float-divide-by-zero, -fsanitize=kernel-address and -fsanitize=address. For these sanitizers error recovery is turned on by default, except -fsanitize=address, for which this feature is experimental. -fsanitize-recover=all and -fno-sanitize-recover=all is also accepted, the former enables recovery for all sanitizers that support it, the latter disables recovery for all sanitizers that support it.
Syntax without explicit opts parameter is deprecated. It is equivalent to
-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
Similarly -fno-sanitize-recover is equivalent to
-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
-fsanitize-undefined-trap-on-error-fsanitize-undefined-trap-on-error option instructs the compiler to report undefined behavior using __builtin_trap rather than a libubsan library routine. The advantage of this is that the libubsan library is not needed and is not linked in, so this is usable even in freestanding environments. -fsanitize-coverage=trace-pc__sanitizer_cov_trace_pc into every basic block. -fbounds-check-fcheck-pointer-boundsCurrently there is only an implementation for Intel MPX available, thus x86 GNU/Linux target and -mmpx are required to enable this feature. MPX-based instrumentation requires a runtime library to enable MPX in hardware and handle bounds violation signals. By default when -fcheck-pointer-bounds and -mmpx options are used to link a program, the GCC driver links against the libmpx and libmpxwrappers libraries. Bounds checking on calls to dynamic libraries requires a linker with -z bndplt support; if GCC was configured with a linker without support for this option (including the Gold linker and older versions of ld), a warning is given if you link with -mmpx without also specifying -static, since the overall effectiveness of the bounds checking protection is reduced. See also -static-libmpxwrappers.
MPX-based instrumentation may be used for debugging and also may be included in production code to increase program security. Depending on usage, you may have different requirements for the runtime library. The current version of the MPX runtime library is more oriented for use as a debugging tool. MPX runtime library usage implies -lpthread. See also -static-libmpx. The runtime library behavior can be influenced using various CHKP_RT_* environment variables. See https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler for more details.
Generated instrumentation may be controlled by various -fchkp-* options and by the bnd_variable_size structure field attribute (see Type Attributes) and bnd_legacy, and bnd_instrument function attributes (see Function Attributes). GCC also provides a number of built-in functions for controlling the Pointer Bounds Checker. See Pointer Bounds Checker builtins, for more information.
-fchkp-check-incomplete-type-fchkp-narrow-bounds-fchkp-narrow-to-innermost-array and -fchkp-first-field-has-own-bounds. Enabled by default. -fchkp-first-field-has-own-bounds-fchkp-narrow-to-innermost-array-fchkp-optimize-O, -O2, -O3. -fchkp-use-fast-string-functions*_nobnd versions of string functions (not copying bounds) by Pointer Bounds Checker. Disabled by default. -fchkp-use-nochk-string-functions*_nochk versions of string functions (not checking bounds) by Pointer Bounds Checker. Disabled by default. -fchkp-use-static-bounds-fchkp-use-static-const-bounds-fchkp-use-static-bounds is enabled. -fchkp-treat-zero-dynamic-size-as-infinite-fchkp-check-read-fchkp-check-write-fchkp-store-bounds-fchkp-instrument-calls-fchkp-instrument-marked-onlybnd_instrument attribute (see Function Attributes). Disabled by default. -fchkp-use-wrappers-fchkp-use-wrappers is used to link a program, the GCC driver automatically links against libmpxwrappers. See also -static-libmpxwrappers. Enabled by default. -fstack-protectoralloca, and functions with buffers larger than 8 bytes. The guards are initialized when a function is entered and then checked when the function exits. If a guard check fails, an error message is printed and the program exits. -fstack-protector-all-fstack-protector except that all functions are protected. -fstack-protector-strong-fstack-protector but includes additional functions to be protected — those that have local array definitions, or have references to local frame addresses. -fstack-protector-explicit-fstack-protector but only protects those functions which have the stack_protect attribute. -fstack-checkNote that this switch does not actually cause checking to be done; the operating system or the language runtime must do that. The switch causes generation of code to ensure that they see the stack being extended.
You can additionally specify a string parameter: ‘no’ means no checking, ‘generic’ means force the use of old-style checking, ‘specific’ means use the best checking method and is equivalent to bare -fstack-check.
Old-style checking is a generic mechanism that requires no specific target support in the compiler but comes with the following drawbacks:
Note that old-style stack checking is also the fallback method for ‘specific’ if no target support has been added in the compiler.
-fstack-limit-register=reg-fstack-limit-symbol=sym-fno-stack-limitFor instance, if the stack starts at absolute address ‘0x80000000’ and grows downwards, you can use the flags -fstack-limit-symbol=__stack_limit and -Wl,--defsym,__stack_limit=0x7ffe0000 to enforce a stack limit of 128KB. Note that this may only work with the GNU linker.
You can locally override stack limit checking by using the no_stack_limit function attribute (see Function Attributes).
-fsplit-stackWhen code compiled with -fsplit-stack calls code compiled without -fsplit-stack, there may not be much stack space available for the latter code to run. If compiling all code, including library code, with -fsplit-stack is not an option, then the linker can fix up these calls so that the code compiled without -fsplit-stack always has a large stack. Support for this is implemented in the gold linker in GNU binutils release 2.21 and later.
-fvtable-verify=[std|preinit|none]
-fvtable-verify=none) the security feature that verifies at run time, for every virtual call, that the vtable pointer through which the call is made is valid for the type of the object, and has not been corrupted or overwritten. If an invalid vtable pointer is detected at run time, an error is reported and execution of the program is immediately halted. This option causes run-time data structures to be built at program startup, which are used for verifying the vtable pointers. The options ‘std’ and ‘preinit’ control the timing of when these data structures are built. In both cases the data structures are built before execution reaches main. Using -fvtable-verify=std causes the data structures to be built after shared libraries have been loaded and initialized. -fvtable-verify=preinit causes them to be built before shared libraries have been loaded and initialized.
If this option appears multiple times in the command line with different values specified, ‘none’ takes highest priority over both ‘std’ and ‘preinit’; ‘preinit’ takes priority over ‘std’.
-fvtv-debug-fvtable-verify=std or -fvtable-verify=preinit, causes debug versions of the runtime functions for the vtable verification feature to be called. This flag also causes the compiler to log information about which vtable pointers it finds for each class. This information is written to a file named vtv_set_ptr_data.log in the directory named by the environment variable VTV_LOGS_DIR if that is defined or the current working directory otherwise. Note: This feature appends data to the log file. If you want a fresh log file, be sure to delete any existing one.
-fvtv-counts-fvtable-verify=std or -fvtable-verify=preinit, this causes the compiler to keep track of the total number of virtual calls it encounters and the number of verifications it inserts. It also counts the number of calls to certain run-time library functions that it inserts and logs this information for each compilation unit. The compiler writes this information to a file named vtv_count_data.log in the directory named by the environment variable VTV_LOGS_DIR if that is defined or the current working directory otherwise. It also counts the size of the vtable pointer sets for each class, and writes this information to vtv_class_set_sizes.log in the same directory. Note: This feature appends data to the log files. To get fresh log files, be sure to delete any existing ones.
-finstrument-functions__builtin_return_address does not work beyond the current function, so the call site information may not be available to the profiling functions otherwise.) void __cyg_profile_func_enter (void *this_fn,
void *call_site);
void __cyg_profile_func_exit (void *this_fn,
void *call_site); The first argument is the address of the start of the current function, which may be looked up exactly in the symbol table.
This instrumentation is also done for functions expanded inline in other functions. The profiling calls indicate where, conceptually, the inline function is entered and exited. This means that addressable versions of such functions must be available. If all your uses of a function are expanded inline, this may mean an additional expansion of code size. If you use extern inline in your C code, an addressable version of such functions must be provided. (This is normally the case anyway, but if you get lucky and the optimizer always expands the functions inline, you might have gotten away without providing static copies.)
A function may be given the attribute no_instrument_function, in which case this instrumentation is not done. This can be used, for example, for the profiling functions listed above, high-priority interrupt routines, and any functions from which the profiling functions cannot safely be called (perhaps signal handlers, if the profiling routines generate output or allocate memory).
-finstrument-functions-exclude-file-list=file,file,...
-finstrument-functions). If the file that contains a function definition matches with one of file, then that function is not instrumented. The match is done on substrings: if the file parameter is a substring of the file name, it is considered to be a match. For example:
-finstrument-functions-exclude-file-list=/bits/stl,include/sys
excludes any inline function defined in files whose pathnames contain /bits/stl or include/sys.
If, for some reason, you want to include letter ‘,’ in one of sym, write ‘\,’. For example, -finstrument-functions-exclude-file-list='\,\,tmp' (note the single quote surrounding the option).
-finstrument-functions-exclude-function-list=sym,sym,...
-finstrument-functions-exclude-file-list, but this option sets the list of function names to be excluded from instrumentation. The function name to be matched is its user-visible name, such as vector<int> blah(const vector<int> &), not the internal mangled name (e.g., _Z4blahRSt6vectorIiSaIiEE). The match is done on substrings: if the sym parameter is a substring of the function name, it is considered to be a match. For C99 and C++ extended identifiers, the function name must be given in UTF-8, not using universal character names.
© Free Software Foundation
Licensed under the GNU Free Documentation License, Version 1.3.
https://gcc.gnu.org/onlinedocs/gcc-6.3.0/gcc/Instrumentation-Options.html