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 provide a 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).

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 discriptors 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 commands's standard input.

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 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 frees the process stream without waiting for command to complete. Presumably some other mechanism will be used to wait for proc.pid.

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)