Provided by: libbobcat-dev_2.20.01-1_amd64 bug

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  parent.  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...\n";

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

       int main()
       try
       {
           Background bg;

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

           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_2.20.01-x.dsc: detached signature;

       o      bobcat_2.20.01-x.tar.gz: source archive;

       o      bobcat_2.20.01-x_i386.changes: change log;

       o      libbobcat1_2.20.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_2.20.01-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).