{
    "mode": "man",
    "parameter": "GP-ARCHIVE.1",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/GP-ARCHIVE.1/1/json",
    "generated": "2026-10-22T13:17:33Z",
    "synopsis": "gprofng archive [option(s)] experiment",
    "sections": {
        "NAME": {
            "content": "gp-archive - Archive gprofng experiment data\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "gprofng archive [option(s)] experiment\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Archive the associated application binaries and source files in a gprofng experiment to make\nit self contained and portable.\n\nBy default, the binaries are archived as part of the data collection, but the application\nsource files are not archived.  Use this tool to change this and afterwards archive\nadditional components.\n\nThis tool has to be executed on the same system where the profiling data was recorded.\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "",
            "subsections": [
                {
                    "name": "--version",
                    "content": "Print the version number and exit.\n",
                    "long": "--version"
                },
                {
                    "name": "--help",
                    "content": "Print usage information and exit.\n",
                    "long": "--help"
                },
                {
                    "name": "-a {off | on | ldobjects | src | usedldobjects | used[src]}",
                    "content": "Specify  archiving  of  binaries  and  other  files.  In addition to disable this feature\n(off), or enable archiving of all loadobjects and sources (on), the other choices support\na more refined selection.\n\nAll of these choices enable archiving, but the keyword controls what exactly is selected:\nall load objects (ldobjects), all source files (src), the loadobjects associated  with  a\nprogram  counter  (usedldobjects),  or the source files associated with a program counter\n(used[src]).  The default is -a ldobjects.\n",
                    "flag": "-a"
                },
                {
                    "name": "-d _",
                    "content": "The path is the absolute path to a common archive, which is  a  directory  that  contains\narchived  files.   If  the  directory does not exist, then it will be created.  Files are\nsaved in the common archive directory, and a symbolic link is created in  the  experiment\narchive.\n",
                    "flag": "-d"
                },
                {
                    "name": "-F",
                    "content": "recreated, except  if  the  -n  or  -m  option  is  used,  or  if  the  experiment  is  a\nsubexperiment.\n",
                    "flag": "-F"
                },
                {
                    "name": "-m _",
                    "content": "Archive  only those source, object, and debug info files whose full path name matches the\ngiven POSIX compliant regex regular expression.\n",
                    "flag": "-m"
                },
                {
                    "name": "-n",
                    "content": "",
                    "flag": "-n"
                },
                {
                    "name": "-q",
                    "content": "the experiment directory.  They are shown in the  output  of  the  gprofng  display  text\ncommand.\n",
                    "flag": "-q"
                },
                {
                    "name": "-r _",
                    "content": "This  option  specifies the location of a common archive.  The value is the relative path\nto a common archive, which is a directory that contains archived files.  If the directory\ndoes not exist, then it  will  be  created.   Files  are  saved  in  the  common  archive\ndirectory, and a symbolic link is created in the experiment archive.\n",
                    "flag": "-r"
                },
                {
                    "name": "-s _",
                    "content": "Specify archiving of source files.  The allowed values for selection are:\n\nno  Do not archive any source files.\n\nall Archive all source and object files that can be found.\n\nused[src]\nArchive  source and object files for functions against which data was recorded in the\nexperiment, and that can be found.\n\nBy default, application source files are not archived into the  experiment.   If  the  -s\nall,  or  -s  used  option is used, sources and object files are archived.  These options\nalso ensure that source files are available in  the  experiment,  even  if  the  original\nsource files have been modified, or are inaccessible afterwards.\n\nIn  case  archive files cannot be found, use the addpath, or pathmap command, or both, in\nan .er.rc file to specify the location of the missing file(s).\n",
                    "flag": "-s"
                }
            ]
        },
        "NOTES": {
            "content": "-   Archiving of application binaries - By default, binaries are archived automatically  when\nan  experiment  is  created.   However,  archiving  does  not occur in one or more of the\nfollowing circumstances:\n\n•   If the profiled application is terminated before it exits normally.\n\n•   If a running process is profiled.\n\n•   If archiving is explicitly disabled when profiling.  For example by using the -a  off\noption on gprofng collect app.\n\nIn  these  cases,  gprofng archive must be run manually and on the same machine where the\nprofiling data was recorded.\n\nArchiving of experiment data during the data collection process can be  quite  expensive.\nEspecially  if  the  experiment  has  many  descendant  processes.  In such cases, a more\nefficient strategy is to use the -a off  option  when  collecting  the  data.   Once  the\ncollection  has  completed, the data can be archived using the -s all option.  This saves\nall executables and source files in the experiment.\n\nIf during the archiving there is an error message that  an  executable,  or  source  file\ncannot  be  found,  the  addpath  command  to  add the path to the missing file(s) can be\nincluded in the .er.rc file.  After this command has been added, archive  the  experiment\nagain.  The archiving archiving can be repeated as many times as necessary to archive all\nfiles.\n\nArchiving  should  be  done on the same system as was used to collect the experiment.  If\nsome files cannot be accessed from this system (e.g.   sources  or  object  files),  then\nadditional archiving can be done using another system that can access them.  For example,\nthe system where the application was built.\n\nSome  Java  applications  store  shared  objects  in  jar files.  By default, such shared\nobjects are not automatically archived.  To  archive  shared  objects  contained  in  jar\nfiles,  make  sure to include the addpath command in an .er.rc file.  The addpath command\nshould give the path to the jar file, including the jar file  itself.   The  .er.rc  file\nshould be saved in the user home directory, or experiment parent directory.\n\n-   Archiving  of application sources - By default, application source files are not archived\nin the experiment.  Execute the gprofng archive command with  the  -s  all,  or  -s  used\noption on each experiment to store source files in the experiment.\n\n-   Automatic  archiving of application sources - Environment variable GPROFNGARCHIVE may be\nset to automatically archive sources when the experiment has completed.  This environment\nvariable can contain -s and -m arguments, as pairs of argument and options, separated  by\none or more blanks.\n\nIf  more  than one -s argument appears on the command line, the last one prevails.  If -s\nis both passed on the command line, and set by the environment variable, the option  from\nthe environment variable prevails.\n\nNote  that  in  case  automatic  source archiving during data collection has been enabled\nusing either the GPROFNGARCHIVE variable, or the -a src, or -a  usedsrc  option,  it  is\nrecommended  to  confirm  that source files have been correctly resolved by executing the\ngprofng archive -s all, or gprofng archive -s used command.\n\n-   The -d and -r options are mutually exclusive.\n\n-   When using the -d or -r option, environment variable  GPROFNGARCHIVECOMMONDIR  can  be\nused  to  specify  the  location of the common archive.  This can be very convenient when\nusing a script to profile applications.\n\n-   If more than one -s option is given on the command line, or specified in the  environment\nvariable,  the  specified option for all must be the same.  If not, gprofng archive exits\nwith an error.\n\n-   This tool does not work on experiments recorded with earlier versions of the  tools.   If\ninvoked  on  such  experiments, a warning is printed.  Use the version of gprofng archive\nfrom the same release with which the experiment was recorded.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "gprofng(1),  gp-collect-app(1),  gp-display-gui(1),  gp-display-html(1),   gp-display-src(1),\ngp-display-text(1)\n\nThe  user  guide  for  gprofng  is  maintained  as a Texinfo manual.  If the info and gprofng\nprograms are correctly installed, the  command  info  gprofng  should  give  access  to  this\ndocument.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (c) 2022-2024 Free Software Foundation, Inc.\n\nPermission  is granted to copy, distribute and/or modify this document under the terms of the\nGNU Free Documentation License, Version 1.3 or  any  later  version  published  by  the  Free\nSoftware Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-\nCover  Texts.   A  copy  of  the  license  is  included  in  the  section  entitled \"GNU Free\nDocumentation License\".\n\nbinutils-2.42                                2026-02-09                              GP-ARCHIVE.1(1)",
            "subsections": []
        }
    },
    "summary": "gp-archive - Archive gprofng experiment data",
    "flags": [
        {
            "flag": "",
            "long": "--version",
            "arg": null,
            "description": "Print the version number and exit."
        },
        {
            "flag": "",
            "long": "--help",
            "arg": null,
            "description": "Print usage information and exit."
        },
        {
            "flag": "-a",
            "long": null,
            "arg": null,
            "description": "Specify archiving of binaries and other files. In addition to disable this feature (off), or enable archiving of all loadobjects and sources (on), the other choices support a more refined selection. All of these choices enable archiving, but the keyword controls what exactly is selected: all load objects (ldobjects), all source files (src), the loadobjects associated with a program counter (usedldobjects), or the source files associated with a program counter (used[src]). The default is -a ldobjects."
        },
        {
            "flag": "-d",
            "long": null,
            "arg": null,
            "description": "The path is the absolute path to a common archive, which is a directory that contains archived files. If the directory does not exist, then it will be created. Files are saved in the common archive directory, and a symbolic link is created in the experiment archive."
        },
        {
            "flag": "-F",
            "long": null,
            "arg": null,
            "description": "recreated, except if the -n or -m option is used, or if the experiment is a subexperiment."
        },
        {
            "flag": "-m",
            "long": null,
            "arg": null,
            "description": "Archive only those source, object, and debug info files whose full path name matches the given POSIX compliant regex regular expression."
        },
        {
            "flag": "-n",
            "long": null,
            "arg": null,
            "description": ""
        },
        {
            "flag": "-q",
            "long": null,
            "arg": null,
            "description": "the experiment directory. They are shown in the output of the gprofng display text command."
        },
        {
            "flag": "-r",
            "long": null,
            "arg": null,
            "description": "This option specifies the location of a common archive. The value is the relative path to a common archive, which is a directory that contains archived files. If the directory does not exist, then it will be created. Files are saved in the common archive directory, and a symbolic link is created in the experiment archive."
        },
        {
            "flag": "-s",
            "long": null,
            "arg": null,
            "description": "Specify 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 ensure that source files are available in the experiment, even if the original source files have been modified, or are inaccessible afterwards. 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)."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "gprofng",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/gprofng/1/json"
        },
        {
            "name": "gp-collect-app",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/gp-collect-app/1/json"
        },
        {
            "name": "gp-display-gui",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/gp-display-gui/1/json"
        },
        {
            "name": "gp-display-html",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/gp-display-html/1/json"
        },
        {
            "name": "gp-display-src",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/gp-display-src/1/json"
        },
        {
            "name": "gp-display-text",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/gp-display-text/1/json"
        }
    ]
}