.TH "FBB::StdExtractor" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "Executing Child Processes"

.PP 
.SH "NAME"
FBB::StdExtractor \- Runs external programs writing standard error
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/cerrextractor>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
The \fBFBB::StdExtractor\fP class offers a basic interface for calling
external programs (so\-called \fIchild processes\fP) writing their standard
output and error streams\&. The standard input stream of the child processes are
by default not handled by \fIStdExtractor\fP objects\&. The child\(cq\&s standard
output and standard error streams are read through the \fIStdExtractor\fP
object: information written by the child process to these streams is extracted
or read from \fIStdExtractor\fP object\&. The \fIPATH\fP environment variable is not
used when calling child processes: child process programs must be specified
using paths\&.
.PP 
\fIStdExtractor\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 
\fBStdExtractor(size_t bufSize = 100)\fP:
.br 
A \fIbufSize\fP argument may be specified: it defines the internal
buffer size used by the \fIStdExtractor\(cq\&s\fP streambuf\&. By default the
stdandard input  stream is not handled\&.
.IP o 
\fBCoutExtractor(Mode mode, size_t bufSize = 100)\fP:
.br 
The \fImode\fP argument must be \fIStdExtractor::CLOSE_STD\fP\&. It indicates
that the standard input stream is redirected to \fI/dev/null\fP: the
child processes cannot read their standard input streams\&. 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 and standard error
streams may be extracted from the \fIStdExtractor\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 error output into the pipe\&.

.PP 
.SH "EXAMPLE"

.PP 
.nf 
#include <iostream>

#include <bobcat/cerrextractor>

using namespace std;
using namespace FBB;

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