Provided by: libbobcat-dev_4.08.02-2build1_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.
              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).