man/man3/rfork.3

.TH RFORK 3
.SH NAME
rfork \- manipulate process state
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.nf
.B
int rfork(int flags)
.fi
.SH DESCRIPTION
.I Rfork
is a partial implementation of the Plan 9 system call.
It can be used to manipulate some process state and to create
new processes a la 
.IR fork (2).
It cannot be used to create shared-memory processes 
(Plan 9's
.B RFMEM
flag); for that functionality use
.I proccreate
(see 
.IR thread (3)).
.PP
The
.I flags
argument to
.I rfork
selects which resources of the
invoking process (parent) are shared
by the new process (child) or initialized to
their default values.
.I Flags
is the logical OR of some subset of
.TF RFCNAMEG
.TP
.B RFPROC
If set a new process is created; otherwise changes affect the
current process.
.TP
.B RFNOWAIT
If set, the child process will be dissociated from the parent. Upon
exit the child will leave no
.B Waitmsg
(see
.IR wait (3))
for the parent to collect.
.\" .TP
.\" .B RFNAMEG
.\" If set, the new process inherits a copy of the parent's name space;
.\" otherwise the new process shares the parent's name space.
.\" Is mutually exclusive with
.\" .BR RFCNAMEG .
.\" .TP
.\" .B RFCNAMEG
.\" If set, the new process starts with a clean name space. A new
.\" name space must be built from a mount of an open file descriptor.
.\" Is mutually exclusive with
.\" .BR RFNAMEG .
.\" .TP
.\" .B RFNOMNT
.\" If set, subsequent mounts into the new name space and dereferencing
.\" of pathnames starting with
.\" .B #
.\" are disallowed.
.\" .TP
.\" .B RFENVG
.\" If set, the environment variables are copied;
.\" otherwise the two processes share environment variables.
.\" Is mutually exclusive with
.\" .BR RFCENVG .
.\" .TP
.\" .B RFCENVG
.\" If set, the new process starts with an empty environment.
.\" Is mutually exclusive with
.\" .BR RFENVG .
.TP
.B RFNOTEG
Each process is a member of a group of processes that all
receive notes when a note is sent to the group
(see
.IR postnote (3)
and
.IR signal (2)).
The group of a new process is by default the same as its parent, but if
.B RFNOTEG
is set (regardless of
.BR RFPROC ),
the process becomes the first in a new group, isolated from
previous processes.
In Plan 9, a process can call
.B rfork(RFNOTEG)
and then be sure that it will no longer receive console interrupts
or other notes.
Unix job-control shells put each command in its own process group
and then relay notes to the current foreground command, making
the idiom less useful.
.TP
.B RFFDG
If set, the invoker's file descriptor table (see
.IR intro ( ))
is copied; otherwise the two processes share a
single table.
.\" .TP
.\" .B RFCFDG
.\" If set, the new process starts with a clean file descriptor table.
.\" Is mutually exclusive with
.\" .BR RFFDG .
.\" .TP
.\" .B RFREND
.\" If set, the process will be unable to
.\" .IR rendezvous (3)
.\" with any of its ancestors; its children will, however, be able to
.\" .B rendezvous
.\" with it.  In effect,
.\" .B RFREND
.\" makes the process the first in a group of processes that share a space for
.\" .B rendezvous
.\" tags.
.\" .TP
.\" .B RFMEM
.\" If set, the child and the parent will share
.\" .B data
.\" and
.\" .B bss
.\" segments.
.\" Otherwise, the child inherits a copy of those segments.
.\" Other segment types, in particular stack segments, will be unaffected.
.\" May be set only with
.\" .BR RFPROC .
.PD
.PP
File descriptors in a shared file descriptor table are kept
open until either they are explicitly closed
or all processes sharing the table exit.
.PP
If
.B RFPROC
is set, the
value returned in the parent process
is the process id
of the child process; the value returned in the child is zero.
Without
.BR RFPROC ,
the return value is zero.
Process ids range from 1 to the maximum integer
.RB ( int )
value.
.I Rfork
will sleep, if necessary, until required process resources are available.
.PP
Calling
.B rfork(RFFDG|RFPROC)
is equivalent to calling
.IR fork (2).
.SH SOURCE
.B \*9/src/lib9/rfork.c
.SH DIAGNOSTICS
.I Rfork
sets
.IR errstr .