FBB::Redirector - Redirects a file descriptor to another descriptor
#include <bobcat/redirector>
Linking option:
-lbobcat
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.
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace
FBB.
-
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.
- 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.
Copy and move constructors (and assignment operators) are available.
- 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.
#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;
}
bobcat/redirector - defines the class interface
bobcat(7),
dup2(2),
execl(3)
None Reported.
- o
-
https://fbb-git.gitlab.io/bobcat/: gitlab project
page;
- o
-
bobcat_6.02.02-x.dsc: detached signature;
- o
-
bobcat_6.02.02-x.tar.gz: source archive;
- o
-
bobcat_6.02.02-x_i386.changes: change log;
- o
-
libbobcat1_6.02.02-x_*.deb: debian package
containing the libraries;
- o
-
libbobcat1-dev_6.02.02-x_*.deb: debian package
containing the libraries, headers and manual pages;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU General Public
License (GPL).
Frank B. Brokken (
[email protected]).