/usr/share/doc/libbobcat3-dev/man/sharedsegment.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 | <html><head>
<title>FBB::SharedSegment</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::SharedSegment</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::SharedSegment(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::SharedSegment(3bobcat)</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz Shared Memory Data</h2>
<h2>2005-2013</h2>
<p>
<h2>NAME</h2>FBB::SharedSegment - Shared Memory data structure
<p>
<h2>SYNOPSIS</h2>
<strong>#include <bobcat/sharedsegment></strong><br>
Linking option: <em>-lbobcat </em>
<p>
<h2>DESCRIPTION</h2>
<p>
The class <strong>FBB::SharedSegment</strong> implements the shared memory data
structure which is used by Bobcat's shared memory classes. Bobcat's
<em>SharedMemory</em> class accesses or defines a shared memory segment which is
interpreted as an <em>FBB::SharedSegment</em> object. The total amount of requested
shared memory is always a lower bound to the actual amount of shared memory
that eventually may become available. As a fictitious example: assume 100 kB
of memory is requested, then the <strong>FBB::SharedSegment</strong> object, maintains a
table of, e.g., 10 entries, each controlling the access to a shared memory
block of 10 kB. These 10 kB blocks aren't immediately allocated, but become
available once the program reads from or writes to addresses located in these
data segments.
<p>
The class <strong>FBB::SharedSegment</strong> therefore defines a gateway, controlling
access to and allocating the shared memory data segment. The mentioned table
consists of <em>nBlocks SharedBlock</em> (<strong>sharedblock</strong>(3bobcat)) values,
offering mutexes and IDs of shared data segments. As always, the mutexes
control which process has access to a particular block of shared data memory,
and the IDs are either -1, meaning that their shared memory data segments has
as not yet been defined, or they contain the IDs of defined shared memory data
segments.
<p>
The class <strong>FBB::SharedSegment</strong>'s sole responsibility is to offer the
framework as described. When used by a <em>FBB::SharedMemory</em> object different
processes may gain access to different parts of the shared memory data without
interfering each other's read and write actions.
<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>
<p>
No publicly accessible constructors have been defined for
<strong>FBB::SharedSegment</strong>. A static member function <em>create</em> (see below) is
available, returning a pointer to a shared memory segment, in which a
<strong>FBB::SharedSegment</strong> has been defined.
<p>
<h2>OVERLOADED OPERATORS</h2>
<ul>
<li> <strong>std::ostream &operator<<(std::ostream &out,
SharedSegment const &sharedData)</strong>:<br>
The overloaded insertion operator inserts basic statistics of the
shared memory data into the <em>ostream</em> object. Information about the
IDs of the shared segments, their sizes, the maximum number of shared
data segments and the number of bytes that can be read from the shared
memory are displayed.
<p>
<li> <strong>FBB::SharedBlock &operator[](size_t idx)</strong>:<br>
Table element <em>idx</em> of the table of <em>FBB::SharedBlock</em>
block IDs is returned. The behavior of the program is undefined if
<em>idx</em> is or exceeds <em>nBlocks()</em>.
<p>
</ul>
Overloaded move and copy assignment operators are not available.
<p>
<h2>MEMBER FUNCTIONS</h2>
<ul>
<li> <strong>size_t access() const</strong>:<br>
The access rights of the shared memory segment are returned as a number
which is usually interpreted as an octal value, using the well-known
(<strong>chmod</strong>(1)) way to define the access rights for the owner, the
group and others.
<p>
<li> <strong>void clear()</strong>:<br>
All the shared memory data blocks are unconditionally deleted and
<em>nReadable</em> returns 0 (the shared memory data blocks are not locked
prior to deleting them).
<p>
<li> <strong>void lock(size_t idx) const</strong>:<br>
Access to shared data segment <em>idx</em> is locked. This member itself
does not support recursive locking.
<p>
<li> <strong>size_t nBlocks() const</strong>:<br>
The number of shared memory data blocks that can be used by the
<strong>FBB::SharedSegment</strong> object is returned.
<p>
<li> <strong>int newData(size_t idx)</strong>:<br>
The ID of a newly created shared memory data segment is returned. The
ID is also stored in the table of shared memory data segments that is
maintained by the <strong>FBB::SharedSegment</strong> object.
<p>
<li> <strong>std::streamsize nReadable() const</strong>:<br>
The number of characters (bytes) that can be read from the beginning of
the shared memory is returned.
<p>
<li> <strong>void nReadableLock() const</strong>:<br>
When returning from this member function a lock has been obtained of
<strong>FBB::SharedSegment</strong>'s mutex controlling access the the object's
data member storing the number of characters that can be read from the
shared memory controlled by the <strong>FBB::SharedSegment</strong> object.
<p>
<li> <strong>void nReadableUnlock() const</strong>:<br>
This member function releases the lock previously acquired by
<em>nReadableLock</em>.
<p>
<li> <strong>size_t segmentSize() const</strong>:<br>
The size (in bytes) of the shared memory data blocks is returned. The
<strong>FBB::SharedSegment</strong> object can accomodate at most <em>segmentSize() *
nBlocks()</em> bytes.
<p>
<li> <strong>void unlock(size_t idx) const</strong>:<br>
Releases the lock on the shared memory data segment <em>idx</em>. If the
current process does not own the lock of shared memory data block
<em>idx</em> nothing happens and the function immediately returns.
<p>
<li> <strong>void updateNreadable(std::streamsize offset)</strong>:<br>
The number of bytes that can be retrieved from the shared memory is
updated to <em>max(nReadable(), offset)</em>.
</ul>
<p>
<h2>STATIC MEMBER FUNCTIONS</h2>
<p>
<ul>
<li> <strong>void *attach(int id)</strong>:<br>
The address of shared memory segment <em>id</em>, mapped to the calling
process's memory area, is returned.
<p>
<li> <strong>SharedSegment *create(int *id, size_t nBlocks, size_t segmentSize,
size_t access)</strong>:<br>
This member returns a pointer to a new <strong>FBB::SharedSegment</strong> object,
defined in the computer's shared memory, storing the shared memory's
ID at <em>*id</em>, and expecting the number of data blocks (<em>nBlocks</em>),
the size of these data blocks (<em>segmentSize</em>), and the shared
memory's access rights (<em>access</em>, using the well-known
(<strong>chmod</strong>(1)) way to define the access rights for the owner, the
group and others) as its arguments.
<p>
<li> <strong>void deleteSegment(int id)</strong>:<br>
The shared memory segment having ID <em>id</em> is deleted from memory.
<p>
<li> <strong>Type *detach(Type *sharedPtr, bool requireOK = true)</strong>:<br>
This member is defined as a member template. It expects a pointer to a
shared memory segment, previously mapped on the calling process's
memory space by <em>attach</em>, and detaches it from the process's memory
space, returning 0. By default, detaching the memory must succeed or a
<strong>FBB::Exception</strong> is thrown. Throwing an exception on failure can be
prevented by passing <em>false</em> as the member's second argument.
<p>
<li> <strong>size_t size(int id)</strong>:<br>
The size (in bytes) of shared memory data block having ID <em>id</em>
is returned. An <em>FBB::Exception</em> is thrown if the size of segment
<em>id</em> cannot be determined.
</ul>
<p>
<h2>EXAMPLE</h2>
See the <strong>sharedstream</strong>(3bobcat) man page.
<p>
<h2>FILES</h2>
<em>bobcat/sharedsegment</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
<strong>bobcat</strong>(7), <strong>chmod</strong>(1),
<strong>isharedstream</strong>(3bobcat),
<strong>osharedstream</strong>(3bobcat),
<strong>sharedblock</strong>(3bobcat),
<strong>sharedmemory</strong>(3bobcat),
<strong>sharedmutex</strong>(3bobcat),
<strong>sharedpos</strong>(3bobcat),
<strong>sharedstream</strong>(3bobcat),
<strong>sharedstreambuf</strong>(3bobcat)
<p>
<h2>BUGS</h2>
None Reported.
<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>
|