pipe

FBB::Pipe(3bobcat)       System Level Communication Pipe      FBB::Pipe(3bobcat)



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 might even be
       destroyed. The using code is responsible for closing the pipe. If the
       pipe should be closed at destruction time, then a class could be derived
       from Pipe(3bobcat), whose destructor may then close the pipe.
       Alternatively, Pope’s close member can be called.

       The value -1 indicates that a file descriptor does not refer to a pipe(2)
       file descriptor.

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 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(Pipe &&tmp):
              The move constructor moves the temporary object’s file descriptors
              to the Pipe object being constructed.

       o      Pipe(int const *fd):
              This constructor expects two file descriptors, referring to the
              read and write file descriptors as returned by pipe(2).

       o      Pipe(bool initialize):
              This constructor can be used when the Pipe object should not be
              associated with an existing pipe. Instead it initializes its read
              and write file descriptors to -1. This constructor may be used in
              classes that define Pipe data members that only after the object
              is constructed can open their pipes. Having constructing a Pipe
              obj(false) object it can be associated with an open pipe using obj
              = Pipe{}. When passing the argument true it calls Pipe() to
              construct a pipe.


       The move constructor and move assignment operator are available. Copy
       construction and copy assignment are not defined.

MEMBER FUNCTIONS
       o      void close():
              Both file descriptors of the Pipe object are closed;

       o      void closeReadFd():
              The file descriptor of the Pipe object that is associated with the
              reading end of the pipe is closed;

       o      void close WriteFd():
              The file descriptor of the Pipe object that is associated with the
              writing end of the pipe is closed;

       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      void swap(Pipe &other):
              The current and other Pipe objects are swapped. Following this
              call the current Pipe objects refer to the other object’s pipe
              file descriptors and vice versa.

       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 MEMBER FUNCTION
       o      void close(RW rw):
              When passing argument RW::READ to this member the reading end of
              the Pipe object’s pipe is closed. When passing argument RW::WRITE
              the writing end of the Pipe object’s pipe is closed.


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.05.00-x.dsc: detached signature;

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

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

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

       o      libbobcat1-dev_5.05.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.05.00-x.tar.gz      2005-2020                 FBB::Pipe(3bobcat)