path: root/lib/libc/sys/rfork.2

.\"	$OpenBSD: rfork.2,v 1.25 2010/06/29 17:54:35 tedu Exp $
.\"
.\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 29 2010 $
.Dt RFORK 2
.Os
.Sh NAME
.Nm rfork
.Nd control new processes
.Sh SYNOPSIS
.Fd #include <sys/param.h>
.Fd #include <unistd.h>
.Ft int
.Fn rfork "int flags"
.Sh DESCRIPTION
The fork functions
.Po
.Xr fork 2 ,
.Xr vfork 2 ,
and
.Fn rfork
.Pc
create new processes.
The new process
.Pq child process
is an exact copy of the calling process
.Pq parent process ,
except as outlined in the
.Xr fork 2
manual page.
.Fn rfork
is used to manipulate the resources of the parent process and the
child process.
.Pp
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
.Xr wait 2
for the child process to
.Xr _exit 2 .
.Fn rfork
takes a single argument,
.Fa flags ,
which controls which of these resources should be manipulated.
They are defined in the header file
.Aq Pa sys/param.h
and are the logical OR of one or more of the following:
.Bl -tag -width "RFNOWAIT"
.\" .It Dv RFNAMEG
.\" New Plan 9
.\" .Sq name space .
.\" This is a Plan 9 specific flag, and is not implemented.
.\" .It Dv RFENVG
.\" Copy Plan 9
.\" .Sq env space .
.\" This is a Plan 9 specific flag, and is not implemented.
.It Dv 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
.Dv RFCFDG .
.\" .It Dv RFNOTEG
.\" Create new Plan 9
.\" .Sq note group .
.\" This is a Plan 9 specific flag, and is not implemented.
.It Dv RFPROC
Create a new process.
The current implementation requires this flag to always be set.
.It Dv 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.
.It Dv 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
.Xr wait 2
to collect their exit statuses and have their resources released
explicitly.
.\" .It Dv RFCNAMEG
.\" Zero Plan 9
.\" .Sq name space .
.\" This is a Plan 9 specific flag, and is not implemented.
.\" .It Dv RFCENVG
.\" Zero Plan 9
.\" .Sq env space .
.\" This is a Plan 9 specific flag, and is not implemented.
.It Dv RFCFDG
Zero the child's file descriptor table
.Pq i.e. start with a blank file descriptor table .
May not be used in conjunction with
.Dv RFFDG .
.It Dv RFTHREAD
Create a kernel thread in the current process instead of a separate
process.
Must be combined with
.Dv RFMEM .
Automatically enables
.Dv RFNOWAIT .
The kern.rthreads sysctl must be enabled for this to succeed.
.El
.Pp
.Xr fork 2
can be implemented as a call to
.Fn 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
.Xr execve 2
with extra privileges.
.Sh RETURN VALUES
The parent process returns the process ID
.Pq PID
of the child process.
The child process returns 0.
The range of the process ID is defined in
.Aq Pa sys/proc.h
and is currently between 1 and 32766, inclusive.
.Sh ERRORS
.Fn rfork
will fail and no child process will be created if:
.Bl -tag -width Er
.It Bq Er 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.
.It Bq Er EINVAL
Invalid argument.
Some invalid argument was supplied.
.It Bq Er EAGAIN
Resource temporarily unavailable.
The system-imposed limit on the total
number of processes under execution would be exceeded.
This limit is configuration-dependent.
.It Bq Er EAGAIN
Resource temporarily unavailable.
The system-imposed limit
.Dv MAXUPRC
on the total number of processes under execution by a single user would be
exceeded.
.Dv MAXUPRC
is currently defined in
.Aq Pa sys/param.h
as
.Dv CHILD_MAX ,
which is currently defined as 80 in
.Aq Pa sys/syslimits.h .
.It Bq Er ENOTSUP
The
.Dv RFTHREAD
flag was set but the kern.rthreads sysctl was not enabled.
.El
.Sh SEE ALSO
.Xr _exit 2 ,
.Xr execve 2 ,
.Xr fork 2 ,
.Xr intro 2 ,
.Xr vfork 2
.Sh HISTORY
The
.Fn rfork
function first appeared in Plan 9.
.Sh BUGS
.Dv RFTHREAD
cannot be used from C, as the two threads would return on the same stack.