gprofng/doc/gprofng.1

 -*- mode: troff; coding: utf-8 -*-
 Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.47)

 Standard preamble:
 ========================================================================
..
..

..
 \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` ""
. ds C' ""
'br\}
. ds C`
. ds C'
'br\}

 Escape single quotes in literal strings from groff's Unicode transform.

 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'.
..
.nr rF 0
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF

 Required to disable full justification in groff 1.23.0.
 ========================================================================

 Title "GPROFNG 1"  GPROFNG 1 2026-02-10 binutils-2.46.0 "User Commands"
 For nroff, turn off justification. Always turn off hyphenation; it makes
 way too many mistakes in technical documents.
.nh
 NAME
gprofng - The next generation GNU application profiling tool
 SYNOPSIS
 Header "SYNOPSIS" \fBgprofng [option(s)] action [qualifier]
[option(s)] target [options]
 DESCRIPTION
 Header "DESCRIPTION" This is the driver for the gprofng tools suite to gather and analyze
performance data.

The driver executes the action specified. An example of an action is
\fBcollect to collect performance data. Depending on the action, a
\fIqualifier may be needed to further define the command.
The last item is the target that the command applies to.

There are three places where options are supported. The driver supports
options. These can be found below. The action, possibly in combination
with the qualifier 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.

For example, to collect performance data for an application called
\fBa.out and store the results in experiment directory mydata.er,
the following command may be used:

.Vb 1
  $ gprofng collect app -o mydata.er a.out -t 2
.Ve

In this example, the action is collect, the qualifier is app,
the single argument to the command is \*(C`-o mydata.er\*(C' and the target is
\fBa.out. The target command is invoked with the -t 2 option.

If gprofng is executed without any additional option, action, or target, a
usage overview is printed.
 OPTIONS
 Header "OPTIONS"  --version 4
 Item "--version" Print the version number and exit.
 --help 4
 Item "--help" Print usage information and exit.
 ENVIRONMENT
 Header "ENVIRONMENT" The following environment variables are supported:
 GPROFNG_MAX_CALL_STACK_DEPTH 4
 Item "GPROFNG_MAX_CALL_STACK_DEPTH" Set the depth of the call stack (default is 256).
 GPROFNG_USE_JAVA_OPTIONS 4
 Item "GPROFNG_USE_JAVA_OPTIONS" May be set when profiling a C/C++ application that uses dlopen() to execute
Java code.
 GPROFNG_ALLOW_CORE_DUMP 4
 Item "GPROFNG_ALLOW_CORE_DUMP" Set this variable to allow a core file to be generated; otherwise an error
report is created on /tmp.
 GPROFNG_ARCHIVE 4
 Item "GPROFNG_ARCHIVE" Use this variable to define the settings for automatic archiving upon
experiment recording completion.
 GPROFNG_ARCHIVE_COMMON_DIR 4
 Item "GPROFNG_ARCHIVE_COMMON_DIR" Set this variable to the location of the common archive.
 GPROFNG_JAVA_MAX_CALL_STACK_DEPTH 4
 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.
 GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH 4
 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 (JNI and assembly call stacks are not
captured).
 GPROFNG_SYSCONFDIR 4
 Item "GPROFNG_SYSCONFDIR" Set the path to the gprofng.rc configuration file. By default, this
file is placed in the etc subdirectory of the binutils installation
directory. In case an RPM has been used for the installation, this file is
in directory /etc.
.Sp
When building and installing from the source, the user can set the path
to this configuration file to a non-default location. If this is the case,
the user may set the \*(C`GPROFNG_SYSCONFDIR\*(C' environment variable to point
to this location.
.Sp
Otherwise, the gprofng display text, gprofng display src,
and gprofng archive tools cannot find this file.
 NOTES
 Header "NOTES" The gprofng driver supports the following commands.

\fICollect performance data:
 Item "gprofng collect app" Collect application performance data.

\fIDisplay the performance results:
 Item "gprofng display text" Display the performance data in ASCII format.
 Item "gprofng display html" Generate an HTML file from one or more experiments.
 Item "gprofng display gui" Start the GUI. Note that this tool is not available by default and needs to
be installed seperately.

\fIMiscellaneous commands:
 Item "gprofng display src" Display source or disassembly with compiler annotations.
 Item "gprofng display gmon" Convert a given gmon.out file to gprofng experiments.
 Item "gprofng archive" Include binaries and source code in an experiment directory.

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.

The gprofng GUI is an optional tool that provides a graphical interface
for \*(C`gprofng\*(C'. It is easy to use and supports many views into the
performance data. For those interested in this GUI, we
recommend to search for \*(C`gprofng-gui\*(C' how to obtain, install and use it.
 "SEE ALSO"
 Header "SEE ALSO" \fBgprofng-archive\|(1),
\fBgprofng-collect-app\|(1),
\fBgprofng-display-html\|(1),
\fBgprofng-display-src\|(1),
\fBgprofng-display-text\|(1)
\fBgprofng-display-gmon\|(1)

Each gprofng command also supports the --help option. This lists the
options and a short description for each option.

For example this displays the options supported on the
\fBgprofng collect app command:

.Vb 1
  $ gprofng collect app --help
.Ve

The user guide for gprofng is maintained as a Texinfo manual. If the
\fBinfo and gprofng programs are correctly installed, the
command info gprofng should give access to this document.
 COPYRIGHT
 Header "COPYRIGHT" Copyright (c) 2022-2026 Free Software Foundation, Inc.

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".