.TH "FBB::Redirector" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "System Level File Redirection" .PP .SH "NAME" FBB::Redirector \- Redirects a file descriptor to another descriptor .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" Objects of the class \fBFBB::Redirector\fP set up a system level file redirection, using file descriptors rather than streams\&. \fIRedirector\fP objects are effectively \fIwrappers\fP around the \fBdup2\fP(2) system call\&. System level redirection allows the programmer to send output to, e\&.g\&., the standard output stream, which actually appears at another stream (e\&.g\&., the standard error)\&. .PP \fIRedirector\fP objects are used to redirect the output sent to a stream having file descriptor \fIx\fP to another stream having file descriptor \fIy\fP, much like the shell\(cq\&s \fI>\fP operator redirects the standard output to some file\&. .PP \fIRedirector\fP objects can also be used to extract the information from a stream having file descriptor \fIx\fP in fact from another stream having file descriptor \fIy\fP, much like the shell\(cq\&s \fI<\fP operator is used to read the information in some file from the standard input\&. .PP Redirection using \fIRedirector\fP objects represents a stronger form of redirection than redirection offered by \fBC++\fP itself, which uses \fIstd::streambuf\fP redirection, and which is, because of that, bound to the program\(cq\&s scope\&. System level redirection, on the other hand, is applied at the system level, allowing the programmer to redirect standard streams when starting a program\&. For example, the standard error is commonly written to the standard output using an invocation like \fIprogram 2>&1\fP\&. .PP When constructing \fIRedirector\fP objects a file descriptor is required\&. The file descriptor specified at the constructor is the file descriptor that is used by the program to read information from or to write information to\&. Another file descriptor is required to set up the redirection: the file descriptor used here is the file descriptor of the stream that actually holds the information which is extracted from the file descriptor that was passed to the \fIRedirector\fP\(cq\&s constructor; or it is the file descriptor of the stream receiving the information which is written to the stream having the file descriptor that was passed to the \fIRedirector\fP\(cq\&s constructor\&. .PP When a \fIRedirector\fP object goes out of scope, its file descriptor are left as\-is\&. In particular, note that no \fBclose\fP(2) operation is performed on the \fIRedirector\(cq\&s\fP file descriptors\&. After setting up redirection using the \fIRedirector\(cq\&s\fP member functions and passing the \fIRedirector\(cq\&s\fP file descriptors to code that uses the \fIRedirector\(cq\&s\fP descriptors, the \fIRedirector\fP object could in fact safely be destroyed\&. .PP Formally, file descriptors are not defined in \fBC++\fP, but they are available in many types of operating systems\&. In those systems each `file\(cq\& has an associated `file descriptor\(cq\&\&. A file descriptor is an \fBint\fP, which is an index into the program\(cq\&s file allocation table, maintained by the system\&. Another type of well\-known entities which are file descriptors are \fIsockets\fP\&. .PP Well\-known filedescriptors (defined in, e\&.g\&., \fIunistd\&.h\fP) having fixed values are \fI\fP 0 (\fISTDIN_FILENO\fP), representing the standard input stream (\fIstd::cin\fP); \fI\fP 1, (\fISTDOUT_FILENO\fP), representing the standard output stream (\fIstd::cout\fP); \fI\fP 2, (\fISTDERR_FILENO\fP), representing the standard error stream (\fIcerr\fP); Notes: .IP o System\-level redirections are kept during system calls of the \fBexec\fP(3) family\&. .IP o Destroying a \fIRedirector\fP object does \fInot\fP undo the redirection set up by that object\&. .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" \- .PP .SH "ENUM" The enumeration \fBStandardFileno\fP holds the following values: .IP o \fISTDIN\fP (0) .IP o \fISTDOUT\fP (1) .IP o \fISTDERR\fP (2) These values may be used to set up a redirection instead of the plain numbers\&. .PP .SH "CONSTRUCTORS" .IP o \fBRedirector(int fd)\fP: .br This constructor expects the file descriptor of the file that will be used by the program to access (read, write) another file\&. The file descriptor that is passed to the constructor is used by the program, and will often be \fISTDIN, STDOUT\fP, or \fISTDERR\fP, allowing the program to use \fIcin, cout\fP, or \fIcerr\fP to extract information from, or insert information into other streams using its standard input and output streams\&. .PP Copy and move constructors (and assignment operators) are available\&. .PP .SH "MEMBER FUNCTIONS" .IP o \fBvoid swallow(int otherFd) const\fP: .br This member function expects a file descriptor which should become a synonym of the constructor\(cq\&s file descriptor\&. The constructor\(cq\&s file descriptor is redirected to \fIotherFd\fP\&. .IP After successfully calling \fIswallow\fP information written to \fIotherFd\fP is in fact written to the constructor\(cq\&s file descriptor\&. E\&.g\&., if the constructor\(cq\&s file descriptor represents a file on disk and \fIotherFd\fP is \fISTDOUT_FILENO\fP then all information sent to the standard output stream is actually sent to the file on disk: .nf information sent to otherFd \-> is received at the constructor\(cq\&s Fd (e\&.g\&., otherFd = STDOUT_FILENO) .fi Conversely, if the constructor\(cq\&s file descriptor represents a file on disk and \fIotherFd\fP is \fISTDIN_FILENO\fP then all information extracted from the standard input stream is actually read from the file on disk\&. .nf information extracted from otherFd <\- is read from the constructor\(cq\&s Fd (e\&.g\&., otherFd = STDIN_FILENO) .fi .IP Following \fIswallow\fP both file descriptors are open, and refer to the constructor\(cq\&s file descriptor\&. .IP Before setting up the redirection, the original \fIotherFd\fP is closed by \fBclose\fP(2)\&. Following \fIswallow\fP both file descriptors can be used, and refer to the constructor\(cq\&s file descriptor\&. If after calling \fIswallow\fP \fBclose\fP(2) is called for one of them, then the other one remains open\&. .IP If redirection fails an \fBFBB::Exception\fP object is thrown, whose \fIwhich()\fP member shows the system\(cq\&s \fIerrno\fP value set by the failing \fBdup2\fP(2) function\&. .IP .IP o \fBvoid through(int otherFd) const\fP: .br This member function expects a file descriptor which should become a synonym of the constructor\(cq\&s file descriptor\&. The constructor\(cq\&s file descriptor is redirected to \fIotherFd\fP\&. The constructor\(cq\&s file descriptor can no longer be used, as it is closed by \fBclose\fP(2)\&. .IP After successfully calling \fIthrough\fP information written to \fIotherFd\fP is in fact written to the constructor\(cq\&s file descriptor\&. E\&.g\&., if the constructor\(cq\&s file descriptor represents a file on disk and \fIotherFd\fP is \fISTDOUT_FILENO\fP then all information sent to the standard output stream is actually sent to the file on disk: .nf information sent to otherFd \-> is received at the constructor\(cq\&s Fd (e\&.g\&., otherFd = STDOUT_FILENO) .fi Conversely, if the constructor\(cq\&s file descriptor represents a file on disk and \fIotherFd\fP is \fISTDIN_FILENO\fP then all information extracted from the standard input stream is actually read from the file on disk\&. .nf information extracted from otherFd <\- is read from the constructor\(cq\&s Fd (e\&.g\&., otherFd = STDIN_FILENO) .fi Before setting up the redirection, the original \fIotherFd\fP is closed by \fBclose\fP(2)\&. Following \fIthrough\fP only \fIotherFd\fP can be used, and it refers to (i\&.e\&., reads or writes) the constructor\(cq\&s file descriptor\&. .IP If redirection fails an \fBFBB::Exception\fP object is thrown, whose \fIwhich()\fP member shows the system\(cq\&s \fIerrno\fP value set by the failing \fBdup2\fP(2) function\&. .PP .SH "EXAMPLE" .nf #include #include using namespace std; using namespace FBB; int main() { Redirector redirector(Redirector::STDOUT); redirector\&.swallow(Redirector::STDERR); cerr << \(dq\&This appears at the standard output stream\en\(dq\& \(dq\&use `a\&.out > /dev/null\(cq\& to suppress this message\(dq\& << endl; } .fi .PP .SH "FILES" \fIbobcat/redirector\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBdup2\fP(2), \fBexecl\fP(3) .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