Provided by: libbobcat-dev_4.08.02-2build1_amd64 
NAME
FBB::Redirector - Redirects a file descriptor to another descriptor
SYNOPSIS
#include <bobcat/redirector>
Linking option: -lbobcat
DESCRIPTION
Objects of the class FBB::Redirector set up a system level file redirection, using file
descriptors rather than streams. Redirector objects are effectively wrappers around the
dup2(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).
Redirector objects are used to redirect the output sent to a stream having file descriptor
x to another stream having file descriptor y, much like the shell’s > operator redirects
the standard output to some file.
Redirector objects can also be used to extract the information from a stream having file
descriptor x in fact from another stream having file descriptor y, much like the shell’s <
operator is used to read the information in some file from the standard input.
Redirection using Redirector objects represents a stronger form of redirection than
redirection offered by C++ itself, which uses std::streambuf redirection, and which is,
because of that, bound to the program’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 program 2>&1.
When constructing Redirector 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 Redirector’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 Redirector’s constructor.
When a Redirector object goes out of scope, its file descriptor are left as-is. In
particular, note that no close(2) operation is performed on the Redirector’s file
descriptors. After setting up redirection using the Redirector’s member functions and
passing the Redirector’s file descriptors to code that uses the Redirector’s descriptors,
the Redirector object could in fact safely be destroyed.
Formally, file descriptors are not defined in C++, but they are available in many types of
operating systems. In those systems each `file’ has an associated `file descriptor’. A
file descriptor is an int, which is an index into the program’s file allocation table,
maintained by the system. Another type of well-known entities which are file descriptors
are sockets.
Well-known filedescriptors (defined in, e.g., unistd.h) having fixed values are
0 (STDIN_FILENO), representing the standard input stream (std::cin);
1, (STDOUT_FILENO), representing the standard output stream (std::cout);
2, (STDERR_FILENO), representing the standard error stream (cerr); Notes:
o System-level redirections are kept during system calls of the exec(3) family.
o Destroying a Redirector object does not undo the redirection set up by that object.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
-
ENUM
The enumeration StandardFileno holds the following values:
o STDIN (0)
o STDOUT (1)
o STDERR (2) These values may be used to set up a redirection instead of the plain
numbers.
CONSTRUCTORS
o Redirector(int fd):
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 STDIN, STDOUT, or STDERR,
allowing the program to use cin, cout, or cerr to extract information from, or
insert information into other streams using its standard input and output streams.
The copy constructor is available.
MEMBER FUNCTIONS
o void swallow(int otherFd) const:
This member function expects a file descriptor which should become a synonym of the
constructor’s file descriptor. The constructor’s file descriptor is redirected to
otherFd.
After successfully calling swallow information written to otherFd is in fact
written to the constructor’s file descriptor. E.g., if the constructor’s file
descriptor represents a file on disk and otherFd is STDOUT_FILENO then all
information sent to the standard output stream is actually sent to the file on
disk:
information sent to otherFd -> is received at the constructor’s Fd
(e.g., otherFd = STDOUT_FILENO)
Conversely, if the constructor’s file descriptor represents a file on disk and
otherFd is STDIN_FILENO then all information extracted from the standard input
stream is actually read from the file on disk.
information extracted from otherFd <- is read from the constructor’s Fd
(e.g., otherFd = STDIN_FILENO)
Following swallow both file descriptors are open, and refer to the constructor’s
file descriptor.
Before setting up the redirection, the original otherFd is closed by close(2).
Following swallow both file descriptors can be used, and refer to the constructor’s
file descriptor. If after calling swallow close(2) is called for one of them, then
the other one remains open.
If redirection fails an FBB::Exception object is thrown, whose which() member shows
the system’s errno value set by the failing dup2(2) function.
o void through(int otherFd) const:
This member function expects a file descriptor which should become a synonym of the
constructor’s file descriptor. The constructor’s file descriptor is redirected to
otherFd. The constructor’s file descriptor can no longer be used, as it is closed
by close(2).
After successfully calling through information written to otherFd is in fact
written to the constructor’s file descriptor. E.g., if the constructor’s file
descriptor represents a file on disk and otherFd is STDOUT_FILENO then all
information sent to the standard output stream is actually sent to the file on
disk:
information sent to otherFd -> is received at the constructor’s Fd
(e.g., otherFd = STDOUT_FILENO)
Conversely, if the constructor’s file descriptor represents a file on disk and
otherFd is STDIN_FILENO then all information extracted from the standard input
stream is actually read from the file on disk.
information extracted from otherFd <- is read from the constructor’s Fd
(e.g., otherFd = STDIN_FILENO)
Before setting up the redirection, the original otherFd is closed by close(2).
Following through only otherFd can be used, and it refers to (i.e., reads or
writes) the constructor’s file descriptor.
If redirection fails an FBB::Exception object is thrown, whose which() member shows
the system’s errno value set by the failing dup2(2) function.
EXAMPLE
#include <iostream>
#include <bobcat/redirector>
using namespace std;
using namespace FBB;
int main()
{
Redirector redirector(Redirector::STDOUT);
redirector.swallow(Redirector::STDERR);
cerr << "This appears at the standard output stream\n"
"use `a.out > /dev/null’ to suppress this message" << endl;
}
FILES
bobcat/redirector - defines the class interface
SEE ALSO
bobcat(7), dup2(2), execl(3)
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).