<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
<html>
|
<!-- Copyright (C) 1988-2016 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being "Funding Free Software", the Front-Cover
|
Texts being (a) (see below), and with the Back-Cover Texts being (b)
|
(see below). A copy of the license is included in the section entitled
|
"GNU Free Documentation License".
|
|
(a) The FSF's Front-Cover Text is:
|
|
A GNU Manual
|
|
(b) The FSF's Back-Cover Text is:
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
software. Copies published by the Free Software Foundation raise
|
funds for GNU development. -->
|
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
|
<head>
|
<title>Using the GNU Compiler Collection (GCC): Instrumentation Options</title>
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC): Instrumentation Options">
|
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Instrumentation Options">
|
<meta name="resource-type" content="document">
|
<meta name="distribution" content="global">
|
<meta name="Generator" content="makeinfo">
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
<link href="index.html#Top" rel="start" title="Top">
|
<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
<link href="Invoking-GCC.html#Invoking-GCC" rel="up" title="Invoking GCC">
|
<link href="Preprocessor-Options.html#Preprocessor-Options" rel="next" title="Preprocessor Options">
|
<link href="Optimize-Options.html#Optimize-Options" rel="prev" title="Optimize Options">
|
<style type="text/css">
|
<!--
|
a.summary-letter {text-decoration: none}
|
blockquote.smallquotation {font-size: smaller}
|
div.display {margin-left: 3.2em}
|
div.example {margin-left: 3.2em}
|
div.indentedblock {margin-left: 3.2em}
|
div.lisp {margin-left: 3.2em}
|
div.smalldisplay {margin-left: 3.2em}
|
div.smallexample {margin-left: 3.2em}
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
div.smalllisp {margin-left: 3.2em}
|
kbd {font-style:oblique}
|
pre.display {font-family: inherit}
|
pre.format {font-family: inherit}
|
pre.menu-comment {font-family: serif}
|
pre.menu-preformatted {font-family: serif}
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
pre.smallexample {font-size: smaller}
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
pre.smalllisp {font-size: smaller}
|
span.nocodebreak {white-space:nowrap}
|
span.nolinebreak {white-space:nowrap}
|
span.roman {font-family:serif; font-weight:normal}
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
ul.no-bullet {list-style: none}
|
-->
|
</style>
|
|
|
</head>
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
<a name="Instrumentation-Options"></a>
|
<div class="header">
|
<p>
|
Next: <a href="Preprocessor-Options.html#Preprocessor-Options" accesskey="n" rel="next">Preprocessor Options</a>, Previous: <a href="Optimize-Options.html#Optimize-Options" accesskey="p" rel="prev">Optimize Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
</div>
|
<hr>
|
<a name="Program-Instrumentation-Options"></a>
|
<h3 class="section">3.11 Program Instrumentation Options</h3>
|
<a name="index-instrumentation-options"></a>
|
<a name="index-program-instrumentation-options"></a>
|
<a name="index-run_002dtime-error-checking-options"></a>
|
<a name="index-profiling-options"></a>
|
<a name="index-options_002c-program-instrumentation"></a>
|
<a name="index-options_002c-run_002dtime-error-checking"></a>
|
<a name="index-options_002c-profiling"></a>
|
|
<p>GCC supports a number of command-line options that control adding
|
run-time instrumentation to the code it normally generates.
|
For example, one purpose of instrumentation is collect profiling
|
statistics for use in finding program hot spots, code coverage
|
analysis, or profile-guided optimizations.
|
Another class of program instrumentation is adding run-time checking
|
to detect programming errors like invalid pointer
|
dereferences or out-of-bounds array accesses, as well as deliberately
|
hostile attacks such as stack smashing or C++ vtable hijacking.
|
There is also a general hook which can be used to implement other
|
forms of tracing or function-level instrumentation for debug or
|
program analysis purposes.
|
</p>
|
<dl compact="compact">
|
<dd><a name="index-prof"></a>
|
</dd>
|
<dt><code>-p</code></dt>
|
<dd><a name="index-p"></a>
|
<p>Generate extra code to write profile information suitable for the
|
analysis program <code>prof</code>. You must use this option when compiling
|
the source files you want data about, and you must also use it when
|
linking.
|
</p>
|
<a name="index-gprof"></a>
|
</dd>
|
<dt><code>-pg</code></dt>
|
<dd><a name="index-pg"></a>
|
<p>Generate extra code to write profile information suitable for the
|
analysis program <code>gprof</code>. You must use this option when compiling
|
the source files you want data about, and you must also use it when
|
linking.
|
</p>
|
</dd>
|
<dt><code>-fprofile-arcs</code></dt>
|
<dd><a name="index-fprofile_002darcs"></a>
|
<p>Add code so that program flow <em>arcs</em> 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
|
<samp><var>auxname</var>.gcda</samp> for each source file. The data may be used for
|
profile-directed optimizations (<samp>-fbranch-probabilities</samp>), or for
|
test coverage analysis (<samp>-ftest-coverage</samp>). Each object file’s
|
<var>auxname</var> 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. <samp>foo.gcda</samp> for input file <samp>dir/foo.c</samp>, or
|
<samp>dir/foo.gcda</samp> for output file specified as <samp>-o dir/foo.o</samp>).
|
See <a href="Cross_002dprofiling.html#Cross_002dprofiling">Cross-profiling</a>.
|
</p>
|
<a name="index-gcov"></a>
|
</dd>
|
<dt><code>--coverage</code></dt>
|
<dd><a name="index-coverage"></a>
|
|
<p>This option is used to compile and link code instrumented for coverage
|
analysis. The option is a synonym for <samp>-fprofile-arcs</samp>
|
<samp>-ftest-coverage</samp> (when compiling) and <samp>-lgcov</samp> (when
|
linking). See the documentation for those options for more details.
|
</p>
|
<ul>
|
<li> Compile the source files with <samp>-fprofile-arcs</samp> plus optimization
|
and code generation options. For test coverage analysis, use the
|
additional <samp>-ftest-coverage</samp> option. You do not need to profile
|
every source file in a program.
|
|
</li><li> Link your object files with <samp>-lgcov</samp> or <samp>-fprofile-arcs</samp>
|
(the latter implies the former).
|
|
</li><li> 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</code> calls are detected and correctly handled (double counting
|
will not happen).
|
|
</li><li> For profile-directed optimizations, compile the source files again with
|
the same optimization and code generation options plus
|
<samp>-fbranch-probabilities</samp> (see <a href="Optimize-Options.html#Optimize-Options">Options that
|
Control Optimization</a>).
|
|
</li><li> For test coverage analysis, use <code>gcov</code> to produce human readable
|
information from the <samp>.gcno</samp> and <samp>.gcda</samp> files. Refer to the
|
<code>gcov</code> documentation for further information.
|
|
</li></ul>
|
|
<p>With <samp>-fprofile-arcs</samp>, 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.
|
</p>
|
</dd>
|
<dt><code>-ftest-coverage</code></dt>
|
<dd><a name="index-ftest_002dcoverage"></a>
|
<p>Produce a notes file that the <code>gcov</code> code-coverage utility
|
(see <a href="Gcov.html#Gcov"><code>gcov</code>—a Test Coverage Program</a>) can use to
|
show program coverage. Each source file’s note file is called
|
<samp><var>auxname</var>.gcno</samp>. Refer to the <samp>-fprofile-arcs</samp> option
|
above for a description of <var>auxname</var> and instructions on how to
|
generate test coverage data. Coverage data matches the source files
|
more closely if you do not optimize.
|
</p>
|
</dd>
|
<dt><code>-fprofile-dir=<var>path</var></code></dt>
|
<dd><a name="index-fprofile_002ddir"></a>
|
|
<p>Set the directory to search for the profile data files in to <var>path</var>.
|
This option affects only the profile data generated by
|
<samp>-fprofile-generate</samp>, <samp>-ftest-coverage</samp>, <samp>-fprofile-arcs</samp>
|
and used by <samp>-fprofile-use</samp> and <samp>-fbranch-probabilities</samp>
|
and its related options. Both absolute and relative paths can be used.
|
By default, GCC uses the current directory as <var>path</var>, thus the
|
profile data file appears in the same directory as the object file.
|
</p>
|
</dd>
|
<dt><code>-fprofile-generate</code></dt>
|
<dt><code>-fprofile-generate=<var>path</var></code></dt>
|
<dd><a name="index-fprofile_002dgenerate"></a>
|
|
<p>Enable options usually used for instrumenting application to produce
|
profile useful for later recompilation with profile feedback based
|
optimization. You must use <samp>-fprofile-generate</samp> both when
|
compiling and when linking your program.
|
</p>
|
<p>The following options are enabled: <samp>-fprofile-arcs</samp>, <samp>-fprofile-values</samp>, <samp>-fvpt</samp>.
|
</p>
|
<p>If <var>path</var> is specified, GCC looks at the <var>path</var> to find
|
the profile feedback data files. See <samp>-fprofile-dir</samp>.
|
</p>
|
<p>To optimize the program based on the collected profile information, use
|
<samp>-fprofile-use</samp>. See <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>, for more information.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=address</code></dt>
|
<dd><a name="index-fsanitize_003daddress"></a>
|
<p>Enable AddressSanitizer, a fast memory error detector.
|
Memory access instructions are instrumented to detect
|
out-of-bounds and use-after-free bugs.
|
See <a href="https://github.com/google/sanitizers/wiki/AddressSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizer</a> for
|
more details. The run-time behavior can be influenced using the
|
<code>ASAN_OPTIONS</code> environment variable. When set to <code>help=1</code>,
|
the available options are shown at startup of the instrumented program. See
|
<a href="https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags">https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags</a>
|
for a list of supported options.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=kernel-address</code></dt>
|
<dd><a name="index-fsanitize_003dkernel_002daddress"></a>
|
<p>Enable AddressSanitizer for Linux kernel.
|
See <a href="https://github.com/google/kasan/wiki">https://github.com/google/kasan/wiki</a> for more details.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=thread</code></dt>
|
<dd><a name="index-fsanitize_003dthread"></a>
|
<p>Enable ThreadSanitizer, a fast data race detector.
|
Memory access instructions are instrumented to detect
|
data race bugs. See <a href="https://github.com/google/sanitizers/wiki#threadsanitizer">https://github.com/google/sanitizers/wiki#threadsanitizer</a> for more
|
details. The run-time behavior can be influenced using the <code>TSAN_OPTIONS</code>
|
environment variable; see
|
<a href="https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags">https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags</a> for a list of
|
supported options.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=leak</code></dt>
|
<dd><a name="index-fsanitize_003dleak"></a>
|
<p>Enable LeakSanitizer, a memory leak detector.
|
This option only matters for linking of executables and if neither
|
<samp>-fsanitize=address</samp> nor <samp>-fsanitize=thread</samp> is used. In that
|
case the executable is linked against a library that overrides <code>malloc</code>
|
and other allocator functions. See
|
<a href="https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer</a> for more
|
details. The run-time behavior can be influenced using the
|
<code>LSAN_OPTIONS</code> environment variable.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=undefined</code></dt>
|
<dd><a name="index-fsanitize_003dundefined"></a>
|
<p>Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
|
Various computations are instrumented to detect undefined behavior
|
at runtime. Current suboptions are:
|
</p>
|
<dl compact="compact">
|
<dt><code>-fsanitize=shift</code></dt>
|
<dd><a name="index-fsanitize_003dshift"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=integer-divide-by-zero</code></dt>
|
<dd><a name="index-fsanitize_003dinteger_002ddivide_002dby_002dzero"></a>
|
<p>Detect integer division by zero as well as <code>INT_MIN / -1</code> division.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=unreachable</code></dt>
|
<dd><a name="index-fsanitize_003dunreachable"></a>
|
<p>With this option, the compiler turns the <code>__builtin_unreachable</code>
|
call into a diagnostics message call instead. When reaching the
|
<code>__builtin_unreachable</code> call, the behavior is undefined.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=vla-bound</code></dt>
|
<dd><a name="index-fsanitize_003dvla_002dbound"></a>
|
<p>This option instructs the compiler to check that the size of a variable
|
length array is positive.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=null</code></dt>
|
<dd><a name="index-fsanitize_003dnull"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=return</code></dt>
|
<dd><a name="index-fsanitize_003dreturn"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=signed-integer-overflow</code></dt>
|
<dd><a name="index-fsanitize_003dsigned_002dinteger_002doverflow"></a>
|
<p>This option enables signed integer overflow checking. We check that
|
the result of <code>+</code>, <code>*</code>, and both unary and binary <code>-</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:
|
</p><div class="smallexample">
|
<pre class="smallexample">signed char a = SCHAR_MAX;
|
a++;
|
</pre></div>
|
|
</dd>
|
<dt><code>-fsanitize=bounds</code></dt>
|
<dd><a name="index-fsanitize_003dbounds"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=bounds-strict</code></dt>
|
<dd><a name="index-fsanitize_003dbounds_002dstrict"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=alignment</code></dt>
|
<dd><a name="index-fsanitize_003dalignment"></a>
|
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=object-size</code></dt>
|
<dd><a name="index-fsanitize_003dobject_002dsize"></a>
|
<p>This option enables instrumentation of memory references using the
|
<code>__builtin_object_size</code> function. Various out of bounds pointer
|
accesses are detected.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=float-divide-by-zero</code></dt>
|
<dd><a name="index-fsanitize_003dfloat_002ddivide_002dby_002dzero"></a>
|
<p>Detect floating-point division by zero. Unlike other similar options,
|
<samp>-fsanitize=float-divide-by-zero</samp> is not enabled by
|
<samp>-fsanitize=undefined</samp>, since floating-point division by zero can
|
be a legitimate way of obtaining infinities and NaNs.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=float-cast-overflow</code></dt>
|
<dd><a name="index-fsanitize_003dfloat_002dcast_002doverflow"></a>
|
<p>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, <samp>-fsanitize=float-cast-overflow</samp> is
|
not enabled by <samp>-fsanitize=undefined</samp>.
|
This option does not work well with <code>FE_INVALID</code> exceptions enabled.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=nonnull-attribute</code></dt>
|
<dd><a name="index-fsanitize_003dnonnull_002dattribute"></a>
|
|
<p>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</code> function attribute.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=returns-nonnull-attribute</code></dt>
|
<dd><a name="index-fsanitize_003dreturns_002dnonnull_002dattribute"></a>
|
|
<p>This option enables instrumentation of return statements in functions
|
marked with <code>returns_nonnull</code> function attribute, to detect returning
|
of null values from such functions.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=bool</code></dt>
|
<dd><a name="index-fsanitize_003dbool"></a>
|
|
<p>This option enables instrumentation of loads from bool. If a value other
|
than 0/1 is loaded, a run-time error is issued.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=enum</code></dt>
|
<dd><a name="index-fsanitize_003denum"></a>
|
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize=vptr</code></dt>
|
<dd><a name="index-fsanitize_003dvptr"></a>
|
|
<p>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.
|
</p>
|
</dd>
|
</dl>
|
|
<p>While <samp>-ftrapv</samp> causes traps for signed overflows to be emitted,
|
<samp>-fsanitize=undefined</samp> gives a diagnostic message.
|
This currently works only for the C family of languages.
|
</p>
|
</dd>
|
<dt><code>-fno-sanitize=all</code></dt>
|
<dd><a name="index-fno_002dsanitize_003dall"></a>
|
|
<p>This option disables all previously enabled sanitizers.
|
<samp>-fsanitize=all</samp> is not allowed, as some sanitizers cannot be used
|
together.
|
</p>
|
</dd>
|
<dt><code>-fasan-shadow-offset=<var>number</var></code></dt>
|
<dd><a name="index-fasan_002dshadow_002doffset"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fsanitize-sections=<var>s1</var>,<var>s2</var>,...</code></dt>
|
<dd><a name="index-fsanitize_002dsections"></a>
|
<p>Sanitize global variables in selected user-defined sections. <var>si</var> may
|
contain wildcards.
|
</p>
|
</dd>
|
<dt><code>-fsanitize-recover<span class="roman">[</span>=<var>opts</var><span class="roman">]</span></code></dt>
|
<dd><a name="index-fsanitize_002drecover"></a>
|
<a name="index-fno_002dsanitize_002drecover"></a>
|
<p><samp>-fsanitize-recover=</samp> controls error recovery mode for sanitizers
|
mentioned in comma-separated list of <var>opts</var>. 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 <samp>-fno-sanitize-recover=</samp> 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.
|
</p>
|
<p>Currently this feature only works for <samp>-fsanitize=undefined</samp> (and its suboptions
|
except for <samp>-fsanitize=unreachable</samp> and <samp>-fsanitize=return</samp>),
|
<samp>-fsanitize=float-cast-overflow</samp>, <samp>-fsanitize=float-divide-by-zero</samp>,
|
<samp>-fsanitize=kernel-address</samp> and <samp>-fsanitize=address</samp>.
|
For these sanitizers error recovery is turned on by default, except <samp>-fsanitize=address</samp>,
|
for which this feature is experimental.
|
<samp>-fsanitize-recover=all</samp> and <samp>-fno-sanitize-recover=all</samp> is also
|
accepted, the former enables recovery for all sanitizers that support it,
|
the latter disables recovery for all sanitizers that support it.
|
</p>
|
<p>Syntax without explicit <var>opts</var> parameter is deprecated. It is equivalent to
|
</p><div class="smallexample">
|
<pre class="smallexample">-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
|
</pre></div>
|
<p>Similarly <samp>-fno-sanitize-recover</samp> is equivalent to
|
</p><div class="smallexample">
|
<pre class="smallexample">-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
|
</pre></div>
|
|
</dd>
|
<dt><code>-fsanitize-undefined-trap-on-error</code></dt>
|
<dd><a name="index-fsanitize_002dundefined_002dtrap_002don_002derror"></a>
|
<p>The <samp>-fsanitize-undefined-trap-on-error</samp> option instructs the compiler to
|
report undefined behavior using <code>__builtin_trap</code> rather than
|
a <code>libubsan</code> library routine. The advantage of this is that the
|
<code>libubsan</code> library is not needed and is not linked in, so this
|
is usable even in freestanding environments.
|
</p>
|
</dd>
|
<dt><code>-fsanitize-coverage=trace-pc</code></dt>
|
<dd><a name="index-fsanitize_002dcoverage_003dtrace_002dpc"></a>
|
<p>Enable coverage-guided fuzzing code instrumentation.
|
Inserts a call to <code>__sanitizer_cov_trace_pc</code> into every basic block.
|
</p>
|
</dd>
|
<dt><code>-fbounds-check</code></dt>
|
<dd><a name="index-fbounds_002dcheck"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fcheck-pointer-bounds</code></dt>
|
<dd><a name="index-fcheck_002dpointer_002dbounds"></a>
|
<a name="index-fno_002dcheck_002dpointer_002dbounds"></a>
|
<a name="index-Pointer-Bounds-Checker-options"></a>
|
<p>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.
|
</p>
|
<p>Currently there
|
is only an implementation for Intel MPX available, thus x86 GNU/Linux target
|
and <samp>-mmpx</samp> 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 <samp>-fcheck-pointer-bounds</samp>
|
and <samp>-mmpx</samp> options are used to link a program, the GCC driver
|
links against the <samp>libmpx</samp> and <samp>libmpxwrappers</samp> libraries.
|
Bounds checking on calls to dynamic libraries requires a linker
|
with <samp>-z bndplt</samp> support; if GCC was configured with a linker
|
without support for this option (including the Gold linker and older
|
versions of ld), a warning is given if you link with <samp>-mmpx</samp>
|
without also specifying <samp>-static</samp>, since the overall effectiveness
|
of the bounds checking protection is reduced.
|
See also <samp>-static-libmpxwrappers</samp>.
|
</p>
|
<p>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 <samp>-lpthread</samp>. See
|
also <samp>-static-libmpx</samp>. The runtime library behavior can be
|
influenced using various <code>CHKP_RT_*</code> environment variables. See
|
<a href="https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler">https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler</a>
|
for more details.
|
</p>
|
<p>Generated instrumentation may be controlled by various
|
<samp>-fchkp-*</samp> options and by the <code>bnd_variable_size</code>
|
structure field attribute (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>) and
|
<code>bnd_legacy</code>, and <code>bnd_instrument</code> function attributes
|
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>). GCC also provides a number of built-in
|
functions for controlling the Pointer Bounds Checker. See <a href="Pointer-Bounds-Checker-builtins.html#Pointer-Bounds-Checker-builtins">Pointer Bounds Checker builtins</a>, for more information.
|
</p>
|
</dd>
|
<dt><code>-fchkp-check-incomplete-type</code></dt>
|
<dd><a name="index-fchkp_002dcheck_002dincomplete_002dtype"></a>
|
<a name="index-fno_002dchkp_002dcheck_002dincomplete_002dtype"></a>
|
<p>Generate pointer bounds checks for variables with incomplete type.
|
Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-narrow-bounds</code></dt>
|
<dd><a name="index-fchkp_002dnarrow_002dbounds"></a>
|
<a name="index-fno_002dchkp_002dnarrow_002dbounds"></a>
|
<p>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 <samp>-fchkp-narrow-to-innermost-array</samp>
|
and <samp>-fchkp-first-field-has-own-bounds</samp>. Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-first-field-has-own-bounds</code></dt>
|
<dd><a name="index-fchkp_002dfirst_002dfield_002dhas_002down_002dbounds"></a>
|
<a name="index-fno_002dchkp_002dfirst_002dfield_002dhas_002down_002dbounds"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fchkp-narrow-to-innermost-array</code></dt>
|
<dd><a name="index-fchkp_002dnarrow_002dto_002dinnermost_002darray"></a>
|
<a name="index-fno_002dchkp_002dnarrow_002dto_002dinnermost_002darray"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fchkp-optimize</code></dt>
|
<dd><a name="index-fchkp_002doptimize"></a>
|
<a name="index-fno_002dchkp_002doptimize"></a>
|
<p>Enables Pointer Bounds Checker optimizations. Enabled by default at
|
optimization levels <samp>-O</samp>, <samp>-O2</samp>, <samp>-O3</samp>.
|
</p>
|
</dd>
|
<dt><code>-fchkp-use-fast-string-functions</code></dt>
|
<dd><a name="index-fchkp_002duse_002dfast_002dstring_002dfunctions"></a>
|
<a name="index-fno_002dchkp_002duse_002dfast_002dstring_002dfunctions"></a>
|
<p>Enables use of <code>*_nobnd</code> versions of string functions (not copying bounds)
|
by Pointer Bounds Checker. Disabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-use-nochk-string-functions</code></dt>
|
<dd><a name="index-fchkp_002duse_002dnochk_002dstring_002dfunctions"></a>
|
<a name="index-fno_002dchkp_002duse_002dnochk_002dstring_002dfunctions"></a>
|
<p>Enables use of <code>*_nochk</code> versions of string functions (not checking bounds)
|
by Pointer Bounds Checker. Disabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-use-static-bounds</code></dt>
|
<dd><a name="index-fchkp_002duse_002dstatic_002dbounds"></a>
|
<a name="index-fno_002dchkp_002duse_002dstatic_002dbounds"></a>
|
<p>Allow Pointer Bounds Checker to generate static bounds holding
|
bounds of static variables. Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-use-static-const-bounds</code></dt>
|
<dd><a name="index-fchkp_002duse_002dstatic_002dconst_002dbounds"></a>
|
<a name="index-fno_002dchkp_002duse_002dstatic_002dconst_002dbounds"></a>
|
<p>Use statically-initialized bounds for constant bounds instead of
|
generating them each time they are required. By default enabled when
|
<samp>-fchkp-use-static-bounds</samp> is enabled.
|
</p>
|
</dd>
|
<dt><code>-fchkp-treat-zero-dynamic-size-as-infinite</code></dt>
|
<dd><a name="index-fchkp_002dtreat_002dzero_002ddynamic_002dsize_002das_002dinfinite"></a>
|
<a name="index-fno_002dchkp_002dtreat_002dzero_002ddynamic_002dsize_002das_002dinfinite"></a>
|
<p>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.
|
</p>
|
</dd>
|
<dt><code>-fchkp-check-read</code></dt>
|
<dd><a name="index-fchkp_002dcheck_002dread"></a>
|
<a name="index-fno_002dchkp_002dcheck_002dread"></a>
|
<p>Instructs Pointer Bounds Checker to generate checks for all read
|
accesses to memory. Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-check-write</code></dt>
|
<dd><a name="index-fchkp_002dcheck_002dwrite"></a>
|
<a name="index-fno_002dchkp_002dcheck_002dwrite"></a>
|
<p>Instructs Pointer Bounds Checker to generate checks for all write
|
accesses to memory. Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-store-bounds</code></dt>
|
<dd><a name="index-fchkp_002dstore_002dbounds"></a>
|
<a name="index-fno_002dchkp_002dstore_002dbounds"></a>
|
<p>Instructs Pointer Bounds Checker to generate bounds stores for
|
pointer writes. Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-instrument-calls</code></dt>
|
<dd><a name="index-fchkp_002dinstrument_002dcalls"></a>
|
<a name="index-fno_002dchkp_002dinstrument_002dcalls"></a>
|
<p>Instructs Pointer Bounds Checker to pass pointer bounds to calls.
|
Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-instrument-marked-only</code></dt>
|
<dd><a name="index-fchkp_002dinstrument_002dmarked_002donly"></a>
|
<a name="index-fno_002dchkp_002dinstrument_002dmarked_002donly"></a>
|
<p>Instructs Pointer Bounds Checker to instrument only functions
|
marked with the <code>bnd_instrument</code> attribute
|
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>). Disabled by default.
|
</p>
|
</dd>
|
<dt><code>-fchkp-use-wrappers</code></dt>
|
<dd><a name="index-fchkp_002duse_002dwrappers"></a>
|
<a name="index-fno_002dchkp_002duse_002dwrappers"></a>
|
<p>Allows Pointer Bounds Checker to replace calls to built-in functions
|
with calls to wrapper functions. When <samp>-fchkp-use-wrappers</samp>
|
is used to link a program, the GCC driver automatically links
|
against <samp>libmpxwrappers</samp>. See also <samp>-static-libmpxwrappers</samp>.
|
Enabled by default.
|
</p>
|
</dd>
|
<dt><code>-fstack-protector</code></dt>
|
<dd><a name="index-fstack_002dprotector"></a>
|
<p>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</code>, 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.
|
</p>
|
</dd>
|
<dt><code>-fstack-protector-all</code></dt>
|
<dd><a name="index-fstack_002dprotector_002dall"></a>
|
<p>Like <samp>-fstack-protector</samp> except that all functions are protected.
|
</p>
|
</dd>
|
<dt><code>-fstack-protector-strong</code></dt>
|
<dd><a name="index-fstack_002dprotector_002dstrong"></a>
|
<p>Like <samp>-fstack-protector</samp> but includes additional functions to
|
be protected — those that have local array definitions, or have
|
references to local frame addresses.
|
</p>
|
</dd>
|
<dt><code>-fstack-protector-explicit</code></dt>
|
<dd><a name="index-fstack_002dprotector_002dexplicit"></a>
|
<p>Like <samp>-fstack-protector</samp> but only protects those functions which
|
have the <code>stack_protect</code> attribute.
|
</p>
|
</dd>
|
<dt><code>-fstack-check</code></dt>
|
<dd><a name="index-fstack_002dcheck"></a>
|
<p>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.
|
</p>
|
<p>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.
|
</p>
|
<p>You can additionally specify a string parameter: ‘<samp>no</samp>’ means no
|
checking, ‘<samp>generic</samp>’ means force the use of old-style checking,
|
‘<samp>specific</samp>’ means use the best checking method and is equivalent
|
to bare <samp>-fstack-check</samp>.
|
</p>
|
<p>Old-style checking is a generic mechanism that requires no specific
|
target support in the compiler but comes with the following drawbacks:
|
</p>
|
<ol>
|
<li> Modified allocation strategy for large objects: they are always
|
allocated dynamically if their size exceeds a fixed threshold.
|
|
</li><li> 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.
|
|
</li><li> Inefficiency: because of both the modified allocation strategy and the
|
generic implementation, code performance is hampered.
|
</li></ol>
|
|
<p>Note that old-style stack checking is also the fallback method for
|
‘<samp>specific</samp>’ if no target support has been added in the compiler.
|
</p>
|
</dd>
|
<dt><code>-fstack-limit-register=<var>reg</var></code></dt>
|
<dt><code>-fstack-limit-symbol=<var>sym</var></code></dt>
|
<dt><code>-fno-stack-limit</code></dt>
|
<dd><a name="index-fstack_002dlimit_002dregister"></a>
|
<a name="index-fstack_002dlimit_002dsymbol"></a>
|
<a name="index-fno_002dstack_002dlimit"></a>
|
<p>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.
|
</p>
|
<p>For instance, if the stack starts at absolute address ‘<samp>0x80000000</samp>’
|
and grows downwards, you can use the flags
|
<samp>-fstack-limit-symbol=__stack_limit</samp> and
|
<samp>-Wl,--defsym,__stack_limit=0x7ffe0000</samp> to enforce a stack limit
|
of 128KB. Note that this may only work with the GNU linker.
|
</p>
|
<p>You can locally override stack limit checking by using the
|
<code>no_stack_limit</code> function attribute (see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>).
|
</p>
|
</dd>
|
<dt><code>-fsplit-stack</code></dt>
|
<dd><a name="index-fsplit_002dstack"></a>
|
<p>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.
|
</p>
|
<p>When code compiled with <samp>-fsplit-stack</samp> calls code compiled
|
without <samp>-fsplit-stack</samp>, there may not be much stack space
|
available for the latter code to run. If compiling all code,
|
including library code, with <samp>-fsplit-stack</samp> is not an option,
|
then the linker can fix up these calls so that the code compiled
|
without <samp>-fsplit-stack</samp> always has a large stack. Support for
|
this is implemented in the gold linker in GNU binutils release 2.21
|
and later.
|
</p>
|
</dd>
|
<dt><code>-fvtable-verify=<span class="roman">[</span>std<span class="roman">|</span>preinit<span class="roman">|</span>none<span class="roman">]</span></code></dt>
|
<dd><a name="index-fvtable_002dverify"></a>
|
<p>This option is only available when compiling C++ code.
|
It turns on (or off, if using <samp>-fvtable-verify=none</samp>) 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.
|
</p>
|
<p>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</samp>’ and ‘<samp>preinit</samp>’
|
control the timing of when these data structures are built. In both cases the
|
data structures are built before execution reaches <code>main</code>. Using
|
<samp>-fvtable-verify=std</samp> causes the data structures to be built after
|
shared libraries have been loaded and initialized.
|
<samp>-fvtable-verify=preinit</samp> causes them to be built before shared
|
libraries have been loaded and initialized.
|
</p>
|
<p>If this option appears multiple times in the command line with different
|
values specified, ‘<samp>none</samp>’ takes highest priority over both ‘<samp>std</samp>’ and
|
‘<samp>preinit</samp>’; ‘<samp>preinit</samp>’ takes priority over ‘<samp>std</samp>’.
|
</p>
|
</dd>
|
<dt><code>-fvtv-debug</code></dt>
|
<dd><a name="index-fvtv_002ddebug"></a>
|
<p>When used in conjunction with <samp>-fvtable-verify=std</samp> or
|
<samp>-fvtable-verify=preinit</samp>, 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 <samp>vtv_set_ptr_data.log</samp>
|
in the directory named by the environment variable <code>VTV_LOGS_DIR</code>
|
if that is defined or the current working directory otherwise.
|
</p>
|
<p>Note: This feature <em>appends</em> data to the log file. If you want a fresh log
|
file, be sure to delete any existing one.
|
</p>
|
</dd>
|
<dt><code>-fvtv-counts</code></dt>
|
<dd><a name="index-fvtv_002dcounts"></a>
|
<p>This is a debugging flag. When used in conjunction with
|
<samp>-fvtable-verify=std</samp> or <samp>-fvtable-verify=preinit</samp>, 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
|
<samp>vtv_count_data.log</samp> in the directory named by the environment
|
variable <code>VTV_LOGS_DIR</code> 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 <samp>vtv_class_set_sizes.log</samp>
|
in the same directory.
|
</p>
|
<p>Note: This feature <em>appends</em> data to the log files. To get fresh log
|
files, be sure to delete any existing ones.
|
</p>
|
</dd>
|
<dt><code>-finstrument-functions</code></dt>
|
<dd><a name="index-finstrument_002dfunctions"></a>
|
<p>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</code> does not work beyond the current
|
function, so the call site information may not be available to the
|
profiling functions otherwise.)
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">void __cyg_profile_func_enter (void *this_fn,
|
void *call_site);
|
void __cyg_profile_func_exit (void *this_fn,
|
void *call_site);
|
</pre></div>
|
|
<p>The first argument is the address of the start of the current function,
|
which may be looked up exactly in the symbol table.
|
</p>
|
<p>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</code> 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.)
|
</p>
|
<p>A function may be given the attribute <code>no_instrument_function</code>, 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).
|
</p>
|
</dd>
|
<dt><code>-finstrument-functions-exclude-file-list=<var>file</var>,<var>file</var>,…</code></dt>
|
<dd><a name="index-finstrument_002dfunctions_002dexclude_002dfile_002dlist"></a>
|
|
<p>Set the list of functions that are excluded from instrumentation (see
|
the description of <samp>-finstrument-functions</samp>). If the file that
|
contains a function definition matches with one of <var>file</var>, then
|
that function is not instrumented. The match is done on substrings:
|
if the <var>file</var> parameter is a substring of the file name, it is
|
considered to be a match.
|
</p>
|
<p>For example:
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">-finstrument-functions-exclude-file-list=/bits/stl,include/sys
|
</pre></div>
|
|
<p>excludes any inline function defined in files whose pathnames
|
contain <samp>/bits/stl</samp> or <samp>include/sys</samp>.
|
</p>
|
<p>If, for some reason, you want to include letter ‘<samp>,</samp>’ in one of
|
<var>sym</var>, write ‘<samp>\,</samp>’. For example,
|
<samp>-finstrument-functions-exclude-file-list='\,\,tmp'</samp>
|
(note the single quote surrounding the option).
|
</p>
|
</dd>
|
<dt><code>-finstrument-functions-exclude-function-list=<var>sym</var>,<var>sym</var>,…</code></dt>
|
<dd><a name="index-finstrument_002dfunctions_002dexclude_002dfunction_002dlist"></a>
|
|
<p>This is similar to <samp>-finstrument-functions-exclude-file-list</samp>,
|
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<int> blah(const vector<int> &)</code>, not the
|
internal mangled name (e.g., <code>_Z4blahRSt6vectorIiSaIiEE</code>). The
|
match is done on substrings: if the <var>sym</var> 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.
|
</p>
|
</dd>
|
</dl>
|
|
|
<hr>
|
<div class="header">
|
<p>
|
Next: <a href="Preprocessor-Options.html#Preprocessor-Options" accesskey="n" rel="next">Preprocessor Options</a>, Previous: <a href="Optimize-Options.html#Optimize-Options" accesskey="p" rel="prev">Optimize Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
</div>
|
|
|
|
</body>
|
</html>
|
