1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Fork)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
(Template Design Pattern around fork(2))
manpagename(FBB::Fork)
(Implements bf(fork)(2) using the Template Design Pattern)
manpagesynopsis()
bf(#include <bobcat/fork>)nl()
Linking option: tt(-lbobcat)
manpagedescription()
bf(FBB::Fork) objects may be used to implement the bf(fork)(2) call as part
of the Template Algorithm Design Pattern. The class was designed as a virtual
base class for classes implementing the essential parts of the forking
process. The class is a virtual base class. Derived classes em(must) implement
the members tt(childProcess) and tt(parentProcess) as part of the
`Template Method Design Pattern' (see Gamma em(et al.), 1995).
Terminating child processes send tt(SIGCHLD) signals to their parents. The
bf(C) library offers the following em(macros) to analyze the em(status) values
received by the parent process using a bf(wait)(2) or bf(waitpid)(2) system
call:
itemization(
itb(int WIFEXITED(int status))
This macro returns a nonzero value if the child process terminated
normally with `exit' or `_exit'.
itb(int WEXITSTATUS(int status))
If `WIFEXITED' is true of `tt(status)', this macro returns the
low-order 8 bits of the exit status value from the child process.
itb(int WIFSIGNALED(int status))
This macro returns a nonzero value if the child process terminated
because it received a signal that was not handled.
itb(int WTERMSIG(int status))
If `WIFSIGNALED' is true of `tt(status)', this macro returns the
signal number of the signal that terminated the child process.
itb(int WCOREDUMP(int status))
This macro returns a nonzero value if the child process terminated
and produced a core dump.
itb(int WIFSTOPPED(int status))
This macro returns a nonzero value if the child process is stopped.
itb(int WSTOPSIG(int status))
If `WIFSTOPPED' is true of `tt(status)', this macro returns the signal
number of the signal that caused the child process to stop.
)
includefile(include/namespace)
manpagesection(INHERITS FROM)
-
manpagesection(CONSTRUCTORS)
Only the default constructor is available.
manpagesection(DESTRUCTOR)
itemization(
itb(virtual ~Fork())
Derived classes may define their own destructor, which is called when
the tt(Fork) destructor is activated.
)
manpagesection(MEMBER FUNCTIONS)
itemization(
itb(void fork())
Performs the actual forking. It is implemented in such a way that the
corresponding parent- and child- processes are activated from virtual members
of bf(Fork). If the forking operation fails, an tt(FBB::Exception) exception
is thrown.
)
manpagesection(PROTECTED MEMBER FUNCTIONS)
itemization(
itb(int endChild() const)
This member may be called by tt(parentProcess) to end the child
process. To end the child process a tt(SIGTERM) is sent to the child process,
followed by a tt(SIGKILL) (cf. bf(signal)(7)). If the child process has
already ended then the child process's exit value is returned, otherwise the
child process's end is forced (by calling tt(kill)) and -2 is returned. This
member also calls tt(waitForChild) (see below).
itb(pid_t pid() const)
Returns the child's process id in the parent's code (i.e., in the
bf(parent-)members below), and 0 in the child's code (i.e., in the
bf(child-)members below). The tt(pid) member returns -1 when called em(before)
the member tt(fork) has been called.
itb(void prepareDaemon() const)
Prepares for a daemon childprocess. This function may (should) be
called from tt(childProcess) to ensure that the child process changes its
current working directory to the root (/) directory, thus freeing up mount
points; that the child process starts a new session/process group to allow the
parent (group leader) to kill all its processes without terminating the
daemon; and makes sure that the child process closes and reopens the standard
streams by associating them with tt(/dev/null) to prevent ghost input and
output actions from interfering with the daemon's actions. An
tt(FBB::Exception) is thrown if changing directory to the root directory
fails.
itb(void prepareDaemon(std::string const &out, std::string const &err,
mode_t mode = 0600) const)
Prepares for a daemon childprocess like the previous member function,
but allows redirection of the standard output (tt(out)) and standard error
(tt(err)) streams to files. Specify empty strings to redirect these streams to
tt(/dev/null). With non-empty strings the specified files are opened in
append-mode (and created if not yet existing), by default using mode 0600
(read/write mode for the user only). An tt(FBB::Exception) is thrown if
changing directory to the root directory or if using the specified file(s)
fails.
itb(int waitForChild() const)
This member may be called by tt(parentProcess) to wait for the
completion of the child-process. The return value (exit-code) of the child
process is returned as a value between 0 and 255. If the child process
terminates before the completion of the parent process, then
tt(waitForChild) should be called to prevent em(zombies) from
occurring. Alternatively, the parent process may terminate (e.g., using
bf(exit)(2)) while the child process is still alive. This is the normal way to
create a em(daemon) process.
)
manpagesection(PRIVATE (VIRTUAL) MEMBER FUNCTIONS)
itemization(
itb(virtual void childProcess() = 0)
This member em(must) be implemented by derived classes. It defines the
actions that are performed by the child process, following the bf(fork)(2)
system call. Just before tt(childProcess) is called, tt(childRedirections)
(see below) has been executed. The tt(childProcess()) function should
terminate the child process. A good way to do this is to throw an exception
which is caught by tt(main())'s function try block. Terminating a process
using bf(exit)(2) is deprecated in bf(C++).
itb(virtual void childRedirections())
This function em(may) be redefined in derived classes to set up the
redirections that are necessary to communicate with the parent process. See
also the classes bf(redirector)(3bobcat) and bf(pipe)(3bobcat). By default,
tt(childRedirections) does nothing.
itb(virtual void parentProcess() = 0)
This member em(must) be implemented by derived classes. It defines the
actions that are performed by the parent process, following the bf(fork)(2)
system call. Just before tt(parentProcess) is called,
tt(parentRedirections) (see below) has been executed.
When deriving classes from tt(Fork) their tt(parentProcess)
implementation preferably handles all actions to perform by the parent
process. If the child process remains active when the parent process decides
that the program has performed its duties (e.g., the child process
is replaced by a program started by an tt(exec..) function, continuously
producing output, interpreted by the parent process) then the parent process
can call tt(endChild) to end the child process before ending the
tt(parentProcess) function.
itb(virtual void parentRedirections())
This function em(may) be redefined in derived classes to set up the
redirections that are necessary to communicate with, e.g., the parent. See,
e.g., the classes bf(redirector)(3bobcat) and bf(pipe)(3bobcat). By default,
tt(parentRedirections) does nothing.
)
manpagesection(EXAMPLES)
verbinclude(../../fork/driver/driver.cc)
Here's a more extensive example:
verbinclude(../../fork/driver/redirectedchild)
manpagefiles()
em(bobcat/fork) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(cerrextractor)(3bobcat), bf(cininserter)(3bobcat),
bf(coutextractor)(3bobcat), bf(exec)(3), bf(exec)(3bobcat), bf(fork)(2),
bf(kill)(2), bf(pipe)(3bobcat), bf(redirector)(3bobcat),
bf(stdextractor)(3bobcat), bf(wait)(2), bf(waitpid)(2).
manpagebugs()
None Reported.
includefile(include/trailer)
|
