rfork/minherit glue in libc

man pages adapted from OpenBSD's versions.

1 files changed, 112 insertions, 0 deletions

diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2
new file mode 100644
index 0000000..6158f51
--- /dev/null
+++ b/lib/libc/sys/rfork.2
@@ -0,0 +1,112 @@
+.\"
+.\" This manual page is taken directly from Plan9, and modified to
+.\" describe the actual BSD implementation. Permission for
+.\" use of this page comes from Rob Pike <rob@plan9.att.com>.
+.\"
+.Dd Jan 12, 1996
+.Dt RFORK 2
+.Os
+.Sh NAME
+.Nm rfork
+.Nd manipulate process resources
+.Sh SYNOPSIS
+.Fd #include <unistd.h>
+.Ft int
+.Fn rfork "int flags"
+.Sh DESCRIPTION
+Forking, vforking or rforking is the only way new processes are created.
+The
+.Fa flags
+argument to
+.Fn rfork
+selects which resources of the
+invoking process (parent) are shared
+by the new process (child) or initialized to
+their default values.
+The resources include
+the open file descriptor table (which, when shared, permits processes
+to open and close files for other processes),
+and open files.
+.Fa Flags
+is the logical OR of some subset of
+.Bl -tag -width "RFCNAMEG" -compact -offset indent
+.It RFPROC
+If set a new process is created; otherwise changes affect the
+current process.
+The current implementation requires this flag to always be set.
+.It RFNOWAIT
+If set, the child process will be dissociated from the parent. Upon
+exit the child will not leave a status for the parent to collect.
+See 
+.Xr wait 2 .
+This is not currently implemented.
+.It RFNAMEG, RFCNAMEG, RFENVG, RFCENVG, RFNOTEG
+These are Plan 9 specific flags, and not implemented.
+.It RFFDG
+If set, the invoker's file descriptor table (see
+.Xr intro 2
+) is copied; otherwise the two processes share a
+single table.
+.It RFCFDG
+If set, the new process starts with a clean file descriptor table.
+Is mutually exclusive with
+.Dv RFFDG .
+.It RFMEM
+If set, the kernel will force sharing of the entire address space.
+The child
+will then inherit all the shared segments the parent process owns. Other segment
+types will be unaffected.  Subsequent forks by the parent will then
+propagate the shared data and bss between children.  The stack segment
+is always split.  May be set only with
+.Dv RFPROC .
+.El
+.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
+.Dv 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
+.Dv RFPROC ,
+the return value is zero.
+Process id's range from 1 to the maximum integer
+.Ft ( int )
+value.
+.Fn Rfork
+will sleep, if necessary, until required process resources are available.
+.Pp
+.Fn Fork
+can be implemented as a call to
+.Xr rfork "RFFDG|RFPROC"
+but isn't for backwards compatibility.
+.Sh ERRORS
+.Fn Rfork
+will fail and no child process will be created if:
+.Bl -tag -width Er
+.It Bq Er EAGAIN
+The system-imposed limit on the total
+number of processes under execution would be exceeded.
+This limit is configuration-dependent.
+.It Bq Er EAGAIN
+The system-imposed limit
+.Dv MAXUPRC
+.Pq Aq Pa sys/param.h
+on the total number of
+processes under execution by a single user would be exceeded.
+.It Bq Er ENOMEM
+There is insufficient swap space for the new process.
+.El
+.Sh SEE ALSO
+.Xr intro 2 ,
+.Xr fork 2 ,
+.Xr vfork 2 ,
+.Xr minherit 2
+.Sh HISTORY
+The
+.Fn rfork
+function first appeared in Plan9.