Provided by: libbobcat-dev_5.02.00-1build1_amd64 bug

NAME

       FBB::Pipe - Defines a system level communication pipe

SYNOPSIS

       #include <bobcat/pipe>
       Linking option: -lbobcat

DESCRIPTION

       FBB::Pipe  objects  may be used to construct a pipe. Pipe objects offer a simple interface
       to the reading and writing ends of pipes. Pipe  objects  are  object-wrappers  around  the
       pipe(2) system call.

       A  Pipe  which  is  created  just  before  a program forks can be used to set up a line of
       communication between the parent and child process. Information which is  written  by  the
       child  process  to  its standard output stream can be redirected to the writing end of the
       pipe (using the writtenBy member). The information appearing at the  reading  end  of  the
       pipe  can  then be extracted using, e.g., an IFdStream object, initialized with the Pipe’s
       reading file descriptor, or the reading end of the pipe can be redirected to  an  existing
       stream  whose  file  descriptor  is  known,  like  cin  (which  uses the STDIN_FILENO file
       descriptor).

       When a Pipe object goes out of scope, no close(2) operation is  performed  on  the  pipe’s
       file  descriptors. After setting up the pipe using the Pipe’s member functions and passing
       the Pipe’s file descriptors to code that uses the  Pipe’s  descriptors,  the  Pipe  object
       could  in  fact  safely  be destroyed. If the pipe should be closed at destruction time, a
       class could  be  derived  from  Pipe(3bobcat),  whose  destructor  performs  the  required
       closing-operation.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       -

CONSTRUCTORS

       o      Pipe():
              The default Pipe constructor constructs a basic pipe, calling pipe(2).

              This constructor throws an Exception exception if the default Pipe constructor  did
              not  properly  complete.   The  thrown  Exception object’s which() member shows the
              system’s errno value set by the failing pipe(2) function.

       o      Pipe(int const *fd):
              This constructor expects two file descriptors, which already define a pipe,  stored
              at  fd. Following the construction of the Pipe object the array pointed at by fd is
              no longer used by the Pipe object.

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

MEMBER FUNCTIONS

       o      int readFd() const:
              Returns the pipe’s file descriptor that is used for reading

       o      void readFrom(int filedescriptor):
              Sets  up  redirection  from  the  internal  read  filedescriptor   to   the   given
              filedescriptor:  information  written to the write-end of the pipe may be retrieved
              by extracting the information from the stream that is associated with the indicated
              file  descriptor. E.g., after the call readFrom(STDIN_FILENO) information  inserted
              into the write-end of the pipe can be retrieved from cin.

       o      void readFrom(int const *filedescriptors, size_t n):
              Sets  up  redirection  from  the  internal  read  filedescriptor   to   the   given
              filedescriptors:  information is read from the Pipe object when reading from any of
              the n provided filedescriptors (experimental).

       o      int readOnly():
              Closes the writing end of the pipe, returns the reading end’s file descriptor. This
              member  can  be  used,  e.g.,  to  construct  an  IFdStream  object  to extract the
              information that is inserted into the write-end of the pipe.

       o      int writeFd() const:
              Returns the pipe’s file descriptor that is used for writing.

       o      void writtenBy(int filedescriptor):
              Sets  up  redirection  from  the  internal  write  filedescriptor  to   the   given
              filedescriptor:  information  is   written  to  the Pipe object when writing to the
              provided filedescriptor. E.g., after the call writtenBy(STDOUT_FILENO)  information
              sent  to  the  standard  output  stream  (by either cout or by a child process (cf.
              exec(3))) is inserted into the write-end of the pipe.

       o      void writtenBy(int const *filedescriptors, size_t n):
              Sets  up  redirection  from  the  internal  write  filedescriptor  to   the   given
              filedescriptors: information is inserted into the write-end of the Pipe object when
              writing to each of the n provided filedescriptors.  E.g., when passing an array  of
              two  int  values,  respectively  equal  to  STDOUT_FILENO and STDERR_FILENO to this
              member, all information which is thereafter sent to the standard  output  or  error
              streams is inserted into the write-end of the pipe.

       o      int writeOnly():
              Closes the reading end of the pipe, returns the writing end’s file descriptor.

PROTECTED ENUMERATION

       The RW protected enumeration has the following elements:

       o      READ:
              The  index  in  d_fd[]  (see  below) of the element holding the pipe’s reading file
              descriptor;

       o      WRITE:
              The index in d_fd[] (see below) of the element  holding  the  pipe’s  writing  file
              descriptor

PROTECTED DATA

       o      int d_fd[2]:
              The array holding the pipe’s file descriptors. The READ element contains the pipe’s
              reading file descriptor,  the  WRITE  element  contains  the  pipe’s  writing  file
              descriptor,

EXAMPLE

           #include <bobcat/pipe>
           #include <sys/types.h>
           #include <sys/wait.h>
           #include <unistd.h>
           #include <iostream>
           #include <string>

           using namespace std;
           using namespace FBB;

           int main()
           {
               Pipe p;                         // construct a pipe

               cout << "Read file descriptor: " << p.getReadFd() << endl;
               cout << "Write file descriptor: " << p.getWriteFd() << endl;

               int pid = fork();

               if (pid == -1)
                   return 1;

               if (!pid)                       //child
               {
                   p.readFrom(STDIN_FILENO);   // read what goes into the pipe

                   string s;

                   getline(cin, s);
                   cout << "CHILD: Got `" << s << "’" << endl;

                   getline(cin, s);
                   cout << "CHILD: Got `" << s << "’" << endl;

                   return 0;
               }

               p.writtenBy(STDOUT_FILENO);      // write to the pipe via cout

               cout << "first line" << endl;
               cout << "second line" << endl;

               waitpid(pid, 0, 0);
           }

       See also the 2nd example at fork(3bobcat)

FILES

       bobcat/pipe - defines the class interface

SEE ALSO

       bobcat(7), fork(3bobcat), pipe(2), mkfifo(3)

BUGS

       Note  that  when  the  pipe  goes  out of scope, no close(2) operation is performed on the
       pipe’s ends. If the pipe should  be  closed  by  the  desctructor,  derive  a  class  from
       Pipe(3bobcat), whose destructor performs the required closing-operation.

DISTRIBUTION FILES

       o      bobcat_5.02.00-x.dsc: detached signature;

       o      bobcat_5.02.00-x.tar.gz: source archive;

       o      bobcat_5.02.00-x_i386.changes: change log;

       o      libbobcat1_5.02.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.02.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).