unilog(3) - Linux man page

Name

UniLog - Perl module for unified logging on Unix and Win32

Version 0.14

Synopsis

use UniLog qw(:levels syslog);
use UniLog qw(:options :facilities); # 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
     or die "Can not create the logger: $!";

$Logger->Message(LOG_NOTICE, "Message text here, time: %d", time())
      or die "Logging error: $!";
         # 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 a 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 possibility 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" provides only STDERR and file logging on these platforms.

Logging to remote server is not supported in this release.

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

Note about system logging

To utilize the OS logging facilities "UniLog" is using external modules. These modules are not available on some platforms. On these platforms you can use "UniLog" for STDERR and/or file logging, you just have to prevent "UniLog" from attempt to load system logging module. It can be done by importing 'fake' function "nosyslog". You would typically do it by saying

perl -MUniLog=nosyslog script.pl

or by including the string "-MUniLog=nosyslog" in the PERL5OPT environment variable. Also, the command

use UniLog qw(:levels :options :facilities nosyslog);

can be used inside of perl script.

See also the EXPORT section.

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. The message 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".

"SysLog"

If this flag have a 'true' value all messages are logged using Unix::Syslog or Win32::EventLog, if possible.

You will be able to change this flag using "SysLog" method.

Default is 1 - log to system log.

"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".

"LogFile"

The name for the log file. If defined, all messages are logged to this file in addition to syslog/EventLog and "STDERR".

The "LogFile" have to be treated as a template for the file name because it is processed by "POSIX::strftime" function before actual file opening. See POSIX::strftime for details.

Of course, the log file will be automatically changed if necessary. For example, new log file will be created every hour if "LogFile" contains '%H'. Of course, all necessary directories will be created.

"FilePerms"

The permissions for log file. Default is 0640

"DirPerms"

The permissions for directories created for log file. Default is 0750

"Truncate"

If this flag have a 'true' value the log file will be truncated before start logging. You will be able to change this flag using Truncate method.

Default is 0 - do not truncate file.

"SafeStr"

If 'true' all the 'dangerous' symbols will be printed as their hex codes.

Default is 1 - change dangerous symbols to their hex codes.

In case of fatal error "new()" returns "undef". $! variable will contain the error message.

"Message($Level, $Format, @SprintfParams);"

The "Message" method send a log string to the syslog or EventLog and, if allowed, to "STDERR". Log string will be formed by "sprintf" function from $Format format string and parameters passed in @SprintfParams. Of course, @SprintfParams could be empty if no parameters required by format string. See "sprintf" in "perlfunc" for details.

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.

In case of fatal error "Message()" returns "undef". $! variable will contain the error message.

"emergency($Format, @SprintfParams);"

Just a synonym for "Message(LOG_EMERG, $Format, @SprintfParams)"

"alert($Format, @SprintfParams);"

Just a synonym for "Message(LOG_ALERT, $Format, @SprintfParams)"

"critical($Format, @SprintfParams);"

Just a synonym for "Message(LOG_CRIT, $Format, @SprintfParams)"

"error($Format, @SprintfParams);"

Just a synonym for "Message(LOG_ERR, $Format, @SprintfParams)"

"warning($Format, @SprintfParams);"

Just a synonym for "Message(LOG_WARNING, $Format, @SprintfParams)"

"notice($Format, @SprintfParams);"

Just a synonym for "Message(LOG_NOTICE, $Format, @SprintfParams)"

"info($Format, @SprintfParams);"

Just a synonym for "Message(LOG_INFO, $Format, @SprintfParams)"

"debug($Format, @SprintfParams);"

Just a synonym for "Message(LOG_DEBUG, $Format, @SprintfParams)"

"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.

"SysLog([$Flag]);"

If $Flag is not specified "SysLog" returns a current state of logging-to-system-log flag. If $Flag is specified "SysLog" sets the logging-to-system-log flag to the new state and returns a previous state.

"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.

"LogFile([$NewLogFileName, [$FilePerms]]);"

If $NewLogFileName is not specified "LogFile" returns a current log file name. Not the "log file name template" but the actual file name.

If $NewLogFileName is specified "LogFile" sets the "log file name template" to the $NewLogFileName and returns a previous log file name (the actual file name). The actual closing old file and opening ne one will be done during next "Message()" call.

Note: you can specify an empty line as a $NewLogFileName parameter. It will mean "disable file logging".

"Permissions([$FilePerms, [$DirPerms]]);"

If no parameters is specified "Permissions" returns the current permissions used for new log file creation.

If $FilePerms is specified "Permissions" sets the log file permissions to the $FilePerms and returns a previous value.

If $DirPerms is specified "Permissions" sets the new directories permissions to the $DirPerms.

In scalar context "Permissions" returns the previous log file permissions value. In list context "Permissions" returns an two-elements array, firs is original log file permissions, second is directories permissions.

"Truncate([$Flag]);"

If $Flag is not specified "Truncate" returns a current state of "Truncate" flag. If $Flag is specified "Truncate" sets the "Truncate" flag to the new state and returns a previous state.

"CloseLogFile([$NewLogFileName]);"

Enforce "UniLog" to close log file temporary. It will be re-opened for next message. If you set the "Truncate" flag to 'true' value file will be truncated during re-opening.

"Close();"

Close the logger.

"SafeStr($Str);"

Just change all dangerous symbols ("\x00-\x1F" and "\xFF") in a $Str to their hexadecimal codes and returns the updated string.

EXPORT

None by default.

":levels"

All "Levels", described in the "Message" method documentation

":options"

All "Options", described in the "new" method documentation

":facilities"

All "Facilities", described in the "new" method documentation

":functions"

All auxiliary functions. Just "SafeStr()" at the moment.

"SafeStr"

"SafeStr()" function.

"syslog"

Fake symbol, tells "UniLog" to try to load the system logging module at the module load time.

"nosyslog"

Fake symbol, tells "UniLog" do not to try to load the system logging module at the module load time. The logging to Syslog/EventLog will be disabled.

If no "syslog" nor "nosyslog" present, "UniLog" will try to load the system logging module at the first "new" method call.

Known problems

Problem with Perl2Exe utility.

UniLog is using external module (Unix::Syslog or Win32::Event) for actual logging. The appropriate module is loading during runtime (in "eval" section) so Perl2Exe is not able to determinate this module have to be compiled in. You have to include "use Unix::Syslog;" or "use Win32::EventLog;" to your script or disable syslog usage.

Uptate (Jan 10 2005): forget about Perl2Exe, use PAR instead (see bundled pp utility).

Author

Daniel Podolsky, <tpaba@cpan.org>

See Also

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