includefile(header.inc)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Process)(3bobcat)(_CurYrs_)(libbobcat1-dev__CurVers_-x.tar.gz)
                    (Running Child Processes)

manpagename(FBB::Process)(Runs external programs)

manpagesynopsis()
    bf(#include <bobcat/process>)nl()
    Linking option: tt(-lbobcat) 

manpagedescription()
    The bf(FBB::Process) class offers an elaborate interface to external
programs and/or scripts from a bf(C++) program (so-called
em(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 bf(FBB::Process) class use standard process-executing
functions, like bf(sh)(1) and members of the bf(execl)(1) family to execute
the child process, and allow em(shell-scripts) to be executed as well.

The standard input, output and error streams of executed child processes may
be accessed via their tt(Process) parent objects. Input expected by the child
process may be inserted into the tt(Process) object, output generated by the
child process may be extracted from the tt(Process) object. tt(Process)
objects will not be able to access these streams when child processes
themselves redirect their standard streams.

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

The same tt(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
tt(stop()) member) to end a child process explicitly.

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

Some child processes continue until their standard input streams are
exhausted. The tt(close()) member is provided to close such streams.

The class tt(Process) should not be used to construct em(daemon)s. To create 
daemon processes the bf(FBB::Fork) 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 will forcefully be terminated when its parent
tt(Process) object goes out of scope. Since tt(Process) inherits from
tt(FBB::Fork) it may use the latter class's member tt(waitForChild()) to
prevent premature termination of a child process.

includefile(namespace.inc)

manpagesection(INHERITS FROM)
    bf(FBB::Fork)(3bobcat) (private), nl()
    bf(FBB:IOStream)(3bobcat)

manpagesection(ENUMERATIONS)

    bf(enum ProcessType):nl()
       This enumeration has the following values:
        itemization(
        itb(NO_PATH)
            This value indicates that the external program should be called as
        specified, without searching the elements in the tt(PATH) environment
        variable. 
        itb(USE_PATH)
            This value indicates that the tt(PATH) environment variable should
        be used to locate the external program to be executed.
        itb(USE_SHELL)
            This value indicates that the external program should be called as
        a command (using its tt(-c) option) to bf(/bin/sh). When
        (output) redirection is used with the specified command the
        tt(IGNORE_COUT IOMode) (and possibly the tt(IGNORE_CERR IOMode) as
        well) should be specified.
        )


    bf(enum IOMode):nl()
       The tt(IOMode) specification is used to define which of the standard
streams used by child processes are accessed through the tt(Process)
object. Sensible combinations may be formed using the tt(bit_or) operator.
This enumeration defines the following values:
        itemization(
        itb(CIN)
            This value indicates that information inserted into the
tt(Process) object should be forwared to its child process. If this is not
required then the tt(CIN) specification can be omitted.
        itb(CERR)
            This value indicates that information written by the child process
to its standard error stream should be accessible through the
tt(FBB::Process::cerr()) member. If this is not required then the tt(CERR)
specification can be omitted.
        itb(COUT)
            This value indicates that information extracted from the
tt(Process) object should be the information written by the child process to
its standard output stream.  If this is not required then the tt(COUT)
specification can be omitted.
        itb(IGNORE_ALL)
            This value indicates that the tt(Process) object will not extract
information from or insert information into the standard streams of its child
process. It is ignored if any other specification is provided as well.
        itb(IGNORE_CERR)
            This value indicates that information written by the child process
to its standard error stream should be sent to tt(/dev/null). This
specification is ignored when either bf(CERR) or bf(MERGE_COUT_CERR) is
specified.
        itb(IGNORE_COUT)
            This value indicates that information written by the child process
to its standard output stream should be sent to tt(/dev/null). This
specification is ignored when either bf(COUT) or bf(MERGE_COUT_CERR) is
specified.
        itb(MERGE_COUT_CERR)
            This value indicates that information extracted from the
tt(Process) object should be the information written by the child process to
its standard output or error streams. 
            )

    bf(enum ChildOutput):nl()
       The tt(ChildOutput) enumeration defines values returned by the
tt(available()) member (see below) indicating to which standard stream the
child process has written information.  This enumeration defines the following
values:
        itemization(
        itb(NOTHING_AVAILABLE)
    This value indicates that the child process did not (yet) write any
information to its standard streams;
        itb(CHILD_COUT)
    This value indicates that the child process did write 
information to its standard output stream which is waiting for extraction.
        itb(CHILD_CERR)
    This value indicates that the child process did write 
information to its standard error stream which is waiting for extraction.
        )
    The latter two values may be combined using the tt(bit_or) operator
indicating that information on both standard streams is available. 

manpagesection(TYPE)
    itemization(
    itb(IOMode)
        Combinations of values of the bf(enum IOMode) may be used as value of a
variable of this type. In functions expecting an bf(IOMode) argument the empty
set should not normally be specified. To specify multiple tt(IOMode) values
the tt(bit_or) operator should be used.
    )

manpagesection(PROCESS PARAMETERS)
    
When running a child process three process parameters may be specified: the
child streams to access from the tt(Process) object (as an bf(IOMode) value);
the way to locate or start the child program (as a bf(ProcessType) value); and
the maximum time (in seconds) the child program is allowed to run.nl()
    Unless specified otherwise, all the child's standard streams (standard
input, output and error) will be accessible from the tt(Parent) process; the
tt(PATH) environment variable will em(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.nl()
    Following the construction of a tt(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 tt(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.

manpagesection(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 em(back-tick)
(tt(`)). The back-ticks will be removed just before the specified program is
executed.

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

    itemization(
    itb(Process(std::string const &cmd = ""))
       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
tt(Process) object. Standard default values are used for the process
parameters (see section bf(PROCESS PARAMETERS)).

    itb(Process(IOMode mode, std::string const &cmd = ""))
        This constructor requires the specification of the object's initial
default bf(IOMode) setting and it can be used to specify the (initial part of
a) command to execute from a tt(Process) object. Standard default values
are used for the remaining two process parameters ((tt(NO_PATH)) and no time
limit imposed on the child process).

    itb(Process(IOMode mode, ProcessType type, std::string const &cmd = ""))
        This constructor requires the specification of the object's initial
default bf(IOMode) setting and tt(ProcessType) and it can be used to specify
the (initial part of a) command to execute from a tt(Process) object. By
default no time limit will be imposed upon the child process.

    itb(Process(IOMode mode, ProcessType type, size_t timeLimit, 
std::string const &cmd = ""))
        This constructor requires the specification of the object's initial
default bf(IOMode) setting, tt(ProcessType) and time limit imposed upon child
processes it can be used to specify the (initial part of a) command to execute
from a tt(Process) object. To prevent a time limit from being imposed upon the
child process specify a time limit of 0 (zero).

    )
    The class bf(Process) does not offer a copy constructor.

manpagesection(OVERLOADED OPERATORS)

    itemization(
    itb(Process &operator<<(Type value))
        This operator will insert tt(value) into the child's standard
input stream. I.e., the child process will read tt(value) from its standard
input. A value of any type that can be inserted into an tt(ostream) can be
inserted into a tt(Process) object. Nothing happens if the member is used when
the child process has terminated. The behavior of this operator is undefined
unless tt(IOMode CIN) was specified.

    itb(Process &operator>>(Type value))
        This operator will extract tt(value) from the child's standard output
stream and optionally (if tt(IOMode MERGE_COUT_CERR) was specified) from the
child's error stream. I.e., tt(value) may be extracted from tt(Process)
objects. A value of any type that can be extracted from an tt(istream)
can be extracted from a tt(Process) object. Nothing happens if the member is
used when the child process has terminated. The behavior of this operator is
undefined unless tt(IOMode COUT) or tt(MERGE_COUT_CERR) was specified.

    itb(Process &operator+=(std::string const &))
       This operator adds the provided tt(std::string) object to the command
specification currenly stored in a tt(Process) object. The currently stored
command specification may be redefined using the member tt(setCommand()) (see
below).  The member tt(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.

    itb(int operator=(std::string const &cmd))
       The tt(operator=()) member defines tt(cmd) as the  stored command in
a tt(Process) object.  If the command starts and ends with a em(back-tick)
(tt(`)) then the back-ticks are removed, and the resulting contents are
interpreted as a command to execute.nl()
    Next it will call tt(stop()) (see below) to end any ongoing process
followed by calling tt(start()) to execute the newly defined command using the
current default process parameters. It returns tt(stop())'s return value.

    itb(Process &operator()(iomode mode))
        This operator changes the tt(IOMode) of the next child process. It
returns the tt(Process) object allowing constructions like
        verb(
    process(COUT) = "/bin/cat"; 
        )
    to start a new child process with the specified tt(IOMode). 

    itb(Process &operator()(iomode mode, ProcessType type))
        This operator changes the tt(IOMode) and tt(ProcessType) process
parameters of the next child process.

    itb(Process &operator()(iomode mode, ProcessType type, size_t timeLimit))
        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.
       )

    The default overloaded assignment operator is not available.

manpagesection(MEMBERS)

    itemization(
    itb(bool active())
        This member returns tt(true) if the child process is currently running
and tt(false) if not. It is automatically called from the insertion and
extraction operators and from the tt(cerr()) member but is available as a
public member as well. It may terminate the child process if the child process
has timed out.

    itb(size_t available())
        This member returns immediately. Its return value indicates whether
any information can be obtained from the child process as value(s) from the
tt(enum ChildOutput). tt(NOTHING_AVAILABLE) is returned if no information is
ready for extraction. tt(CHILD_COUT) is returned if information from the child
process's standard output stream is available; tt(CHILD_CERR) is returned if
information from the child process's standard error stream is available;
tt(CHILD_COUT | CHILD_CERR) is returned if information from both the standard
output and standard error streams is available.

    itb(std::istream &cerr())
        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
tt(IOMode CERR) was specified for the currently running child process;
otherwise its behavior is undefined.

    itb(void close())
        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
tt(IOMode CIN) was specified for the currently running child process;
otherwise its behavior is undefined.

    itb(iomode ioMode() const)
        This member returns the current default tt(IOMode). Note that the
tt(actual) tt(IOMode) 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 tt(operator()) above).

    itb(ProcessType processType() const)
        This member returns the current default tt(ProcessType). Note that the
tt(actual) tt(ProcessType) 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 tt(operator()) above).

    itb(size_t timeLimit() const)
        This member returns the current default child process time limit. Note
that the tt(actual) 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 tt(operator()) above).

    itb(void setCommand(std::string const &cmd))
       The tt(setCommand()) member (re)defines the (initial part of a) command
specification currently stored in an tt(Process) object. When the program is
eventually started it may start and end with a em(back-tick) (tt(`)). The
back-ticks will be removed just before the specified program is executed.nl()
    The tt(setCommand()) member will em(not) start the specified command and
tt(operator+=()) 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.

    itb(void setIOMode(iomode mode))
        This member will change the current default tt(IOMode) process
parameter of child processes.

    itb(void setProcessType(ProcessType type))
        This member will change the current default tt(ProcessType) process
parameter of child processes.

    itb(void setTimeLimit(size_t timeLimit))
        This member will change the current default time limit process
parameter of child processes. No time limit will be imposed upon child
processes if tt(timeLimit 0) is specified.

    itb(int start())
        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 tt(start()) members,
the tt(system()) members, function call operator or various
tt(set-)members.nl()
    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
bf(sh)(1), the  tt(USE_SHELL ProcessType) or a tt(system()) member 
should be used.nl()
    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 tt(Process) object's tt(start()) or tt(stop()) members are called; when
the object's assignment operator is used; or when the object goes out of
scope.

    itb(int start(IOMode mode))
       The currently specified command is executed using the specified
tt(IOMode) rather than the currently specified default but otherwise using the
currently specified default process parameters. The specified tt(IOMode) will
only be used for the process executed by this tt(start()) member.

    itb(int start(IOMode mode, Program program))
       The currently specified command is executed using the specified
tt(IOMode) and tt(ProcessType) as well as the currently specified child
process time limit. The specified arguments will only be used for the process
executed by this tt(start()) member.

    itb(int start(IOMode mode, Program program, size_t timeLimit))
       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 tt(start()) member.

    itb(std::string const &str() const)
        This member returns the text of the command currently stored in the
tt(Process) object. It shows the command as it will be executed by
tt(start()), tt(system()) or the assignment operator. If the command's first
and last characters are back-ticks (tt(`)) then those back-ticks will be
removed when the command is actually executed.

    itb(void system())
        This member executes the currently stored command as a command to
bf(sh)(1) (therefore executing the command as a shell command).  When using
tt(system()) redirections can be included in the command itself (although this
might render the redirected streams implied by the current bf(IOMode))
useless. The currently set process parameters are used when bf(sh)(1) is
executed.  Calling tt(system()) implies calling tt(start()).

    itb(void system(IOMode mode))
        This member executes the currently stored command as a command to
bf(sh)(1) (cf. tt(system()) above) using the specified tt(IOMode) rather than
the current default tt(IOMode) setting. The currently specified default time
limit, however, will be used when executing the bf(sh)(1) process.

    itb(void system(IOMode mode, size_t timeLimit))
        This member executes the currently stored command as a command to
bf(sh)(1) (cf. tt(system()) above) using the specified tt(IOMode) and time
limit values rather than their current default settings.

    itb(int stop())
       This member terminates a currently active child process. The child
process is twice sent a tt(SIG_TERM) signal, followed by a tt(SIG_KILL)
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. nl()
    Following tt(stop()) a new command may be called using tt(start(),
system()) or the assignment operator (see earlier). Those members will first
call tt(stop()) so when the intention is to start another child process
calling tt(stop()) can be skipped. Also, tt(stop()) is called when the
tt(Process) object goes out of scope.

    itb(int waitForChild())
        This member is inherited from the class tt(FBB::Fork) and will wait
for a child process to finish. It can be used to prevent premature termination
of a child process before calling tt(stop()). It is not always required to use
tt(waitForChild()). 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 tt(waitForChild()). 

    )

manpagesection(EXAMPLE)
        verbinclude(../../process/driver/driver.cc)

manpagefiles()
    em(bobcat/process) - defines the class interface

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

manpagebugs()
    With the release of Bobcat 1.21.1 the class tt(Process) was completely
rewritten. The new implementation, however, should not affect existing
programs other than that tt(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 tt(Process)
class em(has) changed though, requiring recompilation of sources defining
tt(Process) class type objects and linking dynamically to the tt(Bobcat)
library. 

includefile(trailer.inc)