.TH "FBB::CinInserter" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Executing Child Processes"

.PP 
.SH "NAME"
FBB::CinInserter \- Runs external programs reading standard input
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/cininserter>\fP
.br 
Linking option: \fI\-lbobcat\fP 
.PP 
.SH "DESCRIPTION"
The \fBFBB::CinInserter\fP class offers a basic interface for calling
external programs (so\-called child processes) reading their standard input
streams\&. The standard output and standard error streams of the child processes
by default are not handled by ttCinInserter) objects\&. The child\(cq\&s standard
input is provided through the \fICinInserter\fP object: information inserted
into an \fICinInserter\fP object is forwarded to the child process\(cq\&s standard
input stream\&. The \fIPATH\fP environment variable is not used when calling child
processes: child process programs must be specified using paths\&.
.PP 
\fICinInserter\fP objects may repeatedly be used to execute the same or
different child processes\&. Before starting the next child process, the current
child process must have finished\&.
.PP 
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\&., \fI\e100\fP is converted to \fI@\fP)\&.
.PP 
When information of undetermined size or structure must be inserted into a
child process then the child process cannot determine when to stop\&. This
creates an interesting problem: the child process starts, and the parent
process must wait until its child process has finished processing its
input\&. But input can only be forwarded to the child\(cq\&s input stream after the
child process has started\&. To solve this problem \fIInterterFork\fP offers an
overloaded \fIexecute\fP member, passing information to the child process via a
separate thread\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fBFBB::Exec\fP (private),
\fBFBB::OFdBuf\fP (private),
\fBstd::ostream\fP\&.
.PP 
.SH "CONSTRUCTOR"

.PP 
.IP o 
\fBCinInserter(size_t bufSize = 100)\fP:
.br 
A \fIbufSize\fP argument may be specified: it defines the internal buffer
size used by the \fICinInserter\(cq\&s\fP streambuf\&. By default the stdandard
output and standard error streams are not handled\&.
.IP o 
\fBCinInserter(Mode mode, size_t bufSize = 100)\fP:
.br 
The \fImode\fP argument must be \fICinInserter::CLOSE_STD\fP\&. It indicates
that the standard output and standard error streams are redirected to
\fI/dev/null\fP: any standard output generated by child processes is
ignored\&. A \fIbufSize\fP argument may be specified: it defines the
internal buffer size used by the \fICinInserter\(cq\&s\fP streambuf\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "DESTRUCTOR"

.PP 
The destructor ends the \fICinInserter\(cq\&s\fP child process, if it is still
active\&. 
.PP 
.SH "MEMBERS"

.PP 
.IP o 
\fBvoid execute(std::string const &cmd)\fP:
.br 
The argument specifies the command to execute: the command itself must
be specified as a path (the \fIPATH\fP environment variable isn\(cq\&t used)\&.  This
member immediately returns, after which information can be inserted into the
\fICinInserter\fP object which is then forwarded to the childprocess\(cq\&s standard
input stream\&. See also the description of the next (overloaded \fIexecute\fP)
member function\&.
.IP 
Once all information has been inserted, the child process\(cq\&s standard input
stream must be closed\&. This is realized by either calling \fIstop\fP; by
calling \fIexecute\fP once again; or by ending the \fICinInserter\fP object\(cq\&s
lifetime\&.
.IP 
Arguments specified in the \fIcmd\fP string are passed to the child process, and
may optionally be specified using single or double quotes, as described in
this man\-page\(cq\&s DESCRIPTION section\&.
.IP 
.IP o 
\fBbool execute(std::string const &cmd, std::string const &text)\fP:
.br 
This member is used to forward a limited amount of information
(contained in the \fItext\fP parameter) to the child process specified at
\fIcmd\fP (defined identically as the \fIcmd\fP parameter of the previous
\fIexecute\fP member)\&.
.IP 
This member returns \fItrue\fP if the child process\(cq\&s exit value equals 0\&.
.IP 
.IP o 
\fBint stop()\fP:
.br 
This function can be called after all information has been inserted
into the \fICinInserter\fP object to close the child process\(cq\&s standard input
stream\&. It is not required after calling \fIexecute(cmd, text)\fP, or when
calling \fIexecute\fP again, or when the \fICinInseror\fP object\(cq\&s lifetime ends\&.
.IP 
This member returns the exit code of the last executed child process,
which may also be obtained from the next member:
.IP 
.IP o 
\fBint ret() const\fP:
.br 
Once a child process has finished this member provides the actual exit
code of the child process\&. Its value equals \-1 before the first \fIexectue\fP
call\&.

.PP 
.SH "PROTECTED MEMBER"

.PP 
.IP o 
\fBPipe &childInPipe()\fP:
.br 
If derived classes need to override the redirections\-members then they
probabaly need access to the pipe read by the child process\&. This
member provides a reference to that pipe\&. By default the parent
process inserts information into the pipe, while the 
child process reads the inserted information from the pipe\&.

.PP 
.SH "EXAMPLE"

.PP 
.nf 
//#include <bobcat/cininserter>
#include \(dq\&\&.\&./cininserter\(dq\&

#include <iostream>
#include <fstream>

using namespace std;
using namespace FBB;

int main()
{
    CinInserter inserter;

    inserter\&.execute(\(dq\&/bin/cat\(dq\&);
    ifstream in(\(dq\&build\(dq\&);
    inserter << in\&.rdbuf();

    cout << \(dq\&child returns: \(dq\& << inserter\&.stop() << \(cq\&\en\(cq\&;

    inserter\&.execute(\(dq\&/bin/cat\(dq\&);
    in\&.seekg(0);                    // reset to the beginning
    inserter << in\&.rdbuf();

    // when immediately followed by another execute, \(cq\&stop\(cq\& is optional

    inserter\&.execute(\(dq\&/bin/cat\(dq\&, \(dq\&a simple text\en\(dq\&);
    inserter\&.execute(\(dq\&/bin/cat\(dq\&, \(dq\&a simple text\en\(dq\&);
    bool bret = inserter\&.execute(\(dq\&/bin/cat\(dq\&, \(dq\&a simple text\en\(dq\&);

    cout << \(dq\&direct string insertion: \(dq\& << bret << \(cq\&\en\(cq\&;
}

.fi 

.PP 
.SH "FILES"
\fIbobcat/cininserter\fP \- provides the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBcerrextractor\fP(3bobcat), \fBcoutextractor\fP(3bobcat), 
\fBexecl\fP(3), \fBexec\fP(3bobcat), 
\fBfork\fP(3bobcat), \fBpipe\fP(3bobcat), \fBprocess\fP(3bobcat), 
\fBstdextractor\fP(3bobcat)\&.
.PP 
.SH "BUGS"
None reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP