PMPROCESSPIPE(3)

💖 PMPROCESSPIPE 💖

okay bestie, welcome to the PMPROCESSPIPE page from the Library Functions Manual — yes it's a section 3 one, we love a library function moment 🫶

✨ NAME ✨

__pmProcessPipe, __pmProcessPipeClose — they give you support for running a whole entire process at the end of a pipe 🎀

---

🌸 C SYNOPSIS 🌸

#include "pmapi.h"
#include "libpcp.h"

int __pmProcessPipe(__pmExecCtl_t **handle, const char *type, int toss,
                    FILE **fp);
int __pmProcessPipeClose(FILE *fp);

cc ... -lpcp

---

🚨 CAVEAT 🚨

heads up bestie, this one's for the internal girlies only — this documentation is intended for internal Performance Co-Pilot (PCP) developer use.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future. so like… it's giving "trust me but also don't @ me" 😭

---

💅 DESCRIPTION 💅

so within the libraries and applications of the Performance Co-Pilot (PCP), these routines are a convenient and safe alternative to popen(3) and pclose(3) for executing commands in a separate process that's connected to the caller by a pipe. iconic behaviour honestly 👑

Setting up the command and the arguments is fully documented over in __pmProcessAddArg(3), and it's identical to the procedure you use to set up __pmProcessExec(3). same vibe, same steps, no cap ✨

Once all the command name and arguments have been registered, calling __pmProcessPipe uses a pipe(2), fork(2) and execvp(2) sequence to actually execute the command. the whole trifecta fr fr 🔥

The type argument needs to be `r` to read from the pipe, else `w` to write to the pipe. pick your fighter 🎀

The argument toss may be used to assign some or all of the standard I/O streams for the command to /dev/null — specifically toss is either PM_EXEC_TOSS_NONE to keep all I/O streams the same as the parent process, else the bit-wise or of PM_EXEC_TOSS_STDIN and/or PM_EXEC_TOSS_STDOUT and/or PM_EXEC_TOSS_STDERR to reassign stdin, stdout and stderr respectively. and PM_EXEC_TOSS_ALL is a convenience macro equivalent to PM_EXEC_TOSS_STDIN | PM_EXEC_TOSS_STDOUT | PM_EXEC_TOSS_STDERR. the way that's just a lil shortcut macro… obsessed 🦋

Obviously some combinations of argument values make no sense, e.g. type equal to `r` and PM_EXEC_TOSS_STDOUT set in toss, or type equal to `w` and PM_EXEC_TOSS_STDIN set in type. like girl what are you doing 💀

__pmProcessPipe returns a standard I/O stream for the pipe via the fp argument. cute 🎀

Once the caller determines all the work has been done, __pmProcessPipeClose should be called. that's your lil goodbye kiss 🫶

Nested calling of __pmProcessExec(3) and/or __pmProcessPipe is not allowed. Once __pmProcessAddArg(3) is called with handle set to NULL to start the registration and execution sequence, any attempt to start a second registration sequence will be blocked until the first one is completed by calling __pmProcessExec(3) or __pmProcessPipe. one at a time bestie, main character energy only 🧚

__pmProcessPipe will release any storage allocations prior to return, so there's no need for the caller to worry about memory leaks. we love a clean girlie who cleans up after herself ✨

---

🌈 DIAGNOSTICS 🌈

If successful, __pmProcessPipe returns 0. Other conditions are rare (e.g. memory allocation failure) and are indicated by a return value that can be decoded using pmErrStr(3). 🍓

The return status from __pmProcessPipeClose is a little more complicated. buckle up:

• If the command completes with an exit status of 0, the return value is 0. 🎉
• Return values less than 0 indicate a more serious error and the value can be decoded using pmErrStr(3). 😭
• If the command was executed, but did not exit with status of 0, then the return value is an encoding of the waitpid(2) status as follows: 2000 if something unknown went wrong, else 1000 + signal number if the command was killed or stopped by a signal, else the exit status of the command. 💀

---

⭐ SEE ALSO ⭐

execvp(2), fork(2), pclose(2), pipe(2), popen(2), __pmProcessAddArg(3), __pmProcessExec(3) and waitpid(3). go read those too bestie, iykyk 💜

---

and that's the whole page!! this one came from Performance Co-Pilot / PCP, page PMPROCESSPIPE(3) — mwah, slay, periodt 💅✨🎀