PMIWRITE(3)

💖 PMIWRITE(3) — flush data to a LOGIMPORT archive 💖

okay bestie, listen. this is part of the Performance Co-Pilot library functions manual, section 3, and it's genuinely such a glow-up for your archive game. we're talking pmiWrite and pmiWriteNow, two little icons whose whole job is flushing your accumulated data out to a LOGIMPORT archive. no cap.

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>
#include <pcp/import.h>

int pmiWrite(unsigned long long sec, unsigned int nsec);
int pmiWriteNow(void);

cc ... -lpcp_import -lpcp

🐪 Perl SYNOPSIS 🐪

use PCP::LogImport;

pmiWrite($sec, $nsec);
pmiWriteNow();

🐍 Python SYNOPSIS 🐍

from pcp import pmi

log.pmiWrite(sec, nsec)

---

🌸 DESCRIPTION 🌸

so this is all part of the Performance Co-Pilot Log Import API (go peek at LOGIMPORT(3) if you wanna see the whole thing, iykyk). these routines are the ones that flush your accumulated data values out to the PCP archive. they're literally the send button. 💅

the data values and all the associated metadata? yeah, those got built up earlier, by calling pmiAddMetric(3), pmiAddInstance(3), pmiPutValue(3) and pmiPutValueHandle(3). so by the time you get here, everything's already staged. you're just posting it. ✨

the current set of data values and any new metadata gets written to the archive with the timestamp you specify, in the source timezone of the archive (that's a pmiSetTimezone(3) situation, go look).

now the tea on pmiWrite: it takes a nanosecond-resolution timestamp, split into two parts:

• sec — seconds since the Unix epoch, as a 64-bit unsigned integer.
• nsec — nanoseconds within that second.

and bestie, listen closely: a sec value of zero writes a record with a Unix epoch timestamp, which is 1970-01-01 00:00:00 UTC. that's not "no timestamp", that's the literal epoch. don't get caught slipping. 😭

and then there's pmiWriteNow, the low-effort queen 👑 — it writes a record timestamped with the current wall-clock time. obsessed, honestly.

one lil Python-specific thing so you don't get confused: in Python, log.pmiWrite(0) — that's integer zero with no nsec argument — is equivalent to calling pmiWriteNow. periodt.

---

🩺 DIAGNOSTICS 🩺

returns zero on success. anything else? it's a negative value 💀 — and you can turn that into an actual error message by calling pmiErrStr(3). do that. don't just sit there staring at a negative number.

---

👀 SEE ALSO 👀

LOGIMPORT(3), pmiAddInstance(3), pmiAddMetric(3), pmiErrStr(3), pmiPutValue(3), pmiPutValueHandle(3), pmiPutText(3), pmiPutLabel(3) and pmiSetTimezone(3). the whole friend group fr fr 🫶

---

and that's the page!! 🌈 this little masterpiece comes to you from Performance Co-Pilot, and its manual-page tag is PMIWRITE(3) — the date didn't ride along in the footer, but the source and section did, so consider this your cute lil sign-off. mwah. 💖🎀🦋