1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   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.
   5 .\" All rights reserved.  The Berkeley software License Agreement
   6 .\" specifies the terms and conditions for redistribution.
   7 .Dd Aug 20, 2014
   8 .Dt VFORK 2
   9 .Os
  10 .Sh NAME
  11 .Nm vfork ,
  12 .Nm vforkx
  13 .Nd spawn new process in a virtual memory efficient way
  14 .Sh SYNOPSIS
  15 .In unistd.h
  16 .Ft pid_t
  17 .Fn vfork void
  18 .
  19 .In sys/fork.h
  20 .Ft pid_t
  21 .Fn vforkx "int flags"
  22 .Sh DESCRIPTION
  23 The
  24 .Fn vfork
  25 and
  26 .Fn vforkx
  27 functions create a new process without
  28 fully copying the address space of the old process. These functions are useful
  29 in instances where the purpose of a
  30 .Xr fork 2
  31 operation is to create a new
  32 system context for an
  33 .Xr exec 2
  34 operation.
  35 .Lp
  36 Unlike with the
  37 .Fn fork
  38 function, the child process borrows the parent's
  39 memory and thread of control until a call to
  40 .Fn execve
  41 or an exit
  42 .Pq either abnormally or by a call to Xr _exit 2 .
  43 Any modification
  44 made during this time to any part of memory in the child process is reflected
  45 in the parent process on return from
  46 .Fn vfork
  47 or
  48 .Fn vforkx .
  49 The parent process is suspended while the child is using its resources.
  50 .Lp
  51 In a multithreaded application,
  52 .Fn vfork
  53 and
  54 .Fn vforkx
  55 borrow only the thread of control that called
  56 .Fn vfork
  57 or
  58 .Fn vforkx
  59 in the parent; that is, the child contains only one thread. The use of
  60 .Fn vfork
  61 or
  62 .Fn vforkx
  63 in multithreaded applications, however, is unsafe due to race
  64 conditions that can cause the child process to become deadlocked and
  65 consequently block both the child and parent process from execution
  66 indefinitely.
  67 .Lp
  68 The
  69 .Fn vfork
  70 and
  71 .Fn vforkx
  72 functions can normally be used the same way as
  73 .Fn fork
  74 and
  75 .Fn forkx ,
  76 respectively. The calling procedure,
  77 however, should not return while running in the child's context, since the
  78 eventual return from
  79 .Fn vfork
  80 or
  81 .Fn vforkx
  82 in the parent would be to
  83 a stack frame that no longer exists. The
  84 .Fn _exit
  85 function should be used
  86 in favor of
  87 .Xr exit 3C
  88 if unable to perform an
  89 .Fn execve
  90 operation, since
  91 .Fn exit
  92 will invoke all functions registered by
  93 .Xr atexit 3C
  94 and will flush and close standard I/O channels, thereby corrupting the parent
  95 process's standard I/O data structures. Care must be taken in the child process
  96 not to modify any global or local data that affects the behavior of the parent
  97 process on return from
  98 .Fn vfork
  99 or
 100 .Fn vforkx ,
 101 unless such an effect
 102 is intentional.
 103 .Lp
 104 Unlike
 105 .Fn fork
 106 and
 107 .Fn forkx ,
 108 fork handlers are not run when
 109 .Fn vfork
 110 and
 111 .Fn vforkx
 112 are called.
 113 .Lp
 114 The
 115 .Fn vfork
 116 and
 117 .Fn vforkx
 118 functions are deprecated. Their sole
 119 legitimate use as a prelude to an immediate call to a function from the
 120 .Xr exec 2
 121 family can be achieved safely by
 122 .Xr posix_spawn 3C
 123 or
 124 .Xr posix_spawnp 3C .
 125 .Ss "Fork Extensions"
 126 The
 127 .Fn vforkx
 128 function accepts a
 129 .Fa flags
 130 argument consisting of a
 131 bitwise inclusive-OR of zero or more of the following flags, which are defined
 132 in the header
 133 .In sys/fork.h :
 134 .Lp
 135 .Bl -item -compact -offset indent
 136 .It
 137 .Dv FORK_NOSIGCHLD
 138 .It
 139 .Dv FORK_WAITPID
 140 .El
 141 .Lp
 142 See
 143 .Xr fork 2
 144 for descriptions of these flags. If the
 145 .Fa flags
 146 argument is 0,
 147 .Fn vforkx
 148 is identical to
 149 .Fn vfork .
 150 .Sh RETURN VALUES
 151 Upon successful completion,
 152 .Fn vfork
 153 and
 154 .Fn vforkx
 155 return 0 to
 156 the child process and return the process ID of the child process to the parent
 157 process. Otherwise, \(mi1 is returned to the parent process, no child
 158 process is created, and
 159 .Va errno
 160 is set to indicate the error.
 161 .Sh ERRORS
 162 The
 163 .Fn vfork
 164 and
 165 .Fn vforkx
 166 functions will fail if:
 167 .Bl -tag -width Er
 168 .It Er EAGAIN
 169 The system-imposed limit on the total number of processes under execution
 170 (either system-quality or by a single user) would be exceeded. This limit is
 171 determined when the system is generated.
 172 .
 173 .It Er ENOMEM
 174 There is insufficient swap space for the new process.
 175 .El
 176 .Lp
 177 The
 178 .Fn vforkx
 179 function will fail if:
 180 .Bl -tag -width Er
 181 .It Er EINVAL
 182 The
 183 .Va flags
 184 argument is invalid.
 185 .El
 186 .Sh INTERFACE STABILITY
 187 The
 188 .Fn vfork
 189 function is
 190 .Sy Obsolete Standard .
 191 .Lp
 192 The
 193 .Fn vforkx
 194 function is
 195 .Sy Obsolete Uncommitted .
 196 .Sh MT-LEVEL
 197 .Sy Unsafe .
 198 .Sh SEE ALSO
 199 .Xr exec 2 ,
 200 .Xr exit 2 ,
 201 .Xr fork 2 ,
 202 .Xr ioctl 2 ,
 203 .Xr atexit 3C ,
 204 .Xr exit 3C ,
 205 .Xr posix_spawn 3C ,
 206 .Xr posix_spawnp 3C ,
 207 .Xr signal.h 3HEAD ,
 208 .Xr wait 3C ,
 209 .Xr standards 5
 210 .Sh NOTES
 211 To avoid a possible deadlock situation, processes that are children in the
 212 middle of a
 213 .Fn vfork
 214 or
 215 .Fn vforkx
 216 are never sent
 217 .Dv SIGTTOU
 218 or
 219 .Dv SIGTTIN
 220 signals; rather, output or ioctls are allowed and input attempts
 221 result in an
 222 .Dv EOF
 223 indication.
 224 .Lp
 225 To forestall parent memory corruption due to race conditions with signal
 226 handling,
 227 .Fn vfork
 228 and
 229 .Fn vforkx
 230 treat signal handlers in the child
 231 process in the same manner as the
 232 .Xr exec 2
 233 functions: signals set to be
 234 caught by the parent process are set to the default action
 235 .Pq Dv SIG_DFL
 236 in the child process
 237 .Pq see Xr signal.h 3HEAD .
 238 Any attempt to set a signal
 239 handler in the child before
 240 .Fn execve
 241 to anything other than
 242 .Dv SIG_DFL
 243 or
 244 .Dv SIG_IGN
 245 is disallowed and results in setting the handler to
 246 .Dv SIG_DFL .
 247 .Lp
 248 On some systems, the implementation of
 249 .Fn vfork
 250 and
 251 .Fn vforkx
 252 cause
 253 the parent to inherit register values from the child. This can create problems
 254 for certain optimizing compilers if
 255 .In unistd.h
 256 is not included in the source calling
 257 .Fn vfork
 258 or if
 259 .In sys/fork.h
 260 is not included in the
 261 source calling
 262 .Fn vforkx .
 263 .Sh STANDARDS
 264 The
 265 .Fn vfork
 266 function is available in the following compilation environments.  See
 267 .Xr standards 5 .
 268 .Lp
 269 .Bl -bullet -compact
 270 .It
 271 .St -xpg4.2
 272 .It
 273 .St -susv2
 274 .It
 275 .St -susv3
 276 .El
 277 .Lp
 278 It was marked obsolete in
 279 .St -susv3
 280 and removed from
 281 .St -p1003.1-2008 .
 282 .Lp
 283 The
 284 .Fn vforkx
 285 function is a local extension and not available in any strictly
 286 standards-compliant compilation environment.