NAME

UniLog - Perl module for unified logging on Unix and Win32

SYNOPSIS

use UniLog qw(:levels);
use UniLog qw(:options :facilites); # Not useful on Win32

$Logger=UniLog->new(Ident    => "MyProgram",
                                # The log source identification
                    Options  => LOG_PID|LOG_CONS|LOG_NDELAY,
                                # Logger options, see "man 3 syslog"
                    Facility => LOG_USER,
                                # Logger facility, see "man 3 syslog"
                    Level    => LOG_INFO,
                                # The log level                       
                    StdErr   => 1);
                                # Log messages also to STDERR

$Logger->Message(LOG_NOTICE, "Message text here");
         # Send message to the log

$Logger->Message(LOG_DEBUG, "You should not see this");
         # Will not be logged
$Logger->Level(LOG_DEBUG);
$Logger->Message(LOG_DEBUG, "You should see this now");
         # Will be logged

$Logger->StdErr(0);
         # Stop logging to STDERR
$Logger->Message(LOG_INFO, "Should not be logged to STDERR");
         # Send message to the log

$Logger->Close();

DESCRIPTION

This module provides an unified way to send log messages on Unix and Win32. Messages are logged using syslog on Unix and using EventLog on Win32.

This module uses Unix::Syslog Perl module on Unix and Win32::EventLog Perl module on Win32.

The idea was to give a programmer a posibility to write a program which will be able to run on Unix and on Win32 without code adjusting and with the same logging functionality.

Notes:

Win32::EventLog does not support any Win32 platform except WinNT. So, UniLog does not support them too.

Logging to remote server is not supported in this release.

Module was tested on FreeBSD 4.2, Win2000 and Solaris 7.

The UniLog methods

new(%PARAMHASH);

The new method creates the logger object and returns a handle to it. This handle is then used to call the methods below.

The %PARAMHASH could contain the following keys:

Ident

Ident field specifies a string which will be used as message source identifier. syslogd(8) will print it into every message and EventLog will put it to the "Source" message field.

Default is $0, the name of the program being executed.

Options

This is an integer value which is the result of ORed options: LOG_CONS, LOG_NDELAY, LOG_PID.

See Unix::Syslog, syslog(3) for details.

Default is LOG_PID|LOG_CONS.

This field is ignored on Win32.

Facility

This is an integer value which specifies the part of the system the message should be associated with (e.g. kernel message, mail subsystem).

Could be LOG_AUTH, LOG_CRON, LOG_DAEMON, LOG_KERN, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_SYSLOG, LOG_USER, LOG_UUCP, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.

See Unix::Syslog, syslog(3) for details.

Default is LOG_USER.

This field is ignored on Win32.

Level

This is an integer value which specifies log level. All messages with Level greater than Level will not be logged. You will be able to change Level using Level method. See Message method description for available log levels.

Default log level is LOG_INFO.

StdErr

If this flag have a 'true' value all messages are logged to STDERR in addition to syslog/EventLog. You will be able to change this flag using StdErr method.

Default is 0 - do not log to STDERR.

Message($Level, $MessageStr);

The Message method send a $MessageStr to the syslog or EventLog and, if allowed, to STDERR.

The $Level should be an integer and could be:

LOG_EMERG

Value 0. Will be logged as LOG_EMERG in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_ALERT

Value 1. Will be logged as LOG_ALERT in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_CRIT

Value 2. Will be logged as LOG_CRIT in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_ERR

Value 3. Will be logged as LOG_ERR in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_WARNING

Value 4. Will be logged as LOG_WARNING in syslog, as EVENTLOG_WARNING_TYPE in EventLog.

LOG_NOTICE

Value 5. Will be logged as LOG_NOTICE in syslog, as EVENTLOG_INFORMATION_TYPE in EventLog.

LOG_INFO

Value 6. Will be logged as LOG_INFO in syslog, as EVENTLOG_INFORMATION_TYPE in EventLog.

LOG_DEBUG

Value 7. Will be logged as LOG_DEBUG in syslog, as EVENTLOG_INFORMATION_TYPE in EventLog.

Default is LOG_INFO.

See Unix::Syslog(3) for "LOG_*" description, see Win32::EventLog(3) for "EVENTLOG_*_TYPE" descriptions.

$MessageStr is a string which will be sended to syslog/EventLog and, if allowed, printed to STDERR.

Following substitutions will be made for $MessageStr:

$MessageStr =~ s/\A\s+//;
$MessageStr =~ s/\s+\Z//;
chomp($MessageStr);
$MessageStr =~ s/\s+/ /g;
$MessageStr =~ s/\n/"; "/g;

Level([$LogLevel]);

If $LogLevel is not specified Level returns a current log level. If $LogLevel is specified Level sets the log level to the new value and returns a previous value.

StdErr([$Flag]);

If $Flag is not specified StdErr returns a current state of logging-to-STDERR flag. If $Flag is specified StdErr sets the logging-to-STDERR flag to the new state and returns a previous state.

Close();

Close the logger.

EXPORT

None by default.

AUTHOR

Daniel Podolsky, <tpaba@cpan.org>

SEE ALSO

Unix::Syslog, Win32::EventLog, syslog(3).