run(2) — AIX PS/2 1.2.1



RUN(2,L)                    AIX Technical Reference                    RUN(2,L)



-------------------------------------------------------------------------------
run: runl, runv, runle, runve, runlp, runvp



PURPOSE

Runs a file.

SYNTAX

#include <sys/types.h>

pid_t runl(path, arg0, arg1, ..., argn, (char *)0, site_number,
   fdmapsize, fdmap)
char *path, *arg0, *arg1, ..., *argn, *fdmap;
siteno_t site_number;
int fdmapsize;

pid_t runv(path, argv, site_number, fdmapsize, fdmap)
char *path, *argv[ ], *fdmap;
siteno_t site_number;
int fdmapsize;

pid_t runle(path, arg0, arg1, ..., argn, (char *)0, envp, site_number,
   fdmapsize, fdmap)
char *path, *arg0, *arg1, ..., *argn, *envp[ ], *fdmap;
siteno_t site_number;
int fdmapsize;

pid_t runve(path, argv, envp, site_number, fdmapsize, fdmap)
char *path, *argv[ ], *envp[ ], *fdmap;
siteno_t site_number;
int fdmapsize;

pid_t runlp(file, arg0, arg1, ..., argn, (char *)0, site_number,
   fdmapsize, fdmap)
char *file, *arg0, *arg1, ..., *argn, *fdmap;
siteno_t site_number;
int fdmapsize;

pid_t runvp(file, argv, site_number, fdmapsize, fdmap)
char *file, *argv[ ], *fdmap;
siteno_t site_number;
int fdmapsize;

DESCRIPTION

The run family of system calls is only available with the Transparent Computing
Facility.  These calls in all their forms create a new process, overlay it with
the named file and transfer to the entry point for that file in the new core
image.  They are essentially combinations of the fork and exec system calls;



Processed November 7, 1990         RUN(2,L)                                   1



RUN(2,L)                    AIX Technical Reference                    RUN(2,L)



however, much of the internal overhead of fork is avoided, providing a more
efficient implementation.  Also, they verify that the exec system call is going
to succeed before the fork system call is attempted.

The new process is created on the site specified by site_number.  If
site_number is 0, the site is chosen using the process's site path (see
"getspath, setspath").

If fdmap is nonzero, it specifies from where each of the child process's file
descriptors will be copied.  The value stored at fdmap[i] specifies which of
the parent's file descriptors (if any) will become the child process's i-th
descriptor.  The child process's i-th descriptor are be closed if any of the
following are true:

  o fdmap[i] is not a valid file descriptor number (-1 is used by convention to
    get a closed descriptor in the child process).

  o fdmap[i] is not an open file descriptor in the parent.

  o fdmap[i] is equal to i, and the close-on-exec flag is set in the parent for
    this file descriptor.

Under no circumstances are the parent's files be affected by this mapping.  If
fdmap is 0, the child process's files are be copied from the parent's as in a
fork call.

The argument fdmapsize specifies the number of files descriptors contained in
the fdmap.  All file descriptors greater than or equal to fdmapsize are copied
from the parent process as is done in a fork call.

See "exec:  execl, execv, execle, execve, execlp, execvp" for details
concerning the arguments to the various forms of run which are analogous to
those of exec.

Note:  Processes may not run on another site if the parent process has too many
       (85 or more) child processes.  Processes may not run on another site if
       the parent process has a file open which is marked as being in error
       (for example, if the storage site is not on the network) or if it has a
       character device open (other than a terminal or the null device).

RETURN VALUE

Upon successful completion, the run family returns the process ID of the child
process to the parent process.  It does not return in the child process; the
child begins execution of the new file.  If an error occurs, a value of (PID_t)
-1 is returned to the parent process, no child process is created (except,
possibly, in the case of ESITEDN2), and errno is set to indicate the error.








Processed November 7, 1990         RUN(2,L)                                   2



RUN(2,L)                    AIX Technical Reference                    RUN(2,L)



ERROR CONDITIONS

The run system calls may fail for any of the reasons listed for the fork and
rexecvp system calls plus:

EFAULT    fdmap points to an illegal address.

EINTR     A signal was caught during the system call.

FILE

/bin/sh Invoked if a shell program is found by runlp or runvp.

RELATED INFORMATION

In this book:  "exec:  execl, execv, execle, execve, execlp, execvp," "fork,
vfork," "getspath, setspath," "getxperm, setxperm," "migrate," "rexec: rexecl,
rexecv, rexecle, rexecve, rexeclp, rexecvp," "rfork," "a.out," and
"environment."




































Processed November 7, 1990         RUN(2,L)                                   3

Museum

Related Articles