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

libbobcat-dev_5.02.00-x.tar.gz                      2005-2019                                 FBB::Pipe(3bobcat)