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 logical 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 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 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(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 archive log

       PM_ERR_LOGREC
              the archive is sufficiently damaged, that not a single valid record can be found