1PMGETARCHIVELABEL(3)       Library Functions Manual       PMGETARCHIVELABEL(3)
2
3
4

NAME

6       pmGetArchiveLabel,  pmGetHighResArchiveLabel  -  fetch the label record
7       from a set of performance metrics archives
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmGetArchiveLabel(pmLogLabel *lp);
13       int pmGetHighResArchiveLabel(pmHighResLogLabel *lp);
14
15       cc ... -lpcp
16

DESCRIPTION

18       Within the framework of the Performance  Co-Pilot  (PCP),  archives  of
19       performance  metrics values may be accumulated and saved using the pro‐
20       gram pmlogger(1) and the LOGIMPORT(3) programming interface.
21
22       The routines pmGetArchiveLabel and pmGetHighResArchiveLabel may be used
23       to  fetch the label record from a set of archives that has already been
24       opened using pmNewContext(3), or pmDupContext(3), and  thereby  associ‐
25       ated  with  the current Performance Metrics Application Programming In‐
26       terface (PMAPI) context.
27
28       It is recommended that new applications use the high resolution API and
29       existing applications transition to this interface over time.
30
31       The result returned via the pointer lp is a structure that must be pre-
32       allocated by the caller and has one of the following two  formats  (de‐
33       fined in pmapi.h).
34
35         typedef struct {
36           int        magic;       /* PM_LOG_MAGIC | archive format version no. */
37           pid_t      pid;         /* PID of logger */
38           struct timespec start;  /* start of this archive */
39           char       hostname[PM_MAX_HOSTNAMELEN];   /* collection host full name */
40           char       timezone[PM_MAX_TIMEZONELEN];   /* generic, squashed $TZ */
41           char       zoneinfo[PM_MAX_ZONEINFOLEN];   /* local platform $TZ */
42         } pmHighResLogLabel;
43
44         typedef struct {
45           int        ll_magic;    /* PM_LOG_MAGIC | archive format version no. */
46           pid_t      ll_pid;      /* PID of logger */
47           struct timeval ll_start;/* start of this archive */
48           char       ll_hostname[PM_LOG_MAXHOSTLEN]; /* name of collection host */
49           char       ll_tz[40];   /* $TZ at collection host */
50         } pmLogLabel;
51
52       Both  forms  can  be  used with either version 2 or version 3 archives.
53       However, the pmHighResLogLabel structure provides the higher resolution
54       start time stored in the newer format, as well as the full timezone and
55       extended length host name fields.  For detailed information  about  the
56       archive on-disk format, refer to LOGARCHIVE(5).
57
58       For  an application using pmGetHighResArchiveLabel, the most useful in‐
59       formation from the archive label is likely to be in the  fields  start,
60       hostname, timezone, and zoneinfo.
61
62       The  zoneinfo  field  contains  the  most detailed timezone information
63       available, and should be used if present (non-zero length string).   It
64       will  only not be present in the case of version 2 archives - this is a
65       new field added as part of the version 3 format.   The  timezone  field
66       will always be present, however it is the 'squashed' timezone value and
67       in certain situations is not the most accurate timezone.
68
69       For older applications using pmGetArchiveLabel, the most useful  infor‐
70       mation  from  the archive label is likely to be in the fields ll_start,
71       ll_hostname or ll_tz.  Note that the size of the ll_hostname  field  is
72       PM_LOG_MAXHOSTLEN  (64  bytes)  which  is less than MAXHOSTNAMELEN (see
73       gethostbyname(3)) on some platforms.  These semantics are necessary  to
74       retain backwards compatibility with the PCP archive file format.
75
76       Both  pmGetArchiveLabel  and  pmGetHighResArchiveLabel  return zero for
77       success.
78

DIAGNOSTICS

80       PM_ERR_NOCONTEXT
81              the current PMAPI context is either invalid, or  not  associated
82              with a set of archives
83

PCP ENVIRONMENT

85       Environment variables with the prefix PCP_ are used to parameterize the
86       file and directory names used by PCP.  On each installation,  the  file
87       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
88       $PCP_CONF variable may be used to specify an alternative  configuration
89       file,  as  described in pcp.conf(5).  Values for these variables may be
90       obtained programmatically using the pmGetConfig(3) function.
91

SEE ALSO

93       pmlogger(1), LOGIMPORT(3), PMAPI(3),  pmDupContext(3),  pmGetConfig(3),
94       pmNewContext(3), LOGARCHIVE(5), pcp.conf(5) and pcp.env(5).
95
96
97
98Performance Co-Pilot                  PCP                 PMGETARCHIVELABEL(3)
Impressum