PMPARSETIMEWINDOW(3)

✨ PMPARSETIMEWINDOW(3) ✨

okay bestie, welcome to pmParseTimeWindow from the Library Functions Manual — yes it's a whole libpcp moment and we're gonna make it make sense 💖

---

🎀 NAME 🎀

pmParseTimeWindow — literally just here to parse time window command line arguments for you, no cap 🫶

---

💅 C SYNOPSIS 💅

#include <pcp/pmapi.h>

int pmParseTimeWindow(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 🌸

so pmParseTimeWindow is designed to encapsulate the interpretation of the -S, -T, -A and -O command line options that Performance Co-Pilot (PCP) applications use to define a time window of interest. iconic behavior honestly 👑

that time window is defined by a start time and an end time, and it constrains the time interval during which the PCP application will retrieve and display performance metrics.

now, if the -O and -A options aren't there to specify an initial sample time origin and time alignment (more on those below, keep reading bestie), then the PCP application will retrieve the first sample at the start of the time window. periodt.

the syntax and meaning of all the various argument formats for these options is described over in PCPIntro(1), so go check that out if you need the deets 📖

---

🦋 USAGE 🦋

pmParseTimeWindow expects to be called like this:

• the argument of the -S option goes in as swStart
• the argument of the -T option goes in as swEnd
• the argument of the -A option goes in as swAlign
• the argument of the -O option goes in as swOffset

any or all of these parameters can be NULL, which is how you say "yeah that command line option wasn't there, bestie" 🙈

---

if your 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
• the time of the last archive entry as logEnd

wanna know how to get those values? pmGetArchiveLabel(3) and pmGetArchiveEnd(3) have you covered 💖

---

if the application is manipulating multiple concurrent archives, then the caller has to resolve how the default time window is defined. (the union of the time intervals in all archives is a likely interpretation, just saying 👀)

---

if the application is using a live feed of performance data:

• logStart should be the current time (but it could be aligned on the next second for example, flexible queen 💅)
• 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. like, allocated first, always, no exceptions 🚨

---

you also need to set the current PCP reporting time zone so it correctly reflects the -z and -Z command line parameters, and you gotta do that before calling these routines. pmUseZone(3) and friends have the info on how that's done 🌈

---

🔥 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. and the errMsg parameter? not changed when pmParseTimeWindow returns 1. untouched, unbothered, living its life ✨

if the conversion is successful but the requested alignment could not be performed (e.g. the set of PCP archives is too short — tragic 😭) then the alignment is ignored, rsltStart, rsltEnd and rsltOffset are still filled in, and pmParseTimeWindow returns 0. in this case, errMsg will point to a warning message in a dynamically allocated buffer.

🫶 bestie reminder: the caller is responsible for releasing that buffer by calling free(3).

if the argument strings could not be parsed, pmParseTimeWindow returns -1. in this case, errMsg will point to an error message in a dynamically allocated buffer.

😭 same deal: the caller is responsible for releasing that buffer by calling free(3).

---

💀 COMPATIBILITY 💀

prior to PCP 7.0 and libpcp.so.4, the logStart, logEnd, rsltStart, rsltEnd and rsltOffset arguments were struct timeval. yes, really, we've come so far 🧚

to support the PMAPI transition, the old interface and semantics can still be used if applications are linked with libpcp.so.3 or recompiled with -DPMAPI_VERSION=2.

and for a time in PCP 6.x there was a routine with the same semantics as the current pmParseTimeWindow called pmParseHighResTimeWindow — although this is now deprecated, and compile-time support for pmParseHighResTimeWindow will be removed in a future release. so like, don't get attached, it's giving legacy 🥲

---

⭐ SEE ALSO ⭐

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

---

and that's the whole page, bestie!! this was Performance Co-Pilot — PCP — dropping PMPARSETIMEWINDOW(3) for you 💖 stay parsed, stay aligned, and go free your buffers 🎀✨