/usr/share/doc/libbobcat3-dev/man/pipe.3.html is in libbobcat-dev 3.19.01-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 | <html><head>
<title>FBB::Pipe</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Pipe</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz</h2>
<h2>2005-2013</h2>
<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>
<html><head>
<title>FBB::Pipe(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Pipe(3bobcat)</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz System Level Communication Pipe</h2>
<h2>2005-2013</h2>
<p>
<h2>NAME</h2>FBB::Pipe - Defines a system level communication pipe
<p>
<h2>SYNOPSIS</h2>
<strong>#include <bobcat/pipe></strong><br>
Linking option: <em>-lbobcat</em>
<p>
<h2>DESCRIPTION</h2>
<strong>FBB::Pipe</strong> objects may be used to construct a <em>pipe</em>. <em>Pipe</em>
objects offer a simple interface to the reading and writing ends of
pipes. <em>Pipe</em> objects are object-wrappers around the <strong>pipe</strong>(2) system
call.
<p>
A <em>Pipe</em> 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 <em>writtenBy</em>
member). The information appearing at the reading end of the pipe can then be
extracted using, e.g., an <em>IFdStream</em> object, initialized with the
<em>Pipe</em>'s reading file descriptor, or the reading end of the pipe can be
redirected to an existing stream whose file descriptor is known, like <em>cin</em>
(which uses the <em>STDIN_FILENO</em> file descriptor).
<p>
When a <em>Pipe</em> object goes out of scope, no <strong>close</strong>(2) operation is
performed on the pipe's file descriptors. After setting up the pipe using the
<em>Pipe's</em> member functions and passing the <em>Pipe's</em> file descriptors to
code that uses the <em>Pipe's</em> descriptors, the <em>Pipe</em> object could in fact
safely be destroyed. If the pipe should be closed at destruction time, a class
could be derived from <strong>Pipe</strong>(3bobcat), whose destructor performs the
required closing-operation.
<p>
<h2>NAMESPACE</h2>
<strong>FBB</strong><br>
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
-
<p>
<h2>CONSTRUCTORS</h2>
<ul>
<li> <strong>Pipe()</strong>:<br>
The default <em>Pipe</em> constructor constructs a basic pipe, calling
<strong>pipe</strong>(2).
<p>
This constructor throws an <em>Exception</em> exception if the default <em>Pipe</em>
constructor did not properly complete. The thrown <strong>Exception</strong> object's
<em>which()</em> member shows the system's <em>errno</em> value set by the failing
<strong>pipe</strong>(2) function.
<p>
<li> <strong>Pipe(int const *fd)</strong>:<br>
This constructor expects two file descriptors, which already define a
pipe, stored at <em>fd</em>. Following the construction of the <em>Pipe</em> object
the array at by <em>fd</em> is no longer used by the <em>Pipe</em> object.
</ul>
The copy constructor is available.
<p>
<h2>MEMBER FUNCTIONS</h2>
<p>
<ul>
<li> <strong>int readFd() const</strong>:<br>
Returns the pipe's file descriptor that is used for reading
<p>
<li> <strong>void readFrom(int filedescriptor)</strong>:<br>
Sets up redirection from the internal <em>read</em> 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
<em>readFrom(STDIN_FILENO)</em> information inserted into the
write-end of the pipe can be retrieved from <em>cin</em>.
<p>
<li> <strong>void readFrom(int const *filedescriptors, size_t n)</strong>:<br>
Sets up redirection from the internal <em>read</em> filedescriptor to the
given filedescriptors: information is read from the <em>Pipe</em> object when
reading from any of the <strong>n</strong> provided filedescriptors (experimental).
<p>
<li> <strong>int readOnly()</strong>:<br>
Closes the writing end of the pipe, returns the reading end's file
descriptor. This member can be used, e.g., to construct an <em>IFdStream</em>
object to extract the information that is inserted into the write-end of the
pipe.
<p>
<li> <strong>void verify() const</strong>:<br>
Obsoleted, can safely be removed from source files.
<p>
<li> <strong>int writeFd() const</strong>:<br>
Returns the pipe's file descriptor that is used for writing.
<p>
<li> <strong>void writtenBy(int filedescriptor)</strong>:<br>
Sets up redirection from the internal <em>write</em> filedescriptor to the
given filedescriptor: information is written to the <em>Pipe</em> object when
writing to the provided filedescriptor. E.g., after the call
<em>writtenBy(STDOUT_FILENO)</em> information sent to the standard output stream (by
either <em>cout</em> or by a child process (cf. <strong>exec</strong>(3))) is inserted into the
write-end of the pipe.
<p>
<li> <strong>void writtenBy(int const *filedescriptors, size_t n)</strong>:<br>
Sets up redirection from the internal <em>write</em> filedescriptor to the
given filedescriptors: information is inserted into the write-end of the
<em>Pipe</em> object when writing to each of the <strong>n</strong> provided filedescriptors.
E.g., when passing an array of two <em>int</em> values, respectively equal to
<em>STDOUT_FILENO</em> and <em>STDERR_FILENO</em> 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.
<p>
<li> <strong>int writeOnly()</strong>:<br>
Closes the reading end of the pipe, returns the writing end's file
descriptor.
</ul>
<p>
<h2>PROTECTED ENUMERATION</h2>
The <strong>RW</strong> protected enumeration has the following elements:
<p>
<ul>
<li> <strong>READ</strong>:<br>
The index in <strong>d_fd[]</strong> (see below) of the element holding the pipe's
reading file descriptor;
<p>
<li> <strong>WRITE</strong>:<br>
The index in <strong>d_fd[]</strong> (see below) of the element holding the pipe's
writing file descriptor
</ul>
<p>
<h2>PROTECTED DATA</h2>
<ul>
<li> <strong>int d_fd[2]</strong>:<br>
The array holding the pipe's file descriptors. The <strong>READ</strong> element
contains the pipe's reading file descriptor, the <strong>WRITE</strong> element
contains the pipe's writing file descriptor,
</ul>
<p>
<h2>EXAMPLE</h2>
<pre>
#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;
}
</pre>
<p>
<h2>FILES</h2>
<em>bobcat/pipe</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
<strong>bobcat</strong>(7), <strong>pipe</strong>(2), <strong>mkfifo</strong>(3)
<p>
<h2>BUGS</h2>
Note that when the pipe goes out of scope, no <strong>close</strong>(2) operation is
performed on the pipe's ends. If the pipe should be closed by the desctructor,
derive a class from <strong>Pipe</strong>(3bobcat), whose destructor performs the required
closing-operation.
<p>
<h2>DISTRIBUTION FILES</h2>
<ul>
<li> <em>bobcat_3.19.01-x.dsc</em>: detached signature;
<li> <em>bobcat_3.19.01-x.tar.gz</em>: source archive;
<li> <em>bobcat_3.19.01-x_i386.changes</em>: change log;
<li> <em>libbobcat1_3.19.01-x_*.deb</em>: debian package holding the
libraries;
<li> <em>libbobcat1-dev_3.19.01-x_*.deb</em>: debian package holding the
libraries, headers and manual pages;
<li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
</ul>
<p>
<h2>BOBCAT</h2>
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
This is free software, distributed under the terms of the
GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
|