FBB::Fork(3bobcat)				      Template Design Pattern around fork(2)					FBB::Fork(3bobcat)

NAME

       FBB::Fork - Implements fork(2) using the Template Design Pattern

SYNOPSIS

       #include <bobcat/fork>
       Linking option: -lbobcat

DESCRIPTION

       FBB::Fork  objects  may be used to implement the 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
       must implement the members childProcess() and parentProcess() as part of the `Template Method Design Pattern' (see Gamma et al., 1995).

       Terminating  child  processes send SIGCHLD signals to their parents. The C library offers the following macros to analyze the status values
       received by the parent process using a wait(2) or waitpid(2) system call:

       o      int WIFEXITED(int status):
	      This macro returns a nonzero value if the child process terminated normally with `exit' or `_exit'.

       o      int WEXITSTATUS(int status):
	      If `WIFEXITED' is true of `status', this macro returns the low-order 8 bits of the exit status value from the child process.

       o      int WIFSIGNALED(int status):
	      This macro returns a nonzero value if the child process terminated because it received a signal that was not handled.

       o      int WTERMSIG(int status):
	      If `WIFSIGNALED' is true of `status', this macro returns the signal number of the signal that terminated the child process.

       o      int WCOREDUMP(int status):
	      This macro returns a nonzero value if the child process terminated and produced a core dump.

       o      int WIFSTOPPED(int status):
	      This macro returns a nonzero value if the child process is stopped.

       o      int WSTOPSIG(int status):
	      If `WIFSTOPPED' is true of `status', this macro returns the signal number of the signal that caused the child process to stop.

NAMESPACE

       FBB
       All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

       -

CONSTRUCTORS

       o      Fork():
	      This is the only available constructor.  Note that there is no copy constructor.

DESTRUCTOR

       o      virtual ~Fork():
	      Derived classes may define their own destructor, which is called when the ~Fork() destructor is activated.

MEMBER FUNCTIONS

       o      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 FBB::Fork. If the forking operation fails, an FBB::Errno exception is thrown.

PROTECTED MEMBER FUNCTIONS

       o      virtual void childProcess() = 0:
	      This  member  must  be implemented by derived classes. It defines the actions that are performed by the child process, following the
	      fork(2) system call. Just before childProcess() is called, childRedirections() (see below) has  been  executed.  The  childProcess()
	      function	should terminate the child process. A good way to do this is to throw an exeption which is caught by main()'s function try
	      block. Terminating a process using exit(2) is deprecated in C++.

       o      virtual void childRedirections():
	      This function may be redefined in derived classes to set up the redirections that are  necessary	to  communicate  with  the  parent
	      process. See also the classes redirector(3bobcat), pipe(3bobcat), ipipe(3bobcat) and opipe(3bobcat). By default, childRedirections()
	      does nothing.

       o      virtual void parentProcess() = 0:
	      This member must be implemented by derived classes. It defines the actions that are performed by the parent process,  following  the
	      fork(2) system call. Just before parentProcess() is called, parentRedirections() (see below) has been executed.

       o      virtual void parentRedirections():
	      This  function may be redefined in derived classes to set up the redirections that are necessary to communicate with, e.g., the par-
	      ent. See, e.g., the classes redirector(3bobcat), pipe(3bobcat), ipipe(3bobcat) and opipe(3bobcat). By default,  parentRedirections()
	      does nothing.

       o      pid_t pid() const:
	      Returns  the  child's  process  id in the parent's code (i.e., in the parent-members below), and 0 in the child's code (i.e., in the
	      child-members below). Note that the value of pid() is undefined when called before the member fork() has been called.

       o      void prepareDaemon() const:
	      Prepares for a daemon childprocess. This function may (should) be called from  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 /dev/null to prevent ghost input and output
	      actions from interfering with the daemon's actions.

       o      int waitForChild():
	      This memebr may be called by 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 waitForChild() should be called to prevent zombies from occurring. Alternatively, the parent process may terminate (e.g., using
	      exit(2)) while the child process is still alive. This is the normal way to create a daemon process.

EXAMPLE

       #include <iostream>
       #include <unistd.h>

       #include <bobcat/fork>

       using namespace std;
       using namespace FBB;

       class Background: public Fork
       {
	   public:
	       void childProcess();
	       void parentProcess();
       };

       void Background::childProcess()
       {
	   for (int idx = 0; idx < 3; ++idx)
	   {
	       cout << "Hello world # " << idx << endl;
	       sleep(1);
	   }
	   throw 0;    // caught in main()
       }

       void Background::parentProcess()
       {
	   cout << "Waiting for the child process to end...
";

	   cout << "The child returns value " << waitForChild() << endl;
       }

       int main()
       try
       {
	   Background bg;

	   bg.fork();
	   cout << "This is from the parent
";

	   return 0;
       }
       catch(int x)
       {
	   cout << "The child terminates with: " << x << endl;
	   return x;
       }

FILES

       bobcat/fork - defines the class interface

SEE ALSO

       bobcat(7), ipipe(3bobcat), fork(2), opipe(3bobcat), pipe(3bobcat), redirector(3bobcat), wait(2), waitpid(2)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_3.01.00-x.dsc: detached signature;

       o      bobcat_3.01.00-x.tar.gz: source archive;

       o      bobcat_3.01.00-x_i386.changes: change log;

       o      libbobcat1_3.01.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.01.00-x_*.deb: debian package holding the libraries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

COPYRIGHT

       This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat1-dev_3.01.00-x.tar.gz 				     2005-2012							FBB::Fork(3bobcat)