PMPARSETIME(3)

💖 PMPARSETIME(3) 💖 — like, the library functions manual era, but make it cute

okay bestie, sit down, hydrate, because we're about to talk about parsing time point specifications and honestly? it's giving brainy AND iconic. this is __pmParseTime and __pmParseHighResTime from the Performance Co-Pilot crew, and yes, the manual name is literally right there in the title, we're just being extra about it. 🎀

---

✨ NAME ✨

__pmParseTime, __pmParseHighResTime — parse time point specification 🕰️

---

🌸 C SYNOPSIS 🌸

so here's the vibe, code-wise:

#include "pmapi.h"
#include "libpcp.h"

int __pmParseTime(const char *string, struct timeval *logStart,
        struct timeval *logEnd, struct timeval *rslt, char **errMsg);
int __pmParseHighResTime(const char *string, struct timespec *logStart,
        struct timeval *logEnd, struct timespec *rslt, char **errMsg);

wait, hold on, let me not mess up a single character here — the actual thing is:

#include "pmapi.h"
#include "libpcp.h"

int __pmParseTime(const char *string, struct timeval *logStart,
        struct timeval *logEnd, struct timeval *rslt, char **errMsg);
int __pmParseHighResTime(const char *string, struct timespec *logStart,
        struct timespec *logEnd, struct timespec *rslt, char **errMsg);

and when you build, it's:

cc ... -lpcp

no cap, that's the whole flex. 💅

---

🫶 CAVEAT 🫶

okay so real talk, this one matters:

this documentation is meant for internal Performance Co-Pilot (PCP) developer use. like, it's the backstage pass, not the main entrance.

and these interfaces? they are not part of the PCP APIs that are guaranteed to remain fixed across releases. so they may not work, or they may provide different semantics at some point in the future. the way that they can just change on you… yeah. don't build your whole personality on them. 😭

---

🦋 DESCRIPTION 🦋

so __pmParseTime and __pmParseHighResTime exist to encapsulate the interpretation of a time point specification in command line switches, for use by the PCP client tools. that's the whole job. that's the assignment. and they ate. 👑

these functions expect to be called with the time point specification as string. cute, simple, love that for us.

now — if the tool is running against PCP archive(s), you also need to supply:

• the start time of the first (only) archive as logStart 🍓
• the end of the last (only) archive as logEnd 🌈

need help getting those? go peek at pmGetArchiveLabel(3) and pmGetArchiveEnd(3) — they'll hook you up with values for these parameters. 💖

but if the tool is running against a live feed of performance data, then it's different bestie:

• logStart should be the current time (but could be aligned on the next second, for example)
• logEnd should have its tv_sec component set to PM_MAX_TIME_T

the rslt structure must be allocated before either calling __pmParseTime or __pmParseHighResTime. do not skip this. it's not optional. it's the vibe check. ✨

you also need to set the current PCP reporting time zone so it correctly reflects the -z and -Z command line parameters before calling __pmParseTime or __pmParseHighResTime. see pmUseZone(3) and friends for info on how that's done. 💜

okay and now the payoff:

• if the conversion is successful, both __pmParseTime and __pmParseHighResTime return 0, and fill in rslt with the time value defined by the input parameters. slay. 🔥
• if the argument strings could not be parsed, it returns -1 and a dynamically allocated error message string in errMsg.

⚠️ and be sure to free(3) this error message string. not me forgetting to free it… couldn't be me… 🙈

---

👑 SEE ALSO 👑

PMAPI(3), pmGetArchiveEnd(3), pmGetArchiveLabel(3), pmNewContextZone(3), pmNewZone(3), pmParseInterval(3), pmParseTimeWindow(3), pmUseZone(3), __pmConvertTime(3) and __pmParseCtime(3) 💅

---

and that's the whole page bestie, we did it, main character energy from start to finish. this one's brought to you by Performance Co-Pilot — PCP, filed under PMPARSETIME(3), and stamped with a date so you know it's fresh. mwah, go parse some time. 🧚💖