docs/callgrind_control.1

'\" t
.\"     Title: Callgrind Control
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 06/15/2017
.\"    Manual: Release 3.13.0
.\"    Source: Release 3.13.0
.\"  Language: English
.\"
.TH "CALLGRIND CONTROL" "1" "06/15/2017" "Release 3.13.0" "Release 3.13.0"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
callgrind_control \- observe and control programs being run by Callgrind
.SH "SYNOPSIS"
.HP \w'\fBcallgrind_control\fR\ 'u
\fBcallgrind_control\fR [\fIoptions\fR] [\fIpid|program\-name\fR...]
.SH "DESCRIPTION"
.PP
\fBcallgrind_control\fR
controls programs being run by the Valgrind tool Callgrind\&. When a
\fBpid/program name\fR
argument is not specified, all applications currently being run by Callgrind on this system will be used for actions given by the specified option(s)\&. The default action is to give some brief information about the applications being run by Callgrind\&.
.SH "OPTIONS"
.PP
\fB\-h \-\-help\fR
.RS 4
Show a short description, usage, and summary of options\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Show version of callgrind_control\&.
.RE
.PP
\fB\-l \-\-long\fR
.RS 4
Show also the working directory, in addition to the brief information given by default\&.
.RE
.PP
\fB\-s \-\-stat\fR
.RS 4
Show statistics information about active Callgrind runs\&.
.RE
.PP
\fB\-b \-\-back\fR
.RS 4
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\&.
.RE
.PP
\fB\-e [A,B,\&.\&.\&.] \fR (default: all)
.RS 4
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\&.
.RE
.PP
\fB\-\-dump[=<desc>] \fR (default: no description)
.RS 4
Request the dumping of profile information\&. Optionally, a 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\&.
.RE
.PP
\fB\-z \-\-zero\fR
.RS 4
Zero all event counters\&.
.RE
.PP
\fB\-k \-\-kill\fR
.RS 4
Force a Callgrind run to be terminated\&.
.RE
.PP
\fB\-\-instr=<on|off>\fR
.RS 4
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
\fB\-\-instr\-atstart\fR\&.
.RE
.PP
\fB\-\-vgdb\-prefix=<prefix>\fR
.RS 4
Specify the vgdb prefix to use by callgrind_control\&. callgrind_control internally uses vgdb to find and control the active Callgrind runs\&. If the
\fB\-\-vgdb\-prefix\fR
option was used for launching valgrind, then the same option must be given to callgrind_control\&.
.RE
.SH "SEE ALSO"
.PP
valgrind(1),
$INSTALL/share/doc/valgrind/html/index\&.html
or
http://www\&.valgrind\&.org/docs/manual/index\&.html\&.
.SH "AUTHOR"
.PP
Josef Weidendorfer <Josef\&.Weidendorfer@gmx\&.de>\&.