gcc: Instrumentation Options
1
1 3.11 Program Instrumentation Options
1 ====================================
1
1 GCC supports a number of command-line options that control adding
1 run-time instrumentation to the code it normally generates. For
1 example, one purpose of instrumentation is collect profiling statistics
1 for use in finding program hot spots, code coverage analysis, or
1 profile-guided optimizations. Another class of program instrumentation
1 is adding run-time checking to detect programming errors like invalid
1 pointer dereferences or out-of-bounds array accesses, as well as
1 deliberately hostile attacks such as stack smashing or C++ vtable
1 hijacking. There is also a general hook which can be used to implement
1 other forms of tracing or function-level instrumentation for debug or
1 program analysis purposes.
1
1 '-p'
1 Generate extra code to write profile information suitable for the
1 analysis program 'prof'. You must use this option when compiling
1 the source files you want data about, and you must also use it when
1 linking.
1
1 '-pg'
1 Generate extra code to write profile information suitable for the
1 analysis program 'gprof'. You must use this option when compiling
1 the source files you want data about, and you must also use it when
1 linking.
1
1 '-fprofile-arcs'
1 Add code so that program flow "arcs" are instrumented. During
1 execution the program records how many times each branch and call
1 is executed and how many times it is taken or returns. On targets
1 that support constructors with priority support, profiling properly
1 handles constructors, destructors and C++ constructors (and
1 destructors) of classes which are used as a type of a global
1 variable.
1
1 When the compiled program exits it saves this data to a file called
1 'AUXNAME.gcda' for each source file. The data may be used for
1 profile-directed optimizations ('-fbranch-probabilities'), or for
1 test coverage analysis ('-ftest-coverage'). Each object file's
1 AUXNAME is generated from the name of the output file, if
1 explicitly specified and it is not the final executable, otherwise
1 it is the basename of the source file. In both cases any suffix is
1 removed (e.g. 'foo.gcda' for input file 'dir/foo.c', or
11 'dir/foo.gcda' for output file specified as '-o dir/foo.o'). ⇒
Cross-profiling.
1
1 '--coverage'
1
1 This option is used to compile and link code instrumented for
1 coverage analysis. The option is a synonym for '-fprofile-arcs'
1 '-ftest-coverage' (when compiling) and '-lgcov' (when linking).
1 See the documentation for those options for more details.
1
1 * Compile the source files with '-fprofile-arcs' plus
1 optimization and code generation options. For test coverage
1 analysis, use the additional '-ftest-coverage' option. You do
1 not need to profile every source file in a program.
1
1 * Compile the source files additionally with
1 '-fprofile-abs-path' to create absolute path names in the
1 '.gcno' files. This allows 'gcov' to find the correct sources
1 in projects where compilations occur with different working
1 directories.
1
1 * Link your object files with '-lgcov' or '-fprofile-arcs' (the
1 latter implies the former).
1
1 * Run the program on a representative workload to generate the
1 arc profile information. This may be repeated any number of
1 times. You can run concurrent instances of your program, and
1 provided that the file system supports locking, the data files
1 will be correctly updated. Unless a strict ISO C dialect
1 option is in effect, 'fork' calls are detected and correctly
1 handled without double counting.
1
1 * For profile-directed optimizations, compile the source files
1 again with the same optimization and code generation options
11 plus '-fbranch-probabilities' (⇒Options that Control
Optimization Optimize Options.).
1
1 * For test coverage analysis, use 'gcov' to produce human
1 readable information from the '.gcno' and '.gcda' files.
1 Refer to the 'gcov' documentation for further information.
1
1 With '-fprofile-arcs', for each function of your program GCC
1 creates a program flow graph, then finds a spanning tree for the
1 graph. Only arcs that are not on the spanning tree have to be
1 instrumented: the compiler adds code to count the number of times
1 that these arcs are executed. When an arc is the only exit or only
1 entrance to a block, the instrumentation code can be added to the
1 block; otherwise, a new basic block must be created to hold the
1 instrumentation code.
1
1 '-ftest-coverage'
11 Produce a notes file that the 'gcov' code-coverage utility (⇒
'gcov'--a Test Coverage Program Gcov.) can use to show program
1 coverage. Each source file's note file is called 'AUXNAME.gcno'.
1 Refer to the '-fprofile-arcs' option above for a description of
1 AUXNAME and instructions on how to generate test coverage data.
1 Coverage data matches the source files more closely if you do not
1 optimize.
1
1 '-fprofile-abs-path'
1 Automatically convert relative source file names to absolute path
1 names in the '.gcno' files. This allows 'gcov' to find the correct
1 sources in projects where compilations occur with different working
1 directories.
1
1 '-fprofile-dir=PATH'
1
1 Set the directory to search for the profile data files in to PATH.
1 This option affects only the profile data generated by
1 '-fprofile-generate', '-ftest-coverage', '-fprofile-arcs' and used
1 by '-fprofile-use' and '-fbranch-probabilities' and its related
1 options. Both absolute and relative paths can be used. By
1 default, GCC uses the current directory as PATH, thus the profile
1 data file appears in the same directory as the object file.
1
1 '-fprofile-generate'
1 '-fprofile-generate=PATH'
1
1 Enable options usually used for instrumenting application to
1 produce profile useful for later recompilation with profile
1 feedback based optimization. You must use '-fprofile-generate'
1 both when compiling and when linking your program.
1
1 The following options are enabled: '-fprofile-arcs',
1 '-fprofile-values', '-fvpt'.
1
1 If PATH is specified, GCC looks at the PATH to find the profile
1 feedback data files. See '-fprofile-dir'.
1
1 To optimize the program based on the collected profile information,
1 use '-fprofile-use'. ⇒Optimize Options, for more
1 information.
1
1 '-fprofile-update=METHOD'
1
1 Alter the update method for an application instrumented for profile
1 feedback based optimization. The METHOD argument should be one of
1 'single', 'atomic' or 'prefer-atomic'. The first one is useful for
1 single-threaded applications, while the second one prevents profile
1 corruption by emitting thread-safe code.
1
1 *Warning:* When an application does not properly join all threads
1 (or creates an detached thread), a profile file can be still
1 corrupted.
1
1 Using 'prefer-atomic' would be transformed either to 'atomic', when
1 supported by a target, or to 'single' otherwise. The GCC driver
1 automatically selects 'prefer-atomic' when '-pthread' is present in
1 the command line.
1
1 '-fsanitize=address'
1 Enable AddressSanitizer, a fast memory error detector. Memory
1 access instructions are instrumented to detect out-of-bounds and
1 use-after-free bugs. The option enables
1 '-fsanitize-address-use-after-scope'. See
1 <https://github.com/google/sanitizers/wiki/AddressSanitizer> for
1 more details. The run-time behavior can be influenced using the
1 'ASAN_OPTIONS' environment variable. When set to 'help=1', the
1 available options are shown at startup of the instrumented program.
1 See
1 <https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags>
1 for a list of supported options. The option cannot be combined
1 with '-fsanitize=thread' and/or '-fcheck-pointer-bounds'.
1
1 '-fsanitize=kernel-address'
1 Enable AddressSanitizer for Linux kernel. See
1 <https://github.com/google/kasan/wiki> for more details. The
1 option cannot be combined with '-fcheck-pointer-bounds'.
1
1 '-fsanitize=pointer-compare'
1 Instrument comparison operation (<, <=, >, >=) with pointer
1 operands. The option must be combined with either
1 '-fsanitize=kernel-address' or '-fsanitize=address' The option
1 cannot be combined with '-fsanitize=thread' and/or
1 '-fcheck-pointer-bounds'. Note: By default the check is disabled
1 at run time. To enable it, add 'detect_invalid_pointer_pairs=2' to
1 the environment variable 'ASAN_OPTIONS'. Using
1 'detect_invalid_pointer_pairs=1' detects invalid operation only
1 when both pointers are non-null.
1
1 '-fsanitize=pointer-subtract'
1 Instrument subtraction with pointer operands. The option must be
1 combined with either '-fsanitize=kernel-address' or
1 '-fsanitize=address' The option cannot be combined with
1 '-fsanitize=thread' and/or '-fcheck-pointer-bounds'. Note: By
1 default the check is disabled at run time. To enable it, add
1 'detect_invalid_pointer_pairs=2' to the environment variable
1 'ASAN_OPTIONS'. Using 'detect_invalid_pointer_pairs=1' detects
1 invalid operation only when both pointers are non-null.
1
1 '-fsanitize=thread'
1 Enable ThreadSanitizer, a fast data race detector. Memory access
1 instructions are instrumented to detect data race bugs. See
1 <https://github.com/google/sanitizers/wiki#threadsanitizer> for
1 more details. The run-time behavior can be influenced using the
1 'TSAN_OPTIONS' environment variable; see
1 <https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags>
1 for a list of supported options. The option cannot be combined
1 with '-fsanitize=address', '-fsanitize=leak' and/or
1 '-fcheck-pointer-bounds'.
1
1 Note that sanitized atomic builtins cannot throw exceptions when
1 operating on invalid memory addresses with non-call exceptions
1 ('-fnon-call-exceptions').
1
1 '-fsanitize=leak'
1 Enable LeakSanitizer, a memory leak detector. This option only
1 matters for linking of executables and the executable is linked
1 against a library that overrides 'malloc' and other allocator
1 functions. See
1 <https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer>
1 for more details. The run-time behavior can be influenced using
1 the 'LSAN_OPTIONS' environment variable. The option cannot be
1 combined with '-fsanitize=thread'.
1
1 '-fsanitize=undefined'
1 Enable UndefinedBehaviorSanitizer, a fast undefined behavior
1 detector. Various computations are instrumented to detect
1 undefined behavior at runtime. Current suboptions are:
1
1 '-fsanitize=shift'
1 This option enables checking that the result of a shift
1 operation is not undefined. Note that what exactly is
1 considered undefined differs slightly between C and C++, as
1 well as between ISO C90 and C99, etc. This option has two
1 suboptions, '-fsanitize=shift-base' and
1 '-fsanitize=shift-exponent'.
1
1 '-fsanitize=shift-exponent'
1 This option enables checking that the second argument of a
1 shift operation is not negative and is smaller than the
1 precision of the promoted first argument.
1
1 '-fsanitize=shift-base'
1 If the second argument of a shift operation is within range,
1 check that the result of a shift operation is not undefined.
1 Note that what exactly is considered undefined differs
1 slightly between C and C++, as well as between ISO C90 and
1 C99, etc.
1
1 '-fsanitize=integer-divide-by-zero'
1 Detect integer division by zero as well as 'INT_MIN / -1'
1 division.
1
1 '-fsanitize=unreachable'
1 With this option, the compiler turns the
1 '__builtin_unreachable' call into a diagnostics message call
1 instead. When reaching the '__builtin_unreachable' call, the
1 behavior is undefined.
1
1 '-fsanitize=vla-bound'
1 This option instructs the compiler to check that the size of a
1 variable length array is positive.
1
1 '-fsanitize=null'
1 This option enables pointer checking. Particularly, the
1 application built with this option turned on will issue an
1 error message when it tries to dereference a NULL pointer, or
1 if a reference (possibly an rvalue reference) is bound to a
1 NULL pointer, or if a method is invoked on an object pointed
1 by a NULL pointer.
1
1 '-fsanitize=return'
1 This option enables return statement checking. Programs built
1 with this option turned on will issue an error message when
1 the end of a non-void function is reached without actually
1 returning a value. This option works in C++ only.
1
1 '-fsanitize=signed-integer-overflow'
1 This option enables signed integer overflow checking. We
1 check that the result of '+', '*', and both unary and binary
1 '-' does not overflow in the signed arithmetics. Note,
1 integer promotion rules must be taken into account. That is,
1 the following is not an overflow:
1 signed char a = SCHAR_MAX;
1 a++;
1
1 '-fsanitize=bounds'
1 This option enables instrumentation of array bounds. Various
1 out of bounds accesses are detected. Flexible array members,
1 flexible array member-like arrays, and initializers of
1 variables with static storage are not instrumented. The
1 option cannot be combined with '-fcheck-pointer-bounds'.
1
1 '-fsanitize=bounds-strict'
1 This option enables strict instrumentation of array bounds.
1 Most out of bounds accesses are detected, including flexible
1 array members and flexible array member-like arrays.
1 Initializers of variables with static storage are not
1 instrumented. The option cannot be combined with
1 '-fcheck-pointer-bounds'.
1
1 '-fsanitize=alignment'
1
1 This option enables checking of alignment of pointers when
1 they are dereferenced, or when a reference is bound to
1 insufficiently aligned target, or when a method or constructor
1 is invoked on insufficiently aligned object.
1
1 '-fsanitize=object-size'
1 This option enables instrumentation of memory references using
1 the '__builtin_object_size' function. Various out of bounds
1 pointer accesses are detected.
1
1 '-fsanitize=float-divide-by-zero'
1 Detect floating-point division by zero. Unlike other similar
1 options, '-fsanitize=float-divide-by-zero' is not enabled by
1 '-fsanitize=undefined', since floating-point division by zero
1 can be a legitimate way of obtaining infinities and NaNs.
1
1 '-fsanitize=float-cast-overflow'
1 This option enables floating-point type to integer conversion
1 checking. We check that the result of the conversion does not
1 overflow. Unlike other similar options,
1 '-fsanitize=float-cast-overflow' is not enabled by
1 '-fsanitize=undefined'. This option does not work well with
1 'FE_INVALID' exceptions enabled.
1
1 '-fsanitize=nonnull-attribute'
1
1 This option enables instrumentation of calls, checking whether
1 null values are not passed to arguments marked as requiring a
1 non-null value by the 'nonnull' function attribute.
1
1 '-fsanitize=returns-nonnull-attribute'
1
1 This option enables instrumentation of return statements in
1 functions marked with 'returns_nonnull' function attribute, to
1 detect returning of null values from such functions.
1
1 '-fsanitize=bool'
1
1 This option enables instrumentation of loads from bool. If a
1 value other than 0/1 is loaded, a run-time error is issued.
1
1 '-fsanitize=enum'
1
1 This option enables instrumentation of loads from an enum
1 type. If a value outside the range of values for the enum
1 type is loaded, a run-time error is issued.
1
1 '-fsanitize=vptr'
1
1 This option enables instrumentation of C++ member function
1 calls, member accesses and some conversions between pointers
1 to base and derived classes, to verify the referenced object
1 has the correct dynamic type.
1
1 '-fsanitize=pointer-overflow'
1
1 This option enables instrumentation of pointer arithmetics.
1 If the pointer arithmetics overflows, a run-time error is
1 issued.
1
1 '-fsanitize=builtin'
1
1 This option enables instrumentation of arguments to selected
1 builtin functions. If an invalid value is passed to such
1 arguments, a run-time error is issued. E.g. passing 0 as the
1 argument to '__builtin_ctz' or '__builtin_clz' invokes
1 undefined behavior and is diagnosed by this option.
1
1 While '-ftrapv' causes traps for signed overflows to be emitted,
1 '-fsanitize=undefined' gives a diagnostic message. This currently
1 works only for the C family of languages.
1
1 '-fno-sanitize=all'
1
1 This option disables all previously enabled sanitizers.
1 '-fsanitize=all' is not allowed, as some sanitizers cannot be used
1 together.
1
1 '-fasan-shadow-offset=NUMBER'
1 This option forces GCC to use custom shadow offset in
1 AddressSanitizer checks. It is useful for experimenting with
1 different shadow memory layouts in Kernel AddressSanitizer.
1
1 '-fsanitize-sections=S1,S2,...'
1 Sanitize global variables in selected user-defined sections. SI
1 may contain wildcards.
1
1 '-fsanitize-recover[=OPTS]'
1 '-fsanitize-recover=' controls error recovery mode for sanitizers
1 mentioned in comma-separated list of OPTS. Enabling this option
1 for a sanitizer component causes it to attempt to continue running
1 the program as if no error happened. This means multiple runtime
1 errors can be reported in a single program run, and the exit code
1 of the program may indicate success even when errors have been
1 reported. The '-fno-sanitize-recover=' option can be used to alter
1 this behavior: only the first detected error is reported and
1 program then exits with a non-zero exit code.
1
1 Currently this feature only works for '-fsanitize=undefined' (and
1 its suboptions except for '-fsanitize=unreachable' and
1 '-fsanitize=return'), '-fsanitize=float-cast-overflow',
1 '-fsanitize=float-divide-by-zero', '-fsanitize=bounds-strict',
1 '-fsanitize=kernel-address' and '-fsanitize=address'. For these
1 sanitizers error recovery is turned on by default, except
1 '-fsanitize=address', for which this feature is experimental.
1 '-fsanitize-recover=all' and '-fno-sanitize-recover=all' is also
1 accepted, the former enables recovery for all sanitizers that
1 support it, the latter disables recovery for all sanitizers that
1 support it.
1
1 Even if a recovery mode is turned on the compiler side, it needs to
1 be also enabled on the runtime library side, otherwise the failures
1 are still fatal. The runtime library defaults to 'halt_on_error=0'
1 for ThreadSanitizer and UndefinedBehaviorSanitizer, while default
1 value for AddressSanitizer is 'halt_on_error=1'. This can be
1 overridden through setting the 'halt_on_error' flag in the
1 corresponding environment variable.
1
1 Syntax without an explicit OPTS parameter is deprecated. It is
1 equivalent to specifying an OPTS list of:
1
1 undefined,float-cast-overflow,float-divide-by-zero,bounds-strict
1
1 '-fsanitize-address-use-after-scope'
1 Enable sanitization of local variables to detect use-after-scope
1 bugs. The option sets '-fstack-reuse' to 'none'.
1
1 '-fsanitize-undefined-trap-on-error'
1 The '-fsanitize-undefined-trap-on-error' option instructs the
1 compiler to report undefined behavior using '__builtin_trap' rather
1 than a 'libubsan' library routine. The advantage of this is that
1 the 'libubsan' library is not needed and is not linked in, so this
1 is usable even in freestanding environments.
1
1 '-fsanitize-coverage=trace-pc'
1 Enable coverage-guided fuzzing code instrumentation. Inserts a
1 call to '__sanitizer_cov_trace_pc' into every basic block.
1
1 '-fsanitize-coverage=trace-cmp'
1 Enable dataflow guided fuzzing code instrumentation. Inserts a
1 call to '__sanitizer_cov_trace_cmp1', '__sanitizer_cov_trace_cmp2',
1 '__sanitizer_cov_trace_cmp4' or '__sanitizer_cov_trace_cmp8' for
1 integral comparison with both operands variable or
1 '__sanitizer_cov_trace_const_cmp1',
1 '__sanitizer_cov_trace_const_cmp2',
1 '__sanitizer_cov_trace_const_cmp4' or
1 '__sanitizer_cov_trace_const_cmp8' for integral comparison with one
1 operand constant, '__sanitizer_cov_trace_cmpf' or
1 '__sanitizer_cov_trace_cmpd' for float or double comparisons and
1 '__sanitizer_cov_trace_switch' for switch statements.
1
1 '-fbounds-check'
1 For front ends that support it, generate additional code to check
1 that indices used to access arrays are within the declared range.
1 This is currently only supported by the Fortran front end, where
1 this option defaults to false.
1
1 '-fcheck-pointer-bounds'
1 Enable Pointer Bounds Checker instrumentation. Each memory
1 reference is instrumented with checks of the pointer used for
1 memory access against bounds associated with that pointer.
1
1 Currently there is only an implementation for Intel MPX available,
1 thus x86 GNU/Linux target and '-mmpx' are required to enable this
1 feature. MPX-based instrumentation requires a runtime library to
1 enable MPX in hardware and handle bounds violation signals. By
1 default when '-fcheck-pointer-bounds' and '-mmpx' options are used
1 to link a program, the GCC driver links against the 'libmpx' and
1 'libmpxwrappers' libraries. Bounds checking on calls to dynamic
1 libraries requires a linker with '-z bndplt' support; if GCC was
1 configured with a linker without support for this option (including
1 the Gold linker and older versions of ld), a warning is given if
1 you link with '-mmpx' without also specifying '-static', since the
1 overall effectiveness of the bounds checking protection is reduced.
1 See also '-static-libmpxwrappers'.
1
1 MPX-based instrumentation may be used for debugging and also may be
1 included in production code to increase program security.
1 Depending on usage, you may have different requirements for the
1 runtime library. The current version of the MPX runtime library is
1 more oriented for use as a debugging tool. MPX runtime library
1 usage implies '-lpthread'. See also '-static-libmpx'. The runtime
1 library behavior can be influenced using various 'CHKP_RT_*'
1 environment variables. See
1 <https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler>
1 for more details.
1
1 Generated instrumentation may be controlled by various '-fchkp-*'
1 options and by the 'bnd_variable_size' structure field attribute
1 (⇒Type Attributes) and 'bnd_legacy', and 'bnd_instrument'
1 function attributes (⇒Function Attributes). GCC also
1 provides a number of built-in functions for controlling the Pointer
1 Bounds Checker. ⇒Pointer Bounds Checker builtins, for more
1 information.
1
1 '-fchkp-check-incomplete-type'
1 Generate pointer bounds checks for variables with incomplete type.
1 Enabled by default.
1
1 '-fchkp-narrow-bounds'
1 Controls bounds used by Pointer Bounds Checker for pointers to
1 object fields. If narrowing is enabled then field bounds are used.
1 Otherwise object bounds are used. See also
1 '-fchkp-narrow-to-innermost-array' and
1 '-fchkp-first-field-has-own-bounds'. Enabled by default.
1
1 '-fchkp-first-field-has-own-bounds'
1 Forces Pointer Bounds Checker to use narrowed bounds for the
1 address of the first field in the structure. By default a pointer
1 to the first field has the same bounds as a pointer to the whole
1 structure.
1
1 '-fchkp-flexible-struct-trailing-arrays'
1 Forces Pointer Bounds Checker to treat all trailing arrays in
1 structures as possibly flexible. By default only array fields with
1 zero length or that are marked with attribute bnd_variable_size are
1 treated as flexible.
1
1 '-fchkp-narrow-to-innermost-array'
1 Forces Pointer Bounds Checker to use bounds of the innermost arrays
1 in case of nested static array access. By default this option is
1 disabled and bounds of the outermost array are used.
1
1 '-fchkp-optimize'
1 Enables Pointer Bounds Checker optimizations. Enabled by default
1 at optimization levels '-O', '-O2', '-O3'.
1
1 '-fchkp-use-fast-string-functions'
1 Enables use of '*_nobnd' versions of string functions (not copying
1 bounds) by Pointer Bounds Checker. Disabled by default.
1
1 '-fchkp-use-nochk-string-functions'
1 Enables use of '*_nochk' versions of string functions (not checking
1 bounds) by Pointer Bounds Checker. Disabled by default.
1
1 '-fchkp-use-static-bounds'
1 Allow Pointer Bounds Checker to generate static bounds holding
1 bounds of static variables. Enabled by default.
1
1 '-fchkp-use-static-const-bounds'
1 Use statically-initialized bounds for constant bounds instead of
1 generating them each time they are required. By default enabled
1 when '-fchkp-use-static-bounds' is enabled.
1
1 '-fchkp-treat-zero-dynamic-size-as-infinite'
1 With this option, objects with incomplete type whose
1 dynamically-obtained size is zero are treated as having infinite
1 size instead by Pointer Bounds Checker. This option may be helpful
1 if a program is linked with a library missing size information for
1 some symbols. Disabled by default.
1
1 '-fchkp-check-read'
1 Instructs Pointer Bounds Checker to generate checks for all read
1 accesses to memory. Enabled by default.
1
1 '-fchkp-check-write'
1 Instructs Pointer Bounds Checker to generate checks for all write
1 accesses to memory. Enabled by default.
1
1 '-fchkp-store-bounds'
1 Instructs Pointer Bounds Checker to generate bounds stores for
1 pointer writes. Enabled by default.
1
1 '-fchkp-instrument-calls'
1 Instructs Pointer Bounds Checker to pass pointer bounds to calls.
1 Enabled by default.
1
1 '-fchkp-instrument-marked-only'
1 Instructs Pointer Bounds Checker to instrument only functions
11 marked with the 'bnd_instrument' attribute (⇒Function
Attributes). Disabled by default.
1
1 '-fchkp-use-wrappers'
1 Allows Pointer Bounds Checker to replace calls to built-in
1 functions with calls to wrapper functions. When
1 '-fchkp-use-wrappers' is used to link a program, the GCC driver
1 automatically links against 'libmpxwrappers'. See also
1 '-static-libmpxwrappers'. Enabled by default.
1
1 '-fcf-protection=[full|branch|return|none]'
1 Enable code instrumentation of control-flow transfers to increase
1 program security by checking that target addresses of control-flow
1 transfer instructions (such as indirect function call, function
1 return, indirect jump) are valid. This prevents diverting the flow
1 of control to an unexpected target. This is intended to protect
1 against such threats as Return-oriented Programming (ROP), and
1 similarly call/jmp-oriented programming (COP/JOP).
1
1 The value 'branch' tells the compiler to implement checking of
1 validity of control-flow transfer at the point of indirect branch
1 instructions, i.e. call/jmp instructions. The value 'return'
1 implements checking of validity at the point of returning from a
1 function. The value 'full' is an alias for specifying both
1 'branch' and 'return'. The value 'none' turns off instrumentation.
1
1 The macro '__CET__' is defined when '-fcf-protection' is used. The
1 first bit of '__CET__' is set to 1 for the value 'branch' and the
1 second bit of '__CET__' is set to 1 for the 'return'.
1
1 You can also use the 'nocf_check' attribute to identify which
11 functions and calls should be skipped from instrumentation (⇒
Function Attributes).
1
1 Currently the x86 GNU/Linux target provides an implementation based
1 on Intel Control-flow Enforcement Technology (CET).
1
1 '-fstack-protector'
1 Emit extra code to check for buffer overflows, such as stack
1 smashing attacks. This is done by adding a guard variable to
1 functions with vulnerable objects. This includes functions that
1 call 'alloca', and functions with buffers larger than 8 bytes. The
1 guards are initialized when a function is entered and then checked
1 when the function exits. If a guard check fails, an error message
1 is printed and the program exits.
1
1 '-fstack-protector-all'
1 Like '-fstack-protector' except that all functions are protected.
1
1 '-fstack-protector-strong'
1 Like '-fstack-protector' but includes additional functions to be
1 protected -- those that have local array definitions, or have
1 references to local frame addresses.
1
1 '-fstack-protector-explicit'
1 Like '-fstack-protector' but only protects those functions which
1 have the 'stack_protect' attribute.
1
1 '-fstack-check'
1 Generate code to verify that you do not go beyond the boundary of
1 the stack. You should specify this flag if you are running in an
1 environment with multiple threads, but you only rarely need to
1 specify it in a single-threaded environment since stack overflow is
1 automatically detected on nearly all systems if there is only one
1 stack.
1
1 Note that this switch does not actually cause checking to be done;
1 the operating system or the language runtime must do that. The
1 switch causes generation of code to ensure that they see the stack
1 being extended.
1
1 You can additionally specify a string parameter: 'no' means no
1 checking, 'generic' means force the use of old-style checking,
1 'specific' means use the best checking method and is equivalent to
1 bare '-fstack-check'.
1
1 Old-style checking is a generic mechanism that requires no specific
1 target support in the compiler but comes with the following
1 drawbacks:
1
1 1. Modified allocation strategy for large objects: they are
1 always allocated dynamically if their size exceeds a fixed
1 threshold. Note this may change the semantics of some code.
1
1 2. Fixed limit on the size of the static frame of functions: when
1 it is topped by a particular function, stack checking is not
1 reliable and a warning is issued by the compiler.
1
1 3. Inefficiency: because of both the modified allocation strategy
1 and the generic implementation, code performance is hampered.
1
1 Note that old-style stack checking is also the fallback method for
1 'specific' if no target support has been added in the compiler.
1
1 '-fstack-check=' is designed for Ada's needs to detect infinite
1 recursion and stack overflows. 'specific' is an excellent choice
1 when compiling Ada code. It is not generally sufficient to protect
1 against stack-clash attacks. To protect against those you want
1 '-fstack-clash-protection'.
1
1 '-fstack-clash-protection'
1 Generate code to prevent stack clash style attacks. When this
1 option is enabled, the compiler will only allocate one page of
1 stack space at a time and each page is accessed immediately after
1 allocation. Thus, it prevents allocations from jumping over any
1 stack guard page provided by the operating system.
1
1 Most targets do not fully support stack clash protection. However,
1 on those targets '-fstack-clash-protection' will protect dynamic
1 stack allocations. '-fstack-clash-protection' may also provide
1 limited protection for static stack allocations if the target
1 supports '-fstack-check=specific'.
1
1 '-fstack-limit-register=REG'
1 '-fstack-limit-symbol=SYM'
1 '-fno-stack-limit'
1 Generate code to ensure that the stack does not grow beyond a
1 certain value, either the value of a register or the address of a
1 symbol. If a larger stack is required, a signal is raised at run
1 time. For most targets, the signal is raised before the stack
1 overruns the boundary, so it is possible to catch the signal
1 without taking special precautions.
1
1 For instance, if the stack starts at absolute address '0x80000000'
1 and grows downwards, you can use the flags
1 '-fstack-limit-symbol=__stack_limit' and
1 '-Wl,--defsym,__stack_limit=0x7ffe0000' to enforce a stack limit of
1 128KB. Note that this may only work with the GNU linker.
1
1 You can locally override stack limit checking by using the
1 'no_stack_limit' function attribute (⇒Function Attributes).
1
1 '-fsplit-stack'
1 Generate code to automatically split the stack before it overflows.
1 The resulting program has a discontiguous stack which can only
1 overflow if the program is unable to allocate any more memory.
1 This is most useful when running threaded programs, as it is no
1 longer necessary to calculate a good stack size to use for each
1 thread. This is currently only implemented for the x86 targets
1 running GNU/Linux.
1
1 When code compiled with '-fsplit-stack' calls code compiled without
1 '-fsplit-stack', there may not be much stack space available for
1 the latter code to run. If compiling all code, including library
1 code, with '-fsplit-stack' is not an option, then the linker can
1 fix up these calls so that the code compiled without
1 '-fsplit-stack' always has a large stack. Support for this is
1 implemented in the gold linker in GNU binutils release 2.21 and
1 later.
1
1 '-fvtable-verify=[std|preinit|none]'
1 This option is only available when compiling C++ code. It turns on
1 (or off, if using '-fvtable-verify=none') the security feature that
1 verifies at run time, for every virtual call, that the vtable
1 pointer through which the call is made is valid for the type of the
1 object, and has not been corrupted or overwritten. If an invalid
1 vtable pointer is detected at run time, an error is reported and
1 execution of the program is immediately halted.
1
1 This option causes run-time data structures to be built at program
1 startup, which are used for verifying the vtable pointers. The
1 options 'std' and 'preinit' control the timing of when these data
1 structures are built. In both cases the data structures are built
1 before execution reaches 'main'. Using '-fvtable-verify=std'
1 causes the data structures to be built after shared libraries have
1 been loaded and initialized. '-fvtable-verify=preinit' causes them
1 to be built before shared libraries have been loaded and
1 initialized.
1
1 If this option appears multiple times in the command line with
1 different values specified, 'none' takes highest priority over both
1 'std' and 'preinit'; 'preinit' takes priority over 'std'.
1
1 '-fvtv-debug'
1 When used in conjunction with '-fvtable-verify=std' or
1 '-fvtable-verify=preinit', causes debug versions of the runtime
1 functions for the vtable verification feature to be called. This
1 flag also causes the compiler to log information about which vtable
1 pointers it finds for each class. This information is written to a
1 file named 'vtv_set_ptr_data.log' in the directory named by the
1 environment variable 'VTV_LOGS_DIR' if that is defined or the
1 current working directory otherwise.
1
1 Note: This feature _appends_ data to the log file. If you want a
1 fresh log file, be sure to delete any existing one.
1
1 '-fvtv-counts'
1 This is a debugging flag. When used in conjunction with
1 '-fvtable-verify=std' or '-fvtable-verify=preinit', this causes the
1 compiler to keep track of the total number of virtual calls it
1 encounters and the number of verifications it inserts. It also
1 counts the number of calls to certain run-time library functions
1 that it inserts and logs this information for each compilation
1 unit. The compiler writes this information to a file named
1 'vtv_count_data.log' in the directory named by the environment
1 variable 'VTV_LOGS_DIR' if that is defined or the current working
1 directory otherwise. It also counts the size of the vtable pointer
1 sets for each class, and writes this information to
1 'vtv_class_set_sizes.log' in the same directory.
1
1 Note: This feature _appends_ data to the log files. To get fresh
1 log files, be sure to delete any existing ones.
1
1 '-finstrument-functions'
1 Generate instrumentation calls for entry and exit to functions.
1 Just after function entry and just before function exit, the
1 following profiling functions are called with the address of the
1 current function and its call site. (On some platforms,
1 '__builtin_return_address' does not work beyond the current
1 function, so the call site information may not be available to the
1 profiling functions otherwise.)
1
1 void __cyg_profile_func_enter (void *this_fn,
1 void *call_site);
1 void __cyg_profile_func_exit (void *this_fn,
1 void *call_site);
1
1 The first argument is the address of the start of the current
1 function, which may be looked up exactly in the symbol table.
1
1 This instrumentation is also done for functions expanded inline in
1 other functions. The profiling calls indicate where, conceptually,
1 the inline function is entered and exited. This means that
1 addressable versions of such functions must be available. If all
1 your uses of a function are expanded inline, this may mean an
1 additional expansion of code size. If you use 'extern inline' in
1 your C code, an addressable version of such functions must be
1 provided. (This is normally the case anyway, but if you get lucky
1 and the optimizer always expands the functions inline, you might
1 have gotten away without providing static copies.)
1
1 A function may be given the attribute 'no_instrument_function', in
1 which case this instrumentation is not done. This can be used, for
1 example, for the profiling functions listed above, high-priority
1 interrupt routines, and any functions from which the profiling
1 functions cannot safely be called (perhaps signal handlers, if the
1 profiling routines generate output or allocate memory).
1
1 '-finstrument-functions-exclude-file-list=FILE,FILE,...'
1
1 Set the list of functions that are excluded from instrumentation
1 (see the description of '-finstrument-functions'). If the file
1 that contains a function definition matches with one of FILE, then
1 that function is not instrumented. The match is done on
1 substrings: if the FILE parameter is a substring of the file name,
1 it is considered to be a match.
1
1 For example:
1
1 -finstrument-functions-exclude-file-list=/bits/stl,include/sys
1
1 excludes any inline function defined in files whose pathnames
1 contain '/bits/stl' or 'include/sys'.
1
1 If, for some reason, you want to include letter ',' in one of SYM,
1 write '\,'. For example,
1 '-finstrument-functions-exclude-file-list='\,\,tmp'' (note the
1 single quote surrounding the option).
1
1 '-finstrument-functions-exclude-function-list=SYM,SYM,...'
1
1 This is similar to '-finstrument-functions-exclude-file-list', but
1 this option sets the list of function names to be excluded from
1 instrumentation. The function name to be matched is its
1 user-visible name, such as 'vector<int> blah(const vector<int> &)',
1 not the internal mangled name (e.g., '_Z4blahRSt6vectorIiSaIiEE').
1 The match is done on substrings: if the SYM parameter is a
1 substring of the function name, it is considered to be a match.
1 For C99 and C++ extended identifiers, the function name must be
1 given in UTF-8, not using universal character names.
1
1 '-fpatchable-function-entry=N[,M]'
1 Generate N NOPs right at the beginning of each function, with the
1 function entry point before the Mth NOP. If M is omitted, it
1 defaults to '0' so the function entry points to the address just at
1 the first NOP. The NOP instructions reserve extra space which can
1 be used to patch in any desired instrumentation at run time,
1 provided that the code segment is writable. The amount of space is
1 controllable indirectly via the number of NOPs; the NOP instruction
1 used corresponds to the instruction emitted by the internal GCC
1 back-end interface 'gen_nop'. This behavior is target-specific and
1 may also depend on the architecture variant and/or other
1 compilation options.
1
1 For run-time identification, the starting addresses of these areas,
1 which correspond to their respective function entries minus M, are
1 additionally collected in the '__patchable_function_entries'
1 section of the resulting binary.
1
1 Note that the value of '__attribute__ ((patchable_function_entry
1 (N,M)))' takes precedence over command-line option
1 '-fpatchable-function-entry=N,M'. This can be used to increase the
1 area size or to remove it completely on a single function. If
1 'N=0', no pad location is recorded.
1
1 The NOP instructions are inserted at--and maybe before, depending
1 on M--the function entry address, even before the prologue.
1