NAME
pmGetArchiveEnd - locate logical end of file for an
archive log
C SYNOPSIS
#include <pcp/pmapi.h>
int pmGetArchiveEnd(struct timeval *tvp);
cc ... -lpcp
DESCRIPTION
Assuming the current PMAPI context is associated with an
archive log, pmGetArchiveEnd will attempt to find the log
ical end of file (after the last complete record in the
archive), and return the last recorded timestamp via tvp.
This timestamp may be passed to pmSetMode(3) to reliably
position the context at the last valid log record, e.g. in
preparation for subsequent reading in reverse chronologi
cal order.
For archive logs that are not concurrently being written,
the physical end of file and the logical end of file are
co-incident. However if an archive log is being written
by pmlogger(1) at the same time an application is trying
to read the archive, the logical end of file may be before
the physical end of file due to write buffering that is
not aligned with the logical record boundaries.
pmGetArchiveEnd returns an error less than zero if the
context is neither valid, nor associated with an archive,
or the archive is seriously corrupted. Otherwise, the
return value is 0 if there has been no change of state
since the last call, or 1 if the logical end of file has
advanced since the last call.
In the absence of an error, the result returned via tvp is
well-defined.
pmGetArchiveEnd preserves the positioning state of the log
file prior to this function call.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to
parameterize the file and directory names used by PCP. On
each installation, the file /etc/pcp.conf contains the
local values for these variables. The $PCP_CONF variable
may be used to specify an alternative configuration file,
as described in pcp.conf(4). Values for these variables
may be obtained programatically using the pmGetConfig(3)
function.
PMAPI(3), pmFetch(3), pmFetchArchive(3), pmGetArchiveLa
bel(3), pmGetConfig(3), pmSetMode(3), pcp.conf(4) and
pcp.env(4).
DIAGNOSTICS
PM_ERR_NOCONTEXT
the current PMAPI context is either invalid, or not
associated with an archive log
PM_ERR_LOGREC
the archive is sufficiently damaged, that not a
single valid record can be found
Man(1) output converted with
man2html