.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "GP-COLLECT-APP.1 1" .TH GP-COLLECT-APP.1 1 "2023-11-25" "binutils-2.41.50" "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" gprofng collect app \- Collect performance data for the target application .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBgprofng collect app\fR [\fIoption(s)\fR] \fItarget\fR [\fIoption(s)\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" Collect performance data on the target program. In addition to Program Counter (\s-1PC\s0) 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\-p {off|on|lo|hi|\fR\fI\fR\fB}\fR" 4 .IX Item "-p {off|on|lo|hi|}" Disable (off) or enable (on) clock-profiling using a default sampling granularity, or enable clock-profiling implicitly by setting the sampling granularity (lo, hi, or a specific value in ms). By default, clock profiling is enabled (\fB\-p on\fR). .IP "\fB\-h\fR \fI{...,}\fR" 4 .IX Item "-h {...,}" Enable hardware event counter profiling and select the counter(s). To see the supported counters on this system, use the \fB\-h\fR option without other arguments. .IP "\fB\-o\fR \fI\fR" 4 .IX Item "-o " 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). .IP "\fB\-O\fR \fI\fR" 4 .IX Item "-O " 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\fR" 4 .IX Item "-C " 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\fR\fB}\fR" 4 .IX Item "-j {on|off|}" Controls Java profiling when the target is a \s-1JVM\s0 machine. The allowed values of this option are: enable (on), disable (off) Java profiling when the target program is a \s-1JVM,\s0 or set \fB\fR to a non-default \s-1JVM.\s0 The default is \fB\-j on\fR .RS 4 .IP "\fBon\fR" 4 .IX Item "on" Record profiling data for the \s-1JVM\s0 machine, and recognize methods compiled by the Java HotSpot virtual machine. Also record Java call stacks. The default is \fB\-j on\fR. .IP "\fBoff\fR" 4 .IX Item "off" Does not record Java profiling data. Profiling data for native call stacks is still recorded. .IP "\fI\fR" 4 .IX Item "" Records profiling data for the \s-1JVM,\s0 and use the \s-1JVM\s0 as installed in \fI\fR. .RE .RS 4 .RE .IP "\fB\-J\fR \fI\fR" 4 .IX Item "-J " Specifies additional options to be passed to the \s-1JVM\s0 used. The \&\fIjvm-options\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 tab. Each item is passed as a separate option to the \s-1JVM.\s0 Note that this option implies \fB\-j on\fR. .IP "\fB\-t\fR \fI\fR\fB[m|s]\fR" 4 .IX Item "-t [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 two numbers separated by 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. If 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 (off), or enable archiving off all loadobjects and sources (on), the other op tions 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\fR\fB}\fR" 4 .IX Item "-S {off|on|}" Disable (off), or enable (on) periodic sampling of process-wide resource utilization. By default, sampling occurs every second. Use the \fI\fR option to change this. The default is \fB\-S on\fR. .IP "\fB\-y\fR \fI\fR\fB[,r]\fR" 4 .IX Item "-y [,r]" Controls recording of data with the signal named \fI\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 \&\s-1SIGUSR1\s0 or \s-1SIGUSR2\s0 are recommended for this use, but any signal that is not used by the target can be used. .IP "\fB\-l\fR \fI\fR" 4 .IX Item "-l " Specify a signal that will trigger a sample of process-wide resource utilization. When the named \fI\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