Provided by: libbobcat-dev_6.03.02-2_amd64 bug

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.

       Copy and move constructors (and assignment operators) are 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.

BOBCAT PROJECT FILES

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_6.03.02-x.dsc: detached signature;

       o      bobcat_6.03.02-x.tar.gz: source archive;

       o      bobcat_6.03.02-x_i386.changes: change log;

       o      libbobcat1_6.03.02-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.03.02-x_*.deb: debian package containing  the  libraries,  headers
              and manual pages;

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).