# vim: se tw=80 ts=4 et:

=head1 NAME

Tie::Syslog - Tie a filehandle to Syslog.


=head1 VERSION

2.04.03

v2.00 is a complete rewrite of Tie::Syslog. If you used v1.x and something
broke after upgrade, please report the problem back and I'll try to fix it 
asap. Thanks.


=head1 SYNOPSIS

    use Tie::Syslog;

    $Tie::Syslog::ident  = "my logging tag";
    $Tie::Syslog::logopt = "pid,ndelay";

    # Tie STDOUT to Syslog, so that every print()ed message will be logged
    tie *STDOUT, 'Tie::Syslog', {
        facility => 'LOG_LOCAL0',
        priority => 'LOG_INFO',
    };

    # Now tie STDERR also, getting parameters from the tied STDOUT
    tie *STDERR, { tied *STDOUT };

    # ...or...

    # tie STDERR with defaults from tied STDOUT, but override priority:
    tie *STDERR, { tied *STDOUT }, {
        priority => 'LOG_ERR',
    };

    ###### 
    # Compatibility with old configuration style:

    tie *STDOUT, 'Tie::Syslog', 
        'local0.error',         # facility.loglevel
        'myname',               # identity 
        'pid,ndelay',           # Other Sys::Syslog options, comma-separated
        'unix';                 # setlogsock socket type: unix or inet

    tie *STDERR, 'Tie::Syslog', 
        'local0.warning',       # facility.loglevel
        'myname',               # USE THE SAME AS ABOVE!
        'pid,ndelay',           # USE THE SAME AS ABOVE!
        'unix';                 # USE THE SAME AS ABOVE!

    # Tying by copying from another tied handle is not supported in 
    # old-compatibility-mode

    # old-compatibility-mode defaults to 'local0.error'

    # socket type is IGNORED

=head1 DESCRIPTION

This module lets you tie a filehandle to Sys::Syslog, providing an easy way to
redirect messages to system logs. 


    $Tie::Syslog::ident  = 'DEBUG :: myprocess';
    $Tie::Syslog::logopt = 'pid,ndelay';

    tie *DEBUG, 'Tie::Syslog', {
        facility => 'LOG_LOCAL0',
        priority => 'LOG_DEBUG',
    };

    print DEBUG "This is a debug message - won't probably get to system logs.";

By tying STDOUT and/or STDERR you can easily redirect all messages to system
logs, including those of warn() and die(). 

Tipically, you'll want to tie STDOUT with a lower priority than STDERR. 


=head1 OPTIONS

=head2 $Tie::Syslog::ident

Identity set for logging. B<< This is a global option >>, and will be valid
from the moment you set it onward. The default value is the last field of $0
split on '/'. 

=head2 $Tie::Syslog::logopt

Logging options. These are standard L<< Sys::Syslog >> logopts. See  L<<
Sys::Syslog >> man page for details. B<< This is a global option >>, default
is 'pid,ndelay'.

=head2 facility

One of the default Sys::Syslog facilities available on your system. See L<<
Sys::Syslog >> man page for details. You can have different facilities for
different filehandles, but this is not recommended, and will prevent 
Tie::Syslog from calling closelog() (see L<< /CAVEATS >> for details).

You can redefine a the facility for a given filehandle on the fly: 

    my $fho = tied *MYFH;
    $fho->facility('LOG_MAIL');

    # better: 

    (tied *MYFH)->facility('LOG_MAIL');

    # better yet: don't do it

but please note that this is B<< against Sys::Syslog rule: >>

=over 4

=item * "I<< The Fourth Rule of Sys::Syslog is: >> One facility, one priority." (from L<< Sys::Syslog >> man page).

=back


=head2 priority

One of the default Sys::Syslog priorities available on your system. See L<<
Sys::Syslog >> man page for details. You can have different priorities for
different filehandles. 

You can redefine the priority for a given filehandle on the fly: 

    my $fho = tied *MYFH;
    $fho->priority('LOG_CRIT');

    # better: 

    (tied *MYFH)->priority('LOG_CRIT');


=head1 CAVEATS

=over 4

=item * We set the most permissive mask for log levels, so that nothing should
be filtered by Sys::Syslog itself, but some messages may still be filtered,
according to your syslog daemon configuration. Consult your local syslog daemon
documentation.

=item * B<< We do not call closelog() >> in case multiple facilities are in use

In general, openlog() is called automatically whenever syslog() is called on a
new facility (although we call it explicitly on tie()). Since closelog() would 
work just once and on the last opened connetion to syslog, it could close a 
connection completely unrelated to the filehandle currently being 
closed/untied/destroyed. B<< In case you tied multiple filehandles >> over
multiple faiclities (you shouldn't, see L<< Sys::Syslog >> for details),
closelog() won't be called at all. 

=item * C<< ident >> and/or C<< logopt >> should be set once, before tying
handles.

If change these variables after tying handles, the behavior is undetermined. At
best, nothing should change; or settings could change if another openlog()
is called afterwards, but don't rely on this. Also, if settings change, they
will affect all tied filehandles. For these reasons, either: 

=over 4 

=item * Set them once at the beginning, or

=item * if you're tying two or more handles B<< using old-style syntax >>, use
the same values for all of them.

=back 

=item * Old method C<< ExtendedSTDERR() >> is no-op by default. 

It is still supported for backward compatibility, but warn() and die() print by
default to STDERR so there should be no need to change them directly. 

=item * We do not call setlogsock() 

=back 


=head1 SEE ALSO

Log priorities, facilities and valid values for C<< logopt >> are listed in 
L<< Sys::Syslog >> man page. 

Read syslog(3) for details on syslog. 


=head1 AUTHOR

Broc Seib, C<< bseib at purdue.edu >> - up to 1.07

Giacomo Montagner, C<< <kromg at entirelyunlike.net> >> - from 2.00 onward.


=head1 BUGS

Please report any bugs or feature requests to C<bug-tie-syslog at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tie-Syslog>.  
I'will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.




=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Tie::Syslog


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tie-Syslog>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Tie-Syslog>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Tie-Syslog>

=item * Search CPAN

L<http://search.cpan.org/dist/Tie-Syslog/>

=back


=head1 ACKNOWLEDGEMENTS

Many thanks to Broc Seib, who wrote this module back in 1999. 



=head1 LICENSE AND COPYRIGHT

Copyright (C) 1999-2001 Broc Seib

Copyright (C) 2012 Giacomo Montagner.

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

See http://dev.perl.org/licenses/ for more information.


=cut


