.TH "FBB::LogBuf" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "log messages stream buffer"

.PP 
.SH "NAME"
FBB::LogBuf \-  \fBstd::streambuf\fP handling log messages
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/logbuf>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"

.PP 
\fBFBB::LogBuf\fP is a class derived from \fBstd::streambuf\fP handling log
messages\&. The stream to log to, timestamps and log\-levels can be configured
both at construction time and beyond\&. The \fBFBB::LogBuf\fP may be used to
initialize a \fBstd::ostream\fP\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fBstd::streambuf\fP
.PP 
.SH "ENUMERATIONS"
The enumeration \fBTimeStamps\fP is defined in the namespace \fBFBB\fP to be
used when initializing \fBFBB::LogBuf\fP objects\&. It has the following
values:
.IP o 
\fBNOTIMESTAMPS\fP:
.br 
Log\-messages will not have timestamps prepended to them\&.
.IP o 
\fBTIMESTAMPS\fP:
.br 
Log\-messages will have timestamps prepended to them\&.
.IP o 
\fBUTCTIMESTAMPS\fP:
.br 
Log\-messages will have timestamps showing the UTC time prepended to
them\&.

.PP 
The enumeration \fIActive\fP is used to distinguish between suspending
message insertion when a message\(cq\&s level does not exceed a minimum level and
suspending all message insertions (e\&.g\&., when suspending inserting messages
into \fBFBB::Log\fP objects after calling their \fIoff\fP member):
.IP o 
\fBOFF\fP:
.br 
All insertions into the \fILogBuf\fP object are suspended;
.IP o 
\fBNOT_ACTIVE\fP:
.br 
Insertions of messages into the \fILogBuf\fP object are suspended if
their levels are less than the a specified minimum (as set by, e\&.g\&.,
\fILog::setLevel\fP)\&.
.IP o 
\fBACTIVE\fP:
.br 
Messages are inserted

.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBLogBuf(TimeStamps timestamps = TIMESTAMPS,
bool active = true,
char const *delim = \(dq\& \(dq\&)\fP:
.br 
This constructor constructs an \fBFBB::LogBuf\fP object writing its
log\-messages to \fBstd::cerr\fP\&. If the \fBactive\fP parameter is initialized to
\fBfalse\fP no messages will be logged until the buffer\(cq\&s activity is switched
on (see \fBsetActive()\fP below)\&.  The parameter \fBdelim\fP is inserted
immediately beyond the time stamp\&. If a delimiter is inappropriate, an empty
string or a 0\-pointer may be specified\&. When \fBstamps == FBB::NOTIMESTAMPS
delim\fP is ignored\&. A time stamp consists of the month, the day number of the
month and the (local) time of the current message, as usually appearing in
messages in \fI/var/log\fP files\&. E\&.g\&., \fIAug 5 13:52:23\fP;
.IP 
.IP o 
\fBLogBuf(std::ostream &stream,
TimeStamps timestamps = TIMESTAMPS,
bool active = true,
char const *delim = \(dq\& \(dq\&)\fP:
.br 
This constructor constructs an \fBFBB::LogBuf\fP object writing its
log\-messages to the stream used to initialize its \fBstream\fP parameter\&. If the
\fBactive\fP parameter is initialized to \fBfalse\fP no messages will be logged
until the buffer\(cq\&s activity is switched on (see \fBsetActive()\fP below)\&. The
parameter \fBdelim\fP is inserted immediately beyond the time stamp\&. If a
delimiter is inappropriate, an empty string or a 0\-pointer may be
specified\&. When \fBstamps == FBB::NOTIMESTAMPS delim\fP is ignored\&. A time stamp
consists of the month, the day number of the month and the (local) time of the
current message, as usually appearing in messages in \fI/var/log\fP files\&. E\&.g\&.,
\fIAug 5 13:52:23\fP\&.

.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "PUBLIC MEMBER FUNCTIONS"
All members of \fBstd::streambuf\fP are available, as \fBFBB::LogBuf\fP
inherits from this class\&.
.IP o 
\fBbool active() const\fP:
.br 
Returns \fItrue\fP if log\-messages are currently processed;
.IP 
.IP o 
\fBbool empty() const\fP:
.br 
Returns \fItrue\fP if the object\(cq\&s buffer is currently empty (initially
or after a newline character has been inserted);
.IP 
.IP o 
\fBvoid setStream(std::ostream &stream)\fP:
.br 
This member may be used to switch the stream to log to\&. It is the
responsibility of the programmer to ensure that the external stream remains
available for as long as log\-messages are inserted into it;
.IP 
.IP o 
\fBvoid settimestamp(FBB::TimeStamps timestamps,
char const *delim = \(dq\& \(dq\&)\fP:
.br 
The member function (de)activates time stamp prepending\&. Use the value
\fBFBB::TIMESTAMPS\fP to prepend time stamps, \fBFBB::NOTIMESTAMPS\fP suppresses
time stamps\&.   A time stamp consists of the month, the day number of the month
and the (local) time of the current message, as usually appearing in messages
in \fI/var/log\fP files\&. E\&.g\&., \fIAug 5 13:52:23\fP\&. The parameter \fBdelim\fP is
inserted immediately beyond the time stamp\&. If a delimiter is inappropriate,
an empty string or a 0\-pointer may be specified\&. When \fBstamps ==
FBB::NOTIMESTAMPS delim\fP is ignored;
.IP 
.IP o 
\fBvoid setActive(bool active)\fP:
.br 
Unless the current object\(cq\&s \fIActive\fP state is \fIOFF\fP this member
can be used to (de)activate logging\&. The argument \fBtrue\fP activates logging,
the argument \fBfalse\fP deactivates it\&. If the current \fIActive\fP status is
\fIOFF\fP then this member does not change the object\(cq\&s activity status\&. This
member is normally called by \fBFBB::Log::level\fP members;
.IP 
.IP o 
\fBvoid setActive(Active active)\fP:
.br 
The member function (de)activates logging\&. The argument \fBACTIVE\fP
activates logging, the argument \fBOFF\fP completely suppresses logging, the
argument \fINOT_ACTIVE\fP also suppresses logging, but here \fIsetActive(true)\fP
can also be used reactivate logging;
.IP 
.IP o 
\fBvoid setEmpty(bool empty)\fP:
.br 
This member may be called to ensure that a timestamp is inserted
before the next insertion\&. It is called as \fBsetEmpty(true)\fP when a newline
character (\fI\en\fP) is inserted, ensuring that another timestamp is prepended
before the next insertion\&.

.PP 
.SH "EXAMPLE"
.nf 
#include <iostream>
#include <iomanip>

#include <bobcat/log>
#include <bobcat/level>

using namespace std;
using namespace FBB;

int main()
{
    LogBuf buffer(cout, FBB::TIMESTAMPS);
    ostream log(&buffer);

    log << \(dq\&This message is written to cout\(dq\& << nl <<
           setw(16) << \(cq\& \(cq\& << \(dq\&occupying multiple lines\en\(dq\&;

    buffer\&.setActive(false);

    log << \(dq\&one line\en\(dq\&;
    log << \(dq\&more lines \(dq\&;
    log << fnl;
    log << \(dq\&another\en\(dq\&;

    buffer\&.setActive(true);
    log << \(dq\&and active again\en\(dq\&;
    log << \(dq\&another log msg\en\(dq\&;
}

.fi 

.PP 
.SH "FILES"
\fIbobcat/logbuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBlog\fP(3bobcat)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.06\&.02\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.06\&.02\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP