NAME
pmParseTimeWindow - parse time window command line argu
ments
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)
cc ... -lpcp
DESCRIPTION
pmParseTimeWindow is designed to encapsulate the interpre
tation 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 inter
val 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 expects 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 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 PCP archive log as the
source of performance metrics, you also need to supply the
time of the first archive log entry as logStart, and the
time of the last archive log entry as logEnd. See
pmGetArchiveLabel(3) and pmGetArchiveEnd(3) for how to
obtain values for these times.
If the application is manipulating multiple concurrent
archive logs, then the caller must resolve how the default
time window is to be defined (the union of the time inter
vals in all archive logs is a likely interpretation).
If the application is using a live feed of performance
data, logStart should be the current time (but could be
should have its tv_sec component set to INT_MAX.
The rsltStart, rsltEnd and rsltOffset structures must be
allocated before calling pmParseTimeWindow.
You also need to set the current PCP reporting time zone
to correctly reflect the -z and -Z command line parameters
before calling pmParseTimeWindow. See pmUseZone(3) and
friends for information on how this is done.
SEE ALSO
PMAPI(3), pmGetArchiveEnd(3), pmGetArchiveLabel(3), pmNew
ContextZone(3), pmNewZone(3), pmParseInterval(3) and
pmUseZone(3).
DIAGNOSTICS
If the conversion is successful, pmParseTimeWindow returns
1 and fills 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 pmParseTimeWindow returns 1.
If the conversion is successful, but the requested align
ment could not be performed (e.g. the PCP archive log is
too short) the alignment is ignored, rsltStart, rsltEnd
and rsltOffset are filled in and pmParseTimeWindow returns
0. In this case, errMsg will point to a warning message
in an internal static buffer. This buffer should not be
freed.
If the argument strings could not be parsed, pmParse
TimeWindow returns -1. In this case, errMsg will point to
an error message in a static internal buffer.
Man(1) output converted with
man2html