FBB::Redirector(3bobcat)				   System Level File Redirection				  FBB::Redirector(3bobcat)

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. FBB::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). It is a stronger form of redirection than
       the standard one offered by C++, 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 FBB::Redirector objects a file descriptor is required, and another file descriptor is required when  defining	the  redi-
       rection.  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 redirection outlives system calls from the execl(3) family.

       o      Destroying a FBB::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 in the program to access (read, write) another file.  The
	      copy constructor is available.

MEMBER FUNCTIONS

       o      void swallow(int otherFd) const:
	      This member function expects the file descriptor of the file that will be redirected. Redirection means that the descriptor provided
	      to  the constructor will be used when referring to the file descriptor provided to the swallow() member (see the example below).	If
	      the redirection fails an FBB::Errno 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  also redirects otherFd to the file descriptor provided to the constructor, but will also close the construc-
	      tor's file descriptor. After calling through the file referred to by the constructor's file descriptor can  only	be  accessed  from
	      otherFd. The file originally referred to by otherFd is not accessible anymore from the current process.

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
"
		       "use `a.out > /dev/null' to suppress this message" << endl;
	   }

FILES

       bobcat/redirector - defines the class interface

SEE ALSO

       bobcat(7), errno(3bobcat), dup2(2), execl(3)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_3.01.00-x.dsc: detached signature;

       o      bobcat_3.01.00-x.tar.gz: source archive;

       o      bobcat_3.01.00-x_i386.changes: change log;

       o      libbobcat1_3.01.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.01.00-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).

libbobcat1-dev_3.01.00-x.tar.gz 				     2005-2012						  FBB::Redirector(3bobcat)