SFORK(2) BSD Programmer's Manual SFORK(2)NAMEsfork - create a child process that shares resources with a parent pro-
cess
SYNOPSIS
#include <sys/sfork.h>
#include <signal.h>
int
sfork(int flags, void *stack, int sig);
DESCRIPTION
The sfork() system call creates a ``child'' process that copies or shares
most of its state from the current ``parent'' process. The amount of
sharing is controlled by the flags parameter as follows:
SF_MEM Share virtual memory. Any change to any memory object in
the parent or child will be visible to the other process.
This sharing includes the standard data, heap and stack seg-
ments as well as memory mappings created using mmap(2).
SF_CRED Share process credentials. User ID (setuid(2)), group ID
membership (setgroups(2)), and set-UID information
(seteuid(2)) are shared between parent and child. For ex-
ample, a successful setuid(2) in the child that changes the
child's user ID will also change the parent's user ID.
SF_DESCRIP Share file descriptor information. Parent and child share
their file descriptor table (open(2)), current directory
(chdir(2)), root directory (chroot(2)), file creation mask
(umask(2)) and file descriptor flags (fcntl(2)). Note that
file status flags, as opposed to file descriptor flags, are
always shared for descriptors that are open when sfork() is
called, as are file status features like file offsets
(lseek(2)).
SF_RLIM Share resource limits (setrlimit(2)).
SF_SIG Share most (but not all) signal state. The shared signal
information includes all of the state controlled by
sigaction(2):
o set of ignored signals
o set of caught signals
o signal actions
o set of signals to take on an alternate stack
o set of signals that interrupt system calls
Note that the following signal information is never shared:
o set of blocked signals (sigprocmask(2))
o set of pending signals (sigpending(2))
o location of alternate signal stack (sigaltstack(2))
o signal sent to parent on exit
The convenience flag SF_SHARE_ALL selects all sharable features. Note
that process state that is not shared is either copied from the parent to
the child or is set uniquely in the child.
The flags parameter also may specify the SF_WAITCHILD flag, which forces
the parent process to wait until the child process has either called ex-
ecve(2) or exited. If the child is likely to call execve(2) and the par-
ent is likely to call wait(2) to wait for it, then using SF_WAITCHILD to
serialize their actions can avoid problems with synchronization (see be-
low).
The stack parameter may specify an alternate stack location for the child
process. The memory for this stack segment should be allocated before
calling sfork(). If the child process should run on its parent's stack,
then you may specify the stack parameter as NULL. You should always use
SF_WAITCHILD if the parent and child both expect to use the same stack.
(See the vfork(2) manual page for information about the difficulties with
sharing stacks.)
The sig parameter provides the number of the signal that the child will
automatically send to its parent when it exits (sigaction(2)). You may
specify 0 to indicate that no signal should be sent. Processes conven-
tionally send SIGCHLD to their parent process on exit. Processes that
become children of the init(8) process are silently modified to send
SIGCHLD on exit.
On success, the sfork() function returns 0 in the child process and re-
turns the value of the child's process ID in the parent process. On
failure, the sfork() function returns -1 and sets the global variable
errno to indicate the error.
Calling the fork(2) function is identical to calling:
sfork(0, NULL, SIGCHLD)
Calling the vfork(2) function is identical to calling:
sfork(SF_MEM|SF_WAITCHILD, NULL, SIGCHLD)
ERRORS
The sfork() function will fail and no child process will be created if:
[EAGAIN] The system-imposed limit on the total number of processes under
execution would be exceeded. This limit is configuration-de-
pendent.
[EAGAIN] The system-imposed RLIMIT_NPROC resource limit on the total
number of processes under execution by the invoking user would
be exceeded. See setrlimit(2).
[ENOMEM] There is insufficient swap space for the new process.
SEE ALSOexecve(2), wait(2).
BUGS
This interface is tentative and may change in future releases.
There is no machine-independent way to set up a stack for the child pro-
cess. In particular, the stack may grow in different directions on dif-
ferent architectures, or it may require different alignments.
September 14, 2000 2