FBB::Fork(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

🌸 FBB::Fork 🌸 (3bobcat)

okay so this whole page is about FBB::Fork, and its whole personality is literally "Template Design Pattern around fork(2)". bestie, let's get into it 💖

✨ NAME ✨

FBB::Fork — implements fork(2) using the Template Design Pattern 🫶

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

So, FBB::Fork objects let you do the whole fork(2) call as part of the Template Algorithm Design Pattern. The class was designed to be a virtual base class for classes that implement the essential parts of the forking process. And yes, it is literally a virtual base class. 👑

Here's the deal: derived classes must implement the members childProcess and parentProcess, because that's the whole Template Method Design Pattern situation (see Gamma et al., 1995). No skipping, bestie.

Now for the part that makes people go 😭: terminating child processes send SIGCHLD signals to their parents. And the C library hands you these macros to analyze the status values the parent receives via a wait(2) or waitpid(2) system call:

  • int WIFEXITED(int status): returns a nonzero value if the child process terminated normally with exit or _exit.
  • int WEXITSTATUS(int status): if WIFEXITED is true of status, this one returns the low-order 8 bits of the exit status value from the child process.
  • int WIFSIGNALED(int status): returns a nonzero value if the child process terminated because it received a signal that was not handled.
  • int WTERMSIG(int status): if WIFSIGNALED is true of status, this gives you back the signal number of the signal that terminated the child process.
  • int WCOREDUMP(int status): returns a nonzero value if the child process terminated and produced a core dump. 💀
  • int WIFSTOPPED(int status): returns a nonzero value if the child process is stopped.
  • int WSTOPSIG(int status): if WIFSTOPPED is true of status, this 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. iykyk.

🌈 INHERITS FROM 🌈

-

(yeah. nothing. it's giving founder energy 👑)

🎀 CONSTRUCTORS 🎀

Only the default constructor is available. that's it, that's the whole menu. 🍓

💅 DESTRUCTOR 💅

  • virtual ~Fork() — derived classes may define their own destructor, and that one gets called when the Fork destructor is activated.

🔥 MEMBER FUNCTIONS 🔥

  • void fork() — performs the actual forking. It's implemented so that the corresponding parent- and child- processes get activated from virtual members of Fork. And if the forking operation fails? an FBB::Exception exception is thrown, no cap. 🫶

👑 PROTECTED MEMBER FUNCTIONS 👑

  • int endChild() const — this member may be called by parentProcess to end the child process. To end the child process, a SIGTERM is sent to the child process, followed by a SIGKILL (cf. 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 kill) and -2 is returned. This member also calls waitForChild (see below). 💀
  • 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). The pid member returns -1 when called before the member fork has been called. so heads up, don't call it too early bestie 🙈
  • void prepareDaemon() const — prepares for a daemon childprocess. This function may (should) be called from childProcess to make sure 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 it 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. An FBB::Exception is thrown if changing directory to the root directory fails. 👻
  • 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 it additionally allows redirection of the standard output (out) and standard error (err) streams to files. Specify empty strings to redirect these streams to /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 FBB::Exception is thrown if changing directory to the root directory or if using the specified s fails.
  • int waitForChild() const — this member 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.

💖 PRIVATE (VIRTUAL) MEMBER FUNCTIONS 💖

  • 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 exception which is caught by main()'s function try block. Terminating a process using exit(2) is deprecated in C++. 😭
  • 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) and pipe(3bobcat). By default, childRedirections does nothing.
  • 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.

When deriving classes from Fork, their 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 exec.. function, continuously producing output, interpreted by the parent process), then the parent process can call endChild to end the child process before ending the parentProcess function.

  • 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) and pipe(3bobcat). By default, parentRedirections does nothing.

🌟 EXAMPLES 🌟

okay here's the first one, and honestly? it ate. 💅

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

#include <bobcat/fork>

using namespace std;
using namespace FBB;

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

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"
            "The child returns value " << waitForChild() << endl;
}

int main()
try
{
    Background bg;

    bg.fork();
    cout << "This is from the parent\n";
}
catch(int x)
{
    cout << "The child terminates with: " << x << endl;
    return x;
}

Here's a more extensive example:

#include <iostream>
#include <string>

#include <signal.h>
#include <unistd.h>

#include <sys/types.h>

#include <bobcat/pipe>
#include <bobcat/ofdstream>
#include <bobcat/ifdstream>
#include <bobcat/process>
#include <bobcat/fork>

class ChildIO: public FBB::Fork
{
    FBB::Pipe childInput;   // child reads this
    FBB::Pipe childOutput;   // child writes this

    public:
        void childRedirections()    override;
        void childProcess()         override;
        void parentProcess()        override;
};

using namespace std;
using namespace FBB;

void ChildIO::childRedirections()
{
    childInput.readFrom(Redirector::STDIN);
    childOutput.writtenBy(Redirector::STDOUT);
}

void ChildIO::childProcess()
{
        // The /bin/cat program replaces the
        // child process started by Fork::fork()
    Process process(Process::DIRECT, "/bin/cat");
    process.start();

    // this point is never reached
}

void ChildIO::parentProcess()
{
        // Set up the parent's sides of the pipes
    IFdStream fromChild(childOutput.readOnly());
    OFdStream toChild(childInput.writeOnly());

        // write lines to the child, read its output
    string line;
    while (true)
    {
        cout << "? ";
        line.clear();
        getline(cin, line);

        if (line.empty())
        {
            kill(pid(), SIGTERM);
            break;
        }

        toChild << line << endl;

        getline(fromChild, line);
        cout << "Got: " << line << endl;
    }
    cout << "The child returns value " << waitForChild() << endl;
}

int main()
try
{
    ChildIO io;

    io.fork();

    return 0;
}
catch(exception const &exc)
{
    cerr << "Exception: " << exc.what() << endl;
}
catch(int x)
{
    cout << "The child terminates with: " << x << endl;
    return x;
}

🎀 FILES 🎀

  • bobcat/fork — defines the class interface

✨ SEE ALSO ✨

Okay bestie, if you wanna go down the rabbit hole (and you should, it's giving scholarly excellence 💅), here's the whole squad:

💀 BUGS 💀

None Reported.

Not a single one, bestie. Clean. Flawless. No notes. 🎀 (The bugs are simply not bugging, periodt.)

🌈 BOBCAT PROJECT FILES 🌈

Here's where all the good stuff lives, iykyk:

Debian Bobcat project files, aka the packaging situation:

  • libbobcat6: the debian package holding the shared library, plus the changelog and copyright note;
  • libbobcat-dev: the debian package holding the static library, the headers, the manual pages, and the developer info;

Like, everything you need is right there. Obsessed. 🫶

👑 BOBCAT 👑

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

Yeah. The name is literally the lore. Iconic behavior, no cap. 🦋

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

Free as in freedom, bestie — respect the license, it's the vibe. 🌸

🎀 AUTHOR 🎀

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

The main character himself. We stan. ⭐

And that's a wrap on FBB::Fork(3bobcat), bestie — the whole page, start to finish, no crumbs left behind. 💅 It ships in the libbobcat-dev_6.15.01 package, dated 2005-2026, so you know it's got history and it's still slaying. Go fork something (responsibly). 🫶✨

📦 where this page comes from