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.
-p-pg-fprofile-arcsWhen the compiled program exits it saves this data to a file called auxname.gcda for each source file. The data may be used for profile-directed optimizations (-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.
--coveragefork calls are
detected and correctly handled without double counting.
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-coverage-fprofile-abs-path-fprofile-dir=path-fprofile-generate-fprofile-generate=pathThe 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.
-fprofile-update=methodWarning: When an application does not properly join all threads (or creates an detached thread), a profile file can be still corrupted.
Using ‘prefer-atomic’ would be transformed either to ‘atomic’,
when supported by a target, or to ‘single’ otherwise. The GCC driver
automatically selects ‘prefer-atomic’ when -pthread
is present in the command line.
-fsanitize=addresshelp=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.
The option cannot be combined with -fsanitize=thread
and/or -fcheck-pointer-bounds.
-fsanitize=kernel-address-fsanitize=pointer-comparedetect_invalid_pointer_pairs=2 to the environment variable
ASAN_OPTIONS. Using detect_invalid_pointer_pairs=1 detects
invalid operation only when both pointers are non-null.
-fsanitize=pointer-subtractdetect_invalid_pointer_pairs=2 to the environment variable
ASAN_OPTIONS. Using detect_invalid_pointer_pairs=1 detects
invalid operation only when both pointers are non-null.
-fsanitize=threadNote that sanitized atomic builtins cannot throw exceptions when
operating on invalid memory addresses with non-call exceptions
(-fnon-call-exceptions).
-fsanitize=leakmalloc
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.
The option cannot be combined with -fsanitize=thread.
-fsanitize=undefined-fsanitize=shift-fsanitize=shift-exponent-fsanitize=shift-base-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-cast-overflowFE_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=vptr-fsanitize=pointer-overflow-fsanitize=builtin__builtin_ctz
or __builtin_clz invokes undefined behavior and is diagnosed
by this option.
While -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-fasan-shadow-offset=number-fsanitize-sections=s1,s2,...-fsanitize-recover[=opts]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=bounds-strict, -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.
Even if a recovery mode is turned on the compiler side, it needs to be also
enabled on the runtime library side, otherwise the failures are still fatal.
The runtime library defaults to halt_on_error=0 for
ThreadSanitizer and UndefinedBehaviorSanitizer, while default value for
AddressSanitizer is halt_on_error=1. This can be overridden through
setting the halt_on_error flag in the corresponding environment variable.
Syntax without an explicit opts parameter is deprecated. It is equivalent to specifying an opts list of:
undefined,float-cast-overflow,float-divide-by-zero,bounds-strict
-fsanitize-address-use-after-scope-fsanitize-undefined-trap-on-error__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.
-fsanitize-coverage=trace-cmp__sanitizer_cov_trace_cmp1,
__sanitizer_cov_trace_cmp2, __sanitizer_cov_trace_cmp4 or
__sanitizer_cov_trace_cmp8 for integral comparison with both operands
variable or __sanitizer_cov_trace_const_cmp1,
__sanitizer_cov_trace_const_cmp2,
__sanitizer_cov_trace_const_cmp4 or
__sanitizer_cov_trace_const_cmp8 for integral comparison with one
operand constant, __sanitizer_cov_trace_cmpf or
__sanitizer_cov_trace_cmpd for float or double comparisons and
__sanitizer_cov_trace_switch for switch statements.
-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-first-field-has-own-bounds-fchkp-flexible-struct-trailing-arrays-fchkp-narrow-to-innermost-array-fchkp-optimize-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-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-fcf-protection=[full|branch|return|none]The value branch tells the compiler to implement checking of
validity of control-flow transfer at the point of indirect branch
instructions, i.e. call/jmp instructions. The value return
implements checking of validity at the point of returning from a
function. The value full is an alias for specifying both
branch and return. The value none turns off
instrumentation.
The macro __CET__ is defined when -fcf-protection is
used. The first bit of __CET__ is set to 1 for the value
branch and the second bit of __CET__ is set to 1 for
the return.
You can also use the nocf_check attribute to identify
which functions and calls should be skipped from instrumentation
(see Function Attributes).
Currently the x86 GNU/Linux target provides an implementation based
on Intel Control-flow Enforcement Technology (CET).
-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-strong-fstack-protector-explicitstack_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-check=’ is designed for Ada's needs to detect infinite recursion
and stack overflows. ‘specific’ is an excellent choice when compiling
Ada code. It is not generally sufficient to protect against stack-clash
attacks. To protect against those you want ‘-fstack-clash-protection’.
-fstack-clash-protectionMost targets do not fully support stack clash protection. However, on
those targets -fstack-clash-protection will protect dynamic stack
allocations. -fstack-clash-protection may also provide limited
protection for static stack allocations if the target supports
-fstack-check=specific.
-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]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-debugNote: This feature appends data to the log file. If you want a fresh log
file, be sure to delete any existing one.
-fvtv-countsNote: 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,...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,...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.
-fpatchable-function-entry=N[,M]0 so the
function entry points to the address just at the first NOP.
The NOP instructions reserve extra space which can be used to patch in
any desired instrumentation at run time, provided that the code segment
is writable. The amount of space is controllable indirectly via
the number of NOPs; the NOP instruction used corresponds to the instruction
emitted by the internal GCC back-end interface gen_nop. This behavior
is target-specific and may also depend on the architecture variant and/or
other compilation options.
For run-time identification, the starting addresses of these areas,
which correspond to their respective function entries minus M,
are additionally collected in the __patchable_function_entries
section of the resulting binary.
Note that the value of __attribute__ ((patchable_function_entry
(N,M))) takes precedence over command-line option
-fpatchable-function-entry=N,M. This can be used to increase
the area size or to remove it completely on a single function.
If N=0, no pad location is recorded.
The NOP instructions are inserted at—and maybe before, depending on M—the function entry address, even before the prologue.