内容

名称

Sys::Syslog - Perl 对 UNIX syslog(3) 调用的接口

版本

这是版本 0.36 的文档

概要

use Sys::Syslog;                        # all except setlogsock()
use Sys::Syslog qw(:standard :macros);  # standard functions & macros

openlog($ident, $logopt, $facility);    # don't forget this
syslog($priority, $format, @args);
$oldmask = setlogmask($mask_priority);
closelog();

描述

Sys::Syslog 是对 UNIX syslog(3) 程序的接口。使用字符串优先级和 printf() 参数列表调用 syslog()，就像 syslog(3) 一样。

导出

Sys::Syslog 导出以下 Exporter 标签

默认情况下，Sys::Syslog 导出 :standard 标签中的符号。

函数

openlog($ident, $logopt, $facility)

打开系统日志。$ident 会被添加到每条消息的前面。$logopt 包含一个或多个下面详细说明的选项。$facility 指定要报告的系统部分，例如 LOG_USER 或 LOG_LOCAL0：有关常用设施的列表，请参阅 "设施"，有关系统中可用的设施，请参阅 syslog(3) 文档。查看 "参见" 获取有用链接。设施可以作为字符串或数字宏给出。

如果无法连接到系统日志守护进程，此函数将报错。

请注意，openlog() 现在接受三个参数，就像 openlog(3) 一样。

在调用 syslog() 之前，您应该使用 openlog()。

选项

  • cons - 此选项被忽略，因为如果所有其他介质都失败，故障转移机制将自动降级到控制台。

  • ndelay - 立即打开连接（通常，连接在记录第一条消息时打开）。

  • noeol - 当设置为 true 时，不会在消息末尾添加换行符 (\n)。这对于某些系统日志守护进程可能很有用。在 Sys::Syslog 0.29 中添加。

  • nofatal - 当设置为 true 时，如果无法建立与系统日志的连接，openlog() 和 syslog() 将只发出警告，而不是退出。在 Sys::Syslog 0.15 中添加。

  • nonul - 当设置为 true 时，不会在消息末尾添加 NUL 字符 (\0)。这对于某些系统日志守护进程可能很有用。在 Sys::Syslog 0.29 中添加。

  • nowait - 不要等待可能在记录消息时创建的子进程。（GNU C 库不会创建子进程，因此此选项对 Linux 无效。）

  • perror - 将消息写入标准错误输出以及系统日志。在 Sys::Syslog 0.22 中添加。

  • pid - 在每条消息中包含 PID。

示例

使用选项 ndelay 和 pid 打开系统日志，并使用设施 LOCAL0

openlog($name, "ndelay,pid", "local0");

相同的事情，但这次使用与 LOCAL0 相对应的宏

openlog($name, "ndelay,pid", LOG_LOCAL0);
syslog($priority, $message)
syslog($priority, $format, @args)

如果 $priority 允许，则记录 $message 或 sprintf($format, @args)，另外，$message 或 $format 中的 %m 将被替换为 "$!"（最新的错误消息）。

$priority 可以指定级别或级别和设施。级别和设施可以作为字符串或宏给出。使用 eventlog 机制时，优先级 DEBUG 和 INFO 映射到事件类型 informational，NOTICE 和 WARNING 映射到 warning，ERR 和 EMERG 映射到 error。

如果您在使用 syslog() 之前没有使用 openlog()，syslog() 将尝试通过提取 $format 中以 ":" 结尾的最短前缀来猜测 $ident。

示例

# informational level
syslog("info", $message);
syslog(LOG_INFO, $message);

# information level, Local0 facility
syslog("info|local0", $message);
syslog(LOG_INFO|LOG_LOCAL0, $message);
注意

Sys::Syslog 版本 v0.07 及更早版本将 $message 作为格式化字符串传递给 sprintf()，即使没有提供格式化参数也是如此。如果调用 syslog() 的代码可能与该模块的旧版本一起执行，请确保将函数调用为 syslog($priority, "%s", $message) 而不是 syslog($priority, $message)。这可以防止恶意格式化序列在 $message 包含受污染的数据时出现。

setlogmask($mask_priority)

将当前进程的日志掩码设置为$mask_priority，并返回旧的掩码。如果掩码参数为 0，则不会修改当前日志掩码。有关可用级别的列表，请参见"级别"。可以使用LOG_UPTO()函数允许所有级别（但它只接受数字宏作为参数）。

示例

仅记录错误

setlogmask( LOG_MASK(LOG_ERR) );

记录除信息消息之外的所有内容

setlogmask( ~(LOG_MASK(LOG_INFO)) );

记录严重消息、错误和警告

setlogmask( LOG_MASK(LOG_CRIT)
          | LOG_MASK(LOG_ERR)
          | LOG_MASK(LOG_WARNING) );

记录所有消息，直到调试

setlogmask( LOG_UPTO(LOG_DEBUG) );
setlogsock()

设置用于下一次调用openlog()或syslog()的套接字类型和选项。成功时返回 true，失败时返回undef。

作为 Perl 特定的函数，它随着时间的推移而发展。目前可以按如下方式调用它

  • setlogsock($sock_type)

  • setlogsock($sock_type, $stream_location)（在 Perl 5.004_02 中添加）

  • setlogsock($sock_type, $stream_location, $sock_timeout)（在Sys::Syslog 0.25 中添加）

  • setlogsock(\%options)（在Sys::Syslog 0.28 中添加）

可用的选项是

  • type - 等效于$sock_type，选择套接字类型（或“机制”）。可以传递数组引用来指定要尝试的几种机制，按给定的顺序。

  • path - 等效于$stream_location，设置流位置。默认为标准 Unix 位置，或_PATH_LOG。

  • timeout - 等效于$sock_timeout，设置套接字超时时间（以秒为单位）。在所有系统上默认为 0，除了Mac OS X，它设置为 0.25 秒。

  • host - 设置要发送消息的主机名。默认为本地主机。

  • port - 设置要连接到的 TCP 或 UDP 端口。默认为系统上第一个可用的标准 syslog 端口。

可用的机制是

  • "native" - 使用来自syslog(3) 库的本机 C 函数（在Sys::Syslog 0.15 中添加）。

  • "eventlog" - 将消息发送到 Win32 事件记录器（仅限 Win32；在Sys::Syslog 0.19 中添加）。

  • "tcp" - 连接到 TCP 套接字，在syslog/tcp 或syslogng/tcp 服务上。另请参见host、port 和timeout 选项。

  • "udp" - 连接到 UDP 套接字，在syslog/udp 服务上。另请参见host、port 和timeout 选项。

  • "inet" - 连接到 INET 套接字，TCP 或 UDP，按此顺序尝试。另请参见host、port 和timeout 选项。

  • "unix" - 连接到 UNIX 域套接字（在某些系统中为字符特殊设备）。该套接字的名称由path 选项给出，如果省略，则由_PATH_LOG 宏（如果您的系统定义了它）返回的值，/dev/log 或/dev/conslog，以可写者为准。

  • "stream" - 连接到由 path 选项指示的流，或者，如果省略，则连接到由 _PATH_LOG 宏返回的值（如果您的系统定义了它），/dev/log 或 /dev/conslog，以可写者为准。例如，Solaris 和 IRIX 系统可能更喜欢 "stream" 而不是 "unix"。

  • "pipe" - 连接到由 path 选项指示的命名管道，或者，如果省略，则连接到由 _PATH_LOG 宏返回的值（如果您的系统定义了它），或 /dev/log（在 Sys::Syslog 0.21 中添加）。HP-UX 是使用此类命名管道的系统。

  • "console" - 将消息直接发送到控制台，如 openlog() 的 "cons" 选项。

默认情况下，将尝试 native、tcp、udp、unix、pipe、stream、console。在具有 Win32 API 的系统下，如果 Win32::EventLog 可用，则会将 eventlog 添加为第一个尝试的机制。

为 $sock_type 提供无效值将 croak。

示例

选择 UDP 套接字机制

setlogsock("udp");

使用 TCP 套接字机制在自定义端口上发送消息

setlogsock({ type => "tcp", port => 2486 });

使用 TCP 套接字机制将消息发送到远程主机

setlogsock({ type => "tcp", host => $loghost });

尝试本机、UDP 套接字然后 UNIX 域套接字机制

setlogsock(["native", "udp", "unix"]);
注意

现在 Sys::Syslog 支持 "native" 机制，并且默认情况下选择它，因此不鼓励使用 setlogsock() 函数，因为其他机制在不同操作系统之间的可移植性较差。使用此函数的模块和程序的作者，尤其是其货物崇拜形式 setlogsock("unix")，建议删除所有出现此函数的地方，除非他们特别想使用给定的机制（如 TCP 或 UDP 连接到远程主机）。

closelog()

关闭日志文件，并在成功时返回 true。

SYS::SYSLOG 的规则

Sys::Syslog 的第一条规则是：你不能调用 setlogsock。

Sys::Syslog 的第二条规则是：你不能调用 setlogsock。

Sys::Syslog 的第三条规则是：程序崩溃、die、调用 closelog，日志结束。

Sys::Syslog 的第四条规则是：一个设施，一个优先级。

Sys::Syslog 的第五条规则是：一次一个日志。

Sys::Syslog 的第六条规则是：在 openlog 之前没有 syslog。

Sys::Syslog 的第七条规则是：日志将持续下去，只要它们需要。

Sys::Syslog 的第八条也是最后一条规则是：如果您是第一次使用 Sys::Syslog，您必须阅读文档。

示例

一个例子

openlog($program, 'cons,pid', 'user');
syslog('info', '%s', 'this is another test');
syslog('mail|warning', 'this is a better test: %d', time);
closelog();

syslog('debug', 'this is the last test');

另一个例子

openlog("$program $$", 'ndelay', 'user');
syslog('notice', 'fooprogram: this is really done');

%m 使用示例

$! = 55;
syslog('info', 'problem was %m');   # %m == $! in syslog(3)

将日志记录到 $remotehost 上的 UDP 端口，而不是本地记录

setlogsock("udp", $remotehost);
openlog($program, 'ndelay', 'user');
syslog('info', 'something happened over here');

常量

设施

级别

诊断

传递给 setlogsock 的参数无效

(F) 您为 setlogsock() 提供了 $sock_type 的无效值。

将 eventlog 传递给 setlogsock，但没有可用的 Win32 API

(W) 您要求 setlogsock() 使用 Win32 事件记录器，但运行程序的操作系统不是 Win32 或不提供与 Win32 兼容的功能。

无法连接到 syslog

(F) syslog() 无法连接到指定的套接字。

将流传递给 setlogsock，但 %s 不可写

(W) 您要求 setlogsock() 使用流套接字，但给定的路径不可写。

将流传递给 setlogsock，但找不到任何设备

(W) 您要求 setlogsock() 使用流套接字，但没有提供路径，并且 Sys::Syslog 无法找到合适的路径。

将 tcp 传递给 setlogsock，但 tcp 服务不可用

(W) 您要求 setlogsock() 使用 TCP 套接字，但系统上该服务不可用。

syslog：需要参数 %s

(F) 您忘记为 syslog() 提供指示的参数。

syslog：级别/设施无效：%s

(F) 您指定了无效的级别或设施。

syslog: too many levels given: %s

(F) 您指定了太多级别。

syslog: too many facilities given: %s

(F) 您指定了太多设施。

syslog: level must be given

(F) 您忘记指定级别。

udp passed to setlogsock, but udp service unavailable

(W) 您要求 setlogsock() 使用 UDP 套接字，但系统上该服务不可用。

unix passed to setlogsock, but path not available

(W) 您要求 setlogsock() 使用 UNIX 套接字，但 Sys::Syslog 无法找到合适的设备。

历史

Sys::Syslog 是一个核心模块，自 1990 年起就成为标准 Perl 发行版的一部分。当时，我们所知的模块还不存在，Perl 库是一组 .pl 文件，用于发送 syslog 消息的文件只是 lib/syslog.pl，包含在 Perl 3.0 中。它在 Perl 5.0 中被转换为模块，但只有从 Perl 5.6 开始才具有版本号。以下是一个小型表格，列出了匹配的 Perl 和 Sys::Syslog 版本。

Sys::Syslog     Perl
-----------     ----
   undef        5.0.0 ~ 5.5.4
   0.01         5.6.*
   0.03         5.8.0
   0.04         5.8.1, 5.8.2, 5.8.3
   0.05         5.8.4, 5.8.5, 5.8.6
   0.06         5.8.7
   0.13         5.8.8
   0.22         5.10.0
   0.27         5.8.9, 5.10.1 ~ 5.14.*
   0.29         5.16.*
   0.32         5.18.*
   0.33         5.20.*
   0.33         5.22.*

另请参阅

其他模块

Log::Log4perl - Perl 对 Log4j API 的实现

Log::Dispatch - 将消息分派到一个或多个输出

Log::Report - 报告问题，包括异常和语言支持

手册页

syslog(3)

SUSv3 第 6 版，IEEE Std 1003.1，2004 年版，http://www.opengroup.org/onlinepubs/000095399/basedefs/syslog.h.html

GNU C 库关于 syslog 的文档，http://www.gnu.org/software/libc/manual/html_node/Syslog.html

FreeBSD 关于 syslog 的文档，https://www.freebsd.org/cgi/man.cgi?query=syslog

Solaris 11 关于 syslog 的文档，https://docs.oracle.com/cd/E53394_01/html/E54766/syslog-3c.html

Mac OS X 关于 syslog 的文档，http://developer.apple.com/documentation/Darwin/Reference/ManPages/man3/syslog.3.html

IRIX 关于 syslog 的文档，http://nixdoc.net/man-pages/IRIX/man3/syslog.3c.html

AIX 5L 5.3 系统日志文档，http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.basetechref/doc/basetrf2/syslog.htm

HP-UX 11i 系统日志文档，http://docs.hp.com/en/B2355-60130/syslog.3C.html

Tru64 系统日志文档，http://nixdoc.net/man-pages/Tru64/man3/syslog.3.html

Stratus VOS 15.1，http://stratadoc.stratus.com/vos/15.1.1/r502-01/wwhelp/wwhimpl/js/html/wwhelp.htm?context=r502-01&file=ch5r502-01bi.html

RFCs

RFC 3164 - BSD syslog 协议，http://www.faqs.org/rfcs/rfc3164.html -- 请注意，这是一个信息性 RFC，因此不指定任何标准。

RFC 3195 - syslog 的可靠传递，http://www.faqs.org/rfcs/rfc3195.html

文章

使用 Perl 进行系统日志记录，http://lexington.pm.org/meetings/022001.html

事件日志

Windows 事件日志，http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wes/wes/windows_event_log.asp

作者和致谢

Tom Christiansen <tchrist (at) perl.com> 和 Larry Wall <larry (at) wall.org>。

UNIX 域套接字由 Sean Robinson <robinson_s (at) sc.maricopa.edu> 添加，并得到 Tim Bunce <Tim.Bunce (at) ig.co.uk> 和 perl5-porters 邮件列表的支持。

对 syslog.ph 的依赖由 Tom Hughes <tom (at) compton.nu> 用 XS 代码替换。

constant() 的代码由 Nicholas Clark <nick (at) ccl4.org> 重新生成。

故障转移到不同的通信模式由 Nick Williams <Nick.Williams (at) morganstanley.com> 完成。

从核心发行版中提取出来，并在 CPAN 上发布，由 Sébastien Aperghis-Tramoni <sebastien (at) aperghis.net> 完成。

使用原生 C 函数的 XS 代码借鉴自 Unix::Syslog，由 Marcus Harnisch <marcus.harnisch (at) gmx.net> 编写。

Yves Orton 建议并帮助 Sys::Syslog 在 Win32 系统下使用原生事件记录器。

Jerry D. Hedden 和 Reini Urban 在 Cygwin 下调试和完善 Sys::Syslog 提供了非常宝贵的帮助。

错误

请将任何错误或功能请求报告给 bug-sys-syslog (at) rt.cpan.org，或通过网页界面报告至 http://rt.cpan.org/Public/Dist/Display.html?Name=Sys-Syslog。我会收到通知，然后您会在我对错误进行更改时自动收到进度通知。

支持

您可以使用 perldoc 命令查找此模块的文档。

perldoc Sys::Syslog

您也可以在以下位置查找信息：

源代码可在 Git Hub 上获取：https://github.com/maddingue/Sys-Syslog/

版权

版权所有 (C) 1990-2012 Larry Wall 及其他。

许可证

本程序是自由软件；您可以根据与 Perl 本身相同的条款重新发布和/或修改它。