RFORK(2,L) AIX Technical Reference RFORK(2,L)
-------------------------------------------------------------------------------
rfork
PURPOSE
Creates a new process on another site.
SYNTAX
#include <sys/types.h>
pid_t rfork (site_number)
siteno_t site_number;
DESCRIPTION
The rfork system call is only available with the Transparent Computing
Facility. The rfork system call is comparable to the fork system call, except
that it allows a site to be specified on which the child process is created.
If site_number is 0, the child is created locally.
The rfork system call causes the creation of a new process. The new process
(child process) is an exact copy of the calling process (parent process). This
means the child process inherits the following attributes from the parent
process:
o Environment
o Close-on-exec flag (see "exec: execl, execv, execle, execve, execlp,
execvp")
o Signal handling settings (that is, SIG_DFL, SIG_IGN, function address)
o Signal mechanism new/old status (see "sigaction, sigvec, signal")
o Set-user-ID and set-group-ID mode bits (see "setxuid")
o Profiling on/off status
o Nice value (see "getpriority, setpriority, nice")
o All attached shared memory segments
Note: If there are any shared memory segments, rfork fails unless the
child process's site is the same as the parent's site.
o Process group ID
o Session ID
Processed November 7, 1990 RFORK(2,L) 1
RFORK(2,L) AIX Technical Reference RFORK(2,L)
o TTY group ID (see "exit, _exit" and "sigaction, sigvec, signal")
o Current working directory
o Root directory
o <LOCAL> alias path name (see "getlocal, setlocal")
o File mode creation mask (see "umask")
o System resource limits (see "getrlimit, setrlimit, vlimit" and "ulimit")
o Site path (see "getspath, setspath")
o Execution site permissions (see "getxperm, setxperm").
The child process differs from the parent process in the following ways:
o The child process has a unique process ID.
o The child process has a different parent process ID (that is, the process
ID of the parent process).
o The child process has its own copy of the parent's file descriptors. Each
of the child process's file descriptors shares a common file pointer with
the corresponding file descriptor of the parent.
o The trace flag is cleared (see "ptrace").
o All semadj values are cleared (see "semop").
o Process locks, text locks, data locks, and file locks are not inherited by
the child process (see "plock" and "fcntl, flock, lockf").
o The child process's utime, stime, cutime, and cstime are set to 0.
o The time left until an alarm clock signal is reset to 0.
Note: Processes may not fork to another site if the destination site has a
different cpu type or if they have too many (85 or more) child
processes. Processes may not use the rfork system call to create a new
process on another site if they have made use of shared memory,
semaphores, or message operations.
Processes may not use the rfork system call to create a new process on
another site if they have a file open which is marked as being in error
(for example, if the storage site is not on the network) or if they have
a character device open (other than a terminal or the null device).
RETURN VALUE
Upon successful completion, rfork returns a value of 0 to the child process and
returns the process ID of the child process to the parent process. Otherwise,
Processed November 7, 1990 RFORK(2,L) 2
RFORK(2,L) AIX Technical Reference RFORK(2,L)
a value of -1 is returned to the parent process, no child process is created,
and errno is set to indicate the error.
ERROR CONDITIONS
The rfork system call fails and no child processes are created if one or more
of the following are true:
EAGAIN The user is the superuser, and the system-imposed limit on the total
number of processes under execution on the remote site would be
exceeded.
EAGAIN The user is the not superuser, and the system-imposed limit on the
total number of processes under execution by a single user on the
remote site would be exceeded.
EBADST site_number is out of range or the destination site is not the same
CPU type as the current site.
EPERM Execute permission is not granted for site_number.
ESITEDN1 The operation failed because a required site is unavailable.
ESITEDN2 The operation was terminated because a site failed.
ENOMEM There is not enough space left for this process on the new site.
ETABLE On either the parent's site, the system's PID-site table, which is
used to keep track of remote processes and process groups, is full.
ELOCALONLY
The process may not remote fork because it is using semaphores,
message queues, and shared memory or it has too many child processes.
ENLDEV The process may not execute on the designated site because one of its
open file descriptors is for a local-only object such as a socket or
a non-tty character special file.
ENOSTORE The current load module cannot be located from site sitenumber
because it has been deleted or superceded by a new version.
RELATED INFORMATION
In this book: "semop," "exec: execl, execv, execle, execve, execlp, execvp,"
"fork, vfork," "getlocal, setlocal," "getpriority, setpriority, nice,"
"getrlimit, setrlimit, vlimit," "getspath, setspath," "getxperm, setxperm,"
"migrate," "plock," "ptrace," "rexec: rexecl, rexecv, rexecle, rexecve,
rexeclp, rexecvp," "run: runl, runv, runle, runve, runlp, runvp,"
"sigaction, sigvec, signal," "times," "ulimit," "umask," "wait, waitpid,"
and "wait3."
Processed November 7, 1990 RFORK(2,L) 3