Print this page
5776 vfork and getwd should not be exposed under XPG7
   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.






























   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.