GPROFNG-ARCHIVE(1)

📦
version 2.47 · 15 versions
, in ubuntu stonking

✨ NAME ✨

okay so this is gprofng-archive — she archives your gprofng experiment data 💖 the manual page lives under User Commands, bestie, and this is her whole lore ↓

🌸 SYNOPSIS 🌸

gprofng archive [option(s)] experiment

💅 DESCRIPTION 💅

So here's the tea 🫖 — this tool takes the application binaries and source files that belong to a gprofng experiment and archives them right into it, so the experiment becomes self contained and portable. Like, it can just pack up and leave, no baggage, main character energy ✨

By default the binaries get archived as part of the data collection, but the application source files do not. That's the whole reason this tool exists — use her to flip that, and afterwards to archive additional components. 🌈

Real talk though: this tool has to be executed on the same system where the profiling data was recorded. No doing it from your laptop on the train, bestie 😭

👑 OPTIONS 👑

  • --version — prints the version number and dips out. ✌️
  • --help — prints usage info and dips out.
  • -a {off | on | ldobjects | src | usedldobjects | used[src]} — controls the archiving of binaries and other files. Besides turning the whole thing off (off) or archiving everything, loadobjects and sources included (on), the other choices let you be picky and refined about it 💅

All of these choices do enable archiving — the keyword is what says exactly what gets selected: all load objects (ldobjects), all source files (src), the loadobjects tied to a program counter (usedldobjects), or the source files tied to a program counter (used[src]). The default is -a ldobjects. no cap.

  • -d path — path is the absolute path to a common archive, which is a directory holding archived files. If that directory doesn't exist, it gets created (she's proactive like that 🎀). Files are saved in the common archive directory, and a symbolic link is created in the experiment archive.
  • -F — forces the writing, or rewriting, of .archive files. All archived files get removed and recreated — except if the -n or -m option is used, or if the experiment is a subexperiment. 🚨
  • -m regex — archives only those source, object, and debug info files whose full path name matches the given POSIX compliant regex regular expression. filtered queen 👑
  • -n — archives the named experiment only, not any of its descendants. just her, no entourage.
  • -q — write no warnings to stderr. Warnings get incorporated into the .archive file in the experiment directory instead, and they show up in the output of the gprofng display text command. (silent but not actually silent 💀)
  • -r path — specifies the location of a common archive. The value is the relative path to a common archive, which is a directory holding archived files. If the directory doesn't exist, it gets created. Files are saved in the common archive directory, and a symbolic link is created in the experiment archive.
  • -s selection — specifies archiving of source files. The allowed values for selection are:
    • no — do not archive any source files. 🙅
    • all — archive all source and object files that can be found.
    • used[src] — archive source and object files for functions against which data was recorded in the experiment, and that can be found.

By default, application source files are not archived into the experiment. If the -s all, or -s used option is used, sources and object files are archived. These options also make sure source files are available in the experiment, even if the original source files have been modified, or are inaccessible afterwards. iconic behavior honestly 💖

In case archive files cannot be found, use the addpath, or pathmap command, or both, in an .er.rc file to specify the location of the missing file(s).

📝 NOTES 📝

  • Archiving of application binaries — by default, binaries are archived automatically when an experiment is created. However, archiving does not occur in one or more of the following circumstances:
    • If the profiled application is terminated before it exits normally.
    • If a running process is profiled.
    • If archiving is explicitly disabled when profiling. For example by using the -a off option on gprofng collect app.

In these cases, gprofng archive must be run manually and on the same machine where the profiling data was recorded. no shortcuts bestie 😤

Archiving of experiment data during the data collection process can be quite expensive. Especially if the experiment has many descendant processes. In such cases, a more efficient strategy is to use the -a off option when collecting the data. Once the collection has completed, the data can be archived using the -s all option. This saves all executables and source files in the experiment. ✨

If during the archiving there is an error message that an executable, or source file cannot be found, the addpath command to add the path to the missing file(s) can be included in the .er.rc file. After this command has been added, archive the experiment again. The archiving can be repeated as many times as necessary to archive all files. 🔁

Archiving should be done on the same system as was used to collect the experiment. If some files cannot be accessed from this system (e.g. sources or object files), then additional archiving can be done using another system that can access them. For example, the system where the application was built.

Some Java applications store shared objects in jar files. By default, such shared objects are not automatically archived. To archive shared objects contained in jar files, make sure to include the addpath command in an .er.rc file. The addpath command should give the path to the jar file, including the jar file itself. The .er.rc file should be saved in the user home directory, or experiment parent directory. ☕

  • Archiving of application sources — by default, application source files are not archived in the experiment. Execute the gprofng archive command with the -s all, or -s used option on each experiment to store source files in the experiment.
  • Automatic archiving of application sources — environment variable GPROFNG_ARCHIVE may be set to automatically archive sources when the experiment has completed. This environment variable can contain -s and -m arguments, as pairs of argument and options, separated by one or more blanks.

If more than one -s argument appears on the command line, the last one prevails. If -s is both passed on the command line, and set by the environment variable, the option from the environment variable prevails.

Note that in case automatic source archiving during data collection has been enabled using either the GPROFNG_ARCHIVE variable, or the -a src, or -a usedsrc option, it is recommended to confirm that source files have been correctly resolved by executing the gprofng archive -s all, or gprofng archive -s used command. 👀

  • The -d and -r options are mutually exclusive. pick a lane bestie.
  • When using the -d or -r option, environment variable GPROFNG_ARCHIVE_COMMON_DIR can be used to specify the location of the common archive. This can be very convenient when using a script to profile applications. 🐚
  • If more than one -s option is given on the command line, or specified in the environment variable, the specified option for all must be the same. If not, gprofng archive exits with an error. 💀
  • This tool does not work on experiments recorded with earlier versions of the tools. If invoked on such experiments, a warning is printed. Use the version of gprofng archive from the same release with which the experiment was recorded. (matching versions only, it's giving ✨soulmates✨)

🔗 SEE ALSO 🔗

gprofng(1), gprofng-collect-app(1), gprofng-display-html(1), gprofng-display-src(1), gprofng-display-text(1)

The user guide for gprofng is maintained as a Texinfo manual. If the info and gprofng programs are correctly installed, the command info gprofng should give access to this document. 📖

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

and that's the whole page, bestie 🫶 she's from binutils-2.47, dated 2026-09-10, and yes you read all of it — we ate that 💅✨ periodt.

📦 where this page comes from