.TH "FBB::Log" "3bobcat" "2005\-2018" "libbobcat\-dev_4\&.08\&.06\-x\&.tar\&.gz" "Log messages" .PP .SH "NAME" FBB::Log \- \fIstd::ostream\fP handling log messages .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" .PP The class \fBFBB::Log\fP is an \fIstd::ostream\fP initialized with a \fIFBB::LogBuffer\fP\&. It is used to send log\-messages to the (r)syslog stream\&. Refer to the \fBlogbuffer\fP(3bobcat) man\-page for details about this process\&. .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" \fIstd::ostream\fP .PP .SH "ENUMERATIONS" .PP The enumeration \fITimeStamps\fP is defined in the namespace \fIFBB\fP, primarily for initializing \fIFBB::LogBuffer\fP objects\&. It is used with \fBFBB::Log\fP members as well\&. 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 \fILogManipulator\fP is used to handle special or exceptional situations through manipulators\&. It is defined in the namespace \fIFBB\fP and has the following two values: .IP o \fBFATAL\fP: .br This value may be inserted into an \fBFBB::Log\fP object to throw an \fIFBB::Exception\fP exception (see \fIoperator<<\fP below); .IP o \fBnl\fP: .br This value may be inserted into an \fBFBB::Log\fP object to terminate the current line\&. It will \fInot\fP cause the next line to begin with a time stamp (if applicable) and the current \fImessage level\fP cannot be modified using a \fBlevel\fP(3bobcat) manipulator\&. It is used to allow a single log message to occupy multiple textual lines\&. .IP o \fBendl\fP: .br This is the standard \fIostream\fP manipulator\&. When inserted into an \fBFBB::Log\fP object the current buffer is flushed\&. Note that flushing does not happen immediately when a newline (\fI\en\fP) is inserted into the log stream\&. Alternatively, \fIstd::flush\fP may be inserted into the \fBFBB::Log\fP object to flush its buffer\&. .PP .SH "CONSTRUCTORS" .IP o \fBLog()\fP: .br The default constructor creates a \fBFBB::Log\fP object which isn\(cq\&t yet associated with a stream to log messages on\&. The member \fIopen\fP (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 \fIsetTimestamp\fP below), and a blank space is inserted as delimiter immediately beyond the time stamp\&. The member \fIopen\fP can be used to modify the default delimiter\&. .IP o \fBLog(std::ostream &out, char const *delim = \(dq\& \(dq\&)\fP: .br This constructor creates a \fBFBB::Log\fP object logging its messages to the provided \fIstd::ostream\fP object\&. By default, all messages will have a time stamp prepended to them (see the description of the member \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter is inappropriate, an empty string or a 0\-pointer may be specified\&. .IP o \fBFBB::Log(std::string const &filename, std::ios::openmode mode = std::ios::out | std::ios::app, char const *delim = \(dq\& \(dq\&)\fP: .br This constructor creates a \fBFBB::Log\fP object logging its messages to the named file\&. If \fIfilename == \(dq\&&1\(dq\&\fP the logmessages will be written to the standard output stream\&. If \fIfilename == \(dq\&&2\(dq\&\fP 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 \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP 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\&. .PP .SH "MEMBER FUNCTIONS" All members of \fIstd::ostream\fP are available, as \fBFBB::Log\fP inherits from this class\&. .IP o \fBsize_t level()\fP: .br This member returns the currently set log level (i\&.e\&., the value set at the latest \fIsetLevel()\fP call)\&. By default, the level is set to zero, meaning that all information is inserted into the log stream\&. .IP o \fBstd::ostream &level(size_t useLevel)\fP: .br This member defines a log\-level\&. Messages will be inserted into the stream when \fIuseLevel\fP is equal to or exceeds the level set by \fIsetLevel\fP\&. The maximum level which can be selected is \fIstd::numeric_limits::max()\fP\&. If not even such messages should be inserted into the \fIostream\fP, then the stream should be deactivated, using \fIoff()\fP, see below\&. The selected level remains active until redefined\&. Alternatively, the \fIFBB::level\fP manipulator may be inserted into an (empty) \fBFBB::Log\fP object (see \fBlevel\fP(3bobcat))\&. .IP o \fBvoid off()\fP: .br Prevents any log messages from being generated\&. It may be cancelled by \fIsetLevel\fP (see below)\&. .IP o \fBvoid open(std::string const &filename, std::ios::openmode mode = std::ios::out | std::ios::app, char const *delim = \(dq\& \(dq\&)\fP: .br This member (re)associates an \fBFBB::Log\fP object with the named file\&. If \fIfilename == \(dq\&&1\(dq\&\fP the logmessages will be written to the standard output stream\&. If \fIfilename == \(dq\&&2\(dq\&\fP 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 \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter is inappropriate, an empty string or a 0\-pointer may be specified\&. .IP o \fBvoid setLevel(size_t newLevel)\fP: .br Redefines the internal message level\&. Messages having at least level \fInewLevel\fP will be written\&. If the member is used without explicit argument, logging is suspended\&. .IP o \fBvoid setTimestamp(FBB::TimeStamps stamp, char const *delim = \(dq\& \(dq\&)\fP: .br The member function (de)activates time stamp prepending\&. Use the value \fIFBB::TIMESTAMPS\fP to prepend time stamps, \fIFBB::NOTIMESTAMPS\fP 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 \fI/var/log\fP files\&. E\&.g\&., \fIAug 5 13:52:23\fP\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter is inappropriate, an empty string or a 0\-pointer may be specified\&. When \fIstamps == FBB::NOTIMESTAMPS delim\fP is ignored\&. .PP .SH "STATIC MEMBERS" .IP o \fBFBB::Log &initialize(std::string const &filename, std::ios::openmode mode = std::ios::out | std::ios::app, char const *delim = \(dq\& \(dq\&)\fP: .br .IP Returns a reference to a static \fBFBB::Log\fP object\&. It may only be called once, or an \fIFBB::Exception\fP exception is thrown\&. It associates a static \fBFBB::Log\fP object with the named file\&. If \fIfilename == \(dq\&&1\(dq\&\fP the logmessages will be written to the standard output stream\&. If \fIfilename == \(dq\&&2\(dq\&\fP 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 \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter is inappropriate, an empty string or a 0\-pointer may be specified\&. .IP o \fBFBB::Log &instance()\fP: .br Returns a reference to a static \fBFBB::Log\fP object, available after calling \fILog::initialize\fP\&. If called before \fILog::initialize()\fP an \fIFBB::Exception\fP exception is thrown\&. .PP .SH "OVERLOADED OPERATOR" The following overloaded operator is defined outside of the \fIFBB\fP namespace\&. It may be used to insert an \fIFBB::LogManipulator\fP into an \fBFBB::Log\fP object\&. If the overloaded operator is used in combination with another type of object it performs no actions\&. .IP o \fBstd::ostream &::operator<<(std::ostream &str, FBB::LogManipulator)\fP: .br When inserting \fIFBB::FATAL\fP an \fIFBB::Exception\fP exception is thrown; when inserting \fIFBB::nl\fP the line is terminated, but next insertions will not start with a time stamp (if applicable)\&. .PP .SH "EXAMPLE" .nf #include #include #include using namespace std; using namespace FBB; int main() { // Log &log = Log::initialize(\(dq\&&1\(dq\&); Log log; log\&.open(\(dq\&/tmp/out\(dq\&); log << \(dq\&This message is written to cout\(dq\& << nl << setw(16) << \(cq\& \(cq\& << \(dq\&occupying multiple lines\en\(dq\&; log\&.off(); log << \(dq\&This message is not shown\en\(dq\&; log\&.setLevel(0); log << \(dq\&This message is shown again\en\(dq\&; } .fi .PP .SH "FILES" \fIbobcat/log\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBexception\fP(3bobcat), \fBlevel\fP(3bobcat), \fBlogbuffer\fP(3bobcat) .PP .SH "BUGS" None reported .PP .SH "DISTRIBUTION FILES" .IP o \fIbobcat_4\&.08\&.06\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_4\&.08\&.06\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_4\&.08\&.06\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_4\&.08\&.06\-x_*\&.deb\fP: debian package holding the libraries; .IP o \fIlibbobcat1\-dev_4\&.08\&.06\-x_*\&.deb\fP: debian package holding the libraries, headers and manual pages; .IP o \fIhttp://sourceforge\&.net/projects/bobcat\fP: public archive location; .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