PMISETIMPORTPROGRAM(3)

💖 PMISETIMPORTPROGRAM 💖

okay bestie, welcome to the Performance Co-Pilot library functions manual, and today's main character is pmiSetImportProgram — the lil function that goes "hey pmdapmimport, notice me 👋" and registers your import tool so the whole world (well, the pmimport.* metric family) can see what it's up to. ✨

---

🌸 NAME 🌸

pmiSetImportProgram — register an import tool with pmdapmimport

---

🎀 C SYNOPSIS 🎀

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

int pmiSetImportProgram(const char *tool, const char *version, const char *args, const char *archive);

cc ... -lpcp_import -lpcp

---

🦋 DESCRIPTION 🦋

So here's the tea ☕ — this function is part of the Performance Co-Pilot Log Import API (peep LOGIMPORT(3) if you wanna get caught up). What pmiSetImportProgram does is register the import tool that's currently running with pmdapmimport(1), so that its status is visible through the pmimport.* metric family. it's giving "main character announces themselves." 👑

The function writes a sidecar status file to PCP_IMPORTRUN_DIR (typically /run/pmimport), and the file is named after tool. It's a simple key=value text format, and it can contain a subset of these fields:

• pid= — the process ID of the import tool. This one gets written only when the PMI_PROCESS flag was passed to pmiStart(3). Long-running daemons should totally use this flag, because then pmdapmimport(1) can detect and suppress stale entries left behind by an unclean exit 💀. One-shot tools (like, say, the ones a cron job invokes periodically) should omit the flag — their sidecar files persist between invocations and are always considered live. no flag, no problem.
• version= — the version string supplied by the caller. (Skipped if NULL or empty. bye.)
• args= — the args string supplied by the caller. (Also skipped if NULL or empty.) Typically this is a summary of the subsystems or data sources being imported, so pcp(1) can display it. slay.
• archive= — the archive base path supplied by the caller. (Yep, skipped if NULL or empty too.)

The sidecar file gets removed automatically when pmiEnd(3) is called, so you don't need to do any explicit cleanup on a clean exit. self-cleaning, iconic behavior 🧚

Timing matters, bestie: pmiSetImportProgram should be called once after pmiStart(3) and before the first call to pmiWrite(3). And calling it again with updated arguments (say, after an archive rotation) is totally permitted — it just overwrites the existing sidecar file. glow-up via overwrite ✨

---

💅 DIAGNOSTICS 💅

• Returns zero on success. periodt.
• PM_ERR_NOCONTEXT — returned if there is no current import context. 😭
• PM_ERR_CONV — returned if tool is NULL or empty.
• Any error opening or writing the sidecar file causes the corresponding negated errno(3) value to be returned.

heads up: that negated errno thing is real — don't go comparing it against plain errno values or you'll be confused and we don't want that for you 🫶

---

🌈 FILES 🌈

• $PCP_IMPORTRUN_DIR/<tool> — sidecar status file for the named import tool.

---

⭐ SEE ALSO ⭐

LOGIMPORT(3), pcp(1), pmdapmimport(1), pmiEnd(3), pmiErrStr(3), pmiStart(3), pmiWrite(3) and pmiWriteNow(3).

---

and that's the whole vibe check, bestie 💖 this page came to you courtesy of Performance Co-Pilot — PMISETIMPORTPROGRAM(3), go forth and register your import tools with confidence. no cap. 🎀🌸🦋