Provided by: libbobcat-dev_5.11.01-1_amd64 
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.
Note that Pipe’s destructor does not close the pipe’s file descriptors. To close the pipes
close must be called.
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 closeWriteFd():
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.readFd() << "\n"
"Write file descriptor: " << p.writeFd() << 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 << "’\n";
getline(cin, s);
cout << "CHILD: Got `" << s << "’\n";
return 0;
}
p.writtenBy(STDOUT_FILENO); // write to the pipe via cout
cout << "first line" << "\n"
"second line" << ’\n’;
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.
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_5.11.01-x.dsc: detached signature;
o bobcat_5.11.01-x.tar.gz: source archive;
o bobcat_5.11.01-x_i386.changes: change log;
o libbobcat1_5.11.01-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_5.11.01-x_*.deb: debian package containing the libraries, headers
and manual pages;
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).