NAME

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

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmGetArchiveEnd(struct timeval *tp);
       int pmGetHighResArchiveEnd(struct timespec *tp);

       cc ... -lpcp

DESCRIPTION

       Assuming  the  current  PMAPI  context  is  associated  with  a  set  of   archive   logs,
       pmGetArchiveEnd  and  pmGetHighResArchiveEnd  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 tp.  This timestamp may be passed to pmSetMode(3) or pmSetHighResMode(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  and  pmGetHighResArchiveEnd return 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 tp is well-defined.

       Both  pmGetArchiveEnd and pmGetHighResArchiveEnd preserve the positioning state of the log
       file prior to this function call.

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

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),
       pmGetHighResArchiveLabel(3),          pmFetchHighRes(3),         pmFetchHighResArchive(3),
       pmSetModeHighRes(3), pmSetMode(3), pcp.conf(5) and pcp.env(5).