usr/src/man/man2/vfork.2

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