FBB::Process

libbobcat1-dev_2.22.00-x.tar.gz

2005-2012


FBB::Process(3bobcat)

FBB::Process(3bobcat)

libbobcat1-dev_2.22.00-x.tar.gz Running Child Processes

2005-2012

NAME

FBB::Process - Runs external programs

SYNOPSIS

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

DESCRIPTION

The FBB::Process class offers an elaborate interface to external programs and/or scripts from a C++ program (so-called child-processes). The class offers an easy to use, stream-based interface to the child process's standard input, standard output and standard error streams.

Objects of the FBB::Process class use standard process-executing functions, like sh(1) and members of the execl(1) family to execute the child process, and allow shell-scripts to be executed as well.

The standard input, output and error streams of executed child processes may be accessed via their Process parent objects. Input expected by the child process may be inserted into the Process object, output generated by the child process may be extracted from the Process object. Process objects cannot use these streams to communicate with the child process's standard streams when the child processes themselves redirect their standard streams.

When using (output) redirection with the USE_SHELL path specification (see below for the path and IOMode specifications) the IGNORE_COUT IOMode (and possibly IGNORE_CERR) will normally be specified as well. See also section PIPING below.

The same Process object may be used repeatedly to execute the same or different child processes in sequence. If a previously started child process is still active it will first be terminated. It is also possible (using the stop member) to end a child process explicitly.

Programs to call as child processes may be specified using Process's constructors. The child processes are not started by Process constructors. To start a child process the start members or the assignment operator may be used.

Some child processes continue until their standard input streams are exhausted. The close member is provided to close such streams, thus ending such child processes.

The class Process cannot be used to construct daemons as Process's destructor forcefully terminates its child process. To create daemon processes the Fork(3bobcat) class can be used.

Command line arguments passed to child processes may be surrounded by double or single quotes. Arguments surrounded by double quotes will have their double quotes removed, interpreting any escape-sequences that may have been used within. Arguments surrounded by single quotes will have their single quotes removed, accepting their contents unmodified.

Child processes may be allowed a limited amount of time (in seconds) to complete. Alternatively, child processes may have no time limit imposed upon then. A child process is forcefully terminated when its parent Process object goes out of scope. Process makes FBB::Fork's waitForChild member available, which may be used to prevent a premature termination of a child process.

If waitForChild is not called but information sent to the child which could not be fully processed by the child process because the child process terminated as a result of the Process object going out of scope, then the operating system issues a Broken pipe message, indicating that information in a pipe was lost.

By default the standard input and output streams of child processes are accessed from their Process parent processes: information inserted into the Process object is forwarded to the child process's standard input stream, information sent by the child process to its standard output stream can be extracted from its parent Process object.

NAMESPACE

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

INHERITS FROM

FBB::Fork(3bobcat) (private),
FBB:IOStream(3bobcat)

ENUMERATIONS

enum ProcessType:
This enumeration has the following values:

enum IOMode:
The IOMode specification is used to define which of the standard streams used by child processes are accessed through the Process object. Sensible combinations may be formed using the bit_or operator. If no IOMode is specified, then CIN | COUT | CERR is used (see below). This is also used by Process's default constructor.

This enumeration defines the following values:

The IOMode enumeration also defines the enumeration values IN_PIPE, OUT_PIPE and CLOSE_ON_EXEC. These enumeration values are ignored when specified by users of the class Process and are for internal use only.

enum ChildOutput:
The ChildOutput enumeration defines values returned by the available member (see below) indicating to which standard stream the child process has written information. This enumeration defines the following values:

The latter two values may be combined using the bit_or operator indicating that information on both standard streams is available.

TYPE

PROCESS PARAMETERS

When running a child process three process parameters may be specified: the child streams to access from the Process object (as an IOMode value); the way to locate or start the child program (as a ProcessType value); and the maximum time (in seconds) the child program is allowed to run.
Unless specified otherwise, all the child's standard streams (standard input, output and error) are accessible from the Parent process; the PATH environment variable will not be used to locate the child program to be executed (often resulting in the requirement to provide an absolute path to the intended program) and the child processes will be allowed unlimited time to run.
Following the construction of a Process object all default parameter values may be modified. Process parameters may be altered for a single process or the general defaults may be modified. The setXXX members (see below) may be used to change the default process parameters. When process parameters are specified otherwise they will be active for the next process only.

CONSTRUCTORS

The command that may be provided to the following constructors may be the (initial part of the) specification of an external program to run. When the program is eventually started it may start and end with a back-tick (`). The back-ticks will be removed just before the specified program is executed.

A child process is not started automatically following the object construction. A start member or the assignment operator (see below) can be used to start the specified child process.

The class Process does not offer copy and move constructors.

OVERLOADED OPERATORS

The default overloaded assignment operator is not available.

MEMBERS

USING PIPING IN COMMANDS

When specifying multiple commands using the piping operator ('|') USE_SHELL must be specified as piping using the piping operator is a shell-feature.

The additional shell process may be avoided by explicitly setting up the stdin-stdout piping using Process's operator|.

EXAMPLE

#ifdef BOBCAT
    #include <bobcat/process>
#else
    #include "process"
#endif

#include <string>
#include <iostream>
#include <climits>

using namespace std;
using namespace FBB;

void prompt(char const *task)
{
    cout << "Press Enter to start " << task << endl;
    cin.ignore(INT_MAX, '\n');
}

int main(int argc, char **argv)
try
{
    cout << "Size of Process: " << sizeof(Process) << endl;
    string line;

        // Nota bene: without IOMode you get CIN, COUT and CERR
    Process p1(Process::CIN, "/bin/cat"); 
    Process p2(Process::STD, "/bin/cat");
    Process p3(Process::STD, "/bin/cat");


    prompt("sending lines (until empty) to cat | cat | cat");
    (p1 | p2 | p3).start();

    while (getline(cin, line) && not line.empty())
    {
        cout << "Entering " << line << endl;
        p3 << line << endl;
    }

    p3.close();
    p3.waitForChild();


    Process process(Process::CIN | Process::COUT,
                    "/usr/bin/sha1sum");

    prompt("sha1sum");
    process.start();
    process << "Hello world\n";         // input to sha1sum
    process.close();
    process >> line;                    // retrieve the value
    cout << line << endl;
    process.stop();

    prompt("cat, ignoring its output");
    process.setCommand("/bin/cat");
    process.setIOMode(Process::CIN | Process::IGNORE_COUT);

    process.start();
    process << "Hello world\n";         // input to sha1sum
    process.close();

    line.clear();
    if (process >> line)                // retrieve the value
        cout << ">>>" << line << "<<<" << endl;
    process.stop();


//    if (argc > 1)                       // sending an e-mail
//    {
//        cout << "Sending mail to " << argv[1] << endl;
//        prompt("/usr/bin/mail");
//        process.setCommand("/usr/bin/mail -s 'from Process' ");
//        process += argv[1];
//        process.start(Process::CIN);
//        process << "This mail was sent by the process drive\n";
//        process << "It consists of multiple lines of text\n";
//        process.close();
//        process.waitForChild();
//    }

    prompt("5 seconds IO to /bin/cat");
    process.setIOMode(Process::CIN | Process::COUT);
    process.setTimeLimit(5);            // change time limit

    process = "/bin/cat";
    while (process.active())
    {
        cout << "? ";
        getline(cin, line);
        process << line << endl;        // to /bin/cat
        line.clear();
        if (!getline(process, line))    // from /bin/cat
            break;
        cout << "Received: " << line << endl;
    }
    cout << "/bin/cat forcefully terminated\n";

    process.setTimeLimit(0);

    cout << "3 times running /bin/ls\n";

    for (size_t trial = 0; trial < 3; ++trial)
    {
        prompt("ls");

        process(Process::COUT) = "/bin/ls";

        cerr << process.str() << endl;
        size_t count = 0;
        while (getline(process, line))
            cout << ++count << ": " << line << endl;
   }

}
catch (Errno const &err)
{
    cerr << "EXCEPTION CAUGHT: " << err.why() << endl;
    return 1;
}
catch (bool)
{
    return 0;
}

catch (...)
{
    cerr << "Unrecognized exception in main()\n";
    return 0;
}

FILES

bobcat/process - defines the class interface

SEE ALSO

bobcat(7), execle(3), fork(3bobcat), iostream(3fork), sh(1)

BUGS

With the release of Bobcat 1.21.1 the class Process was completely rewritten. The new implementation, however, should not affect existing programs other than that Process will no longer impose a limited time-to-live upon child processes. The interface was enlarged, but this should not affect existing programs. The internal organization of the Process class has changed though, requiring recompilation of sources defining Process class type objects and linking dynamically to the Bobcat library.

With the release of Bobcat 2.11.0 another major modification of Process was realized. Although Process's internal organization was again modified this does not affect exeisting programs using Process objects. No recompilation of existing sources using Process is required.

DISTRIBUTION FILES

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).