<para>Then, to gather heap profiling information about the program
<computeroutput>prog</computeroutput>, type:</para>
<screen><![CDATA[
-% valgrind --tool=massif prog
+valgrind --tool=massif prog
]]></screen>
<para>The program will execute (slowly). Upon completion, no summary
the ms_print script. If the output file's name is
<filename>massif.out.12345</filename>, type:</para>
<screen><![CDATA[
-% ms_print massif.out.12345]]></screen>
+ms_print massif.out.12345]]></screen>
<para>ms_print will produce (a) a graph showing the memory consumption over
the program's execution, and (b) detailed information about the responsible
<para>Some more details about the peak: the peak is determined by looking
at every allocation, i.e. it is <emphasis>not</emphasis> just the peak among
-the regular snapshots. However, recording the true peak is expensive, and
+the regular snapshots. However, recording the true peak can be expensive, and
so by default Massif records a peak whose size is within 1% of the size of
the true peak. See the description of the
<option>--peak-inaccuracy</option> option below for more
<option>--heap-admin</option> option.</para>
<para>Second, allocators often round up the number of bytes asked for to a
- larger number. By default, if N bytes are asked for, Massif rounds N up
- to the nearest multiple of 8 that is equal to or greater than N. This is
- typical behaviour for allocators, and is required to ensure that elements
- within the block are suitably aligned. The rounding size can be changed
- with the <option>--alignment</option> option, although it
- cannot be less than 8, and must be a power of two.</para></listitem>
+ larger number, usually 8 or 16. This is required to ensure that elements
+ within the block are suitably aligned. If N bytes are asked for, Massif
+ rounds N up to the nearest multiple of the value specified by the
+ <option><xref linkend="opt.alignment"/></option> option.
+ </para></listitem>
<listitem><para>The size of the stack(s). By default, stack profiling is
off as it slows Massif down greatly. Therefore, the stack column is zero
and C++ <function>new</function>. All heap allocations go through these
functions, and so all 9,000 useful bytes (which is 99.21% of all allocated
bytes) go through them. But how were <function>malloc</function> and new
-called? At this point, every allocation so far has been due to line 21
+called? At this point, every allocation so far has been due to line 20
inside <function>main</function>, hence the second line in the tree. The
<option>-></option> indicates that main (line 20) called
<function>malloc</function>.</para>
]]></screen>
<para>The first four snapshots are similar to the previous ones. But then
-the global allocation peak is reached, and a detailed snapshot is taken.
-Its allocation tree shows that 20,000B of useful heap memory has been
-allocated, and the lines and arrows indicate that this is from three
+the global allocation peak is reached, and a detailed snapshot (number 14)
+is taken. Its allocation tree shows that 20,000B of useful heap memory has
+been allocated, and the lines and arrows indicate that this is from three
different code locations: line 20, which is responsible for 10,000B
(49.74%); line 5, which is responsible for 8,000B (39.79%); and line 10,
which is responsible for 2,000B (9.95%).</para>
<varlistentry id="opt.heap-admin" xreflabel="--heap-admin">
<term>
- <option><![CDATA[--heap-admin=<number> [default: 8] ]]></option>
+ <option><![CDATA[--heap-admin=<size> [default: 8] ]]></option>
</term>
<listitem>
<para>If heap profiling is enabled, gives the number of administrative
bytes per block to use. This should be an estimate of the average,
since it may vary. For example, the allocator used by
glibc on Linux requires somewhere between 4 to
- 15 bytes per block, depending on various factors. It also requires
- admin space for freed blocks, although Massif does not account
- for this.</para>
+ 15 bytes per block, depending on various factors. That allocator also
+ requires admin space for freed blocks, but Massif cannot
+ account for this.</para>
</listitem>
</varlistentry>
<para>Specifies whether stack profiling should be done. This option
slows Massif down greatly, and so is off by default. Note that Massif
assumes that the main stack has size zero at start-up. This is not
- true, but measuring the actual stack size is not easy, and it reflects
- the size of the part of the main stack that a user program actually
- has control over.</para>
+ true, but doing otherwise accurately is difficult. Furthermore,
+ starting at zero better indicates the size of the part of the main
+ stack that a user program actually has control over.</para>
</listitem>
</varlistentry>
This option can be specified multiple times on the command line, to
name multiple functions.</para>
- <para>Note that overloaded C++ names must be written in full. Single
- quotes may be necessary to prevent the shell from breaking them up.
- For example:
+ <para>Note that C++ names are demangled. Note also that overloaded
+ C++ names must be written in full. Single quotes may be necessary to
+ prevent the shell from breaking them up. For example:
<screen><![CDATA[
---alloc-fn='operator new(unsigned, std::nothrow_t const&)'
+--alloc-fn='operator new(unsigned, std::nothrow_t const&)'
]]></screen>
</para>
</listitem>
<listitem>
<para>Any direct heap allocation (i.e. a call to
<function>malloc</function>, <function>new</function>, etc, or a call
- to a function name in a <option>--alloc-fn</option>
+ to a function named by an <option>--alloc-fn</option>
option) that occurs in a function specified by this option will be
ignored. This is mostly useful for testing purposes. This option can
be specified multiple times on the command line, to name multiple
<function>realloc</function>.
</para>
- <para>Note that overloaded C++ names must be written in full, as for
- <option>--alloc-fn</option> above.
+ <para>The rules for writing C++ function names are the same as
+ for <option>--alloc-fn</option> above.
</para>
</listitem>
</varlistentry>
</term>
<listitem>
<para>The significance threshold for heap allocations, as a
- percentage. Allocation tree entries that account for less than this
- will be aggregated. Note that this should be specified in tandem with
- ms_print's option of the same name.</para>
+ percentage of total memory size. Allocation tree entries that account
+ for less than this will be aggregated. Note that this should be
+ specified in tandem with ms_print's option of the same name.</para>
</listitem>
</varlistentry>
<varlistentry id="opt.time-unit" xreflabel="--time-unit">
<term>
- <option><![CDATA[--time-unit=i|ms|B [default: i] ]]></option>
+ <option><![CDATA[--time-unit=<i|ms|B> [default: i] ]]></option>
</term>
<listitem>
<para>The time unit used for the profiling. There are three
<option>%p</option> and <option>%q</option> format specifiers can be
used to embed the process ID and/or the contents of an environment
variable in the name, as is the case for the core option
- <option>--log-file</option>. See <xref
- linkend="manual-core.basicopts"/> for details.
+ <option><xref linkend="opt.log-file"/></option>.
</para>
</listitem>
</varlistentry>
- <varlistentry id="opt.alignment" xreflabel="--alignment">
- <term>
- <option><![CDATA[--alignment=<n> [default: 1.0] ]]></option>
- </term>
- <listitem>
- <para>The minimum alignment (and thus size) of heap blocks.</para>
- </listitem>
- </varlistentry>
-
</variablelist>
<!-- end of xi:include in the manpage -->
<varlistentry>
<term>
- <option><![CDATA[-v --version ]]></option>
+ <option><![CDATA[--version ]]></option>
</term>
<listitem>
<para>Show the version number.</para>
<varlistentry>
<term>
- <option><![CDATA[--x=<n> [default: 72]]]></option>
+ <option><![CDATA[--x=<4..1000> [default: 72]]]></option>
</term>
<listitem>
<para>Width of the graph, in columns.</para>
<varlistentry>
<term>
- <option><![CDATA[--y=<n> [default: 20] ]]></option>
+ <option><![CDATA[--y=<4..1000> [default: 20] ]]></option>
</term>
<listitem>
<para>Height of the graph, in rows.</para>
<para>Massif's file format is plain text (i.e. not binary) and deliberately
easy to read for both humans and machines. Nonetheless, the exact format
is not described here. This is because the format is currently very
-Massif-specific. We plan to make the format more general, and thus suitable
-for possible use with other tools. Once this has been done, the format will
-be documented here.</para>
+Massif-specific. In the future we hope to make the format more general, and
+thus suitable for possible use with other tools. Once this has been done,
+the format will be documented here.</para>
</sect1>
projects / thirdparty / valgrind.git / commitdiff
