1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T.
   4 .\" Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.
   5 .TH VFORK 2 "Dec 13, 2006"
   6 .SH NAME
   7 vfork, vforkx \- spawn new process in a virtual memory efficient way
   8 .SH SYNOPSIS
   9 .LP
  10 .nf
  11 #include <unistd.h>
  12 
  13 \fBpid_t\fR \fBvfork\fR(\fBvoid\fR);
  14 .fi
  15 
  16 .LP
  17 .nf
  18 #include <sys/fork.h>
  19 
  20 \fBpid_t\fR \fBvforkx\fR(\fBint\fR \fIflags\fR);
  21 .fi
  22 
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBvfork()\fR and \fBvforkx()\fR functions create a new process without
  27 fully copying the address space of the old process. These functions are useful
  28 in instances where the purpose of a \fBfork\fR(2) operation is to create a new
  29 system context for an \fBexecve()\fR operation (see \fBexec\fR(2)).
  30 .sp
  31 .LP
  32 Unlike with the \fBfork()\fR function, the child process borrows the parent's
  33 memory and thread of control until a call to \fBexecve()\fR or an exit (either
  34 abnormally or by a call to \fB_exit()\fR (see \fBexit\fR(2)). Any modification
  35 made during this time to any part of memory in the child process is reflected
  36 in the parent process on return from \fBvfork()\fR or \fBvforkx()\fR. The
  37 parent process is suspended while the child is using its resources.
  38 .sp
  39 .LP
  40 In a multithreaded application,  \fBvfork()\fR and \fBvforkx()\fR borrow only
  41 the thread of control that called \fBvfork()\fR or \fBvforkx()\fR in the
  42 parent; that is, the child contains only one thread. The use of \fBvfork()\fR
  43 or \fBvforkx()\fR in multithreaded applications, however, is unsafe due to race
  44 conditions that can cause the child process to become deadlocked and
  45 consequently block both the child and parent process from execution
  46 indefinitely.
  47 .sp
  48 .LP
  49 The \fBvfork()\fR and \fBvforkx()\fR functions can normally be used the same
  50 way as \fBfork()\fR and \fBforkx()\fR, respectively. The calling procedure,
  51 however, should not return while running in the child's context, since the
  52 eventual return from \fBvfork()\fR or \fBvforkx()\fR in the parent would be to
  53 a stack frame that no longer exists. The \fB_exit()\fR function should be used
  54 in favor of \fBexit\fR(3C) if unable to perform an \fBexecve()\fR operation,
  55 since \fBexit()\fR will invoke all functions registered by \fBatexit\fR(3C) and
  56 will flush and close standard I/O channels, thereby corrupting the parent
  57 process's standard I/O data structures. Care must be taken in the child process
  58 not to modify any global or local data that affects the behavior of the parent
  59 process on return from \fBvfork()\fR or \fBvforkx()\fR, unless such an effect
  60 is intentional.
  61 .sp
  62 .LP
  63 Unlike \fBfork()\fR and \fBforkx()\fR, fork handlers are not run when
  64 \fBvfork()\fR and \fBvforkx()\fR are called.
  65 .sp
  66 .LP
  67 The \fBvfork()\fR and \fBvforkx()\fR functions are deprecated. Their sole
  68 legitimate use as a prelude to an immediate call to a function from the
  69 \fBexec\fR family can be achieved safely by \fBposix_spawn\fR(3C) or
  70 \fBposix_spawnp\fR(3C).
  71 .SS "Fork Extensions"
  72 .sp
  73 .LP
  74 The \fBvforkx()\fR function accepts a \fIflags\fR argument consisting of a
  75 bitwise inclusive-OR of zero or more of the following flags, which are defined
  76 in the header \fB<sys/fork.h>\fR:
  77 .br
  78 .in +2
  79 \fBFORK_NOSIGCHLD\fR
  80 .in -2
  81 .br
  82 .in +2
  83 \fBFORK_WAITPID\fR
  84 .in -2
  85 .sp
  86 .LP
  87 See \fBfork\fR(2) for descriptions of these flags. If the \fIflags\fR argument
  88 is 0, \fBvforkx()\fR is identical to \fBvfork()\fR.
  89 .SH RETURN VALUES
  90 .sp
  91 .LP
  92 Upon successful completion, \fBvfork()\fR and \fBvforkx()\fR return  \fB0\fR to
  93 the child process and returns the process ID of the child process to the parent
  94 process. Otherwise, \fB\(mi1\fR is returned to the parent process, no child
  95 process is created, and \fBerrno\fR is set to indicate the error.
  96 .SH ERRORS
  97 .sp
  98 .LP
  99 The \fBvfork()\fR and \fBvforkx()\fR functions will fail if:
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBEAGAIN\fR\fR
 104 .ad
 105 .RS 10n
 106 The system-imposed limit on the total number of processes under execution
 107 (either system-quality or by a single user) would be exceeded. This limit is
 108 determined when the system is generated.
 109 .RE
 110 
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBENOMEM\fR\fR
 115 .ad
 116 .RS 10n
 117 There is insufficient swap space for the new process.
 118 .RE
 119 
 120 .sp
 121 .LP
 122 The \fBvforkx()\fR function will fail if:
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBEINVAL\fR\fR
 127 .ad
 128 .RS 10n
 129 The \fIflags\fR argument is invalid.
 130 .RE
 131 
 132 .SH ATTRIBUTES
 133 .sp
 134 .LP
 135 See \fBattributes\fR(5) for descriptions of the following attributes:
 136 .sp
 137 
 138 .sp
 139 .TS
 140 box;
 141 c | c
 142 l | l .
 143 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 144 _
 145 Interface Stability     Obsolete
 146 _
 147 MT-Level        Unsafe
 148 .TE
 149 
 150 .SH SEE ALSO
 151 .sp
 152 .LP
 153 \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBioctl\fR(2), \fBatexit\fR(3C),
 154 \fBexit\fR(3C), \fBposix_spawn\fR(3C), \fBposix_spawnp\fR(3C),
 155 \fBsignal.h\fR(3HEAD), \fBwait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
 156 .SH NOTES
 157 .sp
 158 .LP
 159 To avoid a possible deadlock situation, processes that are children in the
 160 middle of a \fBvfork()\fR or \fBvforkx()\fR are never sent \fBSIGTTOU\fR or
 161 \fBSIGTTIN\fR signals; rather, output or ioctls are allowed and input attempts
 162 result in an \fBEOF\fR indication.
 163 .sp
 164 .LP
 165 To forestall parent memory corruption due to race conditions with signal
 166 handling, \fBvfork()\fR and \fBvforkx()\fR treat signal handlers in the child
 167 process in the same manner as the \fBexec\fR(2) functions: signals set to be
 168 caught by the parent process are set to the default action (\fBSIG_DFL\fR) in
 169 the child process (see \fBsignal.h\fR(3HEAD)). Any attempt to set a signal
 170 handler in the child before \fBexecve()\fR to anything other than \fBSIG_DFL\fR
 171 or \fBSIG_IGN\fR is disallowed and results in setting the handler to
 172 \fBSIG_DFL\fR.
 173 .sp
 174 .LP
 175 On some systems, the implementation of \fBvfork()\fR and \fBvforkx()\fR cause
 176 the parent to inherit register values from the child. This can create problems
 177 for certain optimizing compilers if \fB<unistd.h>\fR is not included in the
 178 source calling \fBvfork()\fR or if \fB<sys/fork.h>\fR is not included in the
 179 source calling \fBvforkx()\fR.