NAME
run, runv, runp, runvp, runc, runcv, runcp, runcvp - execute
process and wait for it

SYNOPSIS
int run (file,arg0,arg1,arg2,...,argn,0);
int runv (file,arglist);
int runp (file,arg0,arg1,arg2,...,argn,0);
int runvp (file,arglist);
char *file,*arg1,*arg2,...,*argn,**arglist;

int runc (func,file,arg0,arg1,arg2,...,argn,0);
int runcv (func,file,arglist);
int runcp (func,file,arg0,arg1,arg2,...,argn,0);
int runcvp (func,file,arglist);
int (*func)();
char *file,*arg1,*arg2,...,*argn,**arglist;

DESCRIPTION
Run and runv have argument lists identical to the corresponding
functions, execl(2) and execp(2). The run routines perform a
vfork(2), then:

In the new process:
setgid(2) and setuid(2) are used to ensure that privileges
unique to the parent do not propagate to the child. An execl
or execv is then performed with the specified arguments. The
process returns with a -1 code if the exec was not successful.

In the parent process:
the signals SIGQUIT (see signal(2)) and SIGINT are disabled,
the process waits (see wait(2)) until the newly forked process
exits, the signals are restored to their original status, and
the return status of the process is analyzed.

Run and runv return -1 if vfork(2) or exec(2) fail or the child was
terminated by a signal; the exit code of the process otherwise.

Runp and runvp are identical to run and runv, but perform path
searching for the process by using execlp and execvp. These
routines use the PATH environment parameter as a list of directory
names separated by colons; the executable file is sought in each
directory until it is found or all directories have been searched.
If the file is not found, -1 is returned.

The proper way to execute system programs is via runp or runvp for
most purposes; for example, if you want to move file "a" to "b",
the best way to do this via system programs is this:

runp ("mv","mv","a","b",0);

Note that no directory name is needed along with the name of the
file (e.g. /bin/mv is not necessary), and that the program name
should be both file and arg0. This call is similar to:
system ("mv a b");
but is much faster to execute.

Runc, runcp, runcv, and runcvp function analogously to their
similarly named counterparts described above. However, they also
invoke the specified function func in the context of the child
process in order to first perform any application specific
initialization that may be needed before attempting to execute the
program. If func is null, these routines are identical to their
simpler counterparts.

The use of setgid and setuid means that, if the parent process
gained privileges through the use of special file mode bits (see
chmod(2)), the child process will not inherit these privileges.
This makes run "safe" for system programs which require special
privileges, and usually has no effect on user programs.

ENVIRONMENT
The PATH environment parameter is used to find executable files in
runp and runvp. If this parameter is not present, then the default
value :/bin:/usr/bin is used.

SEE ALSO
exec(2), vfork(2), signal(2), system(3), searchp(3)

DIAGNOSTICS
These routines return -1 if any error occurs in executing the
desired program. If the program is executed successfully,
convention dictates that it should return 0 on normal completion
and non-zero (1, 2, etc.) if any error is encountered.

BUGS
The searching rule used by execlp and execvp is not the same as the
rule used by searchp. See the comments in searchp(3) for more
detailed information.