RUN

Section: C Library Functions (3)
Updated: 2/1/90
Index Return to Main Contents

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);

char *file,*arg1,*arg2,...,*argn,**arglist;
int (*func)();

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)failorthechildwasterminated 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:

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 analagously 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 :/usr/cs/bin:/bin:/usr/bin is used.

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.

This document was created by man2html, using the manual pages.
Time: 12:50:27 GMT, May 26, 2025

RUN