PMPARSETIME(3)

💖 PMPARSETIME(3) — like, the manual page for parsing time point specs 💖

Library Functions Manual · PCP · bestie, we're going internal-dev deep today 🫶

---

✨ NAME ✨

__pmtimevalParse, __pmtimespecParse — parse a time point specification, no cap 🌸

---

🎀 C SYNOPSIS 🎀

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

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

cc ... -lpcp

okay so you gotta link against -lpcp, that part is not optional bestie 💅

---

💀 CAVEAT 💀

READ THIS. FOR REAL. NOT ME DROPPING A CAVEAT FOR DRAMA.

This documentation is intended for internal Performance Co-Pilot (PCP) developer use. It's giving backstage pass, not main-stage.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future. 😭 So like... don't build your whole personality on them, iykyk.

---

🦋 DESCRIPTION 🦋

__pmtimevalParse and __pmtimespecParse are designed to encapsulate the interpretation of a time point specification in command line switches for use by the PCP client tools. They're the little translators so the tools don't have to do it themselves, and honestly? Slay. 👑

These functions expect to be called with the time point specification as string. Literally just hand over the string, that's the vibe.

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

See pmGetArchiveLabel(3) and pmGetArchiveEnd(3) for how to obtain values for these parameters. 🫶

If the tool is running against 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. Yes, uppercase, exactly like that. ⭐

The rslt structure must be allocated before either calling __pmtimevalParse or __pmtimespecParse. Not allocated? That's on you, bestie, the function is not gonna do it for you 🙈

You also need to set the current PCP reporting time zone to correctly reflect the -z and -Z command line parameters before calling __pmtimevalParse or __pmtimespecParse. See pmUseZone(3) and friends for information on how this is done. The time zone thing is lowkey the part people forget and then they're confused, so don't be that person. 🌈

💖 what you get back 💖

• If the conversion is successful, both __pmtimevalParse and __pmtimespecParse return 0, and fill in rslt with the time value defined by the input parameters. Periodt. ✨
• If the argument strings could not be parsed, it returns -1 and a dynamically allocated error message string in errMsg.

Be sure to free(3) this error message string. It's dynamically allocated, so it's your responsibility now. Free it. Let it go. 🎀

---

🌸 SEE ALSO 🌸

• PMAPI(3)
• __pmParseCtime(3)
• __pmtimespecConvert(3)
• __pmtimevalConvert(3)
• pmGetArchiveEnd(3)
• pmGetArchiveLabel(3)
• pmNewContextZone(3)
• pmNewZone(3)
• pmParseInterval(3)
• pmParseTimeWindow(3)
• pmUseZone(3)

Like, the whole friend group, fr fr. Go read them, they're iconic. 📚✨

---

Performance Co-Pilot · PCP · PMPARSETIME(3)

That's the whole page bestie, from the Performance Co-Pilot girlies at PCP. Mwah, go parse some time, you absolute main character. 💜🦋💅