vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
253 lines
9.9 KiB
Groff
253 lines
9.9 KiB
Groff
.\" -*- mode: troff; coding: utf-8 -*-
|
|
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.45)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
|
|
.ie n \{\
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds C`
|
|
. ds C'
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.\"
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
|
. if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{\
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "GP-COLLECT-APP.1 1"
|
|
.TH GP-COLLECT-APP.1 1 2024-08-17 binutils-2.43.0 "User Commands"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH NAME
|
|
gp\-collect\-app \- Collect performance data for the target application
|
|
.SH SYNOPSIS
|
|
.IX Header "SYNOPSIS"
|
|
\&\fBgprofng collect app\fR [\fIoption(s)\fR] \fItarget\fR
|
|
[\fItarget\-option(s)\fR]
|
|
.SH DESCRIPTION
|
|
.IX Header "DESCRIPTION"
|
|
Collect performance data on the target program. In addition to Program Counter
|
|
(PC) sampling, hardware event counters and various tracing options are
|
|
supported.
|
|
.PP
|
|
For example, this command collects performance data for an executable called
|
|
\&\fBa.out\fR and stores the data collected in an experiment directory with
|
|
the name \fBexample.er\fR.
|
|
.PP
|
|
.Vb 1
|
|
\& $ gprofng collect app \-o example.er ./a.out
|
|
.Ve
|
|
.SH OPTIONS
|
|
.IX Header "OPTIONS"
|
|
.IP \fB\-\-version\fR 4
|
|
.IX Item "--version"
|
|
Print the version number and exit.
|
|
.IP \fB\-\-help\fR 4
|
|
.IX Item "--help"
|
|
Print usage information and exit.
|
|
.IP "\fB\-v, \-\-verbose\fR" 4
|
|
.IX Item "-v, --verbose"
|
|
By default, verbose mode is disabled. This option enables it.
|
|
.IP "\fB\-p {off | on | lo[w] | hi[gh] |\fR \fI<value>\fR\fB}\fR" 4
|
|
.IX Item "-p {off | on | lo[w] | hi[gh] | <value>}"
|
|
Disable (\fBoff\fR) or enable (\fBon\fR) clock profiling using a default
|
|
sampling granularity, or enable clock profiling implicitly by setting the
|
|
sampling granularity (\fBlo[w]\fR, \fBhi[gh]\fR, or a specific value in
|
|
ms). By default, clock profiling is enabled (\fB\-p on\fR).
|
|
.IP "\fB\-h\fR \fI<ctr_def>[,<ctr_def>]\fR" 4
|
|
.IX Item "-h <ctr_def>[,<ctr_def>]"
|
|
Enable hardware event counter profiling and select one or more counter(s).
|
|
To see the supported counters on this system, use the \fB\-h\fR option
|
|
without other arguments.
|
|
.IP "\fB\-o\fR \fI<exp_name>\fR" 4
|
|
.IX Item "-o <exp_name>"
|
|
Specify the name for the experiment directory. The name has to end with
|
|
\&\fB.er\fR and may contain an absolute path (e.g. \fI/tmp/experiment.er\fR).
|
|
An existing experiment with the same name will not be overwritten.
|
|
.IP "\fB\-O\fR \fI<exp_name>\fR" 4
|
|
.IX Item "-O <exp_name>"
|
|
This is the same as the \fB\-o\fR option, but unlike this option, silently
|
|
overwrites an existing experiment directory with the same name.
|
|
.IP "\fB\-C\fR \fI<comment_string>\fR" 4
|
|
.IX Item "-C <comment_string>"
|
|
Add up to 10 comment strings to the experiment. These comments appear in the
|
|
notes section of the header and can be retrieved with the
|
|
\&\fBgprofng display text\fR command using the \fB\-header\fR option.
|
|
.IP "\fB\-j {on | off |\fR \fI<path>\fR\fB}\fR" 4
|
|
.IX Item "-j {on | off | <path>}"
|
|
Controls Java profiling when the target is a JVM machine. The allowed values
|
|
for this option are:
|
|
.RS 4
|
|
.IP \fBon\fR 4
|
|
.IX Item "on"
|
|
Record profiling data for the JVM machine, and recognize methods compiled by
|
|
the Java HotSpot virtual machine. Also record Java call stacks.
|
|
.IP \fBoff\fR 4
|
|
.IX Item "off"
|
|
Do not record Java profiling data. Profiling data for native call stacks is
|
|
still recorded.
|
|
.IP \fI<path>\fR 4
|
|
.IX Item "<path>"
|
|
Records profiling data for the JVM, and use the JVM as installed in
|
|
\&\fI<path>\fR.
|
|
.RE
|
|
.RS 4
|
|
.Sp
|
|
The default is \fB\-j on\fR.
|
|
.RE
|
|
.IP "\fB\-J\fR \fI<jvm\-option(s)>\fR" 4
|
|
.IX Item "-J <jvm-option(s)>"
|
|
Specifies one or more additional options to be passed to the JVM used. The
|
|
\&\fIjvm\-option(s)\fR list must be enclosed in quotation marks if it contains
|
|
more than one option. The items in the list need to be separated by spaces
|
|
or tabs.
|
|
Each item is passed as a separate option to the JVM. Note that this option
|
|
implies \fB\-j on\fR.
|
|
.IP "\fB\-t\fR \fI<duration>\fR\fB[m|s]\fR" 4
|
|
.IX Item "-t <duration>[m|s]"
|
|
Collects data for the specified duration. The duration can be a single number,
|
|
optionally followed by either \fBm\fR to specify minutes, or \fBs\fR to
|
|
specify seconds, which is the default.
|
|
.Sp
|
|
The duration can also consists of two numbers separated by a minus (\-)
|
|
sign. If a single number is given, data is collected from the start of the run
|
|
until the given time.
|
|
If two numbers are given, data is collected from the first time to the second.
|
|
In case the second time is zero, data is collected until the end of the run.
|
|
If two non-zero numbers are given, the first must be less than the second.
|
|
.IP \fB\-n\fR 4
|
|
.IX Item "-n"
|
|
This is used for a dry run. Several run-time settings are displayed, but the
|
|
target is not executed and no performance data is collected.
|
|
.IP "\fB\-F {off|on|=\fR\fIregex\fR\fB}\fR" 4
|
|
.IX Item "-F {off|on|=regex}"
|
|
Control whether descendant processes should have their data recorded.
|
|
To disable/enable this feature, use \fBoff\fR/\fBon\fR. Use
|
|
\&\fB=\fR\fIregex\fR to record data on those processes whose executable name
|
|
matches the regular expression. Only the basename of the executable is used,
|
|
not the full path. If spaces or characters interpreted by the shell are used,
|
|
enclose the \fIregex\fR in single quotes. The default is \fB\-F on\fR.
|
|
.IP "\fB\-a {off|on|ldobjects|src|usedldobjects|usedsrc}\fR" 4
|
|
.IX Item "-a {off|on|ldobjects|src|usedldobjects|usedsrc}"
|
|
Specify archiving of binaries and other files. In addition to disable this
|
|
feature (\fBoff\fR), or enable archiving off all loadobjects and sources
|
|
(\fBon\fR), the other options support a more refined selection.
|
|
.Sp
|
|
All of these options enable archiving, but the keyword controls what exactly
|
|
is selected: all load objects (ldobjects), all source files (src), the
|
|
loadobjects asscoiated with a program counter (usedldobjects), or the source
|
|
files associated with a program counter (usedsrc).
|
|
The default is \fB\-a ldobjects\fR.
|
|
.IP "\fB\-S {off|on|\fR\fI<seconds>\fR\fB}\fR" 4
|
|
.IX Item "-S {off|on|<seconds>}"
|
|
Disable (off), or enable (on) periodic sampling of process-wide
|
|
resource utilization. By default, sampling occurs every second. Use the
|
|
\&\fI<seconds>\fR option to change this. The default is \fB\-S on\fR.
|
|
.IP "\fB\-y\fR \fI<signal>\fR\fB[,r]\fR" 4
|
|
.IX Item "-y <signal>[,r]"
|
|
Controls recording of data with the signal named \fI<signal>\fR, referred to
|
|
as the pause-resume signal. Whenever the given signal is delivered to the
|
|
process, switch between paused (no data is recorded) and resumed (data is
|
|
recorded) states.
|
|
.Sp
|
|
By default, data collection begins in the paused state. If the optional
|
|
\&\fBr\fR is given, data collection begins in the resumed state and data
|
|
collection begins immediately.
|
|
.Sp
|
|
SIGUSR1 or SIGUSR2 are recommended for this use, but any signal that is
|
|
not used by the target can be used.
|
|
.IP "\fB\-l\fR \fI<signal>\fR" 4
|
|
.IX Item "-l <signal>"
|
|
Specify a signal that will trigger a sample of process-wide resource
|
|
utilization. When the named \fI<signal>\fR is delivered to the process,
|
|
a sample is recorded.
|
|
.Sp
|
|
The signal can be specified using the full name, without the initial
|
|
letters \f(CW\*(C`SIG\*(C'\fR, or the signal number. Note that the \fBkill\fR
|
|
command can be used to deliver a signal.
|
|
.Sp
|
|
If both the \fB\-l\fR and \fB\-y\fR options are used, the signal must be
|
|
different.
|
|
.IP "\fB\-s\fR \fI<option>\fR\fB[,\fR\fI<API>\fR\fB]\fR" 4
|
|
.IX Item "-s <option>[,<API>]"
|
|
Enable synchronization wait tracing, where \fI<option>\fR is used to define the
|
|
specifics of the tracing (on, off, \fI<threshold>\fR, or all). The API is
|
|
selected through the setting for \fI<API>\fR: \fBn\fR selects native/Pthreads,
|
|
\&\fBj\fR selects Java, and \fBnj\fR selects both. The default is
|
|
\&\fB\-s off\fR.
|
|
.IP "\fB\-H {off|on}\fR" 4
|
|
.IX Item "-H {off|on}"
|
|
Disable (off), or enable (on) heap tracing. The default is \fB\-H off\fR.
|
|
.IP "\fB\-i {off|on}\fR" 4
|
|
.IX Item "-i {off|on}"
|
|
Disable (off), or enable (on) I/O tracing. The default is \fB\-i off\fR.
|
|
.SH NOTES
|
|
.IX Header "NOTES"
|
|
Any executable in the ELF (Executable and Linkable Format) object format can
|
|
be used for profiling with gprofng. If debug information is available,
|
|
gprofng can provide more details, but this is not a requirement.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fBgprofng\fR\|(1),
|
|
\&\fBgp\-archive\fR\|(1),
|
|
\&\fBgp\-display\-gui\fR\|(1),
|
|
\&\fBgp\-display\-html\fR\|(1),
|
|
\&\fBgp\-display\-src\fR\|(1),
|
|
\&\fBgp\-display\-text\fR\|(1)
|
|
.PP
|
|
The user guide for gprofng is maintained as a Texinfo manual. If the
|
|
\&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the
|
|
command \fBinfo gprofng\fR should give access to this document.
|
|
.SH COPYRIGHT
|
|
.IX Header "COPYRIGHT"
|
|
Copyright (c) 2022\-2024 Free Software Foundation, Inc.
|
|
.PP
|
|
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 no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled "GNU Free Documentation License".
|