PMPROCESSEXEC(3)

💖 PMPROCESSEXEC(3) 💖

okay bestie, welcome to PMPROCESSEXEC(3) from the Library Functions Manual — literally the group chat where PCP talks about running other processes. sit down, hydrate, and let's get into it ✨

---

🌸 NAME 🌸

__pmProcessAddArg, __pmProcessUnpickArgs, __pmProcessExec, __pmProcessFree — process execution support, periodt 👑

---

✨ C SYNOPSIS ✨

like, here's the whole vibe in code form, no cap:

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

int __pmProcessAddArg(__pmExecCtl_t **handle, const char *arg);
int __pmProcessUnpickArgs(__pmExecCtl_t **handle, const char *command);
int __pmProcessExec(__pmExecCtl_t **handle, int toss, int wait);
void __pmProcessFree(__pmExecCtl_t **handle);

cc ... -lpcp

---

🚨 CAVEAT 🚨

okay so real talk for a sec, this one matters:

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. it's giving "we said what we said" — lowkey unstable, highkey on purpose 💀

---

🦋 DESCRIPTION 🦋

so inside the libraries and applications of the Performance Co-Pilot (PCP), these routines are the convenient and safe alternative to system(3) for executing commands in a separate process. iconic behaviour honestly 💅

Use __pmProcessAddArg to register the executable and command arguments, in order. your handle should be set to NULL before the first call to __pmProcessAddArg for a particular command execution, and it'll get set to an opaque pointer to data structures that get manipulated in __pmProcessAddArg, __pmProcessExec and the related __pmProcessPipe(3) routines. she's mysterious, she's opaque, she's the moment ✨

When called with handle set to NULL, arg is treated as the name of the command to be executed, and subsequent calls (if any) are for the arguments to that command. The name of the command can be a full pathname, or the name of an executable that can be found on the current $PATH as per the rules of execvp(2) that is used by __pmProcessExec. so like, $PATH girlies, she's got you 🎀

__pmProcessUnpickArgs is a convenience wrapper to assist conversion of code that assumes the command is a shell command that has been prepared for use with system(3) or popen(3) in existing code. The arguments in command are picked off one-by-one and used to call __pmProcessAddArg. The parser is simple, because the routine is designed for simple shell command syntax — arguments are separated by one or more spaces, but embedded spaces within an argument are allowed if the argument is enclosed in single or double quotes. More advanced shell syntax like escape characters and input-output redirection are not recognized. so don't come at her with your fancy shell tricks, she's a simple girl 🙈

Once all the command name and arguments have been registered, calling __pmProcessExec uses a fork(2) and execvp(2) sequence to execute the command. fork, exec, slay 🔥

The argument toss may be used to assign some or all of the standard I/O streams for the command to /dev/null — specifically:

• PM_EXEC_TOSS_NONE — keep all I/O streams the same as the parent process, no changes, she's staying home 🏠
• or 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. pick your faves 💖
• PM_EXEC_TOSS_ALL — a convenience macro equivalent to PM_EXEC_TOSS_STDIN | PM_EXEC_TOSS_STDOUT | PM_EXEC_TOSS_STDERR. the "all of the above" option, we love a bundle deal 👑

The wait argument should be:

• PM_EXEC_WAIT — if __pmProcessExec should wait for completion of the command and harvest the exit status
• PM_EXEC_NOWAIT — in which case __pmProcessExec returns immediately (effectively running the command in the background). main character energy, she does not wait for anyone 💅

Nested calling of __pmProcessExec and/or __pmProcessPipe(3) is not allowed. Once __pmProcessAddArg 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 or __pmProcessPipe(3). one at a time, bestie, we are not multitasking here 🚫

---

😭 DIAGNOSTICS 😭

If successful, __pmProcessAddArg 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). When an error does occur, __pmProcessAddArg cleans up any allocations made in the current call and uses handle to clean up any allocations made by previous calls — so there is no need for the caller to worry about memory leaks 🧹✨ — and then (re)sets handle to NULL before returning.

__pmProcessUnpickArgs returns 0 on success. In the case of an unterminated string, a message is generated and PM_ERR_GENERIC is returned. Other return values less than 0 indicate a more serious error and the value can be decoded using pmErrStr(3). When an error does occur, the clean up is similar to __pmProcessAddArg, so there is no need for the caller to worry about memory leaks. she tidies up after herself, unlike some people 💀

Similarly, on success __pmProcessExec will release any storage allocations prior to return, so there is no need for the caller to worry about memory leaks.

The one case where the caller may need to clean up memory allocation is after one or more successful calls to __pmProcessAddArg and/or __pmProcessUnpickArgs, if the caller wishes to abandon the sequence — then calling __pmProcessFree will release any storage allocated by these routines and reset handle to NULL. the "never mind, forget I said anything" button 🙈

The return status from __pmProcessExec is more complicated. buckle up:

• If either PM_EXEC_NOWAIT is specified, or 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 if 1000 + signal number if the command was killed or stopped by a signal, else the exit status of the command.

---

👑 SEE ALSO 👑

go read these too, they're all in the same friend group:

execvp(2), fork(2), __pmProcessPipe(3), popen(3), system(3) and waitpid(2).

---

and that's the whole page, bestie 💜 this one came from the Performance Co-Pilot crew, PCP girlies, and it's the PMPROCESSEXEC(3) page fr fr — go forth and exec safely, mwah 🎀✨🦋