lib/libc/sys/vfork.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)vfork.2     8.1 (Berkeley) 6/4/93
  29 .\"
  30 .Dd May 22, 2016
  31 .Dt VFORK 2
  32 .Os
  33 .Sh NAME
  34 .Nm vfork
  35 .Nd create a new process without copying the address space
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In unistd.h
  40 .Ft pid_t
  41 .Fn vfork void
  42 .Sh DESCRIPTION
  43 .Bf -symbolic
  44 Since this function is hard to use correctly from application software,
  45 it is recommended to use
  46 .Xr posix_spawn 3
  47 or
  48 .Xr fork 2
  49 instead.
  50 .Ef
  51 .Pp
  52 The
  53 .Fn vfork
  54 system call
  55 can be used to create new processes without fully copying the address
  56 space of the old process, which is inefficient in a paged
  57 environment.
  58 It is useful when the purpose of
  59 .Xr fork 2
  60 would have been to create a new system context for an
  61 .Xr execve 2 .
  62 The
  63 .Fn vfork
  64 system call
  65 differs from
  66 .Xr fork 2
  67 in that the child borrows the parent process's address space and the
  68 calling thread's stack
  69 until a call to
  70 .Xr execve 2
  71 or an exit (either by a call to
  72 .Xr _exit 2
  73 or abnormally).
  74 The calling thread is suspended while the child is using its resources.
  75 Other threads continue to run.
  76 .Pp
  77 The
  78 .Fn vfork
  79 system call
  80 returns 0 in the child's context and (later) the pid of the child in
  81 the parent's context.
  82 .Pp
  83 Many problems can occur when replacing
  84 .Xr fork 2
  85 with
  86 .Fn vfork .
  87 For example, it does not work to return while running in the child's context
  88 from the procedure that called
  89 .Fn vfork
  90 since the eventual return from
  91 .Fn vfork
  92 would then return to a no longer existent stack frame.
  93 Also, changing process state which is partially implemented in user space
  94 such as signal handlers with
  95 .Xr libthr 3
  96 will corrupt the parent's state.
  97 .Pp
  98 Be careful, also, to call
  99 .Xr _exit 2
 100 rather than
 101 .Xr exit 3
 102 if you cannot
 103 .Xr execve 2 ,
 104 since
 105 .Xr exit 3
 106 will flush and close standard I/O channels, and thereby mess up the
 107 parent processes standard I/O data structures.
 108 (Even with
 109 .Xr fork 2
 110 it is wrong to call
 111 .Xr exit 3
 112 since buffered data would then be flushed twice.)
 113 .Sh RETURN VALUES
 114 Same as for
 115 .Xr fork 2 .
 116 .Sh SEE ALSO
 117 .Xr _exit 2 ,
 118 .Xr execve 2 ,
 119 .Xr fork 2 ,
 120 .Xr rfork 2 ,
 121 .Xr sigaction 2 ,
 122 .Xr wait 2 ,
 123 .Xr exit 3 ,
 124 .Xr posix_spawn 3
 125 .Sh HISTORY
 126 The
 127 .Fn vfork
 128 system call appeared in
 129 .Bx 3 .
 130 .Sh BUGS
 131 To avoid a possible deadlock situation,
 132 processes that are children in the middle
 133 of a
 134 .Fn vfork
 135 are never sent
 136 .Dv SIGTTOU
 137 or
 138 .Dv SIGTTIN
 139 signals; rather,
 140 output or
 141 .Xr ioctl 2
 142 calls
 143 are allowed
 144 and input attempts result in an end-of-file indication.