PMISETVOLUMESIZE(3)

NAME
pmiSetVolumeSize - configure automatic data volume rotation for a LOGIMPORT archive

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

DESCRIPTION
As part of the Performance Co-Pilot Log Import API (see LOGIMPORT(3)), pmiSetVolumeSize configures automatic data volume rotation for the archive associated with the current context.

After each successful call to pmiHighResWrite(3) or pmiWrite(3), if the current data volume file size meets or exceeds max_bytes, the library closes the current data volume, opens the next numbered volume, and writes a new volume label. Volume files are named archive.0, archive.1, and so on, where archive is the base path given to pmiStart(3). The .meta and .index files are shared across all volumes and remain open throughout.

If on_rotate is not NULL, it is called immediately after the old volume is closed and before the function returns. The single argument is the full path of the just-closed volume file (e.g. myarchive.0). The caller may use this callback to compress the completed volume or perform any other post-rotation work. The callback is invoked synchronously; long-running operations should be deferred to a child process.

Passing max_bytes as zero disables volume rotation (the default).

pmiSetVolumeSize interacts with the existing PCP_LOGIMPORT_MAXLOGSZ environment variable: both mechanisms trigger newvolume() independently, so if both are active the smaller threshold governs.

EXAMPLE
The following fragment opens a PCP archive, configures 100 MB volume rotation, and compresses each completed volume:

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);

DIAGNOSTICS
pmiSetVolumeSize returns zero on success. If there is no current context, PM_ERR_NOCONTEXT is returned. If max_bytes is greater than zero but does not exceed the on-disk label size for the configured archive version (124 bytes for v2, 800 bytes for v3), PM_ERR_CONV is returned. A threshold at or below the label size would cause the new volume's label to immediately exceed the threshold on every write, triggering a rotation cascade.

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