Provided by: libbobcat-dev_6.03.02-2_amd64 
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:
o NO_PATH:
The program specified as child proc is started as specified, without searching the
elements of the PATH environment variable.
o USE_PATH:
The elements of the PATH environment variable are used when locating the program
specified as child proc.
o USE_SHELL:
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:
o ALL:
Shortcut for CIN | COUT | CERR.
o CIN:
Information inserted into the Proc object is forwarded to its child proc. If this
is not required then CIN should not be specified.
o CERR:
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.
o COUT:
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.
o IGNORE_CERR:
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.
o IGNORE_COUT:
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.
o IGNORE_COUT_CERR:
Shortcut for IGNORE_CERR | IGNORE_COUT.
o MERGE_COUT_CERR:
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.
o NONE:
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.
o REPLACE:
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.
o explicit Proc(std::string const &command = "", IOMode mode = ALL, ProcType type =
NO_PATH, size_t bufSize = 200, size_t timeLimit = 0, bool pipeSignal = true):
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
o Proc &operator<<(Type value):
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.
o Proc &operator+=(std::string const &):
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.
o int operator=(std::string const &cmd):
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.
o Return operator|(Proc &lhs, Proc &rhs):
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.
o Return operator|(std::istream &in, Proc &proc):
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.
o Return operator|(std::string const &fname, Proc &proc):
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.
o void operator|(Proc &proc, std::ostream &out):
This operator implements piping. Information sent by proc’s child process to its
standard output stream is written to out.
o void operator|(Proc &proc, std::string &fname):
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
o bool active():
If the child proc is currently running true is returned and and false if not.
o void cerrMode(char const *lab) const:
The label lab, followed by the a textual representation of the currently configured
IOMode is inserted into std::cerr.
o void cerrPipes(char const *lab) const:
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.
o std::string const &cmd() const:
The currently specified child-process starting command is returned.
o int exitStatus() const:
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.
o int finish():
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.
o IOMode ioMode() const:
The IOMode currently used by the Proc object is returned.
o std::string mode() const:
The IOMode currently used by the Proc object is returned as a text-string.
o int pid() const:
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.
o void pipeSignal(bool on):
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.
o size_t procIdx() const:
Every constructed Proc object receives its own construction-order index. The first
Proc object constructed in a program gets index value 0.
o ProcType procType() const:
The ProcType used when starting child processes is returned.
o void setBufSize(size_t bufSize):
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.
o void setCommand(std::string const &cmd):
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.
o void setIOMode(IOMode mode):
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.
o void setProcType(ProcType type):
The ProcType used when starting child processes is set to type.
o void setTimeLimit(size_t timeLimit):
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.
o void start(size_t timeLimit, IOMode mode = ALL, ProcType type = NO_PATH, size_t
bufSize = 200):
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
o void start(IOMode mode, ProcType type = NO_PATH, size_t bufSize = 200):
Same as the previous start member, but using the currently configured timeLimit and
requiring the specification of the IOMode to use.
o void start():
Same as the first start member, but using the currently configured timeLimit,
IOMode, ProcType and bufSize values.
o int stop():
A currently active child process is ended by calling Fork::endChild (see also
fork(3bobcat)).
o void system(size_t timeLimit, IOMode mode = ALL, size_t bufSize = 200):
The currently stored command is executed as a command of sh(1), using the specified
process-arguments.
o void system(IOMode mode = ALL, size_t bufSize = 200):
Same as the previous system command, but using the default timeLimit specification.
o size_t timeLimit() const:
The currently configured execution time limit of Proc’s child process is returned.
The return value zero indicates that no time limit is used.
o void useErr(std::ostream &out):
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.
o void useErr(std::string const &fname):
Same as the previous member, but the child’s standard error output is written to
the file (path) fname.
o void useMerge(std::ostream &out):
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.
o void useMerge(std::string const &fname):
Same as the previous member, but the child’s standard output and standard error
output is written to the file (path) fname.
o void useOut(std::ostream &out):
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.
o void useOut(std::string const &fname):
Same as the previous member, but the child’s standard output is written to the file
(path) fname.
o int waitForChild():
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
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_6.03.02-x.dsc: detached signature;
o bobcat_6.03.02-x.tar.gz: source archive;
o bobcat_6.03.02-x_i386.changes: change log;
o libbobcat1_6.03.02-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_6.03.02-x_*.deb: debian package containing the libraries, headers
and manual pages;
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).