Provided by: libbobcat-dev_4.08.02-2build1_amd64 
NAME
FBB::Log - std::ostream handling log messages
SYNOPSIS
#include <bobcat/log>
Linking option: -lbobcat
DESCRIPTION
The class FBB::Log is an std::ostream initialized with a FBB::LogBuffer. It is used to
send log-messages to the (r)syslog stream. Refer to the logbuffer(3bobcat) man-page for
details about this process.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are
defined in the namespace FBB.
INHERITS FROM
std::ostream
ENUMERATIONS
The enumeration TimeStamps is defined in the namespace FBB, primarily for initializing
FBB::LogBuffer objects. It is used with FBB::Log members as well. It has the following
values:
o NOTIMESTAMPS:
Log-messages will not have timestamps prepended to them.
o TIMESTAMPS:
Log-messages will have timestamps prepended to them.
o UTCTIMESTAMPS:
Log-messages will have timestamps showing the UTC time prepended to them.
The enumeration LogManipulator is used to handle special or exceptional situations through
manipulators. It is defined in the namespace FBB and has the following two values:
o FATAL:
This value may be inserted into an FBB::Log object to throw an FBB::Exception
exception (see operator<< below);
o nl:
This value may be inserted into an FBB::Log object to terminate the current line.
It will not cause the next line to begin with a time stamp (if applicable) and the
current message level cannot be modified using a level(3bobcat) manipulator. It is
used to allow a single log message to occupy multiple textual lines.
o endl:
This is the standard ostream manipulator. When inserted into an FBB::Log object the
current buffer is flushed. Note that flushing does not happen immediately when a
newline (\n) is inserted into the log stream. Alternatively, std::flush may be
inserted into the FBB::Log object to flush its buffer.
CONSTRUCTORS
o Log():
The default constructor creates a FBB::Log object which isn’t yet associated with a
stream to log messages on. The member open (see below) may be used to define such a
stream. By default, all messages will have a time stamp prepended to them (see the
description of the member setTimestamp below), and a blank space is inserted as
delimiter immediately beyond the time stamp. The member open can be used to modify
the default delimiter.
o Log(std::ostream &out, char const *delim = " "):
This constructor creates a FBB::Log object logging its messages to the provided
std::ostream object. By default, all messages will have a time stamp prepended to
them (see the description of the member setTimestamp below). The parameter delim
is inserted immediately beyond the time stamp. If a delimiter is inappropriate, an
empty string or a 0-pointer may be specified.
o FBB::Log(std::string const &filename, std::ios::openmode mode = std::ios::out |
std::ios::app, char const *delim = " "):
This constructor creates a FBB::Log object logging its messages to the named file.
If filename == "&1" the logmessages will be written to the standard output stream.
If filename == "&2" the logmessages will be written to the standard error stream.
By default the file is created if not existing, and all messages are appended to
the stream. By default, all messages will have a time stamp prepended to them (see
the description of the member setTimestamp below). The parameter delim is inserted
immediately beyond the time stamp. If a delimiter is inappropriate, an empty string
or a 0-pointer may be specified. The copy constructor is not available.
MEMBER FUNCTIONS
All members of std::ostream are available, as FBB::Log inherits from this class.
o size_t level():
This member returns the currently set log level (i.e., the value set at the latest
setLevel() call). By default, the level is set to zero, meaning that all
information is inserted into the log stream.
o std::ostream &level(size_t useLevel):
This member defines a log-level. Messages will be inserted into the stream when
useLevel is equal to or exceeds the level set by setLevel. The maximum level which
can be selected is std::numeric_limits<size_t>::max(). If not even such messages
should be inserted into the ostream, then the stream should be deactivated, using
off(), see below. The selected level remains active until redefined. Alternatively,
the FBB::level manipulator may be inserted into an (empty) FBB::Log object (see
level(3bobcat)).
o void off():
Prevents any log messages from being generated. It may be cancelled by setLevel
(see below).
o void open(std::string const &filename, std::ios::openmode mode = std::ios::out |
std::ios::app, char const *delim = " "):
This member (re)associates an FBB::Log object with the named file. If filename ==
"&1" the logmessages will be written to the standard output stream. If filename ==
"&2" the logmessages will be written to the standard error stream. By default the
file is created if not existing, and all messages are appended to the stream. By
default, all messages will have a time stamp prepended to them (see the description
of the member setTimestamp below). The parameter delim is inserted immediately
beyond the time stamp. If a delimiter is inappropriate, an empty string or a
0-pointer may be specified.
o void setLevel(size_t newLevel):
Redefines the internal message level. Messages having at least level newLevel will
be written. If the member is used without explicit argument, logging is suspended.
o void setTimestamp(FBB::TimeStamps stamp, char const *delim = " "):
The member function (de)activates time stamp prepending. Use the value
FBB::TIMESTAMPS to prepend time stamps, FBB::NOTIMESTAMPS suppresses time stamps.
A timestamp consists of the month, the day number of the month and the (local) time
of the current message, as usually appearing in messages in /var/log files. E.g.,
Aug 5 13:52:23. The parameter delim is inserted immediately beyond the time stamp.
If a delimiter is inappropriate, an empty string or a 0-pointer may be specified.
When stamps == FBB::NOTIMESTAMPS delim is ignored.
STATIC MEMBERS
o FBB::Log &initialize(std::string const &filename, std::ios::openmode mode =
std::ios::out | std::ios::app, char const *delim = " "):
Returns a reference to a static FBB::Log object. It may only be called once, or an
FBB::Exception exception is thrown. It associates a static FBB::Log object with the
named file. If filename == "&1" the logmessages will be written to the standard
output stream. If filename == "&2" the logmessages will be written to the standard
error stream. By default the file is created if not existing, and all messages are
appended to the stream. By default, all messages will have a time stamp prepended
to them (see the description of the member setTimestamp below). The parameter
delim is inserted immediately beyond the time stamp. If a delimiter is
inappropriate, an empty string or a 0-pointer may be specified.
o FBB::Log &instance():
Returns a reference to a static FBB::Log object, available after calling
Log::initialize. If called before Log::initialize() an FBB::Exception exception is
thrown.
OVERLOADED OPERATOR
The following overloaded operator is defined outside of the FBB namespace. It may be used
to insert an FBB::LogManipulator into an FBB::Log object. If the overloaded operator is
used in combination with another type of object it performs no actions.
o std::ostream &::operator<<(std::ostream &str, FBB::LogManipulator):
When inserting FBB::FATAL an FBB::Exception exception is thrown; when inserting
FBB::nl the line is terminated, but next insertions will not start with a time
stamp (if applicable).
EXAMPLE
#include <iostream>
#include <iomanip>
#include <bobcat/log>
using namespace std;
using namespace FBB;
int main()
{
// Log &log = Log::initialize("&1");
Log log;
log.open("/tmp/out");
log << "This message is written to cout" << nl <<
setw(16) << ’ ’ << "occupying multiple lines\n";
log.off();
log << "This message is not shown\n";
log.setLevel(0);
log << "This message is shown again\n";
}
FILES
bobcat/log - defines the class interface
SEE ALSO
bobcat(7), exception(3bobcat), level(3bobcat), logbuffer(3bobcat)
BUGS
None reported
DISTRIBUTION FILES
o bobcat_4.08.02-x.dsc: detached signature;
o bobcat_4.08.02-x.tar.gz: source archive;
o bobcat_4.08.02-x_i386.changes: change log;
o libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.08.02-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).