.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "VFORK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" vfork 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
vfork \- create a new process; share virtual memory
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
pid_t vfork(void); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIvfork\fP() function shall be equivalent to \fIfork\fP(), except
that the behavior
is undefined if the process created by \fIvfork\fP() either modifies
any data other than a variable of type \fBpid_t\fP used to
store the return value from \fIvfork\fP(), or returns from the function
in which \fIvfork\fP() was called, or calls any other
function before successfully calling \fI_exit\fP() or one of the \fIexec\fP
family of functions.
.SH RETURN VALUE
.LP
Upon successful completion, \fIvfork\fP() shall return 0 to the child
process and return the process ID of the child process to
the parent process. Otherwise, -1 shall be returned to the parent,
no child process shall be created, and \fIerrno\fP shall be set
to indicate the error.
.SH ERRORS
.LP
The \fIvfork\fP() function shall fail if:
.TP 7
.B EAGAIN
The system-wide limit on the total number of processes under execution
would be exceeded, or the system-imposed limit on the
total number of processes under execution by a single user would be
exceeded.
.TP 7
.B ENOMEM
There is insufficient swap space for the new process.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
Conforming applications are recommended not to depend on \fIvfork\fP(),
but to use \fIfork\fP() instead. The \fIvfork\fP() function may be
withdrawn in a future version.
.LP
On some implementations, \fIvfork\fP() is equivalent to \fIfork\fP().
.LP
The \fIvfork\fP() function differs from \fIfork\fP() only in that
the child process can
share code and data with the calling process (parent process). This
speeds cloning activity significantly at a risk to the
integrity of the parent process if \fIvfork\fP() is misused.
.LP
The use of \fIvfork\fP() for any purpose except as a prelude to an
immediate call to a function from the \fIexec\fP family, or to \fI_exit\fP(),
is not advised.
.LP
The \fIvfork\fP() function can be used to create new processes without
fully copying the address space of the old process. If a
forked process is simply going to call \fIexec\fP, the data space
copied from the parent to
the child by \fIfork\fP() is not used. This is particularly inefficient
in a paged
environment, making \fIvfork\fP() particularly useful. Depending upon
the size of the parent's data space, \fIvfork\fP() can give
a significant performance improvement over \fIfork\fP().
.LP
The \fIvfork\fP() function can normally be used just like \fIfork\fP().
It does not work,
however, to return while running in the child's context from the caller
of \fIvfork\fP() since the eventual return from
\fIvfork\fP() would then return to a no longer existent stack frame.
Care should be taken, also, to call \fI_exit\fP() rather than \fIexit\fP()
if \fIexec\fP cannot be used, since \fIexit\fP() flushes and closes
standard I/O channels, thereby damaging the parent process' standard
I/O data structures. (Even with \fIfork\fP(), it is wrong to call
\fIexit\fP(), since buffered
data would then be flushed twice.)
.LP
If signal handlers are invoked in the child process after \fIvfork\fP(),
they must follow the same rules as other code in the
child process.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
This function may be withdrawn in a future version.
.SH SEE ALSO
.LP
\fIexec\fP(), \fIexit\fP(), \fIfork\fP(), \fIwait\fP(), the Base
Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<unistd.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .