/usr/share/doc/libbobcat2-dev/man/process.3.html

<html><head>
<title>FBB::Process</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Process</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz</h2>
<h2>2005-2011</h2>

<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>

<html><head>
<title>FBB::Process(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Process(3bobcat)</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz Running Child Processes</h2>
<h2>2005-2011</h2>


<p>
<h2>NAME</h2>FBB::Process - Runs external programs
<p>
<h2>SYNOPSIS</h2>
    <strong>#include &lt;bobcat/process&gt;</strong><br>
    Linking option: <em>-lbobcat</em> 
<p>
<h2>DESCRIPTION</h2>
    The <strong>FBB::Process</strong> class offers an elaborate interface to external
programs and/or scripts from a <strong>C++</strong> program (so-called
<em>child-processes</em>). The class offers an easy to use, stream-based interface
to the child process's standard input, standard output and standard error
streams.
<p>
Objects of the <strong>FBB::Process</strong> class use standard process-executing
functions, like <strong>sh</strong>(1) and members of the <strong>execl</strong>(1) family to execute
the child process, and allow <em>shell-scripts</em> to be executed as well.
<p>
The standard input, output and error streams of executed child processes may
be accessed via their <em>Process</em> parent objects. Input expected by the child
process may be inserted into the <em>Process</em> object, output generated by the
child process may be extracted from the <em>Process</em> object. <em>Process</em>
objects cannot use these streams to communicate with the child process's
standard streams when the child processes themselves redirect their standard
streams.
<p>
When using (output) redirection with the <em>USE_SHELL</em> path specification (see
below for the path and IOMode specifications) the <em>IGNORE_COUT IOMode</em> (and
possibly <em>IGNORE_CERR</em>) will normally be specified as well. See also section
<strong>PIPING</strong> below.
<p>
The same <em>Process</em> 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
<em>stop</em> member) to end a child process explicitly.
<p>
Programs to call as child processes may be specified using <em>Process</em>'s
constructors. The child processes are not started by <em>Process</em>
constructors. To start a child process the <em>start</em> members or the assignment
operator may be used.
<p>
Some child processes continue until their standard input streams are
exhausted. The <em>close</em> member is provided to close such streams, thus ending
such child processes.
<p>
The class <em>Process</em> cannot be used to construct <em>daemon</em>s as <em>Process</em>'s
destructor forcefully terminates its child process. To create daemon processes
the <strong>Fork</strong>(3bobcat) class can be used.
<p>
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.
<p>
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 <em>Process</em>
object goes out of scope. <em>Process</em> makes <em>FBB::Fork</em>'s <em>waitForChild</em>
member available, which may be used to prevent a premature termination of a
child process.
<p>
If <em>waitForChild</em> 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 <em>Process</em> object going out of scope, then the
operating system issues a <em>Broken pipe</em> message, indicating that information
in a pipe was lost.
<p>
By default the standard input and output streams of child processes are
accessed from their <em>Process</em> parent processes: information inserted into
the <em>Process</em> 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 <em>Process</em> object.
<p>
<h2>NAMESPACE</h2>
    <strong>FBB</strong><br>
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
    <strong>FBB::Fork</strong>(3bobcat) (private), <br>
    <strong>FBB:IOStream</strong>(3bobcat)
<p>
<h2>ENUMERATIONS</h2>
<p>
<strong>enum ProcessType</strong>:<br>
       This enumeration has the following values:
        <ul>
        <li> <strong>NO_PATH</strong>:<br>
            This value indicates that the external program should be called as
        specified, without searching the elements in the <em>PATH</em> environment
        variable. 
        <li> <strong>USE_PATH</strong>:<br>
            This value indicates that the <em>PATH</em> environment variable should
        be used to locate the external program to be executed.
        <li> <strong>USE_SHELL</strong>:<br>
            This value indicates that the external program should be called as
        a command (using its <em>-c</em> option) to <strong>/bin/sh</strong>. When
        (output) redirection is used with the specified command the
        <em>IGNORE_COUT IOMode</em> (and possibly the <em>IGNORE_CERR IOMode</em> as
        well) should be specified.
        </ul>
<p>
<strong>enum IOMode</strong>:<br>
       The <em>IOMode</em> specification is used to define which of the standard
streams used by child processes are accessed through the <em>Process</em>
object. Sensible combinations may be formed using the <em>bit_or</em> operator.  If
no <em>IOMode</em> is specified, then <em>CIN | COUT | CERR</em> is used (see
below). This is also used by <em>Process</em>'s default constructor.
<p>
This enumeration defines the following values:
        <ul>
        <li> <strong>CIN</strong>:<br>
            Information inserted into the <em>Process</em> object is forwarded to
its child process. If this is not required then the <em>CIN</em> specification can
be omitted (but note <em>IGNORE_ALL</em> below).
        <li> <strong>CERR</strong>:<br>
            Information written by the child process to its standard error
stream is accessible through the <em>cerr</em> member. If this is not required then
the <em>CERR</em> specification can be omitted  (but note <em>IGNORE_ALL</em> below).
        <li> <strong>COUT</strong>:<br>
            Information extracted from the <em>Process</em> object was written by
the child process to its standard output stream.  If this is not required then
the <em>COUT</em> specification can be omitted (but note <em>IGNORE_ALL</em> below).
        <li> <strong>DIRECT</strong>:<br> 
           When starting the child process (see below at the member <em>start</em>)
the current process is replaced by the child process, inheriting the current
process's standard input and output streams. When this mode is specified in
combination with other <em>IOMode</em> values (except for <em>STD</em>, see below) an
<em>std::invalid_argument</em> exception is thrown.
        <li> <strong>IGNORE_ALL</strong>:<br>
            Deprecated. Use <em>STD</em> (see below) instead. This symbolic
enumeration value will be removed in a future <em>Bobcat</em> release.
        <li> <strong>IGNORE_CERR</strong>:<br>
            Information written by the child process to its standard error
stream is sent to <em>/dev/null</em>. This specification is silently ignored if
either <strong>CERR</strong> or <strong>MERGE_COUT_CERR</strong> were specified.
        <li> <strong>IGNORE_COUT</strong>:<br>
            Information written by the child process to its standard output
stream is sent to <em>/dev/null</em>. This specification is silently ignored when
either <strong>COUT</strong> or <strong>MERGE_COUT_CERR</strong> were specified.
        <li> <strong>MERGE_COUT_CERR</strong>:<br>
            Information extracted from the <em>Process</em> object is written by
the child process to its standard output and standard error streams.
        <li> <strong>STD</strong>:<br>
            The <em>Process</em> object will not extract information from or insert
information into the standard streams of its child process. The child process
read from the same standard input stream and write to the same standard output
streams as used by its parent <em>Process</em> object. When this mode is specified
in combination with other <em>IOMode</em> values it is silently ignored.
            </ul>
    The <em>IOMode</em> enumeration also defines the enumeration values <strong>IN_PIPE,
OUT_PIPE</strong> and <strong>CLOSE_ON_EXEC</strong>. These enumeration values are ignored when
specified by users of the class <em>Process</em> and are for internal use only.
<p>
<strong>enum ChildOutput</strong>:<br>
       The <em>ChildOutput</em> enumeration defines values returned by the
<em>available</em> member (see below) indicating to which standard stream the
child process has written information.  This enumeration defines the following
values:
        <ul>
        <li> <strong>NOTHING_AVAILABLE</strong>:<br>
    This value indicates that the child process did not (yet) write any
information to its standard streams;
        <li> <strong>CHILD_COUT</strong>:<br>
    This value indicates that the child process did write 
information to its standard output stream which is waiting for extraction.
        <li> <strong>CHILD_CERR</strong>:<br>
    This value indicates that the child process did write 
information to its standard error stream which is waiting for extraction.
        </ul>
    The latter two values may be combined using the <em>bit_or</em> operator
indicating that information on both standard streams is available. 
<p>
<h2>TYPE</h2>
    <ul>
    <li> <strong>IOMode</strong>:<br>
        Combinations of values of the <strong>enum IOMode</strong> may be used as value of a
variable of this type. In functions expecting an <strong>IOMode</strong> argument the empty
set should not normally be specified. To specify multiple <em>IOMode</em> values
the <em>bit_or</em> operator should be used.
    </ul>
<p>
<h2>PROCESS PARAMETERS</h2>
<p>
When running a child process three process parameters may be specified: the
child streams to access from the <em>Process</em> object (as an <strong>IOMode</strong> value);
the way to locate or start the child program (as a <strong>ProcessType</strong> value); and
the maximum time (in seconds) the child program is allowed to run.<br>
    Unless specified otherwise, all the child's standard streams (standard
input, output and error) are accessible from the <em>Parent</em> process; the
<em>PATH</em> environment variable will <em>not</em> 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.<br>
    Following the construction of a <em>Process</em> 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 <em>setXXX</em> 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.
<p>
<h2>CONSTRUCTORS</h2>
    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 <em>back-tick</em>
(<em>`</em>). The back-ticks will be removed just before the specified program is
executed.
<p>
A child process is <em>not</em> started automatically following the object
construction. A <em>start</em> member or the assignment operator (see below) can
be used to start the specified child process.
<p>
<ul>
    <li> <strong>Process(std::string const &amp;cmd = "")</strong>:<br>
       This constructor can also be used as default constructor. It can be
used to specify the (initial part of a) command to execute from a
<em>Process</em> object. Standard default values are used for the process
parameters (see section <strong>PROCESS PARAMETERS</strong>).
<p>
<li> <strong>Process(IOMode mode, std::string const &amp;cmd = "")</strong>:<br>
        This constructor requires the specification of the object's initial
default <strong>IOMode</strong> setting and it can be used to specify the (initial part of
a) command to execute from a <em>Process</em> object. Standard default values
are used for the remaining two process parameters ((<em>NO_PATH</em>) and no time
limit imposed on the child process).
<p>
<li> <strong>Process(IOMode mode, ProcessType type, std::string const &amp;cmd = "")</strong>:<br>
        This constructor requires the specification of the object's initial
default <strong>IOMode</strong> setting and <em>ProcessType</em> and it can be used to specify
the (initial part of a) command to execute from a <em>Process</em> object. By
default no time limit will be imposed upon the child process.
<p>
<li> <strong>Process(IOMode mode, ProcessType type, size_t timeLimit, 
std::string const &amp;cmd = "")</strong>:<br>
        This constructor requires the specification of the object's initial
default <strong>IOMode</strong> setting, <em>ProcessType</em> and time limit imposed upon child
processes it can be used to specify the (initial part of a) command to execute
from a <em>Process</em> object. To prevent a time limit from being imposed upon the
child process specify a time limit of 0 (zero).
<p>
</ul>
    The class <strong>Process</strong> does not offer copy and move constructors.
<p>
<h2>OVERLOADED OPERATORS</h2>
<p>
<ul>
    <li> <strong>Process &amp;operator&lt;&lt;(Type value)</strong>:<br>
        This operator inserts <em>value</em> into the child's standard
input stream. I.e., the child process reads <em>value</em> from its standard
input. A value of any type that can be inserted into an <em>ostream</em> can be
inserted into a <em>Process</em> object. Nothing happens if the member is used when
the child process has terminated. The behavior of this operator is undefined
unless <em>IOMode CIN</em> was specified.
<p>
<li> <strong>Process &amp;operator&gt;&gt;(Type value)</strong>:<br>
        This operator extracts <em>value</em> from the child's standard output
stream and optionally (if <em>IOMode MERGE_COUT_CERR</em> was specified) from the
child's error stream. I.e., <em>value</em> may be extracted from <em>Process</em>
objects. A value of any type that can be extracted from an <em>istream</em>
can be extracted from a <em>Process</em> object. Nothing happens if the member is
used when the child process has terminated. The behavior of this operator is
undefined unless <em>IOMode COUT</em> or <em>MERGE_COUT_CERR</em> was specified.
<p>
<li> <strong>Process &amp;operator+=(std::string const &amp;)</strong>:<br>
       This operator adds the provided <em>std::string</em> object to the command
specification currenly stored in a <em>Process</em> object. The currently stored
command specification may be redefined using the member <em>setCommand</em> (see
below).  The member <em>operator+=</em> 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.
<p>
<li> <strong>int operator=(std::string const &amp;cmd)</strong>:<br>
       The <em>operator=</em> member defines <em>cmd</em> as the  stored command in
a <em>Process</em> object.  If the command starts and ends with a <em>back-tick</em>
(<em>`</em>) then the back-ticks are removed, and the resulting contents are
interpreted as a command to execute.<br>
    Next it will call <em>stop</em> (see below) to end any ongoing process
followed by calling <em>start</em> to execute the newly defined command using the
current default process parameters. It returns <em>stop</em>'s return value.
<p>
<li> <strong>Process &amp;operator()(iomode mode)</strong>:<br>
        This operator changes the <em>IOMode</em> of the next child process. It
returns the <em>Process</em> object allowing constructions like
        <pre>

    process(COUT) = "/bin/cat"; 
        
</pre>

    to start a new child process with the specified <em>IOMode</em>. 
<p>
<li> <strong>Process &amp;operator()(iomode mode, ProcessType type)</strong>:<br>
        This operator changes the <em>IOMode</em> and <em>ProcessType</em> process
parameters of the next child process.
<p>
<li> <strong>Process &amp;operator()(iomode mode, ProcessType type, size_t timeLimit)</strong>:<br>
        This operator changes all three process parameters  of the next child
process. Time limit 0 prevents a time limit from being imposed upon the next
child process.
<p>
<li> <strong>Process &amp;operator|(Process &amp;lhs, Process &amp;rhs)</strong>:<br>
        This operator implements <em>piping</em>: information sent to the <em>lhs</em>'s
standard output is passed on to the <em>rhs</em>'s standard input. The operator
returns <em>rhs</em>. This operator mimics the piping-operator supported by most
command-shell programs and should not be confused with the binary-or
operator. Before returning, the <em>lhs</em>'s child process is started, but the
<em>rhs</em>'s child process isn't. 
<p>
Since the operator is left-associative and <em>rhs</em> is returned piping can
be <em>chained</em>, allowing constructions like <em>p1 | p2 | p3</em>, where <em>p1, p2</em>
and <em>p3</em> are <em>Process</em> objects. 
<p>
The following idiom can be used to start the execution of the chain of
processes: <em>(p1 | p2 | p3).start()</em>. Alternatively, the following two-step
procedure can be used:
        <pre>

    p1 | p2 | p3;
    p3.start();
        
</pre>

<p>
If <em>p1</em> specifies <em>Process::CIN</em> then this <em>IOMode</em> is forwared to
the final process of the chain of processes. It is not necessary to specify
<em>Process::CIN</em> for <em>p3</em>. In fact, all <em>IOMode</em> flags of processes passed
to <em>operator|</em> are ignored and possibly modified <em>except</em> for
<em>Process::IGNORE_CERR</em> and <em>Process::CERR</em> (for all processes), 
<em>Process::CIN</em> (for the first process of the chain) and <em>Process::COUT</em>
(for the last process of the chain). 
<p>
The following example illustrates how input can be inserted into the first
process from a main process and sent to the standard output stream by the
final process. Note that, due to the forwarding of <em>Process::CIN</em>
information must actually be inserted into the final process, <em>p3</em>:
        <pre>
   
    using namespace std;
    using namespace FBB;

    Process p1(Process::CIN, "/bin/cat"); 
    Process p2("/bin/cat");
    Process p3(Process::STD, "/bin/cat");

    p1 | p2 | p3;

    p3.start();

    string line;
    while (getline(cin, line) &amp;&amp; not line.empty())
        p3 &lt;&lt; line &lt;&lt; endl;

    p3.close();
    p3.waitForChild();
        
</pre>
    
    </ul>
<p>
The default overloaded assignment operator is not available.
<p>
<h2>MEMBERS</h2>
<p>
<ul>
    <li> <strong>bool active()</strong>:<br>
        This member returns <em>true</em> if the child process is currently running
and <em>false</em> if not. It is automatically called from the insertion and
extraction operators and from the <em>cerr</em> member but is available as a
public member as well. It may terminate the child process if the child process
has timed out.
<p>
<li> <strong>size_t available()</strong>:<br>
        This member returns immediately. Its return value indicates whether
any information can be obtained from the child process as value(s) from the
<em>enum ChildOutput</em>. <em>NOTHING_AVAILABLE</em> is returned if no information is
ready for extraction. <em>CHILD_COUT</em> is returned if information from the child
process's standard output stream is available; <em>CHILD_CERR</em> is returned if
information from the child process's standard error stream is available;
<em>CHILD_COUT | CHILD_CERR</em> is returned if information from both the standard
output and standard error streams is available.
<p>
<li> <strong>std::istream &amp;cerr()</strong>:<br>
        This member may be used to extract information written by the child
process to its standard error stream.  This member should only be used when
<em>IOMode CERR</em> was specified for the currently running child process;
otherwise its behavior is undefined.
<p>
<li> <strong>void close()</strong>:<br>
        This member may be called from the parent process to close the child's
input stream. In situations where the child continuously reads information
from its standard input stream this member must be used to inform the child
process that input has terminated. This member should only be used when
<em>IOMode CIN</em> was specified for the currently running child process;
otherwise its behavior is undefined.
<p>
<li> <strong>iomode ioMode() const</strong>:<br>
        This member returns the current default <em>IOMode</em>. Note that the
<em>actual</em> <em>IOMode</em> that will be used may be different from the default
value as the actual value may have been altered using a function call
operator (see <em>operator()</em> above).
<p>
<li> <strong>ProcessType processType() const</strong>:<br>
        This member returns the current default <em>ProcessType</em>. Note that the
<em>actual</em> <em>ProcessType</em> that will be used may be different from the default
value as the actual value may have been altered using a function call operator
(see <em>operator()</em> above).
<p>
<li> <strong>size_t timeLimit() const</strong>:<br>
        This member returns the current default child process time limit. Note
that the <em>actual</em> time limit  that will be used may be different from
the default value as the actual value may have been altered using a function
call operator (see <em>operator()</em> above).
<p>
<li> <strong>void setCommand(std::string const &amp;cmd)</strong>:<br>
       The <em>setCommand</em> member (re)defines the (initial part of a) command
specification currently stored in an <em>Process</em> object. When the program is
eventually started it may start and end with a <em>back-tick</em> (<em>`</em>). The
back-ticks will be removed just before the specified program is executed.<br>
    The <em>setCommand</em> member will <em>not</em> start the specified command and
<em>operator+=</em> may be used to append the command specification before the
command is eventually executed. Also, this member does not affect a currently
running child process.
<p>
<li> <strong>void setIOMode(iomode mode)</strong>:<br>
        This member will change the current default <em>IOMode</em> process
parameter of child processes.
<p>
<li> <strong>void setProcessType(ProcessType type)</strong>:<br>
        This member will change the current default <em>ProcessType</em> process
parameter of child processes.
<p>
<li> <strong>void setTimeLimit(size_t timeLimit)</strong>:<br>
        This member will change the current default time limit process
parameter of child processes. No time limit will be imposed upon child
processes if <em>timeLimit 0</em> is specified.
<p>
<li> <strong>int start()</strong>:<br>
        The currently specified command is executed using the currently active
process parameters. These process parameters may be modified (either as new
defaults or for the next process only) using overloaded <em>start</em> members,
the <em>system</em> members, function call operator or various
<em>set-</em>members.<br>
    Having specified a command to execute, the first white-space delimited
element of the specified command is used as the name of the program to
execute. If the program should be called as a command to be executed by
<strong>sh</strong>(1), the  <em>USE_SHELL ProcessType</em> or a <em>system</em> member 
should be used.<br>
    If a child process does not terminate by itself (within its allotted
amount of time) it is terminated when it has run for its alloted time; when
the <em>Process</em> object's <em>start</em> or <em>stop</em> members are called; when
the object's assignment operator is used; or when the object goes out of
scope.
<p>
<li> <strong>int start(IOMode mode)</strong>:<br>
       The currently specified command is executed using the specified
<em>IOMode</em> rather than the currently specified default but otherwise using the
currently specified default process parameters. The specified <em>IOMode</em> will
only be used for the process executed by this <em>start</em> member.
<p>
<li> <strong>int start(IOMode mode, Program program)</strong>:<br>
       The currently specified command is executed using the specified
<em>IOMode</em> and <em>ProcessType</em> as well as the currently specified child
process time limit. The specified arguments will only be used for the process
executed by this <em>start</em> member.
<p>
<li> <strong>int start(IOMode mode, Program program, size_t timeLimit)</strong>:<br>
       The currently specified command is executed using the specified
arguments for the process parameters. The specified arguments will only be
used for the process executed by this <em>start</em> member.
<p>
<li> <strong>std::string const &amp;str() const</strong>:<br>
        This member returns the text of the command currently stored in the
<em>Process</em> object. It shows the command as it will be executed by
<em>start</em>, <em>system</em> or the assignment operator. If the command's first
and last characters are back-ticks (<em>`</em>) then those back-ticks will be
removed when the command is actually executed.
<p>
<li> <strong>void system()</strong>:<br>
        This member executes the currently stored command as a command to
<strong>sh</strong>(1) (therefore executing the command as a shell command).  When using
<em>system</em> redirections can be included in the command itself (although this
might render the redirected streams implied by the current <strong>IOMode</strong>)
useless. The currently set process parameters are used when <strong>sh</strong>(1) is
executed.  Calling <em>system</em> implies calling <em>start</em>.
<p>
<li> <strong>void system(IOMode mode)</strong>:<br>
        This member executes the currently stored command as a command to
<strong>sh</strong>(1) (cf. <em>system</em> above) using the specified <em>IOMode</em> rather than
the current default <em>IOMode</em> setting. The currently specified default time
limit, however, will be used when executing the <strong>sh</strong>(1) process.
<p>
<li> <strong>void system(IOMode mode, size_t timeLimit)</strong>:<br>
        This member executes the currently stored command as a command to
<strong>sh</strong>(1) (cf. <em>system</em> above) using the specified <em>IOMode</em> and time
limit values rather than their current default settings.
<p>
<li> <strong>int stop()</strong>:<br>
       This member terminates a currently active child process. The child
process is twice sent a <em>SIG_TERM</em> signal, followed by a <em>SIG_KILL</em>
signal. This member's return value is the exit-value of the child process
that was stopped. It is underfined if it was called without a running child
process. <br>
    Following <em>stop</em> a new command may be called using <em>start,
system</em> or the assignment operator (see earlier). Those members will first
call <em>stop</em> so when the intention is to start another child process
calling <em>stop</em> can be skipped. Also, <em>stop</em> is called when the
<em>Process</em> object goes out of scope.
<p>
<li> <strong>int waitForChild()</strong>:<br>
        This member is inherited from the class <em>FBB::Fork</em> and will wait
for a child process to finish. It can be used to prevent premature termination
of a child process before calling <em>stop</em>. It is not always required to use
<em>waitForChild</em>. E.g., when a process writes to its standard output stream
and all output has been read then the child process can be stopped without
calling <em>waitForChild</em>. 
<p>
</ul>
<p>
<h2>USING PIPING IN COMMANDS</h2>
<p>
When specifying multiple commands using the piping operator (<em>'|'</em>)
<em>USE_SHELL</em> must be specified as piping using the piping operator is a
shell-feature.
<p>
The additional shell process may be avoided by explicitly setting up the
stdin-stdout piping using <em>Process</em>'s <em>operator|</em>.
<p>
<h2>EXAMPLE</h2>
        <pre>
#ifdef BOBCAT
    #include &lt;bobcat/process&gt;
#else
    #include "process"
#endif

#include &lt;string&gt;
#include &lt;iostream&gt;
#include &lt;climits&gt;

using namespace std;
using namespace FBB;

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

int main(int argc, char **argv)
try
{
    cout &lt;&lt; "Size of Process: " &lt;&lt; sizeof(Process) &lt;&lt; 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) &amp;&amp; not line.empty())
    {
        cout &lt;&lt; "Entering " &lt;&lt; line &lt;&lt; endl;
        p3 &lt;&lt; line &lt;&lt; endl;
    }

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


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

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

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

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

    line.clear();
    if (process &gt;&gt; line)                // retrieve the value
        cout &lt;&lt; "&gt;&gt;&gt;" &lt;&lt; line &lt;&lt; "&lt;&lt;&lt;" &lt;&lt; endl;
    process.stop();


//    if (argc &gt; 1)                       // sending an e-mail
//    {
//        cout &lt;&lt; "Sending mail to " &lt;&lt; argv[1] &lt;&lt; endl;
//        prompt("/usr/bin/mail");
//        process.setCommand("/usr/bin/mail -s 'from Process' ");
//        process += argv[1];
//        process.start(Process::CIN);
//        process &lt;&lt; "This mail was sent by the process drive\n";
//        process &lt;&lt; "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 &lt;&lt; "? ";
        getline(cin, line);
        process &lt;&lt; line &lt;&lt; endl;        // to /bin/cat
        line.clear();
        if (!getline(process, line))    // from /bin/cat
            break;
        cout &lt;&lt; "Received: " &lt;&lt; line &lt;&lt; endl;
    }
    cout &lt;&lt; "/bin/cat forcefully terminated\n";

    process.setTimeLimit(0);

    cout &lt;&lt; "3 times running /bin/ls\n";

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

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

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

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

catch (...)
{
    cerr &lt;&lt; "Unrecognized exception in main()\n";
    return 0;
}
</pre>

<p>
<h2>FILES</h2>
    <em>bobcat/process</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
    <strong>bobcat</strong>(7), <strong>execle</strong>(3), <strong>fork</strong>(3bobcat), <strong>iostream</strong>(3fork),
    <strong>sh</strong>(1)
<p>
<h2>BUGS</h2>
    With the release of Bobcat 1.21.1 the class <em>Process</em> was completely
rewritten. The new implementation, however, should not affect existing
programs other than that <em>Process</em> 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 <em>Process</em>
class <em>has</em> changed though, requiring recompilation of sources defining
<em>Process</em> class type objects and linking dynamically to the <em>Bobcat</em>
library. 
<p>
With the release of Bobcat 2.11.0 another major modification of
<em>Process</em> was realized. Although <em>Process</em>'s internal organization was
again modified this does not affect exeisting programs using <em>Process</em>
objects. No recompilation of existing sources using <em>Process</em> is required.
<p>

<h2>DISTRIBUTION FILES</h2>
    <ul>
    <li> <em>bobcat_2.20.01-x.dsc</em>: detached signature;
    <li> <em>bobcat_2.20.01-x.tar.gz</em>: source archive;
    <li> <em>bobcat_2.20.01-x_i386.changes</em>: change log;
    <li> <em>libbobcat1_2.20.01-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em>libbobcat1-dev_2.20.01-x_*.deb</em>: debian package holding the
            libraries, headers and manual pages;
    <li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
    </ul>
<p>
<h2>BOBCAT</h2>
    Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
    This is free software, distributed under the terms of the 
    GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
    Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
libbobcat-dev 2.20.01-1 / usr / share / doc / libbobcat2-dev / man / process.3.html
