.fp 5 CW

.de Af

.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2

.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"

..

.de aF

.ie \\$3 .ft \\$1

.el \{\

.ds ;G \&

.nr ;G \\n(.f

.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"

\\*(;G

.ft \\n(;G \}

..

.de L

.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"

..

.de LR

.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"

..

.de RL

.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"

..

.de EX \" start example

.ta 1i 2i 3i 4i 5i 6i

.PP

.RS

.PD 0

.ft 5

.nf

..

.de EE \" end example

.fi

.ft

.PD

.RE

.PP

..

.TH PROC 3

.SH NAME

proc \- process control routines

.SH SYNOPSIS

.EX

#include <proc.h>

Proc_t* procopen(const char* \fIcommand\fP, char** \fIargv\fP, char** \fIenvv\fP, long* \fIopv\fP, long \fIflags\fP);

int procfree(Proc_t* \fIproc\fP);

int procclose(Proc_t* \fIproc\fP);

int procrun(const char* \fIcommand\fP, char** \fIargv\fP);

.EE

.SH DESCRIPTION

These routines provide a portable interface to process creation and execution.

They work on systems with

.IR fork (2)

and

.IR exec (2)

as well as on systems with only

.IR spawnve (2)

or

.IR spanwveg (3).

.PP

.L procopen

runs

.I command

with arguments

.IR argv ,

environment modifications in

.IR envv ,

file descriptor, signal and process group operations in

.I opv

and flags in

.IR flags .

.PP

.I command

is searched for using the

.L PATH

environment variable from the calling environment.

If

.I command

is

.L 0

then the current shell is used (see

.IR pathshell (3)).

If

.I envv

is not

.L 0

then it is a

.L 0

terminated vector of

\fIname\fP[=\fIvalue\fP]

strings that are added to the

.I command

environment using

.IR setenviron (3).

If

.I name

appears in the parent environment then its value is replaced with the new

.IR value .

If

.RI = value

is omitted then

.I name

is removed from the child environment.

The

.L _

environment variable is set to contain the pathname for

.I command

and will appear at the top of the child environment.

.PP

If

.I opv

is not

.L 0

then it is a 0 terminaled vector of operations to perform.

In the following

.I context

is a combination of

.L PROC_FD_CHILD

and

.L PROC_FD_PARENT

for the child and parent process context respectively.

Valid operations are:

.TP

\f5PROC_FD_CLOSE(\fIfd\fP,\fIcontext\fP)\fR

The file descriptor

.I fd

is closed in

.IR context .

.TP

\f5PROC_FD_DUP(\fIfrom\fP,\fIto\fP,\fIcontext\fP)\fR

The file descriptor

.I from

is

.IR dup (2)'d

into the file descriptor

.I to

in

.IR context .

.TP

\f5PROC_SIG_DFL(\fIsig\fP)\fR

The signal handler for

.I sig

is set to

.L SIG_DFL

in the child context.

.TP

\f5PROC_SIG_IGN(\fIsig\fP)\fR

The signal handler for

.I sig

is set to

.L SIG_IGN

in the child context.

.TP

\f5PROC_SYS_PGRP(\fIpgid\fP)\fR

The child process group is set to

.IR pgid .

.I pgid

may have the following values:

.TP

.L <0

The child process becomes a session leader.

.TP

.L 0

The child process is in the parent process group.

.TP

.L 1

The child process becomes a process group leader.

.TP

.L >1

The child process joins the process group

.IR pgid .

.TP

\f5PROC_SYS_UMASK(\fImask\fP)\fR

The child process group file creation mask is set to

.IR mask .

.PP

.I flags

is the inclusive-or of the following:

.TP

.L PROC_ARGMOD

.I "argv[-1]"

and

.I "argv[0]"

may be modified.

This is an optimization that avoids an environment vector

.I realloc(3)

when

.I command

is a shell script.

.TP

.L PROC_BACKGROUND

Standard shell

.L &

setup is done for the child process.

.TP

.L PROC_CLEANUP

Parent process redirection file discriptors are closed on error.

.TP

.L PROC_DAEMON

Standard daemon setup is done for the child process.

.TP

.L PROC_ENVCLEAR

The child environment is cleared before

.I envv

is added.

.TP

.L PROC_GID

The child effective group id is set to the real group id.

.TP

.L PROC_IGNORE

Parent pipe errors are ignored.

.TP

.L PROC_OVERLAY

The current process is overlayed by

.I command

if possible

(i.e., the

.IR fork (2)

call is omitted).

.TP

.L PROC_PARANOID

Paranoid:

.I command

is searched using the default standard

.LR PATH ;

the child environment variable

.L PATH

is set to the default standard;

the

.L PROC_GID

and

.L PROC_UID

modes are set;

only

.L /bin/sh

is used to execute

.I command

if it is a shell script.

.TP

.L PROC_PRIVELEGED

If the effective user id is

.L 0

then the child real user id is set to

.L 0

and the child real group id is set to the effective group id.

.TP

.L PROC_READ

.I proc.rfd

is connected to

.IR command 's

standard output.

.TP

.L PROC_SESSION

The child process becomes a session group leader.

(Equivalent to the

.I opv

entry

.LR PROC_SYS_PGRP(-1) .)

.TP

.L PROC_UID

The child effective user id is set to the real user id.

.TP

.L PROC_WRITE

.I proc.wfd

is connected to

.IR commands 's

standard input.

.PP

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

.TP

.L "pid_t \fIpid\fP"

The child process id.

.TP

.L "pid_t \fIpgrp\fP"

The child process group.

.TP

.L "int \fIrfd\fP"

A read file descriptor connected to

.IR command 's

standard output.

.TP

.L "int \fIwfd\fP"

A write file descriptor connected to

.IR command 's

standard input.

.PP

If an error occurs then

.L 0

is returned.

.PP

.L procclose

waits for the process

.I proc

to complete and then closes the command stream

.IR proc .

The command exit status is returned.

.L -1

is returned if the child portion of

.L procopen

failed.

.PP

.L procfree

frees the process stream without waiting for

.I command

to complete.

Presumably some other mechanism will be used to wait for

.IR proc.pid .

.PP

.L procrun

combines

.L procopen

and

.L procclose

with the flags

.L PROC_GID|PROC_UID

and returns the command exit status.

.SH "SEE ALSO"

popen(3), sfpopen(3), spawnveg(3), system(3)