/usr/share/doc/libbobcat2-dev/man/mstream.3.html is in libbobcat-dev 2.20.01-1.
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 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 | <html><head>
<title>FBB::Mstream</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Mstream</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz</h2>
<h2>2005-2011</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::Mstream(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Mstream(3bobcat)</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz Message handler</h2>
<h2>2005-2011</h2>
<p>
<h2>NAME</h2>FBB::Mstream - Generic message handling stream
<p>
<h2>SYNOPSIS</h2>
<strong>#include <bobcat/mstream></strong><br>
Linking option: <em>-lbobcat</em>
<p>
<h2>DESCRIPTION</h2>
Objects of this class may be used to handle messages in a standardized
way. Messages may be prefixed with order numbers and labels and/or line
numbers. Messages generated by <em>Mstream</em> objects may optionally end in
an exception, allowing simple implementation of, e.g., fatal error messages.
<p>
Four message streams are provided by the <em>BOBCAT</em> library and may be
used after including the <em>mstream</em> header file. They are all defined in the
<em>FBB</em> namespace:
<ul>
<li> <em>FBB::emsg</em> for generating standard (labeled and numbered) error
messages, e.g.
<pre>
[Error 1] this is an error message
</pre>
<li> <em>FBB::fmsg</em> for generating (labeled) fatal error messages, ending in an
exception, e.g.,
<pre>
[Fatal] this fatal message is followed by an exception
</pre>
<li> <em>FBB::imsg</em> for generating plain informational messages, e.g.,
<pre>
this is a plain message
</pre>
<li> <em>FBB::wmsg</em> for generating (labeled) warning messages;
<pre>
[Warning] this is a warning
</pre>
</ul>
By default all messages are inserted into the standard output stream, but
other destinations (standard error, a named file, etc.) can easily be
configured.
<p>
<em>Mstream</em> objects themselves are <em>std::ostream</em> objects, so they
can be used as objects passed to functions expecting <em>ostream</em>
arguments. Messages inserted into <em>Mstream</em> objects are buffered until
the buffer is flushed by their <em>std::ostream</em> parts or when either the
<em>FBB::endl</em> or <em>FBB::flush</em> is inserted into the message stream. Since
these manipulators act like <em>std::endl</em> and <em>std::flush</em> when inserted
into another kind of <em>std::ostream</em> object, <em>using FBB::endl</em> and <em>using
FBB::flush</em> might be worth considering. Also, when <em>using namespace std</em>
<em>and</em> <em>using namespace FBB</em> is specified the <em>FBB::endl</em> and
<em>FBB::flush</em> manipulator will automatically be used with <em>Mstream</em>
objects.
<p>
Messages inserted into <em>Mstream</em> objects are considered completed
at the insertion of the <em>FBB::endl</em> or <em>FBB::flush</em> manipulators. Message
labels, line number labels and line numbers will only be shown for the next
line after these manipulators have been inserted and exceptions are, if
needed, thrown from these manipulators.
<p>
<h2>NAMESPACE</h2>
<strong>FBB</strong><br>
All elements mentioned in this man-page, are defined in the namespace
<strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
<strong>std::ostream</strong>
<p>
<h2>CONSTRUCTORS</h2>
<ul>
<li> <strong>Mstream()</strong>:<br>
The default constructor generates messages using the
<em>std::streambuf</em> used by <em>std::cout</em>. There is no limit to the number of
messages that may be inserted. No message or line numbers are shown, no
exception are thrown when inserting messages.
<li> <strong>explicit Mstream(std::ostream &ostr, size_t maxCount = UINT_MAX,
std::string const &tag = "", bool throwing = false)</strong>:<br>
This constructor uses the <em>std::streambuf</em> that is also used by the
<em>ostream ostr</em>. By default (using the default argument values) there is no
limit to the number of messages that may be inserted. No message or line
numbers are shown, no exception are thrown when inserting messages. Specifying
any other value than <em>UINT_MAX</em> will set the maximum number of messages that
can be inserted to that value. The <em>tag</em> defines the text of the message
label (e.g., <em>Error</em>). When <em>throwing</em> is specified as <em>true</em> an
<em>FBB::Errno</em> exception is thrown after completing a message. The generated
exception holds the id (see below for the member <em>id</em>) of the
<em>Mstream</em> object from which the exception was thrown as well as the
text <em>FBB::Mstream</em>.
<li> <strong>explicit Mstream(std::streambuf &buf, size_t maxCount = UINT_MAX,
std::string const &tag = "", bool throwing = false)</strong>:<br>
This constructor uses <em>buf</em> to insert messages into. The remaining
parameters are identical to those of the previous constructor.
<li> <strong>explicit Mstream(std::string const &name, size_t maxCount = UINT_MAX,
std::string const &tag = "", bool throwing = false)</strong>:<br>
This constructor creates a <em>std::ofstream</em> from the provided
<em>name</em> parameter. It throws an <em>FBB::Errno</em> exception if the stream cannot
be opened for writing. If a file by that name already exists it is rewritten.
The remaining parameters are identical to those of the previous two
constructors.
</ul>
As <em>Mstream</em> inherits from <em>std::ostream</em> the copy constructor is
not available. Neither is the move constructor.
<p>
<h2>MEMBER FUNCTIONS</h2>
<p>
<ul>
<li> <strong>size_t count() const</strong>:<br>
returns the number of inserted messages (if <em>setCount</em> has been
called: the value set by the last <em>setCount</em> call plus the number of
inserted messages since that call).
<p>
<li> <strong>bool isActive() const</strong>:<br>
returns <em>true</em> if messages can actually be inserted into the
<strong>FBB::MStream</strong> object, and <em>false</em> if inserted messages are ignored. When
ignoring messages the message count is not updated.
<p>
<li> <strong>int id() const</strong>:<br>
returns the unique <em>id</em> of the <em>Mstream</em> object.
<p>
<li> <strong>bool lineExcess() const</strong>:<br>
returns <strong>true</strong> after attempting to insert an additional message
after <em>maxCount</em> number of messages have been inserted.
<p>
<li> <strong>std::string const &lineTag() const</strong>:<br>
returns the currently used line-tag (by default `<em>Line</em>').
<p>
<li> <strong>size_t maxCount() const</strong>:<br>
returns the maximum number of messages that can be inserted. If the
returned value equals <em>UINT_MAX</em> then there is no limit to the number of
messages that can be inserted.
<p>
<li> <strong>void noLineNr()</strong>:<br>
calling this member will suppress the display of a line number if it
is called after calling <em>setLineNr</em> (see below) but before a message is
being (or has been) inserted.
<p>
<li> <strong>void off()</strong>:<br>
after calling <em>off</em> messages inserted into the <em>Mstream</em>
object are silently ignored. After calling <em>off</em> the internal message
counter is not incremented when messages are inserted.
<p>
<li> <strong>void on()</strong>:<br>
by default and after calling <em>on</em> messages inserted into the
<em>Mstream</em> object are sent to their destination stream.
<p>
<li> <strong>void reset(std::ostream &ostr)</strong>:<br>
messages inserted into the <em>Mstream</em> object are handled by the
<em>std::streambuf</em> also used by <em>ostr</em>. Other parameters (e.g.,
<em>maxCount</em>, the message label) are kept as-is.
<p>
<li> <strong>void reset(std::streambuf *buf)</strong>:<br>
messages inserted into the <em>Mstream</em> object are handled by
<em>std::streambuf buf</em>. Other parameters (e.g., <em>maxCount</em>, the message
label) are kept as-is.
<p>
<li> <strong>void reset(FBB::Mstream const &mstream)</strong>:<br>
the current object is reset using the parameters of the <em>mstream</em>
parameter.
<p>
<li> <strong>void reset(std::string const &name, size_t maxCount,
std::string const &tag, bool throwing)</strong>:<br>
messages inserted into <em>Mstream</em> objects are handled by a
<em>std::ofstream</em> created using the provided <em>name</em> parameter.
<em>FBB::Errno</em> exception if the stream cannot be opened for writing. If a file
by that name already exists it is rewritten. Other parameters (e.g.,
<em>maxCount</em>, the message label) are kept as-is.
<p>
<li> <strong>void reset(std::ostream &ostr, size_t maxCount,
std::string const &tag, bool throwing)</strong>:<br>
messages inserted into <em>Mstream</em> objects are handled by the
<em>std::streambuf</em> also used by <em>ostr</em>. By specifying <em>UINT_MAX</em> for
<em>maxCount</em> there is no limit to the number of messages that may be handled
by this <em>std::streambuf</em>. The <em>tag</em> defines the text of the message label
(e.g., <em>Error</em> or the empty string for no message label). When <em>throwing</em>
is specified as <em>true</em> an <em>FBB::Errno</em> exception is thrown after
completing a message.
<p>
<li> <strong>void reset(std::streambuf *buf, size_t maxCount,
std::string const &tag, bool throwing)</strong>:<br>
messages inserted into <em>Mstream</em> objects are handled by
<em>std::streambuf buf</em>. The remaining parameters are identical to those of the
previous <em>reset</em> member.
<p>
<li> <strong>void reset(std::string const &name, size_t maxCount,
std::string const &tag, bool throwing)</strong>:<br>
messages inserted into <em>Mstream</em> objects are handled by a
<em>std::ofstream</em> created using the provided <em>name</em> parameter. It throws an
<em>FBB::Errno</em> exception if the stream cannot be opened for writing. If a file
by that name already exists it is rewritten. The remaining parameters are
identical to those of the previous two <em>reset</em> members.
<p>
<li> <strong>void reset(FBB::Mstream const &mstream)</strong>:<br>
the current object is reset using the parameters of the <em>mstream</em>
parameter. Following the reset all of the current object's parameters can
independently be modified from those used by <em>mstream</em>.
<p>
<li> <strong>bool setActive(bool ifTrue)</strong>:<br>
If <em>ifTrue</em> equals <em>true</em> the <em>Mstream</em> is activated
otherwise its actions are suppressed. Returns <em>ifTrue</em>.
<p>
<li> <strong>void setCount(size_t count)</strong>:<br>
assigns the value <em>count</em> to the object's message counter.
<p>
<li> <strong>void setLineNr(size_t lineNr)</strong>:<br>
specifies the value <em>lineNr</em> as the message's line number when the
next line is displayed (see also <em>noLineNr</em>). This value is <em>not</em>
changed by the <em>Mstream</em> object. To display another line number the
member will have to be called again (i.e., the line number is not displayed
automatically again at every new line).
<p>
<li> <strong>void setLineTag(std::string const &tag)</strong>:<br>
specifies the tag prefixing line numbers. By default the line tag
equals `<em>Line</em>'.
<p>
<li> <strong>void setMaxCount(size_t maxCount)</strong>:<br>
defines <em>maxCount</em> as the maximum number of messages that can be
inserted into the <em>Mstream</em> object.
<p>
<li> <strong>void setTag(std::string const &tag)</strong>:<br>
specifies the tag prefixing messages. By default the tag is empty. If
not empty the tag is enclosed by square brackets. E.g., specifying the tag
`<em>Error</em>' will prefix messages with <em>[Error]</em>.
<p>
<li> <strong>std::string const &tag() const</strong>:<br>
returns the currently used message tag (by default an empty string).
<p>
<li> <strong>bool throws()</strong>:<br>
returns <em>true</em> when the <em>Mstream</em> object will throw an
<em>FBB::Errno</em> exception at the next completed message. The generated
exception holds the id (see earlier for the member <em>id</em>) of the
<em>Mstream</em> object from which the exception was thrown as well as the
text <em>FBB::Mstream</em>.
<p>
<li> <strong>void throwing(bool ifTrue)</strong>:<br>
modifies the behaviro of <em>Mstream</em> objects at completed
messages. After passing <em>true</em> <em>Mstream</em> objects will throw an
<em>FBB::Errno</em> exception at the next completed message, otherwise this
exception is not thrown. The generated exception holds the id (see earlier for
the member <em>id</em>) of the <em>Mstream</em> object from which the exception was
thrown as well as the text <em>FBB::Mstream</em>.
</ul>
<p>
<h2>MANIPULATORS</h2>
Note that the following two manipulators are not members of the class
<strong>Mstream</strong>, but are free functions defined in the namespace <strong>FBB</strong>.
<p>
<ul>
<li> <strong>std::ostream &endl(std::ostream &out)</strong>:<br>
This manipulator inserts a newline character in the <em>Mstream</em>'s
stream and then calls <em>FBB::flush</em>. This manipulator acts like <em>std::endl</em>
and <em>std::flush</em> when inserted into another kind of <em>std::ostream</em> object.
<li> <strong>std::ostream &flush(std::ostream &out)</strong>:<br>
This manipulator completes the message that is currently being inserted
into an <em>Mstream</em> object. It flushes the object's destination stream
and prepares the object for the next message. When the object's <em>throws</em>
member returns <em>true</em> it will throw an <em>FBB:::Errno</em> exception which holds
the id (see earlier for the member <em>id</em>) of the <em>Mstream</em> object from
which the exception was thrown as well as the text <em>FBB::Mstream</em>. When
used in combination with another kind of <em>std::ostream</em> object it acts like
<em>std::flush</em>.
</ul>
<p>
As the manipulators <em>FBB::endl</em> and <em>FBB::flush</em> act like, respectively,
<em>std::endl</em> and <em>std::flush</em> when inserted into another kind of
<em>std::ostream</em> object, using the declarations `<em>using FBB::endl</em>' and
`<em>using FBB::flush</em>' might be worth considering. Also, when <em>using
namespace std</em> <em>and</em> <em>using namespace FBB</em> is specified the <em>FBB::endl</em>
and <em>FBB::flush</em> manipulator will automatically be called when inserting
<em>endl</em> or <em>flush</em> into <em>Mstream</em> objects.
<p>
<h2>EXAMPLE</h2>
<pre>
#include <iostream>
#include <algorithm>
#include <iterator>
#include <bobcat/mstream>
#include <bobcat/errno>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
try
{
imsg << "Informational: " << endl;
imsg.off();
cout << "The i-msg stream is now off. This message should appear once" <<
endl;
imsg << "The i-msg stream is now off. This message should appear once" <<
endl;
imsg << "The i-msg stream is now off. This message should appear once" <<
endl;
cout << "But this message is shown" << endl;
wmsg << "Warning message" << endl;
emsg << "Oops, this this is an error (not really)" << endl;
emsg << "Oops, this goes wrong, too" << endl;
imsg.on();
imsg << "And another informational msg: " << emsg.count() <<
" error messages\n" << flush;
emsg << "Third error" << endl;
emsg.setMaxCount(3);
imsg << "Msg in between" << endl;
cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
emsg.count() << endl;
emsg << "Fourth error" << endl;
cerr << "(cerr) LineExcess: " << emsg.lineExcess() << ", count = " <<
emsg.count() << endl;
cerr << "Beyond\n";
}
catch(FBB::Errno const &e)
{
std::cerr << "Got an Errno object: " << e.why() << '\n';
}
catch(...)
{
std::cerr << "Got an exception\n";
}
</pre>
<p>
<h2>FILES</h2>
<em>bobcat/mstream</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
<strong>bobcat</strong>(7), <strong>errno</strong>(3bobcat), <strong>mbuf</strong>(3bobcat)
<p>
<h2>BUGS</h2>
None Reported.
<p>
<h2>DISTRIBUTION FILES</h2>
<ul>
<li> <em>bobcat_2.20.01-x.dsc</em>: detached signature;
<li> <em>bobcat_2.20.01-x.tar.gz</em>: source archive;
<li> <em>bobcat_2.20.01-x_i386.changes</em>: change log;
<li> <em>libbobcat1_2.20.01-x_*.deb</em>: debian package holding the
libraries;
<li> <em>libbobcat1-dev_2.20.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>
|