Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gprofng-archive.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-ARCHIVE 1"
61 .TH GPROFNG-ARCHIVE 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\-archive \- Archive gprofng experiment data
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBgprofng archive\fR [\fIoption(s)\fR] \fIexperiment\fR
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 Archive the associated application binaries and source files in a gprofng
74 experiment to make it self contained and portable.
75 .PP
76 By default, the binaries are archived as part of the data collection, but the
77 application source files are not archived. Use this tool to change this and
78 afterwards archive additional components.
79 .PP
80 This tool has to be executed on the same system where the profiling data was
81 recorded.
82 .SH OPTIONS
83 .IX Header "OPTIONS"
84 .IP \fB\-\-version\fR 4
85 .IX Item "--version"
86 Print the version number and exit.
87 .IP \fB\-\-help\fR 4
88 .IX Item "--help"
89 Print usage information and exit.
90 .IP "\fB\-a {off | on | ldobjects | src | usedldobjects | used[src]}\fR" 4
91 .IX Item "-a {off | on | ldobjects | src | usedldobjects | used[src]}"
92 Specify archiving of binaries and other files. In addition to disable this
93 feature (\fBoff\fR), or enable archiving of all loadobjects and sources
94 (\fBon\fR), the other choices support a more refined selection.
95 .Sp
96 All of these choices enable archiving, but the keyword controls what exactly
97 is selected: all load objects (\fBldobjects\fR), all source files
98 (\fBsrc\fR), the loadobjects associated with a program counter
99 (\fBusedldobjects\fR), or the source files associated with a program counter
100 (\fBused[src]\fR). The default is \fB\-a ldobjects\fR.
101 .IP "\fB\-d\fR \fIpath\fR" 4
102 .IX Item "-d path"
103 The \fIpath\fR is the absolute path to a common archive, which is a
104 directory that contains archived files. If the directory does not
105 exist, then it will be created. Files are saved in the common archive
106 directory, and a symbolic link is created in the experiment archive.
107 .IP \fB\-F\fR 4
108 .IX Item "-F"
109 Force writing, or rewriting of .archive files. All archived files will be
110 removed and recreated, except if the \fB\-n\fR or \fB\-m\fR option is used,
111 or if the experiment is a subexperiment.
112 .IP "\fB\-m\fR \fIregex\fR" 4
113 .IX Item "-m regex"
114 Archive only those source, object, and debug info files whose full path name
115 matches the given POSIX compliant \fIregex\fR regular expression.
116 .IP \fB\-n\fR 4
117 .IX Item "-n"
118 Archive the named experiment only, not any of its descendants.
119 .IP \fB\-q\fR 4
120 .IX Item "-q"
121 Do not write any warnings to \fIstderr\fR. Warnings are incorporated into
122 the .archive file in the experiment directory. They are shown in the output
123 of the \fBgprofng display text\fR command.
124 .IP "\fB\-r\fR \fIpath\fR" 4
125 .IX Item "-r path"
126 This option specifies the location of a common archive. The value is the
127 relative path to a common archive, which is a directory that contains
128 archived files.
129 If the directory does not exist, then it will be created. Files are saved
130 in the common archive directory, and a symbolic link is created in the
131 experiment archive.
132 .IP "\fB\-s\fR \fIselection\fR" 4
133 .IX Item "-s selection"
134 Specify archiving of source files. The allowed values for \fIselection\fR are:
135 .RS 4
136 .IP \fBno\fR 4
137 .IX Item "no"
138 Do not archive any source files.
139 .IP \fBall\fR 4
140 .IX Item "all"
141 Archive all source and object files that can be found.
142 .IP \fBused[src]\fR 4
143 .IX Item "used[src]"
144 Archive source and object files for functions against which data was
145 recorded in the experiment, and that can be found.
146 .RE
147 .RS 4
148 .Sp
149 By default, application source files are not archived into the experiment.
150 If the \fB\-s all\fR, or \fB\-s used\fR option is used, sources and object
151 files are archived.
152 These options also ensure that source files are available in the experiment,
153 even if the original source files have been modified, or are inaccessible
154 afterwards.
155 .Sp
156 In case archive files cannot be found, use the \fBaddpath\fR, or
157 \&\fBpathmap\fR command, or both, in an \fI.er.rc\fR file to specify the
158 location of the missing file(s).
159 .RE
160 .SH NOTES
161 .IX Header "NOTES"
162 .IP \- 4
163 Archiving of application binaries \-
164 By default, binaries are archived automatically when an experiment is
165 created. However, archiving does not occur in one or more of the
166 following circumstances:
167 .RS 4
168 .IP \(bu 4
169 If the profiled application is terminated before it exits normally.
170 .IP \(bu 4
171 If a running process is profiled.
172 .IP \(bu 4
173 If archiving is explicitly disabled when profiling. For example by using
174 the \fB\-a off\fR option on \fBgprofng collect app\fR.
175 .RE
176 .RS 4
177 .Sp
178 In these cases, \fBgprofng archive\fR must be run manually and on the same
179 machine where the profiling data was recorded.
180 .Sp
181 Archiving of experiment data during the data collection process can be quite
182 expensive. Especially if the experiment has many descendant processes.
183 In such cases, a more efficient strategy is to use the \fB\-a off\fR option
184 when collecting the data. Once the collection has completed, the data can be
185 archived using the \fB\-s all\fR option. This saves all executables and
186 source files in the experiment.
187 .Sp
188 If during the archiving there is an error message that an executable, or
189 source file cannot be found, the \fBaddpath\fR command to add the path
190 to the missing file(s) can be included in the \fI.er.rc\fR file.
191 After this command has been added, archive the experiment again. The
192 archiving archiving can be repeated as many times as necessary to archive all
193 files.
194 .Sp
195 Archiving should be done on the same system as was used to collect the
196 experiment. If some files cannot be accessed from this system (e.g. sources
197 or object files), then additional archiving can be done using another system
198 that can access them. For example, the system where the application was built.
199 .Sp
200 Some Java applications store shared objects in jar files. By default, such
201 shared objects are not automatically archived. To archive shared objects
202 contained in jar files, make sure to include the \fBaddpath\fR command in
203 an \fI.er.rc\fR file.
204 The \fBaddpath\fR command should give the path to the jar file, including
205 the jar file itself. The \fI.er.rc\fR file should be saved in the user home
206 directory, or experiment parent directory.
207 .RE
208 .IP \- 4
209 Archiving of application sources \-
210 By default, application source files are not archived in the experiment.
211 Execute the \fBgprofng archive\fR command with the \fB\-s all\fR, or
212 \&\fB\-s used\fR option on each experiment to store source files in the
213 experiment.
214 .IP \- 4
215 Automatic archiving of application sources \-
216 Environment variable \fBGPROFNG_ARCHIVE\fR may be set to automatically
217 archive sources when the experiment has completed. This environment
218 variable can contain \fB\-s\fR and \fB\-m\fR arguments, as pairs of
219 argument and options, separated by one or more blanks.
220 .Sp
221 If more than one \fB\-s\fR argument appears on the command line, the
222 last one prevails. If \fB\-s\fR is both passed on the command line, and
223 set by the environment variable, the option from the environment variable
224 prevails.
225 .Sp
226 Note that in case automatic source archiving during data collection has
227 been enabled using either the \fBGPROFNG_ARCHIVE\fR variable, or the
228 \&\fB\-a src\fR, or \fB\-a usedsrc\fR option, it is recommended to confirm that
229 source files have been correctly resolved by executing the
230 \&\fBgprofng archive \-s all\fR, or \fBgprofng archive \-s used\fR
231 command.
232 .IP \- 4
233 The \fB\-d\fR and \fB\-r\fR options are mutually exclusive.
234 .IP \- 4
235 When using the \fB\-d\fR or \fB\-r\fR option, environment variable
236 \&\fBGPROFNG_ARCHIVE_COMMON_DIR\fR can be used to specify the location of
237 the common archive. This can be very convenient when using a script to
238 profile applications.
239 .IP \- 4
240 If more than one \fB\-s\fR option is given on the command line, or
241 specified in the environment variable, the specified option for all must
242 be the same. If not, \fBgprofng archive\fR exits with an error.
243 .IP \- 4
244 This tool does not work on experiments recorded with earlier versions of
245 the tools. If invoked on such experiments, a warning is printed. Use the
246 version of \fBgprofng archive\fR from the same release with which the
247 experiment was recorded.
248 .SH "SEE ALSO"
249 .IX Header "SEE ALSO"
250 \&\fBgprofng\fR\|(1),
251 \&\fBgprofng\-collect\-app\fR\|(1),
252 \&\fBgprofng\-display\-html\fR\|(1),
253 \&\fBgprofng\-display\-src\fR\|(1),
254 \&\fBgprofng\-display\-text\fR\|(1)
255 .PP
256 The user guide for gprofng is maintained as a Texinfo manual. If the
257 \&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the
258 command \fBinfo gprofng\fR should give access to this document.
259 .SH COPYRIGHT
260 .IX Header "COPYRIGHT"
261 Copyright (c) 2022\-2025 Free Software Foundation, Inc.
262 .PP
263 Permission is granted to copy, distribute and/or modify this document
264 under the terms of the GNU Free Documentation License, Version 1.3
265 or any later version published by the Free Software Foundation;
266 with no Invariant Sections, with no Front\-Cover Texts, and with no
267 Back\-Cover Texts. A copy of the license is included in the
268 section entitled "GNU Free Documentation License".