Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gprofng.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "GPROFNG 1"
61 .TH GPROFNG 1 2025-07-27 binutils-2.45 "User Commands"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 gprofng \- The next generation GNU application profiling tool
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBgprofng\fR [\fIoption(s)\fR] \fIaction\fR [\fIqualifier\fR]
71 [\fIoption(s)\fR] \fItarget\fR [\fIoptions\fR]
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 This is the driver for the gprofng tools suite to gather and analyze
75 performance data.
76 .PP
77 The driver executes the \fIaction\fR specified. An example of an action is
78 \&\fBcollect\fR to collect performance data. Depending on the action, a
79 \&\fIqualifier\fR may be needed to further define the command.
80 The last item is the \fItarget\fR that the command applies to.
81 .PP
82 There are three places where options are supported. The driver supports
83 options. These can be found below. The \fIaction\fR, possibly in combination
84 with the \fIqualifier\fR also supports options. A description of these can be
85 found in the man page for the command. Any options needed to execute the
86 target command should follow the target name.
87 .PP
88 For example, to collect performance data for an application called
89 \&\fBa.out\fR and store the results in experiment directory \fBmydata.er\fR,
90 the following command may be used:
91 .PP
92 .Vb 1
93 \& $ gprofng collect app \-o mydata.er a.out \-t 2
94 .Ve
95 .PP
96 In this example, the action is \fBcollect\fR, the qualifier is \fBapp\fR,
97 the single argument to the command is \f(CW\*(C`\-o mydata.er\*(C'\fR and the target is
98 \&\fBa.out\fR. The target command is invoked with the \fB\-t 2\fR option.
99 .PP
100 If gprofng is executed without any additional option, action, or target, a
101 usage overview is printed.
102 .SH OPTIONS
103 .IX Header "OPTIONS"
104 .IP \fI\-\-version\fR 4
105 .IX Item "--version"
106 Print the version number and exit.
107 .IP \fI\-\-help\fR 4
108 .IX Item "--help"
109 Print usage information and exit.
110 .SH ENVIRONMENT
111 .IX Header "ENVIRONMENT"
112 The following environment variables are supported:
113 .IP \fBGPROFNG_MAX_CALL_STACK_DEPTH\fR 4
114 .IX Item "GPROFNG_MAX_CALL_STACK_DEPTH"
115 Set the depth of the call stack (default is 256).
116 .IP \fBGPROFNG_USE_JAVA_OPTIONS\fR 4
117 .IX Item "GPROFNG_USE_JAVA_OPTIONS"
118 May be set when profiling a C/C++ application that uses \fBdlopen()\fR to execute
119 Java code.
120 .IP \fBGPROFNG_ALLOW_CORE_DUMP\fR 4
121 .IX Item "GPROFNG_ALLOW_CORE_DUMP"
122 Set this variable to allow a core file to be generated; otherwise an error
123 report is created on \fB/tmp\fR.
124 .IP \fBGPROFNG_ARCHIVE\fR 4
125 .IX Item "GPROFNG_ARCHIVE"
126 Use this variable to define the settings for automatic archiving upon
127 experiment recording completion.
128 .IP \fBGPROFNG_ARCHIVE_COMMON_DIR\fR 4
129 .IX Item "GPROFNG_ARCHIVE_COMMON_DIR"
130 Set this variable to the location of the common archive.
131 .IP \fBGPROFNG_JAVA_MAX_CALL_STACK_DEPTH\fR 4
132 .IX Item "GPROFNG_JAVA_MAX_CALL_STACK_DEPTH"
133 Set the depth of the Java call stack; the default is 256; set to 0 to disable
134 capturing of call stacks.
135 .IP \fBGPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH\fR 4
136 .IX Item "GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH"
137 Set the depth of the Java native call stack; the default is 256; set to 0 to
138 disable capturing of call stacks (JNI and assembly call stacks are not
139 captured).
140 .IP \fBGPROFNG_SYSCONFDIR\fR 4
141 .IX Item "GPROFNG_SYSCONFDIR"
142 Set the path to the \fIgprofng.rc\fR configuration file. By default, this
143 file is placed in the \fIetc\fR subdirectory of the binutils installation
144 directory. In case an RPM has been used for the installation, this file is
145 in directory \fI/etc\fR.
146 .Sp
147 When building and installing from the source, the user can set the path
148 to this configuration file to a non\-default location. If this is the case,
149 the user may set the \f(CW\*(C`GPROFNG_SYSCONFDIR\*(C'\fR environment variable to point
150 to this location.
151 .Sp
152 Otherwise, the \fBgprofng display text\fR, \fBgprofng display src\fR,
153 and \fBgprofng archive\fR tools cannot find this file.
154 .SH NOTES
155 .IX Header "NOTES"
156 The gprofng driver supports the following commands.
157 .PP
158 \&\fICollect performance data:\fR
159 .ie n .IP """gprofng collect app""" 4
160 .el .IP "\f(CWgprofng collect app\fR" 4
161 .IX Item "gprofng collect app"
162 Collect application performance data.
163 .PP
164 \&\fIDisplay the performance results:\fR
165 .ie n .IP """gprofng display text""" 4
166 .el .IP "\f(CWgprofng display text\fR" 4
167 .IX Item "gprofng display text"
168 Display the performance data in ASCII format.
169 .ie n .IP """gprofng display html""" 4
170 .el .IP "\f(CWgprofng display html\fR" 4
171 .IX Item "gprofng display html"
172 Generate an HTML file from one or more experiments.
173 .ie n .IP """gprofng display gui""" 4
174 .el .IP "\f(CWgprofng display gui\fR" 4
175 .IX Item "gprofng display gui"
176 Start the GUI. Note that this tool is not available by default and needs to
177 be installed seperately.
178 .PP
179 \&\fIMiscellaneous commands:\fR
180 .ie n .IP """gprofng display src""" 4
181 .el .IP "\f(CWgprofng display src\fR" 4
182 .IX Item "gprofng display src"
183 Display source or disassembly with compiler annotations.
184 .ie n .IP """gprofng archive""" 4
185 .el .IP "\f(CWgprofng archive\fR" 4
186 .IX Item "gprofng archive"
187 Include binaries and source code in an experiment directory.
188 .PP
189 It is also possible to invoke the lower level commands directly, but since
190 these are subject to change, in particular the options, we recommend to
191 use the driver.
192 .PP
193 The \fIgprofng GUI\fR is an optional tool that provides a graphical interface
194 for \f(CW\*(C`gprofng\*(C'\fR. It is easy to use and supports many views into the
195 performance data. For those interested in this GUI, we
196 recommend to search for \f(CW\*(C`gprofng\-gui\*(C'\fR how to obtain, install and use it.
197 .SH "SEE ALSO"
198 .IX Header "SEE ALSO"
199 \&\fBgprofng\-archive\fR\|(1),
200 \&\fBgprofng\-collect\-app\fR\|(1),
201 \&\fBgprofng\-display\-html\fR\|(1),
202 \&\fBgprofng\-display\-src\fR\|(1),
203 \&\fBgprofng\-display\-text\fR\|(1)
204 .PP
205 Each gprofng command also supports the \fB\-\-help\fR option. This lists the
206 options and a short description for each option.
207 .PP
208 For example this displays the options supported on the
209 \&\fBgprofng collect app\fR command:
210 .PP
211 .Vb 1
212 \& $ gprofng collect app \-\-help
213 .Ve
214 .PP
215 The user guide for gprofng is maintained as a Texinfo manual. If the
216 \&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the
217 command \fBinfo gprofng\fR should give access to this document.
218 .SH COPYRIGHT
219 .IX Header "COPYRIGHT"
220 Copyright (c) 2022\-2025 Free Software Foundation, Inc.
221 .PP
222 Permission is granted to copy, distribute and/or modify this document
223 under the terms of the GNU Free Documentation License, Version 1.3
224 or any later version published by the Free Software Foundation;
225 with no Invariant Sections, with no Front\-Cover Texts, and with no
226 Back\-Cover Texts. A copy of the license is included in the
227 section entitled "GNU Free Documentation License".