sub printHeader {
if ($headerPrinted) { return; }
$headerPrinted = 1;
- if ($beQuiet) { return; }
print "Observe the status and control currently active callgrind runs.\n";
print "(C) 2003-2005, Josef Weidendorfer (Josef.Weidendorfer\@gmx.de)\n\n";
exit;
}
+sub shortHelp {
+ print "See '$0 -h' for help.\n";
+ exit;
+}
+
sub printHelp {
printHeader;
print "If no PIDs/Names are given, an action is applied to all currently\n";
print "active Callgrind runs. Default action is printing short information.\n\n";
print "Options:\n";
- print " -h Print this help text\n";
- print " -v Print version\n";
- print " -q Be quiet\n";
- print " -l Print more information\n";
- print " -s Print status information\n";
- print " -b Print backtrace information\n";
- print " -e [A,..] Print event counters for A,.. [default: all]\n";
- print " -d [str] Request a profile dump, include <str> as trigger hint\n";
- print " -z Zero all cost counters\n";
- print " -k Kill\n";
- print " -i on/off Switch instrumentation state on/off\n";
- print " -w <dir> Manually specify the working directory of a callgrind run\n";
+ print " -h --help Show this help text\n";
+ print " -v --version Show version\n";
+ print " -l --long Show more information\n";
+ print " -s --stat Show statistics\n";
+ print " -b --back Show stack/back trace\n";
+ print " -e [A, ...] Show event counters for A, ... (default: all)\n";
+ print " -d --dump [s] Request a profile dump using <s> as description\n";
+ print " -z --zero Zero all event counters\n";
+ print " -k --kill Kill\n";
+ print " -i [on|off] Switch instrumentation state on/off (default: on)\n";
+ print " -w <dir> Specify the startup directory of an active callgrind run\n";
print "\n";
exit;
}
$requestDump = 0;
$switchInstr = 0;
$headerPrinted = 0;
-$beQuiet = 0;
$dumpHint = "";
$gotW = 0;
$workingDir = "";
if ($arg =~ /^-?-h/) { printHelp; }
if ($arg =~ /^-?-v/) { printVersion; }
- if ($arg =~ /^-q/) { $beQuiet = 1; next; }
- if ($arg =~ /^-l/) { $printLong = 1; next; }
- if ($arg =~ /^-s/) { $printStatus = 1; next; }
- if ($arg =~ /^-b/) { $printBacktrace = 1; next; }
- if ($arg =~ /^-d/) { $requestDump = 1; next; }
- if ($arg =~ /^-z/) { $requestZero = 1; next; }
- if ($arg =~ /^-k/) { $requestKill = 1; next; }
+ if ($arg =~ /^-?-l/) { $printLong = 1; next; }
+ if ($arg =~ /^-?-s/) { $printStatus = 1; next; }
+ if ($arg =~ /^-?-b/) { $printBacktrace = 1; next; }
if ($arg =~ /^-e/) { $requestEvents = 1; next; }
- if ($arg =~ /^-i/) { $switchInstr = 1; next; }
+ if ($arg =~ /^-?-d/) { $requestDump = 1; next; }
+ if ($arg =~ /^-?-z/) { $requestZero = 1; next; }
+ if ($arg =~ /^-?-k/) { $requestKill = 1; next; }
+ if ($arg =~ /^-?-i/) { $switchInstr = 1; $switchInstrMode = "+"; next; }
if ($arg =~ /^-w/) { $gotW = 1; next; }
- printHeader;
- print "Unknown option '$arg'.\n\n";
- printHelp;
+ print "Error: unknown command line option '$arg'.\n";
+ shortHelp;
}
if ($arg =~ /^[A-Za-z_]/) {
if ($switchInstr == 1) {
$switchInstr = 2;
- $switchInstrMode = "+";
if (($arg eq "off") || ($arg eq "no")) {
$switchInstrMode = "-";
}
$workingDir = $arg;
if (!-d $workingDir) {
print "Error: directory '$workingDir' does not exist.\n";
- printHelp;
+ shortHelp;
}
next;
}
}
if ($nameFound) { next; }
- printHeader;
- print "Non-existent Callgrind task with PID/Name '$arg'.\n\n";
- printHelp;
+ print "Error: Callgrind task with PID/name '$arg' not detected.\n";
+ shortHelp;
+}
+
+if ($gotW == 1) {
+ print "Error: no directory specified after -w.\n";
+ shortHelp;
}
if ($workingDir ne "") {
<sect1 id="cl-manual.callgrind_control-options" xreflabel="callgrind_control Options">
-<title>callgrind_control Options</title>
+<title>Description and options of callgrind_control</title>
+
+<para>The command <command>callgrind_control</command> allows to control
+ programs being run by the Valgrind tool Callgrind. By default, it acts
+ on all programs detected to be run by the current user via Callgrind.
+ It is possible to limit the actions to specified Callgrind runs by
+ providing a list of pids or program names as argument.
+ The default action is to give some brief information about the applications
+ being run by Callgrind.</para>
<!-- start of xi:include in the manpage -->
<variablelist id="callgrind_control.opts.list">
<varlistentry>
- <term><option>-h --help</option></term>
+ <term><option>-h, --help</option></term>
<listitem>
- <para>Show summary of options.</para>
+ <para>Show a short description, usage, and summary of options.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--version</option></term>
+ <term><option>-v, --version</option></term>
<listitem>
<para>Show version of callgrind_control.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-s</option></term>
+ <term><option>-l, --long</option></term>
<listitem>
- <para>Show statistics.</para>
+ <para>Show also the working directory, in addition to the brief
+ information given by default.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-b</option></term>
+ <term><option>-s, --stat</option></term>
<listitem>
- <para>Show stack trace.</para>
+ <para>Show statistics information about active Callgrind runs.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-e [A,B,C] [default: all] </option></term>
+ <term><option>-b, --back</option></term>
<listitem>
- <para>Only show figures for events A,B,C.</para>
+ <para>Show stack/back traces of each thread in active Callgrind runs. For
+ each active function in the stack trace, also the number of invocations
+ since program start (or last dump) is shown. This option can be
+ combined with -e to show inclusive cost of active functions.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-z</option></term>
+ <term><option>-e [A, B, ...]</option> (default: all)</term>
<listitem>
- <para>Zero cost counters.</para>
+ <para>Show the current per-thread, exclusive cost values of event
+ counters. If no explicit event names are given, figures for all event
+ types which are collected in the given Callgrind run are
+ shown. Otherwise, only figures for event types A, B, ... are shown. If
+ this option is combined with -b, inclusive cost for the functions of
+ each active stack frame is provided, too.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-d, --dump [hint]</option></term>
+ <term><option>-d, --dump [desc]</option> (default: empty description)</term>
<listitem>
<para>Request the dumping of profile information. Optionally, a
- string can be specified which is written into the dump as part of
- the Trigger reason. This can be used to distinguish multiple dumps.</para>
+ description can be specified which is written into the dump as part of
+ the information giving the reason which triggered the dump action. This
+ can be used to distinguish multiple dumps.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-k</option></term>
+ <term><option>-z, --zero </option></term>
<listitem>
- <para>Kill.</para>
+ <para>Zero all event counters.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-k, --kill</option></term>
+ <listitem>
+ <para>Force a Callgrind run to be terminated.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-i, --instr [on|off]</option> (default: on)</term>
+ <listitem>
+ <para>Switch instrumentation mode on or off. If a Callgrind run has
+ instrumentation disabled, no simulation is done and no events are
+ counted. This is useful to skip uninteresting program parts, as there
+ is much less slowdown (same as with the Valgrind tool "none"). See also
+ the Callgrind option <option>--instr-atstart</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-w directory</option></term>
+ <listitem>
+ <para>Specify the startup directory of an active Callgrind run. On some
+ systems, active Callgrind runs can not be detected. To be able to
+ control these, the failed auto-detection can be worked around by
+ specifying the directory where a Callgrind run was started.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
<!-- end of xi:include in the manpage -->
projects / thirdparty / valgrind.git / commitdiff
