NAME

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

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 archives, 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 pmSetModeHighRes(3) to  reliably  position
       the  context  at the last valid archive record, e.g. in preparation for subsequent reading
       in reverse chronological order.

       For archives that are not concurrently being written, the physical end  of  file  and  the
       logical  end  of  file  are  co-incident.   However  if  an  archive  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
       archive file prior to this function call.

DIAGNOSTICS

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

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