目錄

名稱

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) 程式的介面。呼叫 syslog() 並傳遞字串優先順序和 printf() 參數清單，就像 syslog(3) 一樣。

匯出

Sys::Syslog 匯出下列 Exporter 標籤

預設情況下，Sys::Syslog 匯出 :standard 標籤中的符號。

FUNCTIONS

openlog($ident, $logopt, $facility)

開啟 syslog。$ident 會加在每則訊息之前。$logopt 包含下列選項中的零個或多個。$facility 指定要報告的系統部分，例如 LOG_USER 或 LOG_LOCAL0：請參閱 "Facilities" 以取得已知設施的清單，並參閱 syslog(3) 文件以取得系統中可用的設施。請查看 "SEE ALSO" 以取得有用的連結。設施可以字串或數字巨集提供。

如果無法連線到 syslog 惡魔程式，此函數會 croak。

請注意，openlog() 現在會採用三個引數，就像 openlog(3) 一樣。

您應該在呼叫 syslog() 之前使用 openlog()。

選項

  • cons - 此選項會被忽略，因為如果所有其他媒體都失敗，故障轉移機制會自動降級到主控台。

  • ndelay - 立即開啟連線（通常，連線會在記錄第一則訊息時開啟）。

  • noeol - 設定為 true 時，訊息不會附加換行字元 (\n)。這對某些 syslog 惡魔程式來說可能很有用。已新增至 Sys::Syslog 0.29。

  • nofatal - 設定為 true 時，如果無法建立與 syslog 的連線，openlog() 和 syslog() 只會發出警告，而不是發生錯誤。已新增至 Sys::Syslog 0.15。

  • nonul - 設定為 true 時，訊息不會附加 NUL 字元 (\0)。這對某些 syslog 惡魔程式來說可能很有用。已新增至 Sys::Syslog 0.29。

  • nowait - 不要等待在記錄訊息時可能已建立的子處理程序。（GNU C 函式庫不會建立子處理程序，因此此選項對 Linux 沒有影響。）

  • perror - 將訊息寫入標準錯誤輸出以及系統記錄。新增於 Sys::Syslog 0.22。

  • pid - 在每則訊息中包含 PID。

範例

使用選項 ndelay 和 pid，以及功能 LOCAL0 開啟 syslog

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() 會嘗試猜測 $ident，方法是擷取 $format 中以 ":" 結尾的最短字首。

範例

# 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，選取 socket 類型 (或「機制」)。可傳遞陣列參考，以指定要嘗試的數個機制，順序為所給定的順序。

  • path - 等同於 $stream_location，設定串流位置。預設為標準 Unix 位置或 _PATH_LOG。

  • timeout - 等同於 $sock_timeout，設定 socket 超時時間 (單位為秒)。在所有系統上預設為 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 socket，在 syslog/tcp 或 syslogng/tcp 服務上。另請參閱 host、port 和 timeout 選項。

  • "udp" - 連線至 UDP socket，在 syslog/udp 服務上。另請參閱 host、port 和 timeout 選項。

  • "inet" - 連線至 INET socket，TCP 或 UDP，依序嘗試。另請參閱 host、port 和 timeout 選項。

  • "unix" - 連線至 UNIX 領域 socket (在某些系統中為字元特殊裝置)。該 socket 的名稱由 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 socket 機制

setlogsock("udp");

使用 TCP socket 機制傳送訊息至自訂埠

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

使用 TCP socket 機制傳送訊息至遠端主機

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

嘗試 native、UDP socket，然後是 UNIX 領域 socket 機制

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

現在，由於 "native" 機制已受 Sys::Syslog 支援且預設選取，因此不建議使用 setlogsock() 函式，因為其他機制在作業系統間的可移植性較低。建議使用此函式（尤其是其 cargo-cult 形式 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 值。

傳遞給 setlogsock 的 eventlog，但沒有 Win32 API 可用

(W) 您要求 setlogsock() 使用 Win32 事件記錄器，但執行程式的作業系統不是 Win32 或不提供相容於 Win32 的設施。

無法連線到 syslog

(F) syslog() 無法連線到指定的 socket。

傳遞給 setlogsock 的串流，但 %s 無法寫入

(W) 您要求 setlogsock() 使用串流 socket，但所提供的路徑無法寫入。

傳遞給 setlogsock 的串流，但找不到任何裝置

(W) 您要求 setlogsock() 使用串流 socket，但沒有提供路徑，而 Sys::Syslog 無法找到適當的路徑。

傳遞給 setlogsock 的 tcp，但 tcp 服務不可用

(W) 您要求 setlogsock() 使用 TCP socket，但此服務在系統上不可用。

syslog：預期參數 %s

(F) 您忘記提供 syslog() 指出的參數。

syslog：無效的層級/設施：%s

(F) 您指定了無效的層級或設施。

syslog：給定的層級太多：%s

(F) 您指定的層級太多。

syslog：給定的設施太多：%s

(F) 您指定的設施太多。

syslog：必須提供層級

(F) 您忘記指定層級。

傳遞給 setlogsock 的 udp，但 udp 服務不可用

(W) 您要求 setlogsock() 使用 UDP socket，但此服務在系統上不可用。

傳遞給 setlogsock 的 unix，但路徑不可用

(W) 您要求 setlogsock() 使用 UNIX socket，但 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 - Log4j API 的 Perl 實作

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 的文件，https://gnu.dev.org.tw/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 關於 syslog 的文件，http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.basetechref/doc/basetrf2/syslog.htm

HP-UX 11i 關於 syslog 的文件，http://docs.hp.com/en/B2355-60130/syslog.3C.html

Tru64 關於 syslog 的文件，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

RFC

RFC 3164 - BSD syslog 通訊協定，http://www.faqs.org/rfcs/rfc3164.html -- 請注意，這是一個資訊性 RFC，因此不指定任何類型的標準。

RFC 3195 - syslog 可靠傳遞，http://www.faqs.org/rfcs/rfc3195.html

文章

使用 Perl 進行 Syslog，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 程式碼。

由 Nicholas Clark <nick (at) ccl4.org> 重新產生 constant() 的程式碼。

由 Nick Williams <Nick.Williams (at) morganstanley.com> 故障轉移到不同的通訊模式。

由 Sébastien Aperghis-Tramoni <sebastien (at) aperghis.net> 從核心發行版中擷取出來，以便在 CPAN 上發布。

用於使用原生 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 相同的條款下重新散布或修改它。