# pmgetarchivelabel

## NAME



           **pmGetArchiveLabel** - fetch the label record from a set of
           performance metrics archives
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmGetArchiveLabel(pmLogLabel ***_lp_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           Within  the  framework of the Performance Co-Pilot (PCP), archives
           of performance metrics values may be accumulated and  saved  using
           the  program  pmlogger(1)  and the LOGIMPORT(3) programming inter‐
           face.
    
           The routines **pmGetArchiveLabel** may be  used  to  fetch  the  label
           record  from  a set of archives that has already been opened using
           pmNewContext(3), or pmDupContext(3), and thereby  associated  with
           the  current Performance Metrics Application Programming Interface
           (PMAPI) context.
    
           The result returned via the pointer _lp_ is a structure that must be
           pre-allocated by the caller and has the following format  (defined
           in **pmapi.h**).
    
             typedef struct {
               int        magic;       /* PM_LOG_MAGIC | archive format version no. */
               pid_t      pid;         /* PID of logger */
               struct timespec start;  /* start of this archive */
               char       hostname[PM_MAX_HOSTNAMELEN];   /* collection host full name */
               char       timezone[PM_MAX_TIMEZONELEN];   /* generic, squashed $TZ */
               char       zoneinfo[PM_MAX_ZONEINFOLEN];   /* local platform $TZ */
             } pmLogLabel;
    
           **pmGetArchiveLabel** can  be used with either version 2 or version 3
           archives, however some mapping may be required with the older ver‐
           sion 2 archives, e.g. the _start_ time only has microsecond  resolu‐
           tion and the _zoneinfo_ field is not present.  For detailed informa‐
           tion about the archive on-disk format, refer to LOGARCHIVE(5).
    
           For an application using **pmGetArchiveLabel** , the most useful infor‐
           mation from the archive label is likely to be in the fields _start_ ,
           _hostname_ , _timezone_ , and _zoneinfo_.
    
           The _zoneinfo_ field contains the most detailed timezone information
           available, and should be used if present (non-zero length string).
           It  will  only  not be present in the case of version 2 archives -
           this is a new field added as part of the version  3  format.   The
           _timezone_   field  will  always  be  present,  however  it  is  the
           'squashed' timezone value and in certain  situations  is  not  the
           most accurate timezone.
    
           For  older  applications  using **pmGetArchiveLabel** , the most useful
           information from the archive label is likely to be in  the  fields
           _ll_start_ ,  _ll_hostname_  or  _ll_tz_.   Note  that  the  size  of the
           _ll_hostname_ field is _PM_LOG_MAXHOSTLEN_ (64 bytes)  which  is  less
           than  **MAXHOSTNAMELEN**(see  gethostbyname(3))  on  some platforms.
           These semantics are necessary to  retain  backwards  compatibility
           with the PCP archive file format.
    
           **pmGetArchiveLabel** return zero for success.
    


## COMPATIBILITY



           Prior  to  PCP  7.0  and  _libpcp.so.4_ the _pmLogLabel_ structure was
           somewhat different.  To support PMAPI transition, the  old  inter‐
           face  and  semantics  can  be used if applications are linked with
           _libpcp.so.3_ or recompiled with **-DPMAPI_VERSION=2**.
    
           For a time in PCP 6.x there was a routine with the same  semantics
           as  the  current **pmGetArchiveLabel** called **pmGetHighResArchiveLabel**
           and a structure with same definition as _pmLogLabel_ called  _pmHigh‐_
           _ResLogLabel_  although  these  are  now deprecated and compile-time
           support for **pmGetHighResArchiveLabel** and _pmHighResLogLabel_ will be
           removed in a future release.
    


## DIAGNOSTICS



           **PM_ERR_NOCONTEXT**
                  the current PMAPI context is either invalid, or not associ‐
                  ated with a set of archives
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to parameter‐
           ize the file and directory names used by PCP.  On each installa‐
           tion, the file _/etc/pcp.conf_ contains the local values for these
           variables.  The **$PCP_CONF** variable may be used to specify an al‐
           ternative configuration file, as described in pcp.conf(5).  Values
           for these variables may be obtained programmatically using the
           pmGetConfig(3) function.
    


* * *