Provided by: libbobcat-dev_4.08.02-2build1_amd64 
NAME
FBB::CinInserter - Runs external programs reading standard input
SYNOPSIS
#include <bobcat/cininserter>
Linking option: -lbobcat
DESCRIPTION
The FBB::CinInserter 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’s standard input is provided through the CinInserter object:
information inserted into an CinInserter object is forwarded to the child process’s
standard input stream. The PATH environment variable is not used when calling child
processes: child process programs must be specified using paths.
CinInserter 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.
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 contents 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 @).
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’s input stream
after the child process has started. To solve this problem InterterFork offers an
overloaded execute member, passing information to the child process via a separate thread.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
FBB::Exec (private), FBB::OFdStreambuf (private), std::ostream.
CONSTRUCTOR
o CinInserter(size_t bufSize = 100):
A bufSize argument may be specified: it defines the internal buffer size used by
the CinInserter’s streambuf. By default the stdandard output and standard error
streams are not handled.
o CinInserter(Mode mode, size_t bufSize = 100):
The mode argument must be CinInserter::CLOSE_STD. It indicates that the standard
output and standard error streams are redirected to /dev/null: any standard output
generated by child processes is ignored. A bufSize argument may be specified: it
defines the internal buffer size used by the CinInserter’s streambuf.
DESTRUCTOR
The destructor ends the CinInserter’s child process, if it is still active.
MEMBERS
o void execute(std::string const &cmd):
The argument specifies the command to execute: the command itself must be specified
as a path (the PATH environment variable isn’t used). This member immediately
returns, after which information can be inserted into the CinInserter object which
is then forwarded to the childprocess’s standard input stream.
Once all information has been inserted, the child process’s standard input stream
must be closed. This is realized by either calling stop or by calling execute once
again, or by ending the CinInserter object’s lifetime.
Arguments specified in the cmd string are passed to the child process, and may
optionally be specified using single or double quotes, as described in this
man-page’s DESCRIPTION section.
o bool execute(std::string const &cmd, std::string const &text):
This member is used to forward a limited amount of information (contained in the
text parameter) to the child process specified at cmd (defined identically as the
cmd parameter of the previous execute member).
This member returns true if the child process’s exit value equals 0.
o int stop():
This function can be called after all information has been inserted into the
CinInserter object to close the child process’s standard input stream. It is not
required after calling execute(cmd, text), or when calling execute again, or when
the CinInseror object’s lifetime ends.
This member returns the exit code of the last executed child process, which may
also be obtained from the next member:
o int ret() const:
Once a child process has finished this member provides the actual exit code of the
child process. Its value equals -1 before the first exectue call.
PROTECTED MEMBER
o Pipe &childInPipe():
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.
EXAMPLE
//#include <bobcat/cininserter>
#include "../cininserter"
#include <iostream>
#include <fstream>
using namespace std;
using namespace FBB;
int main()
{
CinInserter inserter;
inserter.execute("/bin/cat");
ifstream in("build");
inserter << in.rdbuf();
cout << "child returns: " << inserter.stop() << ’\n’;
inserter.execute("/bin/cat");
in.seekg(0); // reset to the beginning
inserter << in.rdbuf();
// when immediately followed by another execute, ’stop’ is optional
inserter.execute("/bin/cat", "a simple text\n");
inserter.execute("/bin/cat", "a simple text\n");
bool bret = inserter.execute("/bin/cat", "a simple text\n");
cout << "direct string insertion: " << bret << ’\n’;
}
FILES
bobcat/cininserter - provides the class interface
SEE ALSO
bobcat(7), cerrextractor(3bobcat), coutextractor(3bobcat), execl(3), exec(3bobcat),
fork(3bobcat), pipe(3bobcat), process(3bobcat), stdextractor(3bobcat).
BUGS
None reported.
DISTRIBUTION FILES
o bobcat_4.08.02-x.dsc: detached signature;
o bobcat_4.08.02-x.tar.gz: source archive;
o bobcat_4.08.02-x_i386.changes: change log;
o libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.08.02-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
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).