The syntax of the er_archive command is as follows.
er_archive [ -nqF ] [-s option [-m regexp ] ] experiment er_archive -V
er_archive runs automatically when an experiment completes normally (unless it was run with archiving turned off). It reads the list of shared objects referenced in the experiment, and copies all shared objects referenced in an experiment into the directory archives in the founder experiment. The copies are stored with mangled names so that the founder experiment and its sub-experiments may have different versions of objects with the same name. For Java experiments, all .jar files referenced are also copied into the experiment. (er_archive no longer generates .archive files.) If the target program terminates abnormally, er_archive might not run; In that case, it should be run manually.
If the user wishes to examine the experiment on a different machine from the one on which it was recorded, er_archive must either have been run when the experiment completed, or must be manually run on the experiment on the machine on which the data was recorded, in order to get the correct versions of all shared objects.
If the shared object cannot be found, or if it has a timestamp differing from that recorded in the experiment, or if er_archive is run on a different machine from that on which the experiment was recorded, the objects are not copied. If er_archive was run manually (without the -q flag), a warning is written to stderr. When an experiment referencing such a shared object is read by er_print or Analyzer a warning is also generated.
er_archive can also archive sources (including any necessary object files with symbol tables needed) by specifying an -s argument when run manually. Archiving of sources can specified to be done automatically when the experiment completes by setting the environment variable SP_ARCHIVE_ARGS. That environment variable may 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.
The following sections describe the options accepted by the er_archive utility.
Archive the named experiment only, not any of its descendants.
Do not write any warnings to stderr. Warnings are incorporated into the archive file, and shown in Performance Analyzer or output from the er_print utility.
Force writing or rewriting of archive files. This argument can be used to run er_archive by hand, to rewrite files that had warnings.
Specify archiving of source files. The allowed values of option are:
Do not archive any source files
Archive all source, object, and .anc files which can be found.
Archive source, object and .anc files for functions against which data was recorded in the experiment, and which can be found.
If more than one -s argument is given on the command line, or specified in the environment variable, the specified option for all must be the same. If not, er_archive will exit with an error.
Archive only those source, object, and .anc files as specified by the -s flag, and whose full pathname, as recorded in the executable or shared object, matches the given regex. For more information on regex, see the regex(5) man page.
Multiple -m arguments can be supplied on the command line or in the environment variable. A source file will be archived if it matches the expression from any of them.
Write version number information for the er_archive utility and exit.