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