NAME

       pmGetArchiveEnd - locate logical end of file for a set of archive logs

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmGetArchiveEnd(struct timeval *tvp);

       cc ... -lpcp

DESCRIPTION

       Assuming   the   current  PMAPI  context  is  associated  with  a  set  of  archive  logs,
       pmGetArchiveEnd will attempt to find the logical end of  file  (after  the  last  complete
       record  in  the  set  of  archives), 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 chronological 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 a set of  archives,  or  the  set  of  archives  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(5).   Values  for  these  variables  may  be
       obtained programmatically using the pmGetConfig(3) function.

SEE ALSO

       PMAPI(3),    pmFetch(3),    pmFetchArchive(3),    pmGetArchiveLabel(3),    pmGetConfig(3),
       pmSetMode(3), pcp.conf(5) and pcp.env(5).

DIAGNOSTICS

       PM_ERR_NOCONTEXT
              the current PMAPI context is either invalid, or  not  associated  with  an  set  of
              archive logs

       PM_ERR_LOGREC
              the  set of archives is sufficiently damaged, that not a single valid record can be
              found