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_3.23.01-x.dsc: detached signature;
- o
- bobcat_3.23.01-x.tar.gz: source archive;
- o
- bobcat_3.23.01-x_i386.changes: change log;
- o
- libbobcat1_3.23.01-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_3.23.01-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).