=encoding euc-jp

=head1 名前

Net::Daemon::Log -  ログ出力のためのユーティリティ関数


=head1 概要

  # ログ出力方法を選択する: syslog または Win32::EventLog
  $self->{'facility'} = 'mail'; # デフォルト: Daemon
  $self->{'logfile'} = undef;   # デフォルト

  # ログ出力方法の選択: stderr
  $self->{'logfile'} = 1;

  # ログ出力方法の選択: IO ハンドル
  my $file = IO::File->new("my.log", "a");
  $self->{'logfile'} = $file;


  # デバッグメッセージ（両方とも同じこと）:
  $self->Log('debug', "This is a debugging message");
  $self->Debug("This is a debugging message");

  # エラー・メッセージ(両方とも同じこと):
  $self->Log('err', "This is an error message");
  $self->Error("This is an error message");

  # 致命的なエラーメッセージ (暗に'die'を意味します）
  $self->Fatal("This is a fatal error message");


=head1 警告

これはALPHA状態のソフトウェアです。これはインターフェース(API)が
最終的に確定されていないためだけに'Alpha'になっています。Alpha状態は
コードの品質や安定性には当てはまりません。


=head1 説明

Net::Daemon::Log は移植性のあるメッセージ・ログ出力のための
ユーティリティ・クラスです。デフォルトではsyslog(Unix）や
Win32::EventLog(Windows)を使いますが、メッセージ・ログ出力を
stderrやログファイルにリダイレクトすることもできます。


=head2 一般的なログ出力

    $self->Log($level, $msg, @args);

これが一般的なインターフェースです。ログ出力のレベルはsyslogスタイルで、
'debug', 'info', 'notice', 'err' または 'crit' という言葉のうちの1つです。
infoとnoticeが必要になることはまずないでしょう。そしてcrit(critical)という
理由も思い当たりません。全体の95%の場合は、deugとerrで十分でしょう。

ログ出力する文字列$msgはprintfと同じフォーマット文字列です。


=head2 ユーティリティ・メソッド

    $self->Debug($msg, @args);
    $self->Error($msg, @args);
    $self->Fatal($msg, @args);

これらはdebugとerrのレベルを持ったログ出力の置換えです。後ろの2つの違いは
FatalはPerl例外を投げることも含んでいるといことです。


=head2 ログ出力先の選択

デフォルトではログ出力はsyslog (Unix) または EventLog (Windows)に行われます。
しかし以下のように設定するとstderrへのログ出力を選択することができます：

    $self->{'logfile'} = 1;

もしsyslogもEventLogも使えないときに必要です。代わりの選択としては以下の
ように設定することがあります

    $self->{'logfile'} = $handle;

$handleはIO::HandleのようにI<print>メソッドをサポートしている
オブジェクトです。通常、ログ出力の出力先は最初に$self->Log()を呼ぶと
すぐに選択されます。しかし最初にLogを呼び出す前に、

    $self->OpenLog();

とすることで出力先の選択を強制することができます。


=head1 マルチスレッド化

このクラスのマルチスレッドの能力は基にしているSys::Syslog、
Win32::EventLog またはIO::Handle に大きく依存しています。それらが
スレッド・セーフであれば、このパッケージも同じだと考えることができます。
（例外はスレッドが開始する前に$self->OpenLog()を呼んでおいた方が
よいということです）


=head1 作者と著作権(AUTHOR AND COPYRIGHT)

  Net::Daemon is Copyright (C) 1998, Jochen Wiedmann
                                     Am Eisteich 9
                                     72555 Metzingen
                                     Germany

                                     Phone: +49 7123 14887
                                     Email: joe@ispsoft.de

  All rights reserved.

  You may distribute this package under the terms of either the GNU
  General Public License or the Artistic License, as specified in the
  Perl README file.


=head1 参考資料

L<Net::Daemon(3)>, L<Sys::Syslog(3)>, L<Win32::EventLog(3)>,
L<IO::Handle(3)>