pmfetcharchive(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | COMPATIBILITY | SEE ALSO | COLOPHON

PMFETCHARCHIVE(3)        Library Functions Manual       PMFETCHARCHIVE(3)

NAME         top

       pmFetchArchive, - get performance metric values directly from
       archives

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmFetchArchive(pmResult **result);

       cc ... -lpcp

DESCRIPTION         top

       The  pmFetchArchive  API  is a variant of the pmFetch(3) interface
       that may only be used when the current Performance Metrics  Appli‐
       cation  Programming Interface (PMAPI) context is associated with a
       set of archives.

       The result is instantiated with all of the metrics (and instances)
       from the next archive record, consequently there is no notion of a
       list of desired metrics, and the instance  profile  of  the  PMAPI
       context is ignored.

       pmFetchArchive may return a result in which numpmid is zero.  This
       is  a <mark> record that indicates a temporal discontinuity in the
       time series of performance metrics.  This can happen at the bound‐
       ary between archives in a set or if the  archive  associated  with
       the  current  PMAPI  context  was created using pmlogextract(1) to
       concatenate two or more PCP archives, and the <mark> record  marks
       a point in time between the end of one input archive and the start
       of the next input archive.

       It  is  expected that pmFetchArchive will be used to create utili‐
       ties that scan sets of archives, while the more common  access  to
       the archives would be via the pmFetch interface.

       To  skip  records  within the set of archives, use pmSetMode(3) to
       change the collection time within the current PMAPI context,  then
       call either pmFetchArchive

       Note that the result returned by pmFetchArchive is dynamically al‐
       located,  and  must  be  released  using  pmFreeResult(3), but not
       free(3).  See pmFetch(3), and pmFreeResult(3) for further details.

       pmFetchArchive returns zero on success.

DIAGNOSTICS         top

       PM_ERR_NOTARCHIVE
              the current PMAPI context is not associated with a set of
              archives

COMPATIBILITY         top

       Prior to PCP 7.0 the timestamp field in the pmResult struct was a
       struct timeval.  To support PMAPI transition, the old interface
       and semantics can be used if applications are recompiled with
       -DPMAPI_VERSION=2.

       For a time in PCP 6.x there was a routine with the same semantics
       as the current pmFetchArchive called pmFetchHighResArchive, and a
       struct with the same definition as the current pmResult struct
       called pmResultHighRes, although both are now deprecated and com‐
       pile-time support for pmFetchHighResArchive and pmResultHighRes
       will be removed in a future release.

SEE ALSO         top

       PMAPI(3), pmFetch(3), pmFreeResult(3), pmNewContext(3),
       pmSetMode(3) and pmTrimNameSpace(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2025-08-11.  (At that time, the date of the most recent commit
       that was found in the repository was 2025-08-11.)  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page,
       or you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a
       mail to man-pages@man7.org

Performance Co-Pilot               PCP                  PMFETCHARCHIVE(3)

Pages that refer to this page: pcpintro(3)pmfetch(3)pmgetarchiveend(3)pmregisterderived(3)pmsetmode(3)