PMISETVOLUMESIZE(3)

💖 pmiSetVolumeSize — the pmiSetVolumeSize(3) page, but make it cute 💖

okay bestie, this one lives in the Library Functions Manual section 3, and it's about making your LOGIMPORT archive ✨rotate volumes automatically✨. yes, like a lil conveyor belt of archive files. obsessed.

---

🌸 NAME 🌸

pmiSetVolumeSize — set up automatic data volume rotation for a LOGIMPORT archive. that's it, that's the whole job, and she does it so well.

---

🎀 C SYNOPSIS 🎀

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

int pmiSetVolumeSize(size_t max_bytes, void (*on_rotate)(const char *));

cc ... -lpcp_import -lpcp

so you gotta pull in both headers, and when you link you're bringing in -lpcp_import and -lpcp. both. no skipping. 💅

---

✨ DESCRIPTION ✨

so this function is part of the Performance Co-Pilot Log Import API (go read LOGIMPORT(3) for the full tea, iykyk). what pmiSetVolumeSize does is configure automatic data volume rotation for the archive that's attached to your current context. current context is doing a lot of heavy lifting here, so keep track of it, bestie.

here's the vibe: after every successful call to pmiHighResWrite(3) or pmiWrite(3), the library peeks at how big the current data volume file is. if it meets or exceeds max_bytes? she goes off:

• closes the current data volume 🚪
• opens the next numbered volume 🔢
• writes a fresh new volume label 🏷️

and the volume files are named like archive.0, archive.1, and so on — where archive is literally the base path you handed to pmiStart(3). meanwhile the .meta and .index files are shared across all the volumes and just stay open the whole time. they're the main characters that never leave the group chat. 👑

now, the callback. if on_rotate is not NULL, it gets called immediately after the old volume is closed, and before this function returns. the one and only argument it gets is the full path of the volume file that was just closed (so like myarchive.0). you can use that callback to compress the finished volume, or do literally any other post-rotation chore you want. but — and this is the important part — the callback is invoked synchronously, so if you've got something long-running in mind, defer that to a child process. do not hold up the whole show. 🙈

passing max_bytes as zero disables volume rotation entirely, and yes, that's the default. zero means "no rotation, we're chilling."

one more thing: pmiSetVolumeSize also interacts with the existing PCP_LOGIMPORT_MAXLOGSZ environment variable. both mechanisms trigger newvolume() independently, so if both of them are active at the same time, the smaller threshold governs. whoever's stricter wins. periodt.

---

🦋 EXAMPLE 🦋

here's a lil fragment that opens a PCP archive, sets up 100 MB volume rotation, and compresses each finished volume as it goes:

static void
on_vol(const char *path)
{
    char cmd[MAXPATHLEN + 32];
    pmsprintf(cmd, sizeof(cmd), "xz %s &", path);
    system(cmd);
}

pmiStart("myarchive", 0);
pmiSetVolumeSize(100 * 1024 * 1024, on_vol);

see how on_vol gets the path and just yeets it into xz? slay. ate. 🔥

---

💀 DIAGNOSTICS 💀

pmiSetVolumeSize returns zero on success. iconic behavior, no notes.

• if there's no current context, you get PM_ERR_NOCONTEXT back. tragic but fair.
• if max_bytes is greater than zero but doesn't exceed the on-disk label size for the archive version you've configured — that's 124 bytes for v2 and 800 bytes for v3 — you get PM_ERR_CONV. and honestly? this check is doing you a favor, because a threshold at or below the label size would make the new volume's label immediately blow past the threshold on every single write, which triggers a rotation cascade. absolute chaos. we do not want that energy. 😭

so like, don't set your threshold smaller than the label size. fr fr. the library will yell at you and it's right to.

---

🌈 SEE ALSO 🌈

LOGIMPORT(3), pmiEnd(3), pmiErrStr(3), pmiHighResWrite(3), pmiStart(3), pmiWrite(3) and pmlogcheck(1).

go read those too, they're all part of the same friend group. 💜

---

and that's the whole page, bestie!! this one's brought to you by Performance Co-Pilot — shoutout to the source, mwah 🫶 — and the page itself is PMISETVOLUMESIZE(3), section 3 of the Library Functions Manual. go forth and rotate those volumes responsibly. ✨💖🎀