--- name: "pipe" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/pipe/3bobcat" --- # pipe(3bobcat) Defines a system level communication pipe ## NAME FBB::Pipe - Defines a system level communication pipe ## SYNOPSIS **#include \**\ 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)](/pipe/2.md) 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)](/close/2.md) 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)](/pipe/2.md) 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)](/pipe/2.md). - 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)](/pipe/2.md) 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)](/pipe/2.md). - - o **Pipe(bool initialize)**:\ This constructor can be used when the *Pipe* object should not be associated with an existing pipe. Instead when, *initialize ==* *false*, it initializes its read and write file descriptors to -1. This constructor may be used by classes that define *Pipe* data members which can only open their pipes after the object has been constructed. Having constructing a *Pipe obj{ false }* object it can be associated with an open pipe using *obj = Pipe{}*. or *obj.reset()*. When passing the argument *true* it initializes its pipe (cf. [**pipe**(2)](/pipe/2.md)). 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 - o **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 - 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*. The original read file descriptor and the pipe’s write file descriptor are closed. - - 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. The original read file descriptor and the pipe’s write file descriptor are closed. - - 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 **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). - - o **void reset()**:\ Closes the the current pipe and reopens it with new pipe read and write destriptors. - - o **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*. - - 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)](/exec/3.md))) is inserted into the write-end of the pipe. The original write file descriptor and the pipe’s read file descriptor are closed. - - 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. The original write file descriptor and the pipe’s read file descriptor are closed. - - o **int writeOnly()**:\ Closes the reading end of the pipe, returns the writing end’s file descriptor. - - o **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: - 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. - - o **int \*fd()**:\ Returns a pointer to the two file descriptors (respectively READ and WRITE) currently used by the *Pipe* object. ## EXAMPLE ``` #include #include #include #include #include #include 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)](/fork/3bobcat.md) ## FILES *bobcat/pipe* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**fork**(3bobcat)](/fork/3bobcat.md), [**pipe**(2)](/pipe/2.md), [**mkfifo**(3)](/mkfifo/3.md) ## BUGS Note that when a *Pipe* object goes out of scope, no [**close**(2)](/close/2.md) 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 - o *https://fbb-git.gitlab.io/bobcat/*: gitlab project page; Debian Bobcat project files: - o *libbobcat6*: debian package containing the shared library, changelog and copyright note; - o *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info; ## 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**).