.TH "FBB::Log" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "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 .br .PP .SH "DESCRIPTION" .PP The class \fBFBB::Log\fP defines an \fIstd::ostream\fP using an \fIFBB::LogBuf std::streambuf\fP\&. It is used to send log\-messages to the (r)syslog stream or to a (configurable) file\&. Refer to the \fBlogbuf\fP(3bobcat) man\-page for details about \fILogBuf\fP\&. .PP Which (parts of) messages are actually logged can be configured using \fBFBB::level\fP in combination with the \fILog\fP member \fIsetLevel\fP or using the function operator in combination with the \fIstr\fP member (see the the members \fIoperator()\fP and \fIstr\fP)\&. By default all information that is inserted into a \fILog\fP object is logged\&. .PP Objects of the \fIlevel\fP class (cf\&. \fBlevel\fP(3bobcat)) can be inserted specifying insertion `forces\(cq\& for the information that is subsequently inserted into \fILog\fP objects\&. Only if these`forces\(cq\& exceed the \fILog\fP object\(cq\&s insertion `resistances\(cq\& (see the member \fIsetLevel\fP) then the information is logged\&. .PP A single log\-insertion statement may contain multiple \fIlevel\fP calls\&. If so, then each \fIlevel\fP call updates the `force\(cq\& of insertions following the \fIlevel\fP call\&. .PP Information inserted into \fILog\fP objects without inserting \fIlevel\fP objects (or before the first \fIlevel\fP object) is always logged (see also the \fBExamples\fP section)\&. .PP Alternatively information may be logged using category\-selector characters\&. The member \fIstr(std::string const &active)\fP defines the characters that can be used to define a non\-hierarchical logging process\&. E\&.g\&., \fIstr(\(dq\&abc\(dq\&)\fP defines the log\-identifying characters \fI\(cq\&a\(cq\&, \(cq\&b\(cq\&,\fP and \fI\(cq\&c\(cq\&\fP which can then be used to define log\-statements for each of those categories\&. These log\-identifying characters may be redefined, activating only those log\-statements whose identifying characters were specified in the last call of the \fIstr\fP member\&. .PP Although hierarchical and non\-hierarchical logging can both be used in a single program, they operate in a mutually exclusive way: once hierarchical logging is defined the non\-hierarchical categories are erased, and once non\-hierarchical categories are defined the hierarchical resistance level is set to its maximum value, effectively suppressing hierarchical logging\&. .PP By default logged messages are prepended by time stamps\&. Following the time stamps a delimiter (by default a single space character) is inserted\&. Delimiters are immediately appended to time stamps and inserted messages are immediately appended to delimiters\&. When specifying text as delimiters consider starting and ending the delimiter\(cq\&s text with space characters to visually separate the delimiter from the time stamp and from the subsequently inserted information\&. .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::LogBuf\fP objects\&. It is used with \fILog\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 When inserting \fIFATAL\fP into a \fILog\fP object an \fIFBB::Exception\fP exception is thrown (see \fIoperator<<\fP below); .IP .IP o \fBnl\fP: .br When inserting \fInl\fP into a \fILog\fP object a \fI\en\fP 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\(cq\&s preferred: the time stamp occupies 15 character positions (not counting the width of the delimiter, see the \fBCONSTRUCTORS\fP section below)\&. If a \fIlevel\fP specification is active, it remains active at insertions following \fInl\fP\&. .IP .IP o \fBfnl\fP: .br When inserting \fIfnl\fP (forced new line) into a \fILog\fP object the current line ends even if the currently active insertion `force\(cq\& (set by \fIlevel\fP) is lower than the \fILog\fP object\(cq\&s `resistance\(cq\& level\&. If a \fIlevel\fP specification is active, it remains active at insertions following \fIfnl\fP\&. .IP .IP o \fBendl\fP or \fB\en\fP: .br When inserting \fIendl\fP or \fI\en\fP the current line is ended and the next logged line starts with a timestamp (unless timestamps are suppressed)\&. The \fIendl\fP manipulator is the standard \fIostream\fP manipulator: when inserted into a \fILog\fP object its buffer is flushed\&. The scope of a \fIlevel\fP specification ends at \fI\en\fP or \fIendl\fP\&. E\&.g\&., .nf log\&.setLevel(2); log << level(1) << \(dq\&first line\en\(dq\& \(dq\&second line\en\(dq\&; .fi results in \fIsecond line\fP (preceded by a timestamp) being logged\&. .PP .SH "CONSTRUCTORS" .IP o \fBLog()\fP: .br The default constructor creates a \fILog\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 are preceded by a time stamp (see the description of the member \fIsetTimestamp\fP below), and a single space character is inserted as delimiter immediately beyond the time stamp\&. The member \fIopen\fP can be used to modify the default delimiter\&. .IP .IP o \fBLog(std::ostream &out, char const *delim = \(dq\& \(dq\&)\fP: .br This constructor creates a \fILog\fP object logging its messages to the provided \fIstd::ostream\fP object\&. By default, all messages are preceded by a time stamp (see the description of the member \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter should not be used an empty string or a 0\-pointer may be specified\&. .IP .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 \fILog\fP object logging its messages to the named file\&. If \fIfilename == \(dq\&&1\(dq\&\fP logmessages are written to the standard output stream\&. If \fIfilename == \(dq\&&2\(dq\&\fP 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 \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter should not be used an empty string or a 0\-pointer may be specified\&. .PP Copy and move constructors (and assignment operators) are not available\&. .PP .SH "MEMBER FUNCTIONS" All members of \fIstd::ostream\fP are available, as \fILog\fP inherits from this class\&. .IP o \fBsize_t level() const\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 .IP o \fBstd::ostream &level(size_t useLevel)\fP: .br This member defines the log\-level of messages that are going to be inserted\&. Messages are inserted when \fIuseLevel\fP is at least equal to the level specified by \fIsetLevel\fP\&. The maximum level 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 level that is specified by this member remains active until another \fIlevel\fP call changes it\&. Alternatively, the level of inserted messages may be specified by inserting a \fIFBB::level\fP manipulator into a \fILog\fP object (see \fBlevel\fP(3bobcat)); .IP .IP o \fBvoid off()\fP: .br Prevents log messages from being generated\&. It is cancelled by calling \fIon\fP (see below); .IP .IP o \fBvoid on(size_t logLevel = 0)\fP: .br Reactivates logging (e\&.g\&., after \fIoff\fP was previously called) setting the level that inserted information must at least have (to \fIlogLevel\fP)\&. Following \fIon\fP and unless specified otherwise (e\&.g\&., by using \fIlevel\fP) all inserted information is accpted by the \fILog\fP object; .IP .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 a \fILog\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\&. Also by default all messages are preceded by time stamps (see the description of the member \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter should not be used an empty string or a 0\-pointer may be specified; .IP .IP o \fBvoid setLevel(size_t resistance)\fP: .br Defines the `resistance\(cq\& when inserting information into a \fILog\fP object\&. Information is inserted if the level set by the \fIlevel\fP member is at least equal to \fIresistance\fP\&. Following \fIsetLevel\fP and unless specified otherwise (e\&.g\&., by using \fIlevel\fP) all inserted information is accpted by the \fILog\fP object\&. \fIsetLevel\fP does not reactivate logging after calling \fIoff\fP\&. To reactivate logging after calling \fIoff on\fP must be called; .IP .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 15 characters showing the abbreviated month\(cq\&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 \fI/var/log\fP files\&. E\&.g\&., \fIAug 05 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 specifying \fIstamps\fP as \fIFBB::NOTIMESTAMPS delim\fP also is ignored\&. .IP .IP o \fBstd::string const &str() const\fP: .br The currently set of characters that can be specified by \fILog\(cq\&s\fP function call operator to insert a log\-entry is returned\&. By default no characters are specified; .IP .IP o \fBvoid str(std::string const &chars)\fP: .br The argument to this member is a \fIstd::string\fP defining the characters that can be specified by \fILog\(cq\&s\fP function call operator to insert a log\-entry\&. If the function call operator specifies a character which is not specified in \fIchars\fP then that log message is ignored\&. By default no characters are specified\&. .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 Returns a reference to a static \fILog\fP object\&. It may only be called once, or an \fIFBB::Exception\fP exception is thrown\&. It associates a static \fILog\fP object with the named file\&. .IP If \fIfilename == \(dq\&&1\(dq\&\fP logmessages are written to the standard output stream\&. If \fIfilename == \(dq\&&2\(dq\&\fP 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 \fIsetTimestamp\fP below)\&. The parameter \fIdelim\fP is inserted immediately beyond the time stamp\&. If a delimiter should not be used an empty string or a 0\-pointer may be specified; .IP .IP o \fBFBB::Log &instance()\fP: .br Returns a reference to a static \fILog\fP object, available after calling \fILog::initialize\fP\&. If called before \fILog::initialize()\fP an \fIFBB::Exception\fP exception is thrown\&. .PP .SH "OVERLOADED OPERATORS" .PP .IP o \fBLog &operator()(char ch)\fP: .br If the function\(cq\&s argument is found in the characters specified at the \fIstr\fP member subsequent insertions until (including) inserting \fIstd::endl\fP or the \fIfnl\fP or \fIFATAL LogManipulator\fP are logged\&. If the function\(cq\&s argument is not found in the characters specified at the \fIstr\fP member then subsequent insertions are ignored\&. By calling this member hierarchical insertions are suppressed until the \fIsetLevel\fP member is called; .IP .IP o \fBLog &operator<<(Log &, LogManipulator)\fP: .br This operator inserts a \fILogManipulator\fP into a \fILog\fP object\&. When inserting \fIFBB::FATAL\fP an \fIFBB::Exception\fP is thrown; when inserting \fIFBB::nl\fP the line is terminated, and the next insertion won\(cq\&t start with a time stamp; when inserting \fIFBB::fnl\fP the line is terminated, and the next insertion will start with a time stamp (if applicable)\&. After calling this insertion operator with the \fIFATAL\fP or \fIfnl LogManipulator\fP value category\-based insertions are suppressed until the function\-call operator is called; .IP .IP o \fBLog &operator<<(Log &log, Type const &type)\fP: .br This operator is defined as a template, where \fIType\fP represents any type that can be inserted into a \fIstd::ostream\fP\&. The value \fItype\fP is inserted into the \fILog\fP object; .IP .IP o \fBLog &operator<<(Log &log, Type &(*fun)(Type &type))\fP: .br In this operator \fIfun\fP represents the standard \fIostream\fP and \fIios_base\fP manipulators, allowing the insertion of manipulators like \fIstd::endl\fP and \fIstd::setw\fP into \fILog\fP objects; .IP .IP o \fBstd::ostream &::operator<<(std::ostream &str, FBB::LogManipulator)\fP: .br This operator is defined outside of the \fIFBB\fP namespace\&. It is kept for backward compatibility with previous \fBbobcat\fP versions, and calls \fIoperator<<(Log, LogManipulatr)\fP when \fI&str\fP can dynamically be casted to a \fILog *\fP\&. If not, then the operator performs no actions\&. .PP .SH "EXAMPLE" .nf #include #include //#include #include \(dq\&\&.\&./log\(dq\& #include using namespace std; using namespace FBB; int main() { // Log &log = Log::initialize(\(dq\&&1\(dq\&); // uses the static Log object Log log; // explicitly defining a Log object // log\&.open(\(dq\&/tmp/out\(dq\&); // or at once: Log log{ \(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 << \(dq\&This message is not shown\en\(dq\&; log << fnl; log << \(dq\&This message is not shown\en\(dq\&; log\&.on(2); log << \(dq\&This message is shown\en\(dq\&; log << level(0) << \(dq\¬ shown\(dq\& << level(2) << \(dq\&shown at level 2\en\(dq\&; log << level(3) << \(dq\&at level(3)\(dq\& << level(1) << \(dq\¬ shown\(dq\& << fnl; log << \(dq\&separate new line\en\(dq\&; log << level(2) << \(dq\&in business again\en\(dq\&; log << \(dq\&final line\en\(dq\&; log\&.str(\(dq\&ab\(dq\&); log(\(cq\&a\(cq\&) << \(dq\&hello a!\(dq\& << endl; log(\(cq\&b\(cq\&) << \(dq\&hello b!\(dq\& << nl << setw(16) << \(cq\& \(cq\& << \(dq\&so far, so good\(dq\& << endl; log << \(dq\¬ shown\(dq\& << endl; log(\(cq\&c\(cq\&) << \(dq\¬ shown\en\(dq\&; log << \(dq\¬ shown\en\(dq\&; log\&.setLevel(2); log << level(2) << \(dq\&in business 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), \fBlogbuf\fP(3bobcat), \fBsyslogstream\fP(3bobcat) .PP .SH "BUGS" The \fInl\fP and \fIfnl\fP manipulators are received by the \fILog\fP objects\(cq\& \fILogBufs\fP as, respectively, characters 0 and 1\&. Since log files in practice only received printable characters this should not cause any problems\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_6\&.04\&.00\-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