PROC(3)

💖 PROC(3) — Library Functions Manual 💖

Okay bestie, this is the PROC(3) page from the Library Functions Manual, and it’s giving portable process-control realness. 🫶

✨ NAME ✨

proc — process control routines

🛠️ SYNOPSIS 🛠️

#include <proc.h>

Proc_t* procopen(const char* command, char** argv, char** envv, long* opv, long flags);
int procfree(Proc_t* proc);
int procclose(Proc_t* proc);
int procrun(const char* command, char** argv);

💅 DESCRIPTION 💅

These routines are your portable interface to process creation and execution. They work on systems with fork(2) and exec(2) as well as on systems with only spawnve(2) or spanwveg(3). No cap. ✨

🌸 procopen 🌸

procopen runs command with arguments argv, environment modifications in envv, file descriptor, signal and process group operations in opv and flags in flags.

command is searched for using the PATH environment variable from the calling environment. If command is 0 then the current shell is used (see pathshell(3)). If envv is not 0 then it is a 0 terminated vector of name[=value] strings that are added to the command environment using setenviron(3). If name appears in the parent environment then its value is replaced with the new value. If =value is omitted then name is removed from the child environment. The _ environment variable is set to contain the pathname for command and will appear at the top of the child environment.

If opv is not 0 then it is a 0 terminaled vector of operations to perform. In the following, context is a combination of PROC_FD_CHILD and PROC_FD_PARENT for the child and parent process context respectively. Valid operations are:

• PROC_FD_CLOSE(fd,context) — the file descriptor fd is closed in context.
• PROC_FD_DUP(from,to,context) — the file descriptor from is dup(2)'d into the file descriptor to in context.
• PROC_SIG_DFL(sig) — the signal handler for sig is set to SIG_DFL in the child context.
• PROC_SIG_IGN(sig) — the signal handler for sig is set to SIG_IGN in the child context.
• PROC_SYS_PGRP(pgid) — the child process group is set to pgid. pgid may have the following values:
  • <0 — the child process becomes a session leader.
  • 0 — the child process is in the parent process group.
  • 1 — the child process becomes a process group leader.
  • >1 — the child process joins the process group pgid.
• PROC_SYS_UMASK(mask) — the child process group file creation mask is set to mask.

flags is the inclusive-or of the following:

• PROC_ARGMOD — argv[-1] and argv[0] may be modified. This is an optimization that avoids an environment vector realloc(3) when command is a shell script.
• PROC_BACKGROUND — standard shell & setup is done for the child process.
• PROC_CLEANUP — parent process redirection file descriptors are closed on error.
• PROC_DAEMON — standard daemon setup is done for the child process.
• PROC_ENVCLEAR — the child environment is cleared before envv is added.
• PROC_GID — the child effective group id is set to the real group id.
• PROC_IGNORE — parent pipe errors are ignored.
• PROC_OVERLAY — the current process is overlayed by command if possible (i.e., the fork(2) call is omitted).
• PROC_PARANOID — paranoid: command is searched using the default standard PATH; the child environment variable PATH is set to the default standard; the PROC_GID and PROC_UID modes are set; only /bin/sh is used to execute command if it is a shell script.
• PROC_PRIVELEGED — if the effective user id is 0 then the child real user id is set to 0 and the child real group id is set to the effective group id.
• PROC_READ — proc.rfd is connected to command's standard output.
• PROC_SESSION — the child process becomes a session group leader. (Equivalent to the opv entry PROC_SYS_PGRP(-1).)
• PROC_UID — the child effective user id is set to the real user id.
• PROC_WRITE — proc.wfd is connected to command’s standard input.

🦋 The returned struct 🦋

The return value is a pointer to a structure with the following members:

• pid_t pid — the child process id.
• pid_t pgrp — the child process group.
• int rfd — a read file descriptor connected to command's standard output.
• int wfd — a write file descriptor connected to command's standard input.

If an error occurs then 0 is returned.

🎀 procclose 🎀

procclose waits for the process proc to complete and then closes the command stream proc. The command exit status is returned. -1 is returned if the child portion of procopen failed.

🧚 procfree 🧚

procfree frees the process stream without waiting for command to complete. Presumably some other mechanism will be used to wait for proc.pid.

👑 procrun 👑

procrun combines procopen and procclose with the flags PROC_GID|PROC_UID and returns the command exit status.

👀 SEE ALSO 👀

• popen(3)
• sfpopen(3)
• spawnveg(3)
• system(3)

---

💖 that’s the whole page, bestie — the footer just repeats PROC(3), with no extra source/version or date tea to spill, so consider this your cute sign-off. 🎀✨