git.saurik.com Git - apple/xnu.git/blob

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 .\" $FreeBSD$

30 .\"

31 .Dd May 22, 2016

32 .Dt VFORK 2

33 .Os

34 .Sh NAME

35 .Nm vfork

36 .Nd create a new process without copying the address space

37 .Sh LIBRARY

38 .Lb libc

39 .Sh SYNOPSIS

40 .In unistd.h

41 .Ft pid_t

42 .Fn vfork void

43 .Sh DESCRIPTION

44 .Bf -symbolic

45 Since this function is hard to use correctly from application software,

46 it is recommended to use

47 .Xr posix_spawn 3

48 or

49 .Xr fork 2

50 instead.

51 .Ef

52 .Pp

53 The

54 .Fn vfork

55 system call

56 can be used to create new processes without fully copying the address

57 space of the old process, which is inefficient in a paged

58 environment.

59 It is useful when the purpose of

60 .Xr fork 2

61 would have been to create a new system context for an

62 .Xr execve 2 .

63 The

64 .Fn vfork

65 system call

66 differs from

67 .Xr fork 2

68 in that the child borrows the parent process's address space and the

69 calling thread's stack

70 until a call to

71 .Xr execve 2

72 or an exit (either by a call to

73 .Xr _exit 2

74 or abnormally).

75 The calling thread is suspended while the child is using its resources.

76 Other threads continue to run.

77 .Pp

78 The

79 .Fn vfork

80 system call

81 returns 0 in the child's context and (later) the pid of the child in

82 the parent's context.

83 .Pp

84 Many problems can occur when replacing

85 .Xr fork 2

86 with

87 .Fn vfork .

88 For example, it does not work to return while running in the child's context

89 from the procedure that called

90 .Fn vfork

91 since the eventual return from

92 .Fn vfork

93 would then return to a no longer existent stack frame.

94 Also, changing process state which is partially implemented in user space

95 such as signal handlers with

96 .Xr libthr 3

97 will corrupt the parent's state.

98 .Pp

99 Be careful, also, to call

100 .Xr _exit 2

101 rather than

102 .Xr exit 3

103 if you cannot

104 .Xr execve 2 ,

105 since

106 .Xr exit 3

107 will flush and close standard I/O channels, and thereby mess up the

108 parent processes standard I/O data structures.

109 (Even with

110 .Xr fork 2

111 it is wrong to call

112 .Xr exit 3

113 since buffered data would then be flushed twice.)

114 .Pp

115 Unlike

116 .Xr fork 2 ,

117 .Fn vfork

118 does not run

119 .Xr pthread_atfork 3

120 handlers.

121 .Sh RETURN VALUES

122 Same as for

123 .Xr fork 2 .

124 .Sh ERRORS

125 The

126 .Fn vfork

127 system call will fail for any of the reasons described

128 in the

129 .Xr fork

130 man page.

131 In addition, it will fail if:

132 .Bl -tag -width Er

133 .\" ===========

134 .It Bq Er EINVAL

135 A system call other than

136 .Xr _exit()

137 or

138 .Xr execve()

139 (or libc functions that make no system calls other than those)

140 is called following calling a

141 .Fn vfork

142 call.

143 .El

144 .Sh SEE ALSO

145 .Xr _exit 2 ,

146 .Xr execve 2 ,

147 .Xr fork 2 ,

148 .Xr sigaction 2 ,

149 .Xr wait 2 ,

150 .Xr exit 3 ,

151 .Xr posix_spawn 3

152 .Sh HISTORY

153 The

154 .Fn vfork

155 system call appeared in

156 .Bx 3 .

157 .Sh BUGS

158 To avoid a possible deadlock situation,

159 processes that are children in the middle

160 of a

161 .Fn vfork

162 are never sent

163 .Dv SIGTTOU

164 or

165 .Dv SIGTTIN

166 signals; rather,

167 output or

168 .Xr ioctl 2

169 calls

170 are allowed

171 and input attempts result in an end-of-file indication.

172 .Sh CAVEATS

173 There are limits to what you can do in the child process.

174 To be totally safe you should restrict yourself to only

175 executing async-signal safe operations until such time

176 as one of the exec functions is called. All APIs, including

177 global data symbols, in any framework or library should be

178 assumed to be unsafe after a

179 .Fn vfork

180 unless explicitly documented to be safe or async-signal

181 safe. If you need to use these frameworks in the child

182 process, you must exec. In this situation it is reasonable

183 to exec yourself.