PMOPENLOG(3)

💖 PMOPENLOG(3) — like, the library functions manual, bestie 💖

okay so real talk, this one lives in the <pcp/pmapi.h> cinematic universe (the PCP girlies know) and it's about giving your diagnostics somewhere cute to live instead of just screaming into the void. it's pmOpenLog, and yes she's a libc-flavored function from the Library Functions Manual. let's get into it ✨

---

🌸 NAME 🌸

pmOpenLog — create a log file for diagnostics and debug output. she makes a home for your little debug thoughts 🏠💅

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>

FILE *pmOpenLog(const char *progname, const char *logname,
                FILE *oldstream, int *status);

cc ... -lpcp

like, include the header, link the lib (-lpcp, don't forget her), and you're so back 🫶

---

🦋 DESCRIPTION 🦋

okay so here's the vibe: pmOpenLog takes your standard I/O stream oldstream (which is normally stderr, the classic) and reassigns it so it's associated with the file logname. glow-up, honestly.

now here's the part where you gotta pay attention, no cap 👀

if logname is not - and that file already exists, it gets renamed to logname.prev… or, if it can't be renamed, it gets removed. and ngl, due to permissions restrictions, the rename or removal may not succeed — that's just how it is sometimes 😭 — but in the common use cases, logname.prev remains, holding all the contents of the previous version of logname. so like, your old logs aren't lost, they're just archived bestie 💖

then logname gets recreated if possible — and the whole reason for that is to ensure the correct ownership and permissions, straight from the caller to pmOpenLog. iconic behaviour, truly 👑

special case alert 🚨 as a special case, if logname is -, then literally no renaming, no removal, no reopening happens. the function just sets status to 1 and returns oldstream, periodt. this is so useful when the caller wants diagnostics on the oldstream stream (normally stderr) instead of a file — think pmlogger -l- or pmcd -f -l-, iykyk.

and logging to stderr is also a whole mood for PMDAs in a containerized environment, where it's beneficial for all PMDA logs to be written to pmcd's stderr stream (and thus to a single destination) — whether that destination is a file such as pmcd.log, or the original stream inherited from the shell. one stream to rule them all, slay 🌈

---

💫 the return value, aka what you get back 💫

on return, the function value is the standard I/O stream — possibly replacing oldstream. so like, she might hand you something new, she might hand you back what you gave her.

but in the event of an error? the return value will be oldstream unchanged, and status will be 0. tragic but at least nothing got messed up 🙈

---

🎀 the success path (yes there's a preamble) 🎀

for success, status is 1, and a standard preamble gets written to logname:

Log for progname on hostname started date and time

and — plot twist — an atexit(3) handler is installed to write the postscript message to logname:

Log finished date and time

…when the process exits. so your log literally gets a little opening ceremony and a farewell note. main character energy fr fr 👑

also quick note: progname is only used to annotate messages. that's it. that's her whole job. she's just there for the vibes ✨

---

🌈 SEE ALSO 🌈

• atexit(3)
• freopen(3)

go read those too, they're part of the lore 💜

---

💀 gentle reminder bestie: that rename-or-remove of an existing logname can fail due to permissions restrictions. not the end of the world, but know it going in. 🫶

---

that's the whole page, babes 💖 this was Performance Co-Pilot / PCP content, the PMOPENLOG(3) girlie herself, and if you're reading the doc date stamp, that's when she was last touched up 💅 stay logged, stay iconic, mwah 🎀✨