NAME

       pmParseTimeWindow, pmParseHighResTimeWindow - parse time window command line arguments

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmParseTimeWindow(const char *swStart, const char *swEnd, const char *swAlign, const char *swOffset,
               const struct timeval *logStart, const struct timeval *logEnd, struct timeval *rsltStart,
               struct timeval *rsltEnd, struct timeval *rsltOffset, char **errMsg);
       int pmParseHighResTimeWindow(const char *swStart, const char *swEnd, const char *swAlign,
               const char *swOffset, const struct timespec *logStart, const struct timespec *logEnd,
               struct timespec *rsltStart, struct timespec *rsltEnd, struct timespec *rsltOffset,
               char **errMsg);

       cc ... -lpcp

DESCRIPTION

       pmParseTimeWindow  and pmParseHighResTimeWindow are designed to encapsulate the interpretation of the -S,
       -T, -A and -O command line options used by Performance Co-Pilot (PCP) applications to define a time  win‐
       dow of interest.  The time window is defined by a start time and an end time that constrains the time in‐
       terval during which the PCP application will retrieve and display performance metrics.  In the absence of
       the  -O  and  -A options to specify an initial sample time origin and time alignment (see below), the PCP
       application will retrieve the first sample at the start of the time window.

       The syntax and meaning of the various argument formats for these options is described in PCPIntro(1).

USAGE

       pmParseTimeWindow and pmParseHighResTimeWindow expect to be called with the argument of the -S option  as
       swStart,  the argument of the -T option as swEnd, the argument of the -A option as swAlign, and the argu‐
       ment of the -O option as swOffset.  Any or all of these parameters may be NULL to indicate that the  cor‐
       responding command line option was not present.

       If  the application is using a set of PCP archives as the source of performance metrics, you also need to
       supply the time of the first archive entry as logStart, and the time of the last archive entry as logEnd.
       See pmGetArchiveLabel(3) and pmGetArchiveEnd(3) for how to obtain values for these times.

       If the application is manipulating multiple concurrent archives, then the caller must resolve how the de‐
       fault time window is to be defined (the union of the time intervals in all archives is a likely interpre‐
       tation).

       If the application is using a live feed of performance data, logStart should be  the  current  time  (but
       could  be  aligned  on the next second for example), while logEnd should have its tv_sec component set to
       PM_MAX_TIME_T.

       The rsltStart, rsltEnd and rsltOffset structures must be allocated before  calling  pmParseTimeWindow  or
       pmParseTimeHighResWindow.

       You  also need to set the current PCP reporting time zone to correctly reflect the -z and -Z command line
       parameters before calling these routines.  See pmUseZone(3) and friends for information on  how  this  is
       done.

DIAGNOSTICS

       If  the  conversion  is  successful,  pmParseTimeWindow and pmParseHighResTimeWindow return 1 and fill in
       rsltStart, rsltEnd and rsltOffset with the start, end, and offset times for the time  window  defined  by
       the  input parameters.  The errMsg parameter is not changed when either pmParseTimeWindow or pmParseHigh‐
       ResTimeWindow returns 1.

       If the conversion is successful, but the requested alignment could not be performed (e.g. the set of  PCP
       archives  is too short) the alignment is ignored, rsltStart, rsltEnd and rsltOffset are filled in and pm‐
       ParseTimeWindow and pmParseHighResTimeWindow return 0.  In this case, errMsg will point to a warning mes‐
       sage in a dynamically allocated buffer.  The caller is responsible for releasing the  buffer  by  calling
       free(3).

       If  the  argument  strings could not be parsed, pmParseTimeWindow and pmParseHighResTimeWindow return -1.
       In this case, errMsg will point to an error message in a dynamically allocated buffer.  The caller is re‐
       sponsible for releasing the buffer by calling free(3).

SEE ALSO

       free(3), PMAPI(3), pmGetArchiveEnd(3), pmGetArchiveLabel(3),  pmNewContextZone(3),  pmNewZone(3),  pmPar‐
       seInterval(3) and pmUseZone(3).

Performance Co-Pilot                                   PCP                                  PMPARSETIMEWINDOW(3)