NAME
OTC_Logger -
Base class for additional message loggers.
SYNOPSIS
#include <OTC/debug/logger.hh>
class OTC_Logger
{
public:
virtual ~OTC_Logger();
static void notify(OTC_LogLevel theLevel, char const* theMessage);
inline static OTC_Boolean stderrOutputEnabled();
inline static void enableStderrOutput();
inline static void disableStderrOutput();
inline static char const* logFile();
inline static void setLogFile(char const* theFile);
protected:
OTC_Logger();
virtual void log(
OTC_LogLevel theLevel,
char const* theMessage
) = 0;
};
CLASS TYPE
Abstract
DESCRIPTION
OTC_Logger is the base class for additional message loggers. The
class is also the entry point for displaying a message using the
logger.
If you wish to log messages to destinations, in addition to those
which may already be active, you should create a derived version
of OTC_Logger which defines log() to send the message to the
appropriate destination. When you create an instance of the
derived class, it will automatically be linked in to the list of
active loggers; when the instance is destroyed, it will
automatically unlink itself from the list of active loggers.
When the OTC_Logger class is compiled, if the symbol NDEBUG is
not defined, in addition to broadcasting messages to user provided
loggers, the logger will display messages on standard error using
file descriptor 2. To turn off output to standard error, you can
define the environment variable OTCLIB_NOLOGSTDERR. If the OSE
C++ libraries have been installed in the standard manner, the
symbol NDEBUG is not defined when the dbg, prf and std
variants of the libraries are compiled. Therefore, if you link
your programs with these variants of the library, messages by
default will be displayed on standard error.
If the OTC_Logger class is compiled with NDEBUG defined, the
logger will NOT log messages to standard error. To turn on
output to standard error, you can define the environment variable
OTCLIB_LOGSTDERR. If the OSE C++ libraries are installed in
the standard manner, the symbol NDEBUG is defined when the
opt variant of the library is compiled.
Regardless of whether NDEBUG was defined when the OTC_Logger
class was compiled, you can enable saving of messages to a file,
by defining the environment variable OTCLIB_LOGFILE to be the
name of a file in which to save them. By default, this file will
be truncated the first time it is opened. If you prefer messages
to be appended to the file, you should define the environment
variable OTCLIB_APPENDLOGFILE.
If you need to change the number of the file descriptor used, to
display messages to standard error, you can define the environment
variable OTCLIB_LOGFD. This can be used to send messages through
a secondary process which either filters or highlights messages
as a debugging aid. There is no abilility to change the log file
descriptor from within an application.
An example of the messages displayed by the standard logger are:
EMERGENCY: EMERGENCY level
ALERT: ALERT level
CRITICAL: CRITICAL level
ERROR: ERROR level
WARNING: WARNING level
NOTICE: NOTICE level
INFO: INFO level
DEBUG: DEBUG level
TRACE: TRACE level
The text after the colon is the message. The text before
the colon corresponds to the priority level at which the message
was logged. Display of a long format message containing a time
stamp and the process ID of the program can be enabled by setting
the environment variable OTCLIB_LOGLONGFORMAT. If multiple
programs are saving messages to the same log file you should
enable this option.
DESTRUCTION
virtual ~OTC_Logger();
Removes this logger from the list of
all active logger modules.
BROADCAST
static void notify(OTC_LogLevel theLevel, char const* theMessage);
If required, this logs theMessage to
standard error and a file and then
broadcasts theMessage to any active
loggers. The value theLevel is the
priority level of the message. Valid
values for theLevel are:
OTCLIB_LOG_EMERGENCY
OTCLIB_LOG_ALERT
OTCLIB_LOG_CRITICAL
OTCLIB_LOG_ERROR
OTCLIB_LOG_WARNING
OTCLIB_LOG_NOTICE
OTCLIB_LOG_INFO
OTCLIB_LOG_DEBUG
OTCLIB_LOG_TRACE
Except for OTCLIB_LOG_TRACE, these are
analogous to the values accepted by
syslog().
STDERR OUTPUT
Note that enabling and disabling of log output has no effect
when an alternate file descriptor is provided for log messages.
inline static OTC_Boolean stderrOutputEnabled();
Returns OTCLIB_TRUE if output of
log messages to stderr is enabled.
inline static void enableStderrOutput();
Enables output of log messages to
stderr.
inline static void disableStderrOutput();
Disables output of log messages to
stderr.
LOG FILE
Note that log file names should always be absolute pathnames.
This is because the file is opened each time a message needs
to be written. If the file name was not absolute and the
working directory of the program was changed, the file would
be written to the new working directory.
Two special tags may be embedded into the name of a file.
These are %p and %h. The tag %p will be replaced with
the process ID, and %h with the hostname of the machine.
To embed a % character in the filename, you should use
%%.
inline static char const* logFile();
If a log file is currently being used,
the name of the file is returned.
Returns 0 if no log file specified.
inline static void setLogFile(char const* theFile);
Sets the name of the log file. All
log messages will now go to this
file until the process terminates
or the file is changed.
CONSTRUCTION
OTC_Logger();
Inserts this logger in to the list of
active loggers.
LOGGING
virtual void log(OTC_LogLevel theLevel, char const* theMessage) = 0;
Must be redefined in a derived class by
your logger. The arguments theLevel and
theMessage are the same as those
originally passed to notify(). Your
derived class is free to use the values of
the arguments as it wishes, however, it
should not assume responsibility for
deleting theMessage.
NOTES
Any logger you write should avoid doing anything that would
require memory to be allocated. This is necessary, as it could be
that the message is to notify you that memory has been exhausted.
Also, your logger should avoid using form() as the message
could have been constructed originally using the function. Using
form() again, without first copying the message, would result in
the original message being lost.
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1992 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED