.TH "FBB::Pipe" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "System Level Communication Pipe"

.PP 
.SH "NAME"
FBB::Pipe \- Defines a system level communication pipe
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/pipe>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::Pipe\fP objects may be used to construct a \fIpipe\fP\&. \fIPipe\fP
objects offer a simple interface to the reading and writing ends of
pipes\&. \fIPipe\fP objects are object\-wrappers around the \fBpipe\fP(2) system
call\&.
.PP 
A \fIPipe\fP 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
\fIwrittenBy\fP member)\&. The information appearing at the reading end of the
pipe can then be extracted using, e\&.g\&., an \fIIFdStream\fP object, initialized
with the \fIPipe\fP\(cq\&s reading file descriptor, or the reading end of the pipe
can be redirected to an existing stream whose file descriptor is known, like
\fIcin\fP (which uses the \fISTDIN_FILENO\fP file descriptor)\&.
.PP 
When a \fIPipe\fP object goes out of scope, no \fBclose\fP(2) operation is
performed on the pipe\(cq\&s file descriptors\&. After setting up the pipe using the
\fIPipe\(cq\&s\fP member functions and passing the \fIPipe\(cq\&s\fP file descriptors to
code that uses the \fIPipe\(cq\&s\fP descriptors, the \fIPipe\fP 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
\fBPipe\fP(3bobcat), whose destructor may then close the pipe\&. Alternatively,
\fIPope\(cq\&s close\fP member can be called\&.
.PP 
The value \-1 indicates that a file descriptor does not refer to a
\fBpipe\fP(2) file descriptor\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\-
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBPipe()\fP:
.br 
The default \fIPipe\fP constructor constructs a pipe, calling
\fBpipe\fP(2)\&.
.IP 
This constructor throws an \fIException\fP exception if the default
\fIPipe\fP constructor did not properly complete\&.  The thrown
\fBException\fP object\(cq\&s \fIwhich()\fP member shows the system\(cq\&s \fIerrno\fP
value set by the failing \fBpipe\fP(2) function\&.
.IP 
.IP o 
\fBPipe(Pipe &&tmp)\fP:
.br 
The move constructor moves the temporary object\(cq\&s file descriptors to
the \fIPipe\fP object being constructed\&.
.IP 
.IP o 
\fBPipe(int const *fd)\fP:
.br 
This constructor expects two file descriptors, referring to the read
and write file descriptors as returned by \fBpipe\fP(2)\&.
.IP 
.IP o 
\fBPipe(bool initialize)\fP:
.br 
This constructor can be used when the \fIPipe\fP object should not be
associated with an existing pipe\&. Instead when, \fIinitialize ==
false\fP, it initializes its read and write file descriptors to \-1\&. This
constructor may be used by classes that define \fIPipe\fP data members
which can only open their pipes after the object has been
constructed\&. Having constructing a \fIPipe obj{ false }\fP object it can
be associated with an open pipe using \fIobj = Pipe{}\fP\&. or
\fIobj\&.reset()\fP\&. When passing the argument \fItrue\fP it initializes its
pipe (cf\&. \fBpipe\fP(2))\&.
Copy construction and copy assignment are not defined\&.
.PP 
Note that \fIPipe\(cq\&s\fP destructor does not close the pipe\(cq\&s file
descriptors\&. To close the pipes \fIclose\fP must be called\&.
.PP 
.SH "OVERLOADED OPERATOR"

.PP 
.IP o 
\fBPipe &operator=(Pipe &&tmp)\fP:
.br 
The overloaded move assignment operator closes the current pipe and
moves \fItmp\(cq\&s\fP pipes to the current \fIPipe\fP object\&.

.PP 
.SH "MEMBER FUNCTIONS"

.PP 
.IP o 
\fBvoid close()\fP:
.br 
Both file descriptors of the \fIPipe\fP object are closed;
.IP 
.IP o 
\fBvoid closeReadFd()\fP:
.br 
The file descriptor of the \fIPipe\fP object that is associated with the
reading end of the pipe is closed;
.IP 
.IP o 
\fBvoid closeWriteFd()\fP:
.br 
The file descriptor of the \fIPipe\fP object that is associated with the
writing end of the pipe is closed;
.IP 
.IP o 
\fBint readFd() const\fP:
.br 
Returns the pipe\(cq\&s file descriptor that is used for reading
.IP 
.IP o 
\fBvoid readFrom(int filedescriptor)\fP:
.br 
Sets up redirection from the internal \fIread\fP 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
\fIreadFrom(STDIN_FILENO)\fP information inserted into the write\-end of
the pipe can be retrieved from \fIcin\fP\&. The original read file
descriptor and the pipe\(cq\&s write file descriptor are closed\&.
.IP 
.IP o 
\fBvoid readFrom(int const *filedescriptors, size_t n)\fP:
.br 
Sets up redirection from the internal \fIread\fP filedescriptor to the
given filedescriptors: information is read from the \fIPipe\fP object
when reading from any of the \fBn\fP provided filedescriptors\&.  The
original read file descriptor and the pipe\(cq\&s write file descriptor are
closed\&.
.IP 
.IP o 
\fBint readOnly()\fP:
.br 
Closes the writing end of the pipe, returns the reading end\(cq\&s file
descriptor\&. This member can be used, e\&.g\&., to construct an
\fIIFdStream\fP object to extract the information that is inserted into
the write\-end of the pipe\&.
.IP 
.IP o 
\fBint readOnlyFd()\fP:
.br 
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\(cq\&s
reading end)\&.
.IP 
.IP o 
\fBvoid reset()\fP:
.br 
Closes the the current pipe and reopens it with new pipe read and
write destriptors\&.
.IP 
.IP o 
\fBvoid reset(int const *fds)\fP:
.br 
Closes the the current pipe and reopens it with the read and
write file destriptors provided by the first two elements of \fIfds\fP\&.
.IP 
.IP o 
\fBvoid swap(Pipe &other)\fP:
.br 
The current and other \fIPipe\fP objects are swapped\&. Following this
call the current \fIPipe\fP objects refer to the other object\(cq\&s pipe file
descriptors and vice versa\&.
.IP 
.IP o 
\fBint writeFd() const\fP:
.br 
Returns the pipe\(cq\&s file descriptor that is used for writing\&.
.IP 
.IP o 
\fBvoid writtenBy(int filedescriptor)\fP:
.br 
Sets up redirection from the internal \fIwrite\fP filedescriptor to the
given filedescriptor: information is written to the \fIPipe\fP object
when writing to the provided filedescriptor\&. E\&.g\&., after the call
\fIwrittenBy(STDOUT_FILENO)\fP information sent to the standard output
stream (by either \fIcout\fP or by a child process (cf\&. \fBexec\fP(3))) is
inserted into the write\-end of the pipe\&.  The original write file
descriptor and the pipe\(cq\&s read file descriptor are closed\&.
.IP 
.IP o 
\fBvoid writtenBy(int const *filedescriptors, size_t n)\fP:
.br 
Sets up redirection from the internal \fIwrite\fP filedescriptor to the
given filedescriptors: information is inserted into the write\-end of
the \fIPipe\fP object when writing to each of the \fBn\fP provided
filedescriptors\&.  E\&.g\&., when passing an array of two \fIint\fP values,
respectively equal to \fISTDOUT_FILENO\fP and \fISTDERR_FILENO\fP 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\(cq\&s read file descriptor
are closed\&.
.IP 
.IP o 
\fBint writeOnly()\fP:
.br 
Closes the reading end of the pipe, returns the writing end\(cq\&s file
descriptor\&.
.IP 
.IP o 
\fBint writeOnlyFd()\fP:
.br 
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\(cq\&s
writing end)\&.

.PP 
.SH "PROTECTED ENUMERATION"
The \fBRW\fP protected enumeration has the following elements:
.PP 
.IP o 
\fBREAD\fP:
.br 
The index in \fBd_fd[]\fP (see below) of the element holding the pipe\(cq\&s
reading file descriptor;
.IP 
.IP o 
\fBWRITE\fP:
.br 
The index in \fBd_fd[]\fP (see below) of the element holding the pipe\(cq\&s
writing file descriptor

.PP 
.SH "PROTECTED MEMBER FUNCTION"

.PP 
.IP o 
\fBvoid close(RW rw)\fP:
.br 
When passing argument RW::READ to this member the reading end of the
\fIPipe\fP object\(cq\&s pipe is closed\&. When passing argument RW::WRITE the
writing end of the \fIPipe\fP object\(cq\&s pipe is closed\&.
.IP 
.IP o 
\fBint *fd()\fP:
.br 
Returns a pointer to the two file descriptors (respectively READ and 
WRITE)  currently used by the \fIPipe\fP object\&.

.PP 
.SH "EXAMPLE"
.nf 

    #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 << \(dq\&Read file descriptor: \(dq\& << pipe\&.readFd() << \(dq\&\en\(dq\&
                \(dq\&Write file descriptor: \(dq\& << 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 << \(dq\&CHILD: Got `\(dq\& << s << \(dq\&\(cq\&\en\(dq\&;

            getline(cin, s);
            cout << \(dq\&CHILD: Got `\(dq\& << s << \(dq\&\(cq\&\en\(dq\&;

            return 0;
        }

        pipe\&.writtenBy(STDOUT_FILENO);      // write to the pipe via cout

        cout << \(dq\&first line\(dq\& << \(dq\&\en\(dq\&
                \(dq\&second line\(dq\& << \(cq\&\en\(cq\&;

        waitpid(pid, 0, 0);
    }
        
.fi 

.PP 
See also the 2nd example at \fBfork\fP(3bobcat)
.PP 
.SH "FILES"
\fIbobcat/pipe\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBfork\fP(3bobcat), \fBpipe\fP(2), \fBmkfifo\fP(3)
.PP 
.SH "BUGS"
Note that when a \fIPipe\fP object goes out of scope, no \fBclose\fP(2)
operation is performed on the pipe\(cq\&s ends\&. If the pipe should be closed by the
destructor, derive a class from \fBPipe\fP(3bobcat), whose destructor performs
the required closing\-operation\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.06\&.02\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP