.TH "FBB::CoutExtractor" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Executing Child Processes"

.PP 
.SH "NAME"
FBB::CoutExtractor \- Runs external programs writing standard output
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/coutextractor>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
The \fBFBB::CoutExtractor\fP class offers a basic interface for calling
external programs (so\-called \fIchild processes\fP) writing their standard
output streams\&. The standard input and standard error streams of the child
processes by default are not handled by \fICoutExtractor\fP objects\&. The child\(cq\&s
standard output is read through the \fICoutExtractor\fP object: information
written by the child process to its standard output stream is extracted or
read from \fICoutExtractor\fP object\&. The \fIPATH\fP environment variable is not
used when calling child processes: child process programs must be specified
using paths\&.
.PP 
\fICoutExtractor\fP objects may repeatedly be used to execute the same or
different child processes\&.
.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 
.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::IFdBuf\fP (private),
\fBstd::istream\fP
.PP 
.SH "CONSTRUCTOR"

.PP 
.IP o 
\fBCoutExtractor(size_t bufSize = 100)\fP:
.br 
A \fIbufSize\fP argument may be specified: it defines the internal buffer
size used by the \fICoutExtractor\(cq\&s\fP streambuf\&. By default the
stdandard input and standard error streams are not handled\&.
.IP o 
\fBCoutExtractor(Mode mode, size_t bufSize = 100)\fP:
.br 
The \fImode\fP argument must be \fICoutExtractor::CLOSE_STD\fP\&. It
indicates that the standard input and standard error streams are
redirected to \fI/dev/null\fP: the child processes cannot read their
standard input streams and any standard error 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 "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 written by
the child process to its standard output stream may be extracted from
the \fICoutExtractor\fP object\&.
.IP 
Once \fIexecute\fP has returned it can be called again, either using the
same or another command\&.
.IP 
Arguments passed to the program to be executed as child process may
optionally be specified using single or double quotes, as described in
this man\-page\(cq\&s DESCRIPTION section\&.
.IP 
.IP o 
\fBint ret() const\fP:
.br 
Once \fIexecute\fP has returned 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 &childOutPipe()\fP:
.br 
If derived classes need to override the redirections\-members then they
probabaly need access to the pipe written by the child process\&. This
member provides a reference to that pipe\&. By default the parent
process reads information from the pipe, while the child process
inserts its standard output into the pipe\&.

.PP 
.SH "EXAMPLE"

.PP 
.nf 
#include <iostream>

#include <bobcat/coutextractor>

using namespace std;
using namespace FBB;

int main()
{
    CoutExtractor extractor;

    extractor\&.execute(\(dq\&/bin/cat driver\&.cc\(dq\&);

    cout << extractor\&.rdbuf();

    cerr << \(dq\&Returning: \(dq\& << extractor\&.ret() << \(dq\&\en\(dq\&
            \(dq\&again:\en\(dq\&;


    extractor\&.execute(\(dq\&/bin/cat driver\&.cc\(dq\&);

    cout << extractor\&.rdbuf();

    cerr << \(dq\&Returning: \(dq\& << extractor\&.ret() << \(cq\&\en\(cq\&;

}

.fi 

.PP 
.SH "FILES"
\fIbobcat/coutextractor\fP \- provides the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBcerrextractor\fP(3bobcat), \fBcininserter\fP(3bobcat),
\fBexecl\fP(3), \fBexec\fP(3bobcat),
\fBfork\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_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.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