This file is indexed.

/usr/share/doc/libbobcat4-dev/man/mstream.3.html is in libbobcat-dev 4.08.02-2build1.

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
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<title>FBB::Mstream(3bobcat)</title>
<style type="text/css">
    figure {text-align: center;}
    img {vertical-align: center;}
    .XXfc {margin-left:auto;margin-right:auto;}
    .XXtc {text-align: center;}
    .XXtl {text-align: left;}
    .XXtr {text-align: right;}
    .XXvt {vertical-align: top;}
    .XXvb {vertical-align: bottom;}
</style>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr/>
<h1 id="title">FBB::Mstream(3bobcat)</h1>
<h2 id="author">Message handler<br/>(libbobcat-dev_4.08.02-x.tar.gz)</h2>
<h2 id="date">2005-2017</h2>


<p>
<h2 >NAME</h2>FBB::Mstream - Generic message handling stream
<p>
<h2 >SYNOPSIS</h2>
    <strong >#include &lt;bobcat/mstream&gt;</strong><br/>
    Linking option: <em >-lbobcat</em> 
<p>
<h2 >DESCRIPTION</h2>
    Objects of this class are used for handling messages in a standardized
way. Messages may be prefixed with order (line) numbers an/or,
labels. Messages generated by <em >Mstream</em> objects may optionally end by
throwing an <em >FBB::Exception</em> (which is an <em >std::exception</em>), 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>

        The exception's <em >what</em> member contains <em >FBB::fmsg's id</em> value (see
        member <em >id</em> below).
    <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
exceptions are thrown when inserting messages.
    <li> <strong >explicit Mstream(std::ostream &amp;ostr, size_t maxCount =
        std::numeric_limits&lt;size_t&gt;::max(), std::string const &amp;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 exceptions are thrown when inserting
        messages. Specifying any other value than
        <em >std::numeric_limits&lt;size_t&gt;::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>). 
<p>
When <em >throwing</em> is <em >true</em> an exception is thrown after completing
        a message. The generated exception's <em >what</em> member may show the
        <strong >FBB::Mstream</strong> object's id (see below at the member <em >id</em>) of the
        <em >Mstream</em> object throwing the exception.
    <li> <strong >explicit Mstream(std::streambuf *buf, size_t maxCount =
        std::numeric_limits&lt;size_t&gt;::max(), std::string const &amp;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 &amp;name, size_t maxCount =
        std::numeric_limits&lt;size_t&gt;::max(), std::string const &amp;tag = "", bool
        throwing = false)</strong>:<br/> 
       This constructor creates a <em >std::ofstream</em> from the provided <em >name</em>
        parameter. It throws an 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 &amp;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 >std::numeric_limits&lt;size_t&gt;::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 &amp;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 &amp;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 &amp;name, size_t maxCount, 
                std::string const &amp;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.  An exception
is thrown 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 &amp;ostr, size_t maxCount, 
                std::string const &amp;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 >std::numeric_limits&lt;size_t&gt;::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 exception is thrown after completing a message.
<p>
<li> <strong >void reset(std::streambuf *buf, size_t maxCount, 
                std::string const &amp;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 &amp;name, size_t maxCount,
                std::string const &amp;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
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 &amp;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 &amp;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 &amp;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 &amp;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 exception
at the next completed message. The generated exception's <em >what</em> member
contains the id (see earlier for the member <em >id</em>) of the <em >Mstream</em> object
throwing the exception.
<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 exception
at the next completed message, otherwise this exception is not thrown. The
generated exception's <em >what</em> member contains the id (see earlier for the
member <em >id</em>) of the <em >Mstream</em> object throwing the exception.
    </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 &amp;endl(std::ostream &amp;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.
<p>
<li> <strong >std::ostream &amp;flush(std::ostream &amp;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 throws an exception whose <em >what</em> member contains the
id (see earlier for the member <em >id</em>) of the <em >Mstream</em> object throwing the
exception. When used in combination with another kind of <em >std::ostream</em>
object it acts like <em >std::flush</em>.
<p>
<li> <strong >std::ostream &amp;noid(std::ostream &amp;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 throws an exception whose <em >what</em> member does not
contain the <strong >Mstream</strong> object's ID. When used in combination with another
kind of <em >std::ostream</em> object it acts like <em >std::flush</em>.
<p>
<li> <strong >std::ostream &amp;noidl(std::ostream &amp;out)</strong>:<br/>
        This manipulator inserts a newline character in the <em >Mstream</em>'s
stream and then calls <em >FBB::noid</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.
    </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 &lt;iostream&gt;
#include &lt;algorithm&gt;
#include &lt;iterator&gt;

#include &lt;bobcat/mstream&gt;

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
try
{
    cout &lt;&lt; sizeof(Mstream) &lt;&lt; ' ' &lt;&lt; sizeof(Mbuf) &lt;&lt; '\n';

    imsg &lt;&lt; "Informational: " &lt;&lt; endl;
    imsg.off();
    cout &lt;&lt; "The i-msg stream is now off. This message should appear once" &lt;&lt;
                                                                        endl;
    imsg &lt;&lt; "The i-msg stream is now off. This message should appear once" &lt;&lt;
                                                                        endl;
    imsg &lt;&lt; "The i-msg stream is now off. This message should appear once" &lt;&lt;
                                                                        endl;
    cout &lt;&lt; "But this message is shown" &lt;&lt; endl;

    wmsg &lt;&lt; "Warning message" &lt;&lt; endl;
    emsg &lt;&lt; "Oops, this this is an error (not really)" &lt;&lt; endl;
    emsg &lt;&lt; "Oops, this goes wrong, too" &lt;&lt; noid;

    imsg.on();
    imsg &lt;&lt; "And another informational msg: " &lt;&lt; emsg.count() &lt;&lt; 
            " error messages\n" &lt;&lt; flush;

    emsg &lt;&lt; "Third error" &lt;&lt; endl;
    emsg.setMaxCount(3);

    imsg &lt;&lt; "Msg in between" &lt;&lt; endl;

    imsg.setTag("tag");
    imsg &lt;&lt; "tagged message" &lt;&lt; endl;

    imsg.setTag("label");
    imsg &lt;&lt; "labeled message" &lt;&lt; endl;

    cerr &lt;&lt; "(cerr) LineExcess: " &lt;&lt; emsg.lineExcess() &lt;&lt; ", count = " &lt;&lt;
            emsg.count() &lt;&lt; endl;

    emsg &lt;&lt; "Fourth error\n" &lt;&lt; noid;       // no id is shown
    emsg &lt;&lt; "Fourth error\n" &lt;&lt; flush;      // shows id (remove the previous
                                            // statement)

    cerr &lt;&lt; "(cerr) LineExcess: " &lt;&lt; emsg.lineExcess() &lt;&lt; ", count = " &lt;&lt;
            emsg.count() &lt;&lt; endl;

    cerr &lt;&lt; "Beyond\n";
}            
catch(exception const &amp;e)
{
    std::cerr &lt;&lt; "Got a std::exception: " &lt;&lt; e.what() &lt;&lt; '\n';
}
catch(...)
{
    std::cerr &lt;&lt; "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 >exception</strong>(3bobcat), <strong >mbuf</strong>(3bobcat)
<p>
<h2 >BUGS</h2>
    None Reported.
<p>

<h2 >DISTRIBUTION FILES</h2>
    <ul>
    <li> <em >bobcat_4.08.02-x.dsc</em>: detached signature;
    <li> <em >bobcat_4.08.02-x.tar.gz</em>: source archive;
    <li> <em >bobcat_4.08.02-x_i386.changes</em>: change log;
    <li> <em >libbobcat1_4.08.02-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em >libbobcat1-dev_4.08.02-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>
</body>
</html>