Index: gcc/doc/invoke.texi =================================================================== --- gcc/doc/invoke.texi (revision 232370) +++ gcc/doc/invoke.texi (working copy) @@ -140,6 +140,7 @@ only one of these two forms, whichever o * Warning Options:: How picky should the compiler be? * Debugging Options:: Symbol tables, measurements, and debugging dumps. * Optimize Options:: How much optimization? +* Instrumentation Options:: Enabling profiling and extra run-time error checking. * Preprocessor Options:: Controlling header files and macro definitions. Also, getting dependency information for Make. * Assembler Options:: Passing options to the assembler. @@ -203,8 +204,6 @@ in the following sections. -fno-threadsafe-statics -fuse-cxa-atexit @gol -fno-weak -nostdinc++ @gol -fvisibility-inlines-hidden @gol --fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol --fvtv-counts -fvtv-debug @gol -fvisibility-ms-compat @gol -fext-numeric-literals @gol -Wabi=@var{n} -Wabi-tag -Wconversion-null -Wctor-dtor-privacy @gol @@ -316,18 +315,6 @@ Objective-C and Objective-C++ Dialects}. @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program or GCC}. @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol --fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol --fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol --fsanitize-undefined-trap-on-error @gol --fcheck-pointer-bounds -fchecking -fchkp-check-incomplete-type @gol --fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol --fchkp-narrow-to-innermost-array -fchkp-optimize @gol --fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol --fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol --fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol --fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol --fchkp-instrument-calls -fchkp-instrument-marked-only @gol --fchkp-use-wrappers @gol -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol -fdisable-ipa-@var{pass_name} @gol -fdisable-rtl-@var{pass_name} @gol @@ -370,12 +357,13 @@ Objective-C and Objective-C++ Dialects}. -fenable-@var{kind}-@var{pass} @gol -fenable-@var{kind}-@var{pass}=@var{range-list} @gol -fdebug-types-section -fmem-report-wpa @gol --fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol +-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol -fopt-info @gol -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol +-fprofile-report @gol -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol -fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol --fstack-usage -ftest-coverage -ftime-report -fvar-tracking @gol +-fstack-usage -ftime-report -fvar-tracking @gol -fvar-tracking-assignments -fvar-tracking-assignments-toggle @gol -g -g@var{level} -gtoggle -gcoff -gdwarf-@var{version} @gol -ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol @@ -385,7 +373,7 @@ Objective-C and Objective-C++ Dialects}. -fdebug-prefix-map=@var{old}=@var{new} @gol -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol --p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol +-print-file-name=@var{library} -print-libgcc-file-name @gol -print-multi-directory -print-multi-lib -print-multi-os-directory @gol -print-prog-name=@var{program} -print-search-dirs -Q @gol -print-sysroot -print-sysroot-headers-suffix @gol @@ -435,9 +423,8 @@ Objective-C and Objective-C++ Dialects}. -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol -fomit-frame-pointer -foptimize-sibling-calls @gol -fpartial-inlining -fpeel-loops -fpredictive-commoning @gol --fprefetch-loop-arrays -fprofile-report @gol --fprofile-correction -fprofile-dir=@var{path} -fprofile-generate @gol --fprofile-generate=@var{path} @gol +-fprefetch-loop-arrays @gol +-fprofile-correction @gol -fprofile-use -fprofile-use=@var{path} -fprofile-values @gol -fprofile-reorder-functions @gol -freciprocal-math -free -frename-registers -freorder-blocks @gol @@ -458,8 +445,7 @@ Objective-C and Objective-C++ Dialects}. -fsingle-precision-constant -fsplit-ivs-in-unroller @gol -fsplit-paths @gol -fsplit-wide-types -fssa-backprop -fssa-phiopt @gol --fstack-protector -fstack-protector-all -fstack-protector-strong @gol --fstack-protector-explicit -fstdarg-opt -fstrict-aliasing @gol +-fstdarg-opt -fstrict-aliasing @gol -fstrict-overflow -fthread-jumps -ftracer -ftree-bit-ccp @gol -ftree-builtin-call-dce -ftree-ccp -ftree-ch @gol -ftree-coalesce-vars -ftree-copy-prop -ftree-dce -ftree-dominator-opts @gol @@ -479,6 +465,32 @@ Objective-C and Objective-C++ Dialects}. --param @var{name}=@var{value} -O -O0 -O1 -O2 -O3 -Os -Ofast -Og} +@item Program Instrumentation Options +@xref{Instrumentation Options,,Program Instrumentation Options}. +@gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol +-fprofile-dir=@var{path} -fprofile-generate -fprofile-generate=@var{path} @gol +-fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol +-fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol +-fsanitize-undefined-trap-on-error -fbounds-check @gol +-fcheck-pointer-bounds -fchecking -fchkp-check-incomplete-type @gol +-fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol +-fchkp-narrow-to-innermost-array -fchkp-optimize @gol +-fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol +-fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol +-fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol +-fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol +-fchkp-instrument-calls -fchkp-instrument-marked-only @gol +-fchkp-use-wrappers @gol +-fstack-protector -fstack-protector-all -fstack-protector-strong @gol +-fstack-protector-explicit fstack-check @gol +-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol +-fno-stack-limit -fsplit-stack @gol +-fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol +-fvtv-counts -fvtv-debug @gol +-finstrument-functions @gol +-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol +-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}} + @item Preprocessor Options @xref{Preprocessor Options,,Options Controlling the Preprocessor}. @gccoptlist{-A@var{question}=@var{answer} @gol @@ -523,21 +535,16 @@ Objective-C and Objective-C++ Dialects}. -fnon-call-exceptions -fdelete-dead-exceptions -funwind-tables @gol -fasynchronous-unwind-tables @gol -fno-gnu-unique @gol --finhibit-size-directive -finstrument-functions @gol --finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol --finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol --fno-common -fno-ident @gol +-finhibit-size-directive -fno-common -fno-ident @gol -fpcc-struct-return -fpic -fPIC -fpie -fPIE -fno-plt @gol -fno-jump-tables @gol -frecord-gcc-switches @gol -freg-struct-return -fshort-enums @gol -fshort-double -fshort-wchar @gol --fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol --fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol --fno-stack-limit -fsplit-stack @gol +-fverbose-asm -fpack-struct[=@var{n}] @gol -fleading-underscore -ftls-model=@var{model} @gol -fstack-reuse=@var{reuse_level} @gol --ftrapv -fwrapv -fbounds-check @gol +-ftrapv -fwrapv @gol -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol -fstrict-volatile-bitfields -fsync-libcalls} @@ -2537,61 +2544,6 @@ and that pointers to function members de objects may not compare equal. When this flag is given, it is a violation of the ODR to define types with the same name differently. -@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} -@opindex fvtable-verify -Turn on (or off, if using @option{-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 @samp{std} and @samp{preinit} -control the timing of when these data structures are built. In both cases the -data structures are built before execution reaches @code{main}. Using -@option{-fvtable-verify=std} causes the data structures to be built after -shared libraries have been loaded and initialized. -@option{-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, @samp{none} takes highest priority over both @samp{std} and -@samp{preinit}; @samp{preinit} takes priority over @samp{std}. - -@item -fvtv-debug -@opindex fvtv-debug -When used in conjunction with @option{-fvtable-verify=std} or -@option{-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 @file{vtv_set_ptr_data.log} -in the directory named by the environment variable @env{VTV_LOGS_DIR} -if that is defined or the current working directory otherwise. - -Note: This feature @emph{appends} data to the log file. If you want a fresh log -file, be sure to delete any existing one. - -@item -fvtv-counts -@opindex fvtv-counts -This is a debugging flag. When used in conjunction with -@option{-fvtable-verify=std} or @option{-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 -@file{vtv_count_data.log} in the directory named by the environment -variable @env{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 @file{vtv_class_set_sizes.log} -in the same directory. - -Note: This feature @emph{appends} data to the log files. To get fresh log -files, be sure to delete any existing ones. - @item -fno-weak @opindex fno-weak Do not use weak symbol support, even if it is provided by the linker. @@ -5954,403 +5906,6 @@ other options are processed, and it does many times it is given. This is mainly intended to be used with @option{-fcompare-debug}. -@item -fsanitize=address -@opindex fsanitize=address -Enable AddressSanitizer, a fast memory error detector. -Memory access instructions are instrumented to detect -out-of-bounds and use-after-free bugs. -See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for -more details. The run-time behavior can be influenced using the -@env{ASAN_OPTIONS} environment variable. When set to @code{help=1}, -the available options are shown at startup of the instrumended program. See -@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags} -for a list of supported options. - -@item -fsanitize=kernel-address -@opindex fsanitize=kernel-address -Enable AddressSanitizer for Linux kernel. -See @uref{https://github.com/google/kasan/wiki} for more details. - -@item -fsanitize=thread -@opindex fsanitize=thread -Enable ThreadSanitizer, a fast data race detector. -Memory access instructions are instrumented to detect -data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more -details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS} -environment variable; see -@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of -supported options. - -@item -fsanitize=leak -@opindex fsanitize=leak -Enable LeakSanitizer, a memory leak detector. -This option only matters for linking of executables and if neither -@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that -case the executable is linked against a library that overrides @code{malloc} -and other allocator functions. See -@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more -details. The run-time behavior can be influenced using the -@env{LSAN_OPTIONS} environment variable. - -@item -fsanitize=undefined -@opindex fsanitize=undefined -Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. -Various computations are instrumented to detect undefined behavior -at runtime. Current suboptions are: - -@table @gcctabopt - -@item -fsanitize=shift -@opindex fsanitize=shift -This option enables checking that the result of a shift operation is -not undefined. Note that what exactly is considered undefined differs -slightly between C and C++, as well as between ISO C90 and C99, etc. - -@item -fsanitize=integer-divide-by-zero -@opindex fsanitize=integer-divide-by-zero -Detect integer division by zero as well as @code{INT_MIN / -1} division. - -@item -fsanitize=unreachable -@opindex fsanitize=unreachable -With this option, the compiler turns the @code{__builtin_unreachable} -call into a diagnostics message call instead. When reaching the -@code{__builtin_unreachable} call, the behavior is undefined. - -@item -fsanitize=vla-bound -@opindex fsanitize=vla-bound -This option instructs the compiler to check that the size of a variable -length array is positive. - -@item -fsanitize=null -@opindex fsanitize=null -This option enables pointer checking. Particularly, the application -built with this option turned on will issue an error message when it -tries to dereference a NULL pointer, or if a reference (possibly an -rvalue reference) is bound to a NULL pointer, or if a method is invoked -on an object pointed by a NULL pointer. - -@item -fsanitize=return -@opindex fsanitize=return -This option enables return statement checking. Programs -built with this option turned on will issue an error message -when the end of a non-void function is reached without actually -returning a value. This option works in C++ only. - -@item -fsanitize=signed-integer-overflow -@opindex fsanitize=signed-integer-overflow -This option enables signed integer overflow checking. We check that -the result of @code{+}, @code{*}, and both unary and binary @code{-} -does not overflow in the signed arithmetics. Note, integer promotion -rules must be taken into account. That is, the following is not an -overflow: -@smallexample -signed char a = SCHAR_MAX; -a++; -@end smallexample - -@item -fsanitize=bounds -@opindex fsanitize=bounds -This option enables instrumentation of array bounds. Various out of bounds -accesses are detected. Flexible array members, flexible array member-like -arrays, and initializers of variables with static storage are not instrumented. - -@item -fsanitize=bounds-strict -@opindex fsanitize=bounds-strict -This option enables strict instrumentation of array bounds. Most out of bounds -accesses are detected, including flexible array members and flexible array -member-like arrays. Initializers of variables with static storage are not -instrumented. - -@item -fsanitize=alignment -@opindex fsanitize=alignment - -This option enables checking of alignment of pointers when they are -dereferenced, or when a reference is bound to insufficiently aligned target, -or when a method or constructor is invoked on insufficiently aligned object. - -@item -fsanitize=object-size -@opindex fsanitize=object-size -This option enables instrumentation of memory references using the -@code{__builtin_object_size} function. Various out of bounds pointer -accesses are detected. - -@item -fsanitize=float-divide-by-zero -@opindex fsanitize=float-divide-by-zero -Detect floating-point division by zero. Unlike other similar options, -@option{-fsanitize=float-divide-by-zero} is not enabled by -@option{-fsanitize=undefined}, since floating-point division by zero can -be a legitimate way of obtaining infinities and NaNs. - -@item -fsanitize=float-cast-overflow -@opindex fsanitize=float-cast-overflow -This option enables floating-point type to integer conversion checking. -We check that the result of the conversion does not overflow. -Unlike other similar options, @option{-fsanitize=float-cast-overflow} is -not enabled by @option{-fsanitize=undefined}. -This option does not work well with @code{FE_INVALID} exceptions enabled. - -@item -fsanitize=nonnull-attribute -@opindex fsanitize=nonnull-attribute - -This option enables instrumentation of calls, checking whether null values -are not passed to arguments marked as requiring a non-null value by the -@code{nonnull} function attribute. - -@item -fsanitize=returns-nonnull-attribute -@opindex fsanitize=returns-nonnull-attribute - -This option enables instrumentation of return statements in functions -marked with @code{returns_nonnull} function attribute, to detect returning -of null values from such functions. - -@item -fsanitize=bool -@opindex fsanitize=bool - -This option enables instrumentation of loads from bool. If a value other -than 0/1 is loaded, a run-time error is issued. - -@item -fsanitize=enum -@opindex fsanitize=enum - -This option enables instrumentation of loads from an enum type. If -a value outside the range of values for the enum type is loaded, -a run-time error is issued. - -@item -fsanitize=vptr -@opindex fsanitize=vptr - -This option enables instrumentation of C++ member function calls, member -accesses and some conversions between pointers to base and derived classes, -to verify the referenced object has the correct dynamic type. - -@end table - -While @option{-ftrapv} causes traps for signed overflows to be emitted, -@option{-fsanitize=undefined} gives a diagnostic message. -This currently works only for the C family of languages. - -@item -fno-sanitize=all -@opindex fno-sanitize=all - -This option disables all previously enabled sanitizers. -@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used -together. - -@item -fasan-shadow-offset=@var{number} -@opindex fasan-shadow-offset -This option forces GCC to use custom shadow offset in AddressSanitizer checks. -It is useful for experimenting with different shadow memory layouts in -Kernel AddressSanitizer. - -@item -fsanitize-sections=@var{s1},@var{s2},... -@opindex fsanitize-sections -Sanitize global variables in selected user-defined sections. @var{si} may -contain wildcards. - -@item -fsanitize-recover@r{[}=@var{opts}@r{]} -@opindex fsanitize-recover -@opindex fno-sanitize-recover -@option{-fsanitize-recover=} controls error recovery mode for sanitizers -mentioned in comma-separated list of @var{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 @option{-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 @option{-fsanitize=undefined} (and its suboptions -except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}), -@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero}, -@option{-fsanitize=kernel-address} and @option{-fsanitize=address}. -For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address}, -for which this feature is experimental. -@option{-fsanitize-recover=all} and @option{-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 @var{opts} parameter is deprecated. It is equivalent to -@smallexample --fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero -@end smallexample -@noindent -Similarly @option{-fno-sanitize-recover} is equivalent to -@smallexample --fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero -@end smallexample - -@item -fsanitize-undefined-trap-on-error -@opindex fsanitize-undefined-trap-on-error -The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to -report undefined behavior using @code{__builtin_trap} rather than -a @code{libubsan} library routine. The advantage of this is that the -@code{libubsan} library is not needed and is not linked in, so this -is usable even in freestanding environments. - -@item -fsanitize-coverage=trace-pc -@opindex fsanitize-coverage=trace-pc -Enable coverage-guided fuzzing code instrumentation. -Inserts call to __sanitizer_cov_trace_pc into every basic block. - -@item -fcheck-pointer-bounds -@opindex fcheck-pointer-bounds -@opindex fno-check-pointer-bounds -@cindex Pointer Bounds Checker options -Enable Pointer Bounds Checker instrumentation. Each memory reference -is instrumented with checks of the pointer used for memory access against -bounds associated with that pointer. - -Currently there -is only an implementation for Intel MPX available, thus x86 target -and @option{-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 @option{-fcheck-pointer-bounds} -and @option{-mmpx} options are used to link a program, the GCC driver -links against the @file{libmpx} runtime library and @file{libmpxwrappers} -library. It also passes '-z bndplt' to a linker in case it supports this -option (which is checked on libmpx configuration). Note that old versions -of linker may ignore option. Gold linker doesn't support '-z bndplt' -option. With no '-z bndplt' support in linker all calls to dynamic libraries -lose passed bounds reducing overall protection level. It's highly -recommended to use linker with '-z bndplt' support. In case such linker -is not available it is adviced to always use @option{-static-libmpxwrappers} -for better protection level or use @option{-static} to completely avoid -external calls to dynamic libraries. 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 @option{-lpthread}. See -also @option{-static-libmpx}. The runtime library behavior can be -influenced using various @env{CHKP_RT_*} environment variables. See -@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler} -for more details. - -Generated instrumentation may be controlled by various -@option{-fchkp-*} options and by the @code{bnd_variable_size} -structure field attribute (@pxref{Type Attributes}) and -@code{bnd_legacy}, and @code{bnd_instrument} function attributes -(@pxref{Function Attributes}). GCC also provides a number of built-in -functions for controlling the Pointer Bounds Checker. @xref{Pointer -Bounds Checker builtins}, for more information. - -@item -fchecking -@opindex fchecking -@opindex fno-checking -Enable internal consistency checking. The default depends on -the compiler configuration. - -@item -fchkp-check-incomplete-type -@opindex fchkp-check-incomplete-type -@opindex fno-chkp-check-incomplete-type -Generate pointer bounds checks for variables with incomplete type. -Enabled by default. - -@item -fchkp-narrow-bounds -@opindex fchkp-narrow-bounds -@opindex fno-chkp-narrow-bounds -Controls bounds used by Pointer Bounds Checker for pointers to object -fields. If narrowing is enabled then field bounds are used. Otherwise -object bounds are used. See also @option{-fchkp-narrow-to-innermost-array} -and @option{-fchkp-first-field-has-own-bounds}. Enabled by default. - -@item -fchkp-first-field-has-own-bounds -@opindex fchkp-first-field-has-own-bounds -@opindex fno-chkp-first-field-has-own-bounds -Forces Pointer Bounds Checker to use narrowed bounds for the address of the -first field in the structure. By default a pointer to the first field has -the same bounds as a pointer to the whole structure. - -@item -fchkp-narrow-to-innermost-array -@opindex fchkp-narrow-to-innermost-array -@opindex fno-chkp-narrow-to-innermost-array -Forces Pointer Bounds Checker to use bounds of the innermost arrays in -case of nested static array access. By default this option is disabled and -bounds of the outermost array are used. - -@item -fchkp-optimize -@opindex fchkp-optimize -@opindex fno-chkp-optimize -Enables Pointer Bounds Checker optimizations. Enabled by default at -optimization levels @option{-O}, @option{-O2}, @option{-O3}. - -@item -fchkp-use-fast-string-functions -@opindex fchkp-use-fast-string-functions -@opindex fno-chkp-use-fast-string-functions -Enables use of @code{*_nobnd} versions of string functions (not copying bounds) -by Pointer Bounds Checker. Disabled by default. - -@item -fchkp-use-nochk-string-functions -@opindex fchkp-use-nochk-string-functions -@opindex fno-chkp-use-nochk-string-functions -Enables use of @code{*_nochk} versions of string functions (not checking bounds) -by Pointer Bounds Checker. Disabled by default. - -@item -fchkp-use-static-bounds -@opindex fchkp-use-static-bounds -@opindex fno-chkp-use-static-bounds -Allow Pointer Bounds Checker to generate static bounds holding -bounds of static variables. Enabled by default. - -@item -fchkp-use-static-const-bounds -@opindex fchkp-use-static-const-bounds -@opindex fno-chkp-use-static-const-bounds -Use statically-initialized bounds for constant bounds instead of -generating them each time they are required. By default enabled when -@option{-fchkp-use-static-bounds} is enabled. - -@item -fchkp-treat-zero-dynamic-size-as-infinite -@opindex fchkp-treat-zero-dynamic-size-as-infinite -@opindex fno-chkp-treat-zero-dynamic-size-as-infinite -With this option, objects with incomplete type whose -dynamically-obtained size is zero are treated as having infinite size -instead by Pointer Bounds -Checker. This option may be helpful if a program is linked with a library -missing size information for some symbols. Disabled by default. - -@item -fchkp-check-read -@opindex fchkp-check-read -@opindex fno-chkp-check-read -Instructs Pointer Bounds Checker to generate checks for all read -accesses to memory. Enabled by default. - -@item -fchkp-check-write -@opindex fchkp-check-write -@opindex fno-chkp-check-write -Instructs Pointer Bounds Checker to generate checks for all write -accesses to memory. Enabled by default. - -@item -fchkp-store-bounds -@opindex fchkp-store-bounds -@opindex fno-chkp-store-bounds -Instructs Pointer Bounds Checker to generate bounds stores for -pointer writes. Enabled by default. - -@item -fchkp-instrument-calls -@opindex fchkp-instrument-calls -@opindex fno-chkp-instrument-calls -Instructs Pointer Bounds Checker to pass pointer bounds to calls. -Enabled by default. - -@item -fchkp-instrument-marked-only -@opindex fchkp-instrument-marked-only -@opindex fno-chkp-instrument-marked-only -Instructs Pointer Bounds Checker to instrument only functions -marked with the @code{bnd_instrument} attribute -(@pxref{Function Attributes}). Disabled by default. - -@item -fchkp-use-wrappers -@opindex fchkp-use-wrappers -@opindex fno-chkp-use-wrappers -Allows Pointer Bounds Checker to replace calls to built-in functions -with calls to wrapper functions. When @option{-fchkp-use-wrappers} -is used to link a program, the GCC driver automatically links -against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}. -Enabled by default. - @item -fdump-final-insns@r{[}=@var{file}@r{]} @opindex fdump-final-insns Dump the final internal representation (RTL) to @var{file}. If the @@ -6501,22 +6056,6 @@ information describing them as in @file{ Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section instead of using GAS @code{.cfi_*} directives. -@cindex @command{prof} -@item -p -@opindex p -Generate extra code to write profile information suitable for the -analysis program @command{prof}. You must use this option when compiling -the source files you want data about, and you must also use it when -linking. - -@cindex @command{gprof} -@item -pg -@opindex pg -Generate extra code to write profile information suitable for the -analysis program @command{gprof}. You must use this option when compiling -the source files you want data about, and you must also use it when -linking. - @item -Q @opindex Q Makes the compiler print out each function name as it is compiled, and @@ -6582,83 +6121,6 @@ the function. If it is not present, the not bounded at compile time and the second field only represents the bounded part. -@item -fprofile-arcs -@opindex fprofile-arcs -Add code so that program flow @dfn{arcs} are instrumented. During -execution the program records how many times each branch and call is -executed and how many times it is taken or returns. When the compiled -program exits it saves this data to a file called -@file{@var{auxname}.gcda} for each source file. The data may be used for -profile-directed optimizations (@option{-fbranch-probabilities}), or for -test coverage analysis (@option{-ftest-coverage}). Each object file's -@var{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.@: @file{foo.gcda} for input file @file{dir/foo.c}, or -@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). -@xref{Cross-profiling}. - -@cindex @command{gcov} -@item --coverage -@opindex coverage - -This option is used to compile and link code instrumented for coverage -analysis. The option is a synonym for @option{-fprofile-arcs} -@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when -linking). See the documentation for those options for more details. - -@itemize - -@item -Compile the source files with @option{-fprofile-arcs} plus optimization -and code generation options. For test coverage analysis, use the -additional @option{-ftest-coverage} option. You do not need to profile -every source file in a program. - -@item -Link your object files with @option{-lgcov} or @option{-fprofile-arcs} -(the latter implies the former). - -@item -Run the program on a representative workload to generate the arc profile -information. This may be repeated any number of times. You can run -concurrent instances of your program, and provided that the file system -supports locking, the data files will be correctly updated. Also -@code{fork} calls are detected and correctly handled (double counting -will not happen). - -@item -For profile-directed optimizations, compile the source files again with -the same optimization and code generation options plus -@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that -Control Optimization}). - -@item -For test coverage analysis, use @command{gcov} to produce human readable -information from the @file{.gcno} and @file{.gcda} files. Refer to the -@command{gcov} documentation for further information. - -@end itemize - -With @option{-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. - -@need 2000 -@item -ftest-coverage -@opindex ftest-coverage -Produce a notes file that the @command{gcov} code-coverage utility -(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to -show program coverage. Each source file's note file is called -@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option -above for a description of @var{auxname} and instructions on how to -generate test coverage data. Coverage data matches the source files -more closely if you do not optimize. - @item -fdbg-cnt-list @opindex fdbg-cnt-list Print the name and the counter upper bound for all debug counters. @@ -9838,31 +9300,6 @@ be inconsistent due to missed counter up GCC uses heuristics to correct or smooth out such inconsistencies. By default, GCC emits an error message when an inconsistent profile is detected. -@item -fprofile-dir=@var{path} -@opindex fprofile-dir - -Set the directory to search for the profile data files in to @var{path}. -This option affects only the profile data generated by -@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs} -and used by @option{-fprofile-use} and @option{-fbranch-probabilities} -and its related options. Both absolute and relative paths can be used. -By default, GCC uses the current directory as @var{path}, thus the -profile data file appears in the same directory as the object file. - -@item -fprofile-generate -@itemx -fprofile-generate=@var{path} -@opindex fprofile-generate - -Enable options usually used for instrumenting application to produce -profile useful for later recompilation with profile feedback based -optimization. You must use @option{-fprofile-generate} both when -compiling and when linking your program. - -The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}. - -If @var{path} is specified, GCC looks at the @var{path} to find -the profile feedback data files. See @option{-fprofile-dir}. - @item -fprofile-use @itemx -fprofile-use=@var{path} @opindex fprofile-use @@ -9873,6 +9310,10 @@ which are generally profitable only with @option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, @option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}. +Before you can use this option, you must first generate profiling information. +@xref{Optimize Options}, for information about the @option{-fprofile-generate} +option. + By default, GCC emits an error message if the feedback profiles do not match the source code. This error can be turned into a warning by using @option{-Wcoverage-mismatch}. Note this may result in poorly optimized @@ -10156,8 +9597,8 @@ section includes experimental options th @item -fbranch-probabilities @opindex fbranch-probabilities After running a program compiled with @option{-fprofile-arcs} -(@pxref{Debugging Options,, Options for Debugging Your Program or -@command{gcc}}), you can compile it a second time using +(@pxref{Instrumentation Options}), +you can compile it a second time using @option{-fbranch-probabilities}, to improve optimizations based on the number of times each branch was taken. When a program compiled with @option{-fprofile-arcs} exits, it saves arc execution @@ -10304,30 +9745,6 @@ threading. When performing branch target register load optimization, don't reuse branch target registers within any basic block. -@item -fstack-protector -@opindex fstack-protector -Emit extra code to check for buffer overflows, such as stack smashing -attacks. This is done by adding a guard variable to functions with -vulnerable objects. This includes functions that call @code{alloca}, 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. - -@item -fstack-protector-all -@opindex fstack-protector-all -Like @option{-fstack-protector} except that all functions are protected. - -@item -fstack-protector-strong -@opindex fstack-protector-strong -Like @option{-fstack-protector} but includes additional functions to -be protected --- those that have local array definitions, or have -references to local frame addresses. - -@item -fstack-protector-explicit -@opindex fstack-protector-explicit -Like @option{-fstack-protector} but only protects those functions which -have the @code{stack_protect} attribute. - @item -fstdarg-opt @opindex fstdarg-opt Optimize the prologue of variadic argument functions with respect to usage of @@ -11283,6 +10700,792 @@ use-def chain. @end table @end table +@node Instrumentation Options +@section Program Instrumentation Options +@cindex instrumentation options +@cindex program instrumentation options +@cindex run-time error checking options +@cindex profiling options +@cindex options, program instrumentation +@cindex options, run-time error checking +@cindex options, profiling + +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. + +@table @gcctabopt +@cindex @command{prof} +@item -p +@opindex p +Generate extra code to write profile information suitable for the +analysis program @command{prof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. + +@cindex @command{gprof} +@item -pg +@opindex pg +Generate extra code to write profile information suitable for the +analysis program @command{gprof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. + +@item -fprofile-arcs +@opindex fprofile-arcs +Add code so that program flow @dfn{arcs} are instrumented. During +execution the program records how many times each branch and call is +executed and how many times it is taken or returns. When the compiled +program exits it saves this data to a file called +@file{@var{auxname}.gcda} for each source file. The data may be used for +profile-directed optimizations (@option{-fbranch-probabilities}), or for +test coverage analysis (@option{-ftest-coverage}). Each object file's +@var{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.@: @file{foo.gcda} for input file @file{dir/foo.c}, or +@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). +@xref{Cross-profiling}. + +@cindex @command{gcov} +@item --coverage +@opindex coverage + +This option is used to compile and link code instrumented for coverage +analysis. The option is a synonym for @option{-fprofile-arcs} +@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when +linking). See the documentation for those options for more details. + +@itemize + +@item +Compile the source files with @option{-fprofile-arcs} plus optimization +and code generation options. For test coverage analysis, use the +additional @option{-ftest-coverage} option. You do not need to profile +every source file in a program. + +@item +Link your object files with @option{-lgcov} or @option{-fprofile-arcs} +(the latter implies the former). + +@item +Run the program on a representative workload to generate the arc profile +information. This may be repeated any number of times. You can run +concurrent instances of your program, and provided that the file system +supports locking, the data files will be correctly updated. Also +@code{fork} calls are detected and correctly handled (double counting +will not happen). + +@item +For profile-directed optimizations, compile the source files again with +the same optimization and code generation options plus +@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that +Control Optimization}). + +@item +For test coverage analysis, use @command{gcov} to produce human readable +information from the @file{.gcno} and @file{.gcda} files. Refer to the +@command{gcov} documentation for further information. + +@end itemize + +With @option{-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. + +@need 2000 +@item -ftest-coverage +@opindex ftest-coverage +Produce a notes file that the @command{gcov} code-coverage utility +(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to +show program coverage. Each source file's note file is called +@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option +above for a description of @var{auxname} and instructions on how to +generate test coverage data. Coverage data matches the source files +more closely if you do not optimize. + +@item -fprofile-dir=@var{path} +@opindex fprofile-dir + +Set the directory to search for the profile data files in to @var{path}. +This option affects only the profile data generated by +@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs} +and used by @option{-fprofile-use} and @option{-fbranch-probabilities} +and its related options. Both absolute and relative paths can be used. +By default, GCC uses the current directory as @var{path}, thus the +profile data file appears in the same directory as the object file. + +@item -fprofile-generate +@itemx -fprofile-generate=@var{path} +@opindex fprofile-generate + +Enable options usually used for instrumenting application to produce +profile useful for later recompilation with profile feedback based +optimization. You must use @option{-fprofile-generate} both when +compiling and when linking your program. + +The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}. + +If @var{path} is specified, GCC looks at the @var{path} to find +the profile feedback data files. See @option{-fprofile-dir}. + +To optimize the program based on the collected profile information, use +@option{-fprofile-use}. @xref{Optimize Options}, for more information. + +@item -fsanitize=address +@opindex fsanitize=address +Enable AddressSanitizer, a fast memory error detector. +Memory access instructions are instrumented to detect +out-of-bounds and use-after-free bugs. +See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for +more details. The run-time behavior can be influenced using the +@env{ASAN_OPTIONS} environment variable. When set to @code{help=1}, +the available options are shown at startup of the instrumended program. See +@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags} +for a list of supported options. + +@item -fsanitize=kernel-address +@opindex fsanitize=kernel-address +Enable AddressSanitizer for Linux kernel. +See @uref{https://github.com/google/kasan/wiki} for more details. + +@item -fsanitize=thread +@opindex fsanitize=thread +Enable ThreadSanitizer, a fast data race detector. +Memory access instructions are instrumented to detect +data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more +details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS} +environment variable; see +@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of +supported options. + +@item -fsanitize=leak +@opindex fsanitize=leak +Enable LeakSanitizer, a memory leak detector. +This option only matters for linking of executables and if neither +@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that +case the executable is linked against a library that overrides @code{malloc} +and other allocator functions. See +@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more +details. The run-time behavior can be influenced using the +@env{LSAN_OPTIONS} environment variable. + +@item -fsanitize=undefined +@opindex fsanitize=undefined +Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. +Various computations are instrumented to detect undefined behavior +at runtime. Current suboptions are: + +@table @gcctabopt + +@item -fsanitize=shift +@opindex fsanitize=shift +This option enables checking that the result of a shift operation is +not undefined. Note that what exactly is considered undefined differs +slightly between C and C++, as well as between ISO C90 and C99, etc. + +@item -fsanitize=integer-divide-by-zero +@opindex fsanitize=integer-divide-by-zero +Detect integer division by zero as well as @code{INT_MIN / -1} division. + +@item -fsanitize=unreachable +@opindex fsanitize=unreachable +With this option, the compiler turns the @code{__builtin_unreachable} +call into a diagnostics message call instead. When reaching the +@code{__builtin_unreachable} call, the behavior is undefined. + +@item -fsanitize=vla-bound +@opindex fsanitize=vla-bound +This option instructs the compiler to check that the size of a variable +length array is positive. + +@item -fsanitize=null +@opindex fsanitize=null +This option enables pointer checking. Particularly, the application +built with this option turned on will issue an error message when it +tries to dereference a NULL pointer, or if a reference (possibly an +rvalue reference) is bound to a NULL pointer, or if a method is invoked +on an object pointed by a NULL pointer. + +@item -fsanitize=return +@opindex fsanitize=return +This option enables return statement checking. Programs +built with this option turned on will issue an error message +when the end of a non-void function is reached without actually +returning a value. This option works in C++ only. + +@item -fsanitize=signed-integer-overflow +@opindex fsanitize=signed-integer-overflow +This option enables signed integer overflow checking. We check that +the result of @code{+}, @code{*}, and both unary and binary @code{-} +does not overflow in the signed arithmetics. Note, integer promotion +rules must be taken into account. That is, the following is not an +overflow: +@smallexample +signed char a = SCHAR_MAX; +a++; +@end smallexample + +@item -fsanitize=bounds +@opindex fsanitize=bounds +This option enables instrumentation of array bounds. Various out of bounds +accesses are detected. Flexible array members, flexible array member-like +arrays, and initializers of variables with static storage are not instrumented. + +@item -fsanitize=bounds-strict +@opindex fsanitize=bounds-strict +This option enables strict instrumentation of array bounds. Most out of bounds +accesses are detected, including flexible array members and flexible array +member-like arrays. Initializers of variables with static storage are not +instrumented. + +@item -fsanitize=alignment +@opindex fsanitize=alignment + +This option enables checking of alignment of pointers when they are +dereferenced, or when a reference is bound to insufficiently aligned target, +or when a method or constructor is invoked on insufficiently aligned object. + +@item -fsanitize=object-size +@opindex fsanitize=object-size +This option enables instrumentation of memory references using the +@code{__builtin_object_size} function. Various out of bounds pointer +accesses are detected. + +@item -fsanitize=float-divide-by-zero +@opindex fsanitize=float-divide-by-zero +Detect floating-point division by zero. Unlike other similar options, +@option{-fsanitize=float-divide-by-zero} is not enabled by +@option{-fsanitize=undefined}, since floating-point division by zero can +be a legitimate way of obtaining infinities and NaNs. + +@item -fsanitize=float-cast-overflow +@opindex fsanitize=float-cast-overflow +This option enables floating-point type to integer conversion checking. +We check that the result of the conversion does not overflow. +Unlike other similar options, @option{-fsanitize=float-cast-overflow} is +not enabled by @option{-fsanitize=undefined}. +This option does not work well with @code{FE_INVALID} exceptions enabled. + +@item -fsanitize=nonnull-attribute +@opindex fsanitize=nonnull-attribute + +This option enables instrumentation of calls, checking whether null values +are not passed to arguments marked as requiring a non-null value by the +@code{nonnull} function attribute. + +@item -fsanitize=returns-nonnull-attribute +@opindex fsanitize=returns-nonnull-attribute + +This option enables instrumentation of return statements in functions +marked with @code{returns_nonnull} function attribute, to detect returning +of null values from such functions. + +@item -fsanitize=bool +@opindex fsanitize=bool + +This option enables instrumentation of loads from bool. If a value other +than 0/1 is loaded, a run-time error is issued. + +@item -fsanitize=enum +@opindex fsanitize=enum + +This option enables instrumentation of loads from an enum type. If +a value outside the range of values for the enum type is loaded, +a run-time error is issued. + +@item -fsanitize=vptr +@opindex fsanitize=vptr + +This option enables instrumentation of C++ member function calls, member +accesses and some conversions between pointers to base and derived classes, +to verify the referenced object has the correct dynamic type. + +@end table + +While @option{-ftrapv} causes traps for signed overflows to be emitted, +@option{-fsanitize=undefined} gives a diagnostic message. +This currently works only for the C family of languages. + +@item -fno-sanitize=all +@opindex fno-sanitize=all + +This option disables all previously enabled sanitizers. +@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used +together. + +@item -fasan-shadow-offset=@var{number} +@opindex fasan-shadow-offset +This option forces GCC to use custom shadow offset in AddressSanitizer checks. +It is useful for experimenting with different shadow memory layouts in +Kernel AddressSanitizer. + +@item -fsanitize-sections=@var{s1},@var{s2},... +@opindex fsanitize-sections +Sanitize global variables in selected user-defined sections. @var{si} may +contain wildcards. + +@item -fsanitize-recover@r{[}=@var{opts}@r{]} +@opindex fsanitize-recover +@opindex fno-sanitize-recover +@option{-fsanitize-recover=} controls error recovery mode for sanitizers +mentioned in comma-separated list of @var{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 @option{-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 @option{-fsanitize=undefined} (and its suboptions +except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}), +@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero}, +@option{-fsanitize=kernel-address} and @option{-fsanitize=address}. +For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address}, +for which this feature is experimental. +@option{-fsanitize-recover=all} and @option{-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 @var{opts} parameter is deprecated. It is equivalent to +@smallexample +-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero +@end smallexample +@noindent +Similarly @option{-fno-sanitize-recover} is equivalent to +@smallexample +-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero +@end smallexample + +@item -fsanitize-undefined-trap-on-error +@opindex fsanitize-undefined-trap-on-error +The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to +report undefined behavior using @code{__builtin_trap} rather than +a @code{libubsan} library routine. The advantage of this is that the +@code{libubsan} library is not needed and is not linked in, so this +is usable even in freestanding environments. + +@item -fsanitize-coverage=trace-pc +@opindex fsanitize-coverage=trace-pc +Enable coverage-guided fuzzing code instrumentation. +Inserts call to __sanitizer_cov_trace_pc into every basic block. + +@item -fbounds-check +@opindex fbounds-check +For front ends that support it, generate additional code to check that +indices used to access arrays are within the declared range. This is +currently only supported by the Java and Fortran front ends, where +this option defaults to true and false respectively. + +@item -fcheck-pointer-bounds +@opindex fcheck-pointer-bounds +@opindex fno-check-pointer-bounds +@cindex Pointer Bounds Checker options +Enable Pointer Bounds Checker instrumentation. Each memory reference +is instrumented with checks of the pointer used for memory access against +bounds associated with that pointer. + +Currently there +is only an implementation for Intel MPX available, thus x86 target +and @option{-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 @option{-fcheck-pointer-bounds} +and @option{-mmpx} options are used to link a program, the GCC driver +links against the @file{libmpx} runtime library and @file{libmpxwrappers} +library. It also passes '-z bndplt' to a linker in case it supports this +option (which is checked on libmpx configuration). Note that old versions +of linker may ignore option. Gold linker doesn't support '-z bndplt' +option. With no '-z bndplt' support in linker all calls to dynamic libraries +lose passed bounds reducing overall protection level. It's highly +recommended to use linker with '-z bndplt' support. In case such linker +is not available it is adviced to always use @option{-static-libmpxwrappers} +for better protection level or use @option{-static} to completely avoid +external calls to dynamic libraries. 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 @option{-lpthread}. See +also @option{-static-libmpx}. The runtime library behavior can be +influenced using various @env{CHKP_RT_*} environment variables. See +@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler} +for more details. + +Generated instrumentation may be controlled by various +@option{-fchkp-*} options and by the @code{bnd_variable_size} +structure field attribute (@pxref{Type Attributes}) and +@code{bnd_legacy}, and @code{bnd_instrument} function attributes +(@pxref{Function Attributes}). GCC also provides a number of built-in +functions for controlling the Pointer Bounds Checker. @xref{Pointer +Bounds Checker builtins}, for more information. + +@item -fchecking +@opindex fchecking +@opindex fno-checking +Enable internal consistency checking. The default depends on +the compiler configuration. + +@item -fchkp-check-incomplete-type +@opindex fchkp-check-incomplete-type +@opindex fno-chkp-check-incomplete-type +Generate pointer bounds checks for variables with incomplete type. +Enabled by default. + +@item -fchkp-narrow-bounds +@opindex fchkp-narrow-bounds +@opindex fno-chkp-narrow-bounds +Controls bounds used by Pointer Bounds Checker for pointers to object +fields. If narrowing is enabled then field bounds are used. Otherwise +object bounds are used. See also @option{-fchkp-narrow-to-innermost-array} +and @option{-fchkp-first-field-has-own-bounds}. Enabled by default. + +@item -fchkp-first-field-has-own-bounds +@opindex fchkp-first-field-has-own-bounds +@opindex fno-chkp-first-field-has-own-bounds +Forces Pointer Bounds Checker to use narrowed bounds for the address of the +first field in the structure. By default a pointer to the first field has +the same bounds as a pointer to the whole structure. + +@item -fchkp-narrow-to-innermost-array +@opindex fchkp-narrow-to-innermost-array +@opindex fno-chkp-narrow-to-innermost-array +Forces Pointer Bounds Checker to use bounds of the innermost arrays in +case of nested static array access. By default this option is disabled and +bounds of the outermost array are used. + +@item -fchkp-optimize +@opindex fchkp-optimize +@opindex fno-chkp-optimize +Enables Pointer Bounds Checker optimizations. Enabled by default at +optimization levels @option{-O}, @option{-O2}, @option{-O3}. + +@item -fchkp-use-fast-string-functions +@opindex fchkp-use-fast-string-functions +@opindex fno-chkp-use-fast-string-functions +Enables use of @code{*_nobnd} versions of string functions (not copying bounds) +by Pointer Bounds Checker. Disabled by default. + +@item -fchkp-use-nochk-string-functions +@opindex fchkp-use-nochk-string-functions +@opindex fno-chkp-use-nochk-string-functions +Enables use of @code{*_nochk} versions of string functions (not checking bounds) +by Pointer Bounds Checker. Disabled by default. + +@item -fchkp-use-static-bounds +@opindex fchkp-use-static-bounds +@opindex fno-chkp-use-static-bounds +Allow Pointer Bounds Checker to generate static bounds holding +bounds of static variables. Enabled by default. + +@item -fchkp-use-static-const-bounds +@opindex fchkp-use-static-const-bounds +@opindex fno-chkp-use-static-const-bounds +Use statically-initialized bounds for constant bounds instead of +generating them each time they are required. By default enabled when +@option{-fchkp-use-static-bounds} is enabled. + +@item -fchkp-treat-zero-dynamic-size-as-infinite +@opindex fchkp-treat-zero-dynamic-size-as-infinite +@opindex fno-chkp-treat-zero-dynamic-size-as-infinite +With this option, objects with incomplete type whose +dynamically-obtained size is zero are treated as having infinite size +instead by Pointer Bounds +Checker. This option may be helpful if a program is linked with a library +missing size information for some symbols. Disabled by default. + +@item -fchkp-check-read +@opindex fchkp-check-read +@opindex fno-chkp-check-read +Instructs Pointer Bounds Checker to generate checks for all read +accesses to memory. Enabled by default. + +@item -fchkp-check-write +@opindex fchkp-check-write +@opindex fno-chkp-check-write +Instructs Pointer Bounds Checker to generate checks for all write +accesses to memory. Enabled by default. + +@item -fchkp-store-bounds +@opindex fchkp-store-bounds +@opindex fno-chkp-store-bounds +Instructs Pointer Bounds Checker to generate bounds stores for +pointer writes. Enabled by default. + +@item -fchkp-instrument-calls +@opindex fchkp-instrument-calls +@opindex fno-chkp-instrument-calls +Instructs Pointer Bounds Checker to pass pointer bounds to calls. +Enabled by default. + +@item -fchkp-instrument-marked-only +@opindex fchkp-instrument-marked-only +@opindex fno-chkp-instrument-marked-only +Instructs Pointer Bounds Checker to instrument only functions +marked with the @code{bnd_instrument} attribute +(@pxref{Function Attributes}). Disabled by default. + +@item -fchkp-use-wrappers +@opindex fchkp-use-wrappers +@opindex fno-chkp-use-wrappers +Allows Pointer Bounds Checker to replace calls to built-in functions +with calls to wrapper functions. When @option{-fchkp-use-wrappers} +is used to link a program, the GCC driver automatically links +against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}. +Enabled by default. + +@item -fstack-protector +@opindex fstack-protector +Emit extra code to check for buffer overflows, such as stack smashing +attacks. This is done by adding a guard variable to functions with +vulnerable objects. This includes functions that call @code{alloca}, 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. + +@item -fstack-protector-all +@opindex fstack-protector-all +Like @option{-fstack-protector} except that all functions are protected. + +@item -fstack-protector-strong +@opindex fstack-protector-strong +Like @option{-fstack-protector} but includes additional functions to +be protected --- those that have local array definitions, or have +references to local frame addresses. + +@item -fstack-protector-explicit +@opindex fstack-protector-explicit +Like @option{-fstack-protector} but only protects those functions which +have the @code{stack_protect} attribute. + +@item -fstack-check +@opindex fstack-check +Generate code to verify that you do not go beyond the boundary of the +stack. You should specify this flag if you are running in an +environment with multiple threads, but you only rarely need to specify it in +a single-threaded environment since stack overflow is automatically +detected on nearly all systems if there is only one stack. + +Note 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: @samp{no} means no +checking, @samp{generic} means force the use of old-style checking, +@samp{specific} means use the best checking method and is equivalent +to bare @option{-fstack-check}. + +Old-style checking is a generic mechanism that requires no specific +target support in the compiler but comes with the following drawbacks: + +@enumerate +@item +Modified allocation strategy for large objects: they are always +allocated dynamically if their size exceeds a fixed threshold. + +@item +Fixed limit on the size of the static frame of functions: when it is +topped by a particular function, stack checking is not reliable and +a warning is issued by the compiler. + +@item +Inefficiency: because of both the modified allocation strategy and the +generic implementation, code performance is hampered. +@end enumerate + +Note that old-style stack checking is also the fallback method for +@samp{specific} if no target support has been added in the compiler. + +@item -fstack-limit-register=@var{reg} +@itemx -fstack-limit-symbol=@var{sym} +@itemx -fno-stack-limit +@opindex fstack-limit-register +@opindex fstack-limit-symbol +@opindex fno-stack-limit +Generate code to ensure that the stack does not grow beyond a certain value, +either the value of a register or the address of a symbol. If a larger +stack is required, a signal is raised at run time. For most targets, +the signal is raised before the stack overruns the boundary, so +it is possible to catch the signal without taking special precautions. + +For instance, if the stack starts at absolute address @samp{0x80000000} +and grows downwards, you can use the flags +@option{-fstack-limit-symbol=__stack_limit} and +@option{-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 +@code{no_stack_limit} function attribute (@pxref{Function Attributes}). + +@item -fsplit-stack +@opindex fsplit-stack +Generate code to automatically split the stack before it overflows. +The resulting program has a discontiguous stack which can only +overflow if the program is unable to allocate any more memory. This +is most useful when running threaded programs, as it is no longer +necessary to calculate a good stack size to use for each thread. This +is currently only implemented for the x86 targets running +GNU/Linux. + +When code compiled with @option{-fsplit-stack} calls code compiled +without @option{-fsplit-stack}, there may not be much stack space +available for the latter code to run. If compiling all code, +including library code, with @option{-fsplit-stack} is not an option, +then the linker can fix up these calls so that the code compiled +without @option{-fsplit-stack} always has a large stack. Support for +this is implemented in the gold linker in GNU binutils release 2.21 +and later. + +@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} +@opindex fvtable-verify +This option is only available when compiling C++ code. +It turns on (or off, if using @option{-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 @samp{std} and @samp{preinit} +control the timing of when these data structures are built. In both cases the +data structures are built before execution reaches @code{main}. Using +@option{-fvtable-verify=std} causes the data structures to be built after +shared libraries have been loaded and initialized. +@option{-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, @samp{none} takes highest priority over both @samp{std} and +@samp{preinit}; @samp{preinit} takes priority over @samp{std}. + +@item -fvtv-debug +@opindex fvtv-debug +When used in conjunction with @option{-fvtable-verify=std} or +@option{-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 @file{vtv_set_ptr_data.log} +in the directory named by the environment variable @env{VTV_LOGS_DIR} +if that is defined or the current working directory otherwise. + +Note: This feature @emph{appends} data to the log file. If you want a fresh log +file, be sure to delete any existing one. + +@item -fvtv-counts +@opindex fvtv-counts +This is a debugging flag. When used in conjunction with +@option{-fvtable-verify=std} or @option{-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 +@file{vtv_count_data.log} in the directory named by the environment +variable @env{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 @file{vtv_class_set_sizes.log} +in the same directory. + +Note: This feature @emph{appends} data to the log files. To get fresh log +files, be sure to delete any existing ones. + +@item -finstrument-functions +@opindex finstrument-functions +Generate instrumentation calls for entry and exit to functions. Just +after function entry and just before function exit, the following +profiling functions are called with the address of the current +function and its call site. (On some platforms, +@code{__builtin_return_address} does not work beyond the current +function, so the call site information may not be available to the +profiling functions otherwise.) + +@smallexample +void __cyg_profile_func_enter (void *this_fn, + void *call_site); +void __cyg_profile_func_exit (void *this_fn, + void *call_site); +@end smallexample + +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 @code{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 @code{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). + +@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} +@opindex finstrument-functions-exclude-file-list + +Set the list of functions that are excluded from instrumentation (see +the description of @option{-finstrument-functions}). If the file that +contains a function definition matches with one of @var{file}, then +that function is not instrumented. The match is done on substrings: +if the @var{file} parameter is a substring of the file name, it is +considered to be a match. + +For example: + +@smallexample +-finstrument-functions-exclude-file-list=/bits/stl,include/sys +@end smallexample + +@noindent +excludes any inline function defined in files whose pathnames +contain @file{/bits/stl} or @file{include/sys}. + +If, for some reason, you want to include letter @samp{,} in one of +@var{sym}, write @samp{\,}. For example, +@option{-finstrument-functions-exclude-file-list='\,\,tmp'} +(note the single quote surrounding the option). + +@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} +@opindex finstrument-functions-exclude-function-list + +This is similar to @option{-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 @code{vector blah(const vector &)}, not the +internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The +match is done on substrings: if the @var{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. + +@end table + + @node Preprocessor Options @section Options Controlling the Preprocessor @cindex preprocessor options @@ -11861,13 +12064,6 @@ can figure out the other form by either it. @table @gcctabopt -@item -fbounds-check -@opindex fbounds-check -For front ends that support it, generate additional code to check that -indices used to access arrays are within the declared range. This is -currently only supported by the Java and Fortran front ends, where -this option defaults to true and false respectively. - @item -fstack-reuse=@var{reuse-level} @opindex fstack_reuse This option controls stack space reuse for user declared local/auto variables @@ -12282,160 +12478,6 @@ code that is not binary compatible with Additionally, it makes the code suboptimal. Use it to conform to a non-default application binary interface. -@item -finstrument-functions -@opindex finstrument-functions -Generate instrumentation calls for entry and exit to functions. Just -after function entry and just before function exit, the following -profiling functions are called with the address of the current -function and its call site. (On some platforms, -@code{__builtin_return_address} does not work beyond the current -function, so the call site information may not be available to the -profiling functions otherwise.) - -@smallexample -void __cyg_profile_func_enter (void *this_fn, - void *call_site); -void __cyg_profile_func_exit (void *this_fn, - void *call_site); -@end smallexample - -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 @code{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 @code{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). - -@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} -@opindex finstrument-functions-exclude-file-list - -Set the list of functions that are excluded from instrumentation (see -the description of @option{-finstrument-functions}). If the file that -contains a function definition matches with one of @var{file}, then -that function is not instrumented. The match is done on substrings: -if the @var{file} parameter is a substring of the file name, it is -considered to be a match. - -For example: - -@smallexample --finstrument-functions-exclude-file-list=/bits/stl,include/sys -@end smallexample - -@noindent -excludes any inline function defined in files whose pathnames -contain @file{/bits/stl} or @file{include/sys}. - -If, for some reason, you want to include letter @samp{,} in one of -@var{sym}, write @samp{\,}. For example, -@option{-finstrument-functions-exclude-file-list='\,\,tmp'} -(note the single quote surrounding the option). - -@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} -@opindex finstrument-functions-exclude-function-list - -This is similar to @option{-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 @code{vector blah(const vector &)}, not the -internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The -match is done on substrings: if the @var{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. - -@item -fstack-check -@opindex fstack-check -Generate code to verify that you do not go beyond the boundary of the -stack. You should specify this flag if you are running in an -environment with multiple threads, but you only rarely need to specify it in -a single-threaded environment since stack overflow is automatically -detected on nearly all systems if there is only one stack. - -Note 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: @samp{no} means no -checking, @samp{generic} means force the use of old-style checking, -@samp{specific} means use the best checking method and is equivalent -to bare @option{-fstack-check}. - -Old-style checking is a generic mechanism that requires no specific -target support in the compiler but comes with the following drawbacks: - -@enumerate -@item -Modified allocation strategy for large objects: they are always -allocated dynamically if their size exceeds a fixed threshold. - -@item -Fixed limit on the size of the static frame of functions: when it is -topped by a particular function, stack checking is not reliable and -a warning is issued by the compiler. - -@item -Inefficiency: because of both the modified allocation strategy and the -generic implementation, code performance is hampered. -@end enumerate - -Note that old-style stack checking is also the fallback method for -@samp{specific} if no target support has been added in the compiler. - -@item -fstack-limit-register=@var{reg} -@itemx -fstack-limit-symbol=@var{sym} -@itemx -fno-stack-limit -@opindex fstack-limit-register -@opindex fstack-limit-symbol -@opindex fno-stack-limit -Generate code to ensure that the stack does not grow beyond a certain value, -either the value of a register or the address of a symbol. If a larger -stack is required, a signal is raised at run time. For most targets, -the signal is raised before the stack overruns the boundary, so -it is possible to catch the signal without taking special precautions. - -For instance, if the stack starts at absolute address @samp{0x80000000} -and grows downwards, you can use the flags -@option{-fstack-limit-symbol=__stack_limit} and -@option{-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 -@code{no_stack_limit} function attribute (@pxref{Function Attributes}). - -@item -fsplit-stack -@opindex fsplit-stack -Generate code to automatically split the stack before it overflows. -The resulting program has a discontiguous stack which can only -overflow if the program is unable to allocate any more memory. This -is most useful when running threaded programs, as it is no longer -necessary to calculate a good stack size to use for each thread. This -is currently only implemented for the x86 targets running -GNU/Linux. - -When code compiled with @option{-fsplit-stack} calls code compiled -without @option{-fsplit-stack}, there may not be much stack space -available for the latter code to run. If compiling all code, -including library code, with @option{-fsplit-stack} is not an option, -then the linker can fix up these calls so that the code compiled -without @option{-fsplit-stack} always has a large stack. Support for -this is implemented in the gold linker in GNU binutils release 2.21 -and later. - @item -fleading-underscore @opindex fleading-underscore This option and its counterpart, @option{-fno-leading-underscore}, forcibly