FBB::Pipe(3bobcat)

System Level Communication Pipe
(libbobcat-dev_4.08.03-x.tar.gz)

2005-2018

NAME

SYNOPSIS

DESCRIPTION

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

INHERITS FROM

CONSTRUCTORS

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

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

MEMBER FUNCTIONS

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

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

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

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

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

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

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

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

PROTECTED ENUMERATION

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

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

PROTECTED DATA

• 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);
    
        return 0;
    }
        

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

FILES

SEE ALSO

BUGS

DISTRIBUTION FILES

• bobcat_4.08.03-x.dsc: detached signature;
• bobcat_4.08.03-x.tar.gz: source archive;
• bobcat_4.08.03-x_i386.changes: change log;
• libbobcat1_4.08.03-x_*.deb: debian package holding the libraries;
• libbobcat1-dev_4.08.03-x_*.deb: debian package holding the libraries, headers and manual pages;
• http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

COPYRIGHT

AUTHOR