.\" 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 "GPROFNG.1 1"
.TH GPROFNG.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 \- The next generation GNU application profiling tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBgprofng\fR [\fIoption(s)\fR] \fIaction\fR [\fIqualifier\fR] [\fIoption(s)\fR] \fItarget\fR [\fIoptions\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the driver for the gprofng tools suite to gather and analyze performance
data.
.PP
The driver executes the \fIaction\fR specified. An example of an action is
\&\fBcollect\fR to collect performance data. Depending on the action, a
\&\fIqualifier\fR may be needed to further define the command.
The last item is the \fItarget\fR that the command applies to.
.PP
There are three places where options are supported.  The driver supports
options.  These can be found below.  The \fIaction\fR, possibly in combination
with the \fIqualifier\fR also supports options. A description of these can be
found in the man page for the command.  Any options needed to execute the
target command should follow the target name.
.PP
For example, to collect performance data for an application called
\&\fBa.out\fR and store the results in experiment directory \fBmydata.er\fR,
the following command may be used:
.PP
.Vb 1
\&        $ gprofng collect app \-o mydata.er a.out \-t 2
.Ve
.PP
In this example, the action is \fBcollect\fR, the qualifier is \fBapp\fR, the single
argument to the command is \f(CW\*(C`\-o mydata.er\*(C'\fR and the target is \fBa.out\fR.
The target command is invoked with the \fB\-t 2\fR option.
.PP
If gprofng is executed without any additional option, action, or target, a usage
overview is printed.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fI\-\-version\fR" 4
.IX Item "--version"
Print the version number and exit.
.IP "\fI\-\-help\fR" 4
.IX Item "--help"
Print usage information and exit.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
The following environment variables are supported:
.IP "\fB\s-1GPROFNG_MAX_CALL_STACK_DEPTH\s0\fR" 4
.IX Item "GPROFNG_MAX_CALL_STACK_DEPTH"
Set the depth of the call stack (default is 256).
.IP "\fB\s-1GPROFNG_USE_JAVA_OPTIONS\s0\fR" 4
.IX Item "GPROFNG_USE_JAVA_OPTIONS"
May be set when profiling a C/\*(C+ application that uses \fBdlopen()\fR to execute
Java code.
.IP "\fB\s-1GPROFNG_ALLOW_CORE_DUMP\s0\fR" 4
.IX Item "GPROFNG_ALLOW_CORE_DUMP"
Set this variable to allow a core file to be generated; otherwise an error
report is created on /tmp.
.IP "\fB\s-1GPROFNG_ARCHIVE\s0\fR" 4
.IX Item "GPROFNG_ARCHIVE"
Use this variable to define the settings for automatic archiving upon experiment
recording completion.
.IP "\fB\s-1GPROFNG_ARCHIVE_COMMON_DIR\s0\fR" 4
.IX Item "GPROFNG_ARCHIVE_COMMON_DIR"
Set this variable to the location of the common archive.
.IP "\fB\s-1GPROFNG_JAVA_MAX_CALL_STACK_DEPTH\s0\fR" 4
.IX Item "GPROFNG_JAVA_MAX_CALL_STACK_DEPTH"
Set the depth of the Java call stack; the default is 256; set to 0 to disable
capturing of call stacks.
.IP "\fB\s-1GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH\s0\fR" 4
.IX Item "GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH"
Set the depth of the Java native call stack; the default is 256; set to 0 to
disable capturing of call stacks (\s-1JNI\s0 and assembly call stacks are not
captured).
.SH "NOTES"
.IX Header "NOTES"
The gprofng driver supports the following commands.
\&\f(CW@vspace\fR{1}
.PP
\&\fICollect performance data:\fR
.ie n .IP """gprofng collect app""" 4
.el .IP "\f(CWgprofng collect app\fR" 4
.IX Item "gprofng collect app"
Collect application performance data.
.PP
\&\fIDisplay the performance results:\fR
.ie n .IP """gprofng display text""" 4
.el .IP "\f(CWgprofng display text\fR" 4
.IX Item "gprofng display text"
Display the performance data in \s-1ASCII\s0 format.
.ie n .IP """gprofng display html""" 4
.el .IP "\f(CWgprofng display html\fR" 4
.IX Item "gprofng display html"
Generate an \s-1HTML\s0 file from one or more experiments.
.PP
\&\fIMiscellaneous commands:\fR
.ie n .IP """gprofng display src""" 4
.el .IP "\f(CWgprofng display src\fR" 4
.IX Item "gprofng display src"
Display source or disassembly with compiler annotations.
.ie n .IP """gprofng archive""" 4
.el .IP "\f(CWgprofng archive\fR" 4
.IX Item "gprofng archive"
Include binaries and source code in an experiment directory.
.PP
It is also possible to invoke the lower level commands directly, but since
these are subject to change, in particular the options, we recommend to
use the driver.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgp\-archive\fR\|(1), \fBgp\-collect\-app\fR\|(1), \fBgp\-display\-html\fR\|(1), \fBgp\-display\-src\fR\|(1),
\&\fBgp\-display\-text\fR\|(1)
.PP
Each gprofng command also supports the \fB\-\-help\fR option. This lists the
options and a short description for each option.
.PP
For example this displays the options supported on the
\&\fBgprofng collect app\fR command:
.PP
.Vb 1
\&        $ gprofng collect app \-\-help
.Ve
.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\-2023 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R".