Manpages

NAME

FBB::Proc - Runs external programs

SYNOPSIS

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

DESCRIPTION

The FBB::Proc offers an alternative to the FBB::Process class. FBB::Proc offers an extensive interface to calling external programs and/or scripts from a C++ program (so-called child-processes). The class offers an easy to use, stream-based interface to communicate with the standard input, output and error streams of child processes.

Objects of the class Proc use standard process-executing functions, like members of the execl(2) family or sh(1) to execute child processes. Thus, child processes can be executable programs or shell-scripts.

The standard input, output and error streams of child processes may be accessed through their Proc parent objects. Input expected by child processes can be inserted into Proc objects. standard output and standard error generated by child processes are inserted into and further handled by std::ostream objects, by default std::cout and std::cerr.

When using (output) redirection when executing child processes using the USE_SHELL path specification (see below for the path and IOMode specifications), the IGNORE_COUT IOMode (and possibly IGNORE_CERR) should normally be specified (cf. section ENUMERATIONS for a description of the IOMode enumeration).

Proc objects may repeatedly be used to execute the same or different child processes. Before the next child process is started, the Proc object ensures that its currently active child process ends. Alternatively, a currently active child process ends if the Proc object goes out of scope, if the allotted execution time of the child process has passed, if a new process is started using Proc’s assignment operator, or if its stop member is called. Otherwise child processes continue until completion when calling finish or, if the child process reads its standard input stream, when the eoi manipulator is inserted into the Proc object.

Programs called as child processes may be specified when constructing a Proc object or by using Proc’s setCommand member. Proc constructors (or Proc’s setCommand-member) don’t start child processes. To start child processes the start members or the assignment operator must be used.

Child processes may receive information at their standard input streams through information inserted into Proc objects. In those cases Proc objects must inform their child processes that they have received all input. For this the eoi manipulator can be inserted into Proc objects, or Proc’s finish member can be called.

If information sent to the child is not fully be processedd by the child process then the operating system issues a Broken pipe message, indicating that information in a pipe was lost, ending the program. The Proc class’s member pipeSignal can be used to suppress the Broken pipe message.

Arguments passed to child processes may be surrounded by double or single quotes. Arguments surrounded by double quotes have their double quotes removed, while interpreting any escape-sequences that may have been used within. Arguments surrounded by single quotes have their single quotes removed, while accepting their content as-is. In addition unquoted escape-sequences may be specified: those escape sequences are evaluated and replaced by their intended characters (e.g., \100 is converted to @).

A full command specification may also be surrounded by backtics (’-characters). These backtick characters are removed by the Proc object when the command starts.

Child processes may be allotted a limited amount of time (in seconds) to complete. By default no time limit is imposed upon child processes. If a time limit is specified then the child process, if still running after the specified number of seconds, is ended by sending it a SIGTERM signal, followed by a SIGKILL signal (cf. signal(7)).

By default the standard input, output and error streams of child processes are handled by their Proc parent processes: information inserted into the Proc object is forwarded to the child process’s standard input stream, information sent by the child process to its standard output and error streams are either forwarded to the corresponding streams of the parent process, or they can be processed by streams, configured by the Proc object.

Multiple Proc processes can be combined using the pipe operator (i.e., the | operator). When used, the standard output stream of the left-hand side (lhs) Proc object is used as the standard input stream of the right-hand side (rhs) Proc object. Since the Proc objects start their own child processes, this effectively boils down to the output of the lhs’s child process being used as the input of the rhs’s child process. The leftmost Proc object may also read its input (using the pipe operator) from an istream object or from a file whose name (path) is specified as the most lhs argument of a pipe expression. Likewise, the rightmost Proc object may pipe its standard output to an existing ostream object or to a file whose name (path) is specified as the most rhs argument of a pipe expression.

Proc objects use Pipe objects (cf. pipe(3bobcat)) for communication with their child processes. To ensure that these pipes are properly closed the members waitForChild, stop or the eoi manipulator should be used. Once a Proc object ceases to exist pipes to its child process are also closed.

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),
std::ostream

ENUMERATIONS

The following enumerations are defined by the Proc class:

enum ProcType:

The enum ProcType defines how a child proc is started or located. Its values are specified at constructor-time or through the setProcType member. This enumeration defines the following symbolic constants:

The program specified as child proc is started as specified, without searching the elements of the PATH environment variable.

The elements of the PATH environment variable are used when locating the program specified as child proc.

The program specified as child proc is called using /bin/sh -c. When (output) redirection is used with the specified command the IGNORE_COUT IOMode (and possibly also the IGNORE_CERR IOMode) should be specified.

enum IOMode:

Values of the enum IOMode are used to define which of the child proc’s standard streams can be accessed through the Proc object. Its symbolic constants may be combined using the bit_or operator. By default CIN | COUT | CERR is used (see below).

IOMode arguments may be combined using bit-or operators.

The following symbolic constants are available:

Shortcut for CIN | COUT | CERR.

Information inserted into the Proc object is forwarded to its child proc. If this is not required then CIN should not be specified.

Information written by the child process to its standard error stream is made available as Proc’s standard error stream. If this is not required then CERR should not be specified.

Information written by the child process to its standard output stream is made available as Proc’s standard output stream. If this is not required then CERR should not be specified.

Information written by the child proc to its standard error stream is ignored (i.e., not made available). An std::invalid_argument exception is thrown if this mode is specified in combination with CERR, MERGE_COUT_CERR, and/or REPLACE.

Information written by the child proc to its standard output stream is ignored. An std::invalid_argument exception is thrown if this mode is specified in combination with COUT, MERGE_COUT_CERR and/or REPLACE.

Shortcut for IGNORE_CERR | IGNORE_COUT.

Information written by the child process to its standard output and standard error streams is made available at the Proc object’s standard output stream. An std::invalid_argument exception is thrown if this mode is specified in combination with COUT, CERR, IGNORE_COUT, IGNORE_CERR or REPLACE.

The Proc object does not insert information into the standard input streams of its child process and information written by the child process to its standard output or error streams is not forwarded to the Proc object. Instead, the child process processes its standard streams by itself. When this mode is specified in combination with other IOMode values it is silently ignored.

When starting a child proc (see below at the member start) the current process (i.e., the program defining the Proc object) is replaced by the child process, inheriting the current process’s standard input and output streams. If this mode is specified in combination with any other IOMode (except for NONE, see below) an std::invalid_argument exception is thrown.

CONSTRUCTOR

Note that child processes are not started automatically following the construction of t(Proc) objects. A start member or the assignment operator (see below) is used to start child processes.

Once a Proc object has been constructed its parameters can be changed using set-member functions or start members.

The parameter bufSize defines the size of the streambuf buffers used by the Proc object. The timeLimit specifies the maximum execution time of a child process in seconds; when timeLimit == 0 no execution time limit is used. When pipeSignal == true incomplete processing of information sent to or read from the child process results in a Broken pipe exception, terminating the program. When specifying false the Broken pipe exception is suppressed, and the input and/or output streams do not have to be completely processed (see also pipeSignal’s description).

Copy and move constructors (and assignment operators) are not available.

OVERLOADED OPERATORS

This operator inserts value into the child’s standard input stream. I.e., the child proc reads value from its standard input. A value of any type that can be inserted into an ostream can be inserted into a Proc object. Nothing happens if the member is used when the child proc has terminated. Manipulators like std::endl are also supported. The behavior of this operator is undefined when IOMode CIN has not been specified.

This operator adds the provided std::string object to the currently defined command specification of a Proc object. The member operator+= does not add a separating blank space between the currently stored command specification and the text to append. It merely adds its right-hand side string to the command stored so far. It does not affect a currently running child process.

The operator= member defines cmd as the stored command in a Proc object, and thereupon starts ’cmd’ as its child process.

Before starting the child process a possibly active child process is first stopped by calling stop. It returns stop’s return value. Immediately after calling stop the new command (cmd) is started. If ending and restarting another command should be separate actions then use finish or stop followed by setCommand, followed by calling an appropriate overloaded version of the member start.

This operator implements piping. Information sent by lhs to its standard output is used as the standard input of the rhs’s child process. The Return value is rhs if the expression is followed by another pipe-operator or it is void.

This operator implements piping. Information read from in is read by proc’s child process. The Return value is proc if the expression is followed by another pipe-operator or it is void.

This operator implements piping. information in the file whose file (path) name is fname is read by proc’s child process. The Return value is proc if the expression is followed by another pipe-operator or it is void.

This operator implements piping. Information sent by proc’s child process to its standard output stream is written to out.

This operator implements piping. Information sent by proc’s child process to its standard output stream is written to the file whose file (path) name is fname.

The pipe (|) operator mimics the pipe-operator supported by most command-shell programs and should not be confused with the bit-or operator. The pipe operator allows constructions like

p1 | p2 | p3 // piping 3 Proc objects
cin | p1 | p2 | cout // p1 reads cin, p2 writes cout
inName | p1 | outName // inName: file name of the file
// read by p1, outName: file name
// of the file written by p1

When using the pipe operator Proc objects reading input automatically specify their CIN modes, while Proc objects writing their standard output automatically specify their COUT modes. Following the pipe-expression the IOMode specifications which were specified before the pipe-expression are restored.

MEMBERS

If the child proc is currently running true is returned and and false if not.

The label lab, followed by the a textual representation of the currently configured IOMode is inserted into std::cerr.

The text Proc, followed by the Proc’s id, followed by label lab, followed by the currently active read and write file descriptors of the pipes currently used by the Proc object are inserted into std::cerr.

The currently specified child-process starting command is returned.

The last child-process’s exit-status is returned. If a child process is currently running or if no child process has yet been started -1 is returned.

Waits until a currently active child process has ended and returns its exit status. If the child process isn’t currently running -1 is returned.

The IOMode currently used by the Proc object is returned.

The IOMode currently used by the Proc object is returned as a text-string.

The child process’s process-id is returned. The returned value is undefined if no child process has yet been started. If the child process has already completed the last child process’s id is returned.

When incompletely forwarding information to a child process or incompletely reading information from a child process a Broken pipe may result, ending the currently running program. To avoid this, pipeSignal(false) can be called. To reactivate recognizing broken pipes pipeSignal(true) can be called. After using pipeSignal(false) failing insertions into a Proc object result in its member good returning false, and its members bad and fail returning true.

Every constructed Proc object receives its own construction-order index. The first Proc object constructed in a program gets index value 0.

The ProcType used when starting child processes is returned.

The stream buffer size in bytes used by streams communicating with child processes is set to bufSize. A zero byte buffer size is silently changed into one.

The (initial part of a) child process command specification is set to cmd. After calling this member operator+= can be used to append additional text to the command specification.

The IOMode used when calling child processes is set to mode. Note that pipe-expressions may modify the mode of Proc objects while the pipe-expression is executed. For details see the end of the OVERLOADED OPERATORS section.

The ProcType used when starting child processes is set to type.

The execution time limit of child processes is set to timeLimit (in seconds). No time limit is used when timeLimit 0 is specified. The time limit set by setTimeLimit is used when starting the next child process. When calling setTimeLimit then pipeSignal(timeLimit == 0) is automatically called. If that’s not intended, then explicitly call pipeSignal after calling setTimeLimit.

The currently specified command is started using the specified timeLimit, IOMode, ProcType and bufSize arguments. The start members do not alter the currently configured default values of their arguments.

If a child process is still active when start is called it first calls stop to end the currently running child process

Same as the previous start member, but using the currently configured timeLimit and requiring the specification of the IOMode to use.

Same as the first start member, but using the currently configured timeLimit, IOMode, ProcType and bufSize values.

A currently active child process is ended by calling Fork::endChild (see also fork(3bobcat)).

The currently stored command is executed as a command of sh(1), using the specified process-arguments.

Same as the previous system command, but using the default timeLimit specification.

The currently configured execution time limit of Proc’s child process is returned. The return value zero indicates that no time limit is used.

The standard error output produced by the child process is sent to out. If the Proc object had specified IGNORE_CERR then that IOMode is unset, and the CERR mode is set.

Same as the previous member, but the child’s standard error output is written to the file (path) fname.

The standard output and standard error output produced by the child process is sent to out. If the Proc object had specified CERR, COUT, IGNORE_CERR, or IGNORE_COUT then those IOModes are unset, and the MERGE_COUT_CERR mode is set.

Same as the previous member, but the child’s standard output and standard error output is written to the file (path) fname.

The standard output produced by the child process is sent to out. If the Proc object had specified IGNORE_COUT then that IOMode is unset, and the COUT mode is set.

Same as the previous member, but the child’s standard output is written to the file (path) fname.

This member calls the identically named member from the class FBB::Fork, waiting for a child process to end. When calling finish or using pipe-expressions waitForChild is automatically called.

EXAMPLES

All examples should start with:

#include <iostream>
#include <bobcat/proc>

using namespace std;
using namespace FBB;

The first example illustrates how a program only producing output can be called. Its child proc simply is /bin/ls:
int main()
{
Proc proc("/bin/ls -Fla", Proc::COUT);

proc.start();
}

The next example illustrates a child program that’s given a limited amount of execution time: lines entered at the keyboard are echoed to the standard output stream for at most 5 seconds:
int main()
{
Proc proc("/bin/cat", Proc::CIN | Proc::COUT);
proc.setTimeLimit(5);

proc.start();

while (true)
{
cout << "? ";
string line;
if (not getline(cin, line))
return 0;

proc << line << endl; // to /bin/cat

if (not proc.good())
{
cout << "child time limit exceeded\n";
break;
}
}

cout << "/bin/cat time limit of 5 seconds reached: child proc ended\n";
}

Piping is illustrated next: information at the program’s standard input is piped to a second Proc object, writing its standard output to the program’s standard output stream:
int main()
{
Proc proc1{ "/bin/cat" };
Proc proc2{ "/bin/cat" };

cin | proc1 | proc2; // By default piping to cout. To do that
// explicitly use ’... | proc2 | cout’
}

FILES

bobcat/proc - defines the class interface

SEE ALSO

bobcat(7), execle(3), fork(3bobcat), process(3bobcat), ostream(3fork), sh(1)

BUGS

BOBCAT PROJECT 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 [AT] rug.nl).