includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Redirector)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (System Level File Redirection)

manpagename(FBB::Redirector)(Redirects a file descriptor to another descriptor)

manpagesynopsis()
    bf(#include <bobcat/redirector>)nl()
    Linking option: tt(-lbobcat)

manpagedescription()
    Objects of the class bf(FBB::Redirector) set up a system level file
redirection, using file descriptors rather than streams. tt(Redirector)
objects are effectively em(wrappers) around the bf(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).

    tt(Redirector) objects are used to redirect the output sent to a stream
having file descriptor tt(x) to another stream having file descriptor tt(y),
much like the shell's tt(>) operator redirects the standard output to some
file.

    tt(Redirector) objects can also be used to extract the information from a
stream having file descriptor tt(x) in fact from another stream having file
descriptor tt(y), much like the shell's tt(<) operator is used to read the
information in some file from the standard input.

Redirection using tt(Redirector) objects represents a stronger form of
redirection than redirection offered by bf(C++) itself, which uses
tt(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 tt(program 2>&1).

    When constructing tt(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 tt(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 tt(Redirector)'s
constructor.

    When a tt(Redirector) object goes out of scope, its file descriptor are
left as-is. In particular, note that no bf(close)(2) operation is performed on
the tt(Redirector's) file descriptors. After setting up redirection using the
tt(Redirector's) member functions and passing the tt(Redirector's) file
descriptors to code that uses the tt(Redirector's) descriptors, the
tt(Redirector) object could in fact safely be destroyed.

    Formally, file descriptors are not defined in bf(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 bf(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
em(sockets).

    Well-known filedescriptors (defined in, e.g., tt(unistd.h))
having fixed values are
    itemization(
    tt() 0 (tt(STDIN_FILENO)), representing the standard input stream
(tt(std::cin));
    tt() 1, (tt(STDOUT_FILENO)), representing the standard output stream
(tt(std::cout));
    tt() 2, (tt(STDERR_FILENO)), representing the standard error stream
(tt(cerr));
    )
    Notes:
    itemization(
    it() System-level redirections are kept during system calls of the
bf(exec)(3) family.
    it() Destroying a tt(Redirector) object does em(not) undo the
redirection set up by that object.
    )

includefile(include/namespace)

manpagesection(INHERITS FROM)
    -

manpagesection(ENUM)
    The enumeration bf(StandardFileno) holds the following values:
    itemization(
    itt(STDIN) (0)
    itt(STDOUT) (1)
    itt(STDERR) (2)
    )
    These values may be used to set up a redirection instead of the plain
numbers.

manpagesection(CONSTRUCTORS)
    itemization(
    itb(Redirector(int fd))
       The constructor's tt(fd) parameter is the file descriptor of the file
        containing or receiving information. It is commonly used by child
        processes of forking programs to allow the child processes to read 
        information from its standard input stream, to write information to
        its standard output stream, or to write its standard error stream to
        its standard output stream.nl()
       In forking programs tt(fd) is usually the reading or writing end of a
        pipe (cf. bf(pipe)(3bobcat)): when the child process reads its standard
        input stream and tt(pipe) is the used pipe object then
 verb(
    Redirector redir{ pipe.readOnly() };
 )
      prepares the child process for reading from the pipe via its standard
        input stream. Alternatively,
 verb(
    Redirector redir{ pipe.writeOnly() };
 )
       prepares it for writing to the pipe via, e.g., its standard output
        stream (see also the member tt(swallow)).
    )

    Copy and move constructors (and assignment operators) are available.

manpagesection(MEMBER FUNCTIONS)
    itemization(
    itb(void swallow(int otherFd) const)
       This member function expects a file descriptor which becomes a
        synonym of the constructor's file descriptor. The bf(Redirector)
        constructor's file descriptor is used when reading or writing to
        tt(otherFd).
       E.g., if a child process reads its information from its standard input
        stream, which information is in fact available at the file descriptor
        specified when constructing the bf(Redirector) object tt(redir) then
        use tt(redir.swallow(Redirector::STDIN)). Conversely, if the child
        process writes to its standard output stream which information should
        be sent to the bf(Redirector) object then use
        tt(redir.swallow(Redirector::STDOUT)) (see also the example,
        illustrating how to redirect the standard error stream's output to the
        standard output stream).

       The tt(swallow) member function first closes the original tt(otherFd)
        using bf(close)(2). Following tt(swallow) both file descriptors are
        open, and refer to the constructor's file descriptor. If, after
        calling tt(swallow), bf(close)(2) is called for one of them, then the
        other one remains open.

       If redirection fails an bf(FBB::Exception) object is thrown, whose
        tt(which()) member shows the system's tt(errno) value set by the
        failing bf(dup2)(2) function.

    itb(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 tt(otherFd). The constructor's file
        descriptor can no longer be used, as it is closed by bf(close)(2).

       After successfully calling tt(through) information written to
        tt(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 tt(otherFd) is tt(STDOUT_FILENO) then all information
        sent to the standard output stream is actually sent to the file on
        disk: 
 verb(
    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 tt(otherFd) is tt(STDIN_FILENO) then all information
        extracted from the standard input stream is actually read from the
        file on disk.
 verb(
    information extracted from otherFd <- is read from the
    constructor's Fd (e.g., otherFd = STDIN_FILENO)
            )
       Before setting up the redirection, the original tt(otherFd) is closed
        by bf(close)(2). Following tt(through) only tt(otherFd) can be used,
        and it refers to (i.e., reads or writes) the constructor's file
        descriptor.

       If redirection fails an bf(FBB::Exception) object is thrown, whose
        tt(which()) member shows the system's tt(errno) value set by the
        failing bf(dup2)(2) function.
    )

manpagesection(EXAMPLE)
    verb(
    #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;
    }
        )

manpagefiles()
    em(bobcat/redirector) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(dup2)(2), bf(execl)(3), bf(pipe)(3bobcat)

manpagebugs()
    None Reported.

includefile(include/trailer)
