FBB::Pipe(3bobcat)
System Level Communication Pipe
(libbobcat-dev_6.04.00)
2005-2023
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 object 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
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.
OVERLOADED OPERATOR
- Pipe &operator=(Pipe &&tmp):
The overloaded move assignment operator closes the current pipe and
moves tmp's pipes to the current Pipe object.
MEMBER FUNCTIONS
- void close():
Both file descriptors of the Pipe object are closed;
- void closeReadFd():
The file descriptor of the Pipe object that is associated with the
reading end of the pipe is closed;
- void closeWriteFd():
The file descriptor of the Pipe object that is associated with the
writing end of the pipe is closed;
- 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. The original read file
descriptor and the pipe's write file descriptor are closed.
- 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. The
original read file descriptor and the pipe's write file descriptor are
closed.
- 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 readOnlyFd():
Same as the previous member, but sets the internally used read file
descriptor to -1 (this member can be used to, e.g., pass the read file
descriptor to another object which eventually closes the pipe's
reading end).
- void reset():
Closes the the current pipe and reopens it with new pipe read and
write destriptors.
- void reset(int const *fds):
Closes the the current pipe and reopens it with the read and
write file destriptors provided by the first two elements of fds.
- 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.
- 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. The original write file
descriptor and the pipe's read file descriptor are closed.
- 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.
The original write file descriptor and the pipe's read file descriptor
are closed.
- int writeOnly():
Closes the reading end of the pipe, returns the writing end's file
descriptor.
- int writeOnlyFd():
Same as the previous member, but sets the internally used write file
descriptor to -1 (this member can be used to, e.g., pass the write file
descriptor to another object which eventually closes the pipe's
writing end).
PROTECTED ENUMERATION
The RW protected enumeration has the following elements:
- 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 MEMBER FUNCTION
- 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.
- int *fd():
Returns a pointer to the two file descriptors (respectively READ and
WRITE) currently used by the Pipe object.
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 pipe; // construct a pipe
cout << "Read file descriptor: " << pipe.readFd() << "\n"
"Write file descriptor: " << pipe.writeFd() << endl;
int pid = fork();
if (pid == -1)
return 1;
if (pid == 0) //child
{
pipe.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;
}
pipe.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 a Pipe object goes out of scope, no close(2)
operation is performed on the pipe's ends. If the pipe should be closed by the
destructor, derive a class from Pipe(3bobcat), whose destructor performs
the required closing-operation.
BOBCAT PROJECT FILES
- https://fbb-git.gitlab.io/bobcat/: gitlab project page;
- bobcat_6.04.00-x.dsc: detached signature;
- bobcat_6.04.00-x.tar.gz: source archive;
- bobcat_6.04.00-x_i386.changes: change log;
- libbobcat1_6.04.00-x_*.deb: debian package containing the
libraries;
- libbobcat1-dev_6.04.00-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).