oracular (3) pmFetchArchive.3.gz

NAME

       pmFetchArchive, pmFetchHighResArchive - get performance metric values directly from archives

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmFetchArchive(pmResult **result);
       int pmFetchHighResArchive(pmHighResResult **result);

       cc ... -lpcp

DESCRIPTION

       The  pmFetchArchive  and  pmFetchHighResArchive APIs are variants of the pmFetch(3) and pmFetchHighRes(3)
       interfaces that may only be used when the current Performance Metrics Application  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  and pmFetchHighResArchive 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  boundary  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 and pmFetchHighResArchive will be used to create utilities that scan
       sets of archives,  while  the  more  common  access  to  the  archives  would  be  via  the  pmFetch  and
       pmFetchHighRes interfaces.

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

       Note  that the result returned by both pmFetchArchive and pmFetchHighResArchive is dynamically allocated,
       and must be released using either  pmFreeResult(3)  or  pmFreeHighResResult(3),  but  not  free(3).   See
       pmFetch(3), pmFetchHighRes(3), pmFreeResult(3) and pmFreeHighResResult(3) for further details.

       Both pmFetchArchive and pmFetchHighResArchive returns zero on success.

DIAGNOSTICS

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

SEE ALSO

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