pmparsetimewindow(3) — Linux manual page

PMPARSETIMEWINDOW(3)    Library Functions Manual    PMPARSETIMEWINDOW(3)

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 window of interest.  The time window is defined  by
       a  start  time  and an end time that constrains the time interval
       during which the PCP application will retrieve and  display  per‐
       formance  metrics.   In  the  absence of the -O and -A options to
       specify an initial sample time origin and time alignment (see be‐
       low), 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 argu‐
       ment of the -T option as swEnd, the argument of the -A option  as
       swAlign,  and  the argument of the -O option as swOffset.  Any or
       all of these parameters may be NULL to indicate that  the  corre‐
       sponding 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 default time window is to be
       defined (the union of the time intervals in  all  archives  is  a
       likely interpretation).

       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 allocat‐
       ed before calling pmParseTimeWindow or pmParseHighResTimeWindow.

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

DIAGNOSTICS

       If  the  conversion is successful, pmParseTimeWindow and pmParse‐
       HighResTimeWindow 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 pmParseHighRes‐
       TimeWindow 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  rsltOff‐
       set  are  filled  in  and  pmParseTimeWindow  and pmParseHighRes‐
       TimeWindow return 0.  In this case, errMsg will point to a  warn‐
       ing message in a dynamically allocated buffer.  The caller is re‐
       sponsible 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  responsible  for releasing the buffer by calling
       free(3).

SEE ALSO

       free(3),  PMAPI(3),   pmGetArchiveEnd(3),   pmGetArchiveLabel(3),
       pmNewContextZone(3),    pmNewZone(3),    pmParseInterval(3)   and
       pmUseZone(3).

COLOPHON

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug  report  for  this  manual  page,  send  it  to
       pcp@groups.io.    This  page  was  obtained  from  the  project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩   on  2024-06-14.
       (At that time, the date of the most recent commit that was  found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems  in  this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or  you  have
       corrections  or  improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a  mail  to
       man-pages@man7.org

Performance Co-Pilot               PCP              PMPARSETIMEWINDOW(3)

Pages that refer to this page: pmseries(1), __pmconverttime(3), pmparseinterval(3), __pmparsetime(3)

---