Scroll to navigation

FBB::Log(3bobcat) Log messages FBB::Log(3bobcat)

NAME

FBB::Log - std::ostream handling log messages

SYNOPSIS

#include <bobcat/log>
Linking option: -lbobcat

DESCRIPTION

The class FBB::Log defines an std::ostream using an FBB::LogBuf std::streambuf. It is used to send log-messages to the (r)syslog stream or to a (configurable) file. Refer to the logbuf(3bobcat) man-page for details about LogBuf.

Which (part of) messages are actually logged can be configured using FBB::level in combination with the Log member setLevel. By default all information that is inserted into a Log object is logged, but level objects (level(3bobcat)) can be inserted specifying insertion `forces’ of the information that is subsequently inserted into Log objects. These `forces’ are compared to insertion `resistances’ that may be specified by Log objects through their setLevel members.

If the level’s `force’ is equal to or exceeds the Log object’s `resistance’ then the insertion is performed, otherwise the insertion is ignored. A single insertion statement may contain multiple level calls. If so, then each level call updates the `force’ of insertions following the level call.

Information inserted into Log objects without inserting level objects (or before the first level object) is always logged (see also the Examples section).

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::LogBuf objects. It is used with 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:
When inserting FATAL into a Log object an FBB::Exception exception is thrown (see operator<< below);
o
nl:
When inserting nl into a Log object a \n character is inserted into the current line. If time stamps are requested the the next line will not begin with a time stamp. It is used to allow a single log message to occupy multiple textual lines. The next logged line is not indented over the width of the omitted time stamp. If that’s preferred: the time stamp occupies 15 character positions (not counting the width of the delimiter, see the CONSTRUCTORS section below). If a level specification is active, it remains active at insertions following nl.
o
fnl:
When inserting fnl (forced new line) into a Log object the current line ends even if the currently active insertion `force’ (set by level) is lower than the Log object’s `resistance’ level. If a level specification is active, it remains active at insertions following fnl.
o
endl or \n:
When inserting endl or \n the current line is ended and the next logged line starts with a timestamp (unless timestamps are suppressed). The endl manipulator is the standard ostream manipulator: when inserted into a Log object its buffer is flushed. The scope of a level specification ends at \n or endl. E.g.,
log.setLevel(2);
log << level(1) << "first line\n"
       "second line\n";
    
    
results in second line (preceded by a timestamp) being logged.

CONSTRUCTORS

o
Log():
The default constructor creates a 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 are preceded by a time stamp (see the description of the member setTimestamp below), and a single space character 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 Log object logging its messages to the provided std::ostream object. By default, all messages are preceded by a time stamp (see the description of the member setTimestamp below). The parameter delim is inserted immediately beyond the time stamp. If a delimiter should not be used 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 Log object logging its messages to the named file. If filename == "&1" logmessages are written to the standard output stream. If filename == "&2" logmessages are written to the standard error stream. By default the file is created if not existing, and all messages are appended to the stream. Also by default all messages are preceded by time stamps (see the description of the member setTimestamp below). The parameter delim is inserted immediately beyond the time stamp. If a delimiter should not be used an empty string or a 0-pointer may be specified.

Copy and move constructors (and assignment operators) are not available.

MEMBER FUNCTIONS

All members of std::ostream are available, as 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) Log object (see level(3bobcat)).
o
void off():
Prevents log messages from being generated. It may be cancelled using 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 a 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. Also by default all messages are preceded by time stamps (see the description of the member setTimestamp below). The parameter delim is inserted immediately beyond the time stamp. If a delimiter should not be used an empty string or a 0-pointer may be specified.
o
void setLevel(size_t resistance):
Redefines the `resistance’ against message insertions. Insertions are performed if their `force’ are equal to or exceed the Log object’s `resistance’. The `force’ of insertions is specified using FBB::level. If setLevel is called without an explicit argument, logging is suspended (comparable to using the member off).
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 15 characters showing the abbreviated month’s name, two-digits specifying the day number of the month, and the (local or UTC) time of the current message, as usually appearing in messages in /var/log files. E.g., Aug 05 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 specifying stamps == FBB::NOTIMESTAMPS delim also 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 Log object. It may only be called once, or an FBB::Exception exception is thrown. It associates a static Log object with the named file.
If filename == "&1" logmessages are written to the standard output stream. If filename == "&2" logmessages are written to the standard error stream. By default the file is created if not existing, and all messages are appended to the stream. Also by default all messages are preceded by time stamps (see the description of the member setTimestamp below). The parameter delim is inserted immediately beyond the time stamp. If a delimiter should not be used an empty string or a 0-pointer may be specified.
o
FBB::Log &instance():
Returns a reference to a static 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 is used to insert an FBB::LogManipulator into a Log object. If the overloaded operator is used in combination with another kind of stream 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>
#include <bobcat/level>
using namespace std;
using namespace FBB;
int main()
{
//    Log &log = Log::initialize("&1"); // uses the static Log object
    Log log;                        // explicitly defining a Log object
    log.open("/tmp/out");           // or at once: Log log{ "/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 << "This message is not shown\n";
    log << fnl;
    log << "This message is not shown\n";
    log.setLevel(2);
    log << "This message is shown\n";
    log << level(0) << "not shown" << level(2) << "shown at level 2\n";
    log << level(3) << "at level(3)" << level(1) << "not shown" << fnl;
    log << "separate new line\n";
    log << level(2) << "in business again\n";
    log << "final line\n";
}

FILES

bobcat/log - defines the class interface

SEE ALSO

bobcat(7), exception(3bobcat), level(3bobcat), logbuf(3bobcat)

BUGS

The nl and fnl manipulators are received by the Log objects’ LogBufs as, respectively, characters 0 and 1. Since log files in practice only received printable characters this should not cause any problems.

DISTRIBUTION FILES

o
bobcat_5.00.03-x.dsc: detached signature;
o
bobcat_5.00.03-x.tar.gz: source archive;
o
bobcat_5.00.03-x_i386.changes: change log;
o
libbobcat1_5.00.03-x_*.deb: debian package holding the libraries;
o
libbobcat1-dev_5.00.03-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).
2005-2019 libbobcat-dev_5.00.03-x.tar.gz