RFORK(2)                  OpenBSD Programmer's Manual                 RFORK(2)

NAME
     rfork - control new processes

SYNOPSIS
     #include <sys/param.h>
     #include <unistd.h>

     int
     rfork(int flags);

DESCRIPTION
     The fork functions (fork(2), vfork(2), and rfork()) create new processes.
     The new process (child process) is an exact copy of the calling process
     (parent process), except as outlined in the fork(2) manual page.  rfork()
     is used to manipulate the resources of the parent process and the child
     process.

     Operations currently supported include whether to copy or share the file
     descriptor table between the two processes, whether to share the address
     space, and whether the parent should wait(2) for the child process to
     _exit(2).  rfork() takes a single argument, flags, which controls which
     of these resources should be manipulated.  They are defined in the header
     file <sys/param.h> and are the logical OR of one or more of the
     following:

     RFFDG     Copy the parent's file descriptor table.  If this flag is
               unset, the parent and child will share the parent's file
               descriptor table.  Descriptors will remain in existence until
               they are closed by all child processes using the table copies
               as well as by the parent process.  May not be used in
               conjunction with RFCFDG.

     RFPROC    Create a new process.  The current implementation requires this
               flag to always be set.

     RFMEM     Force sharing of the entire address space between the parent
               and child processes.  The child will then inherit all the
               shared segments the parent process owns.  Subsequent forks by
               the parent will then propagate the shared data and BSS segments
               among children.

     RFNOWAIT  Child processes will have their resources reaped immediately
               and implicitly when they terminate instead of turning into
               zombies, so the parent process may not call wait(2) to collect
               their exit statuses and have their resources released
               explicitly.

     RFCFDG    Zero the child's file descriptor table (i.e. start with a blank
               file descriptor table).  May not be used in conjunction with
               RFFDG.

     RFTHREAD  Create a kernel thread in the current process instead of a
               separate process.  Must be combined with RFMEM.  Automatically
               enables RFNOWAIT.  The kern.rthreads sysctl must be enabled for
               this to succeed.

     fork(2) can be implemented as a call to rfork() using "RFFDG|RFPROC", but
     isn't for backwards compatibility.  If a process has file descriptor
     table sharing active, setuid or setgid programs will not execve(2) with
     extra privileges.

RETURN VALUES
     The parent process returns the process ID (PID) of the child process.
     The child process returns 0.  The range of the process ID is defined in
     <sys/proc.h> and is currently between 1 and 32766, inclusive.

ERRORS
     rfork() will fail and no child process will be created if:

     [ENOMEM]      Cannot allocate memory.  The new process image required
                   more memory than was allowed by the hardware or by system-
                   imposed memory management constraints.  A lack of swap
                   space is normally temporary; however, a lack of core is
                   not.  Soft limits may be increased to their corresponding
                   hard limits.

     [EINVAL]      Invalid argument.  Some invalid argument was supplied.

     [EAGAIN]      Resource temporarily unavailable.  The system-imposed limit
                   on the total number of processes under execution would be
                   exceeded.  This limit is configuration-dependent.

     [EAGAIN]      Resource temporarily unavailable.  The system-imposed limit
                   MAXUPRC on the total number of processes under execution by
                   a single user would be exceeded.  MAXUPRC is currently
                   defined in <sys/param.h> as CHILD_MAX, which is currently
                   defined as 80 in <sys/syslimits.h>.

     [ENOTSUP]     The RFTHREAD flag was set but the kern.rthreads sysctl was
                   not enabled.

SEE ALSO
     _exit(2), execve(2), fork(2), intro(2), vfork(2)

HISTORY
     The rfork() function first appeared in Plan 9.

BUGS
     RFTHREAD cannot be used from C, as the two threads would return on the
     same stack.

OpenBSD 4.9                      June 29, 2010                     OpenBSD 4.9