package Sys::Syslog;
+use strict;
+use Carp;
require 5.006;
require Exporter;
-use Carp;
-use strict;
our @ISA = qw(Exporter);
our @EXPORT = qw(openlog closelog setlogmask syslog);
our @EXPORT_OK = qw(setlogsock);
-our $VERSION = '0.08';
+our $VERSION = '0.10';
# it would be nice to try stream/unix first, since that will be
# most efficient. However streams are dodgy - see _syslog_send_stream
=head1 NAME
-Sys::Syslog, openlog, closelog, setlogmask, syslog - Perl interface to the UNIX syslog(3) calls
+Sys::Syslog - Perl interface to the UNIX syslog(3) calls
+
+=head1 VERSION
+
+Version 0.10
=head1 SYNOPSIS
- use Sys::Syslog; # all except setlogsock, or:
- use Sys::Syslog qw(:DEFAULT setlogsock); # default set, plus setlogsock
+ use Sys::Syslog; # all except setlogsock(), or:
+ use Sys::Syslog qw(:DEFAULT setlogsock); # default set, plus setlogsock()
setlogsock $sock_type;
openlog $ident, $logopt, $facility; # don't forget this
$oldmask = setlogmask $mask_priority;
closelog;
+
=head1 DESCRIPTION
-Sys::Syslog is an interface to the UNIX C<syslog(3)> program.
+C<Sys::Syslog> is an interface to the UNIX C<syslog(3)> program.
Call C<syslog()> with a string priority and a list of C<printf()> args
just like C<syslog(3)>.
-Syslog provides the functions:
+
+=head1 EXPORTS
+
+By default, C<Sys::Syslog> exports the following symbols:
+
+ openlog closelog setlogmask syslog
+
+as well as the symbols corresponding to most of your C<syslog(3)> macros.
+The symbol C<setlogsock> can be exported on demand.
+
+
+=head1 FUNCTIONS
=over 4
-=item openlog $ident, $logopt, $facility
+=item B<openlog($ident, $logopt, $facility)>
Opens the syslog.
-I<$ident> is prepended to every message. I<$logopt> contains zero or
-more of the words I<pid>, I<ndelay>, I<nowait>. The cons option is
+C<$ident> is prepended to every message. C<$logopt> contains zero or
+more of the words C<pid>, C<ndelay>, C<nowait>. The C<cons> option is
ignored, since the failover mechanism will drop down to the console
-automatically if all other media fail. I<$facility> specifies the
-part of the system to report about, for example LOG_USER or LOG_LOCAL0:
+automatically if all other media fail. C<$facility> specifies the
+part of the system to report about, for example C<LOG_USER> or C<LOG_LOCAL0>:
see your C<syslog(3)> documentation for the facilities available in
your system. This function will croak if it can't connect to the syslog
daemon.
+Note that C<openlog()> now takes three arguments, just like C<openlog(3)>.
+
B<You should use openlog() before calling syslog().>
-=item syslog $priority, $message
+=item B<syslog($priority, $message)>
-=item syslog $priority, $format, @args
+=item B<syslog($priority, $format, @args)>
-If I<$priority> permits, logs I<$message> or I<sprintf($format, @args)>
-with the addition that I<%m> in $message or $format is replaced with
+If C<$priority> permits, logs C<$message> or C<sprintf($format, @args)>
+with the addition that C<%m> in $message or $format is replaced with
C<"$!"> (the latest error message).
-If you didn't use openlog() before using syslog(), syslog will try to
-guess the I<$ident> by extracting the shortest prefix of I<$format>
-that ends in a ":".
+If you didn't use C<openlog()> before using C<syslog()>, syslog will
+try to guess the C<$ident> by extracting the shortest prefix of
+C<$format> that ends in a C<":">.
-Note that Sys::Syslog version v0.07 and older passed the $message as
-the formatting string to sprintf() even when no formatting arguments
-where provided. If the code calling syslog() might execute with older
+Note that C<Sys::Syslog> version v0.07 and older passed the C<$message>
+as the formatting string to C<sprintf()> even when no formatting arguments
+were provided. If the code calling C<syslog()> might execute with older
versions of this module, make sure to call the function as
-syslog($priority, "%s", $message) instead of syslog($priority,
-$message). This protects against hostile formatting sequences that
+C<syslog($priority, "%s", $message)> instead of C<syslog($priority,
+$message)>. This protects against hostile formatting sequences that
might show up if $message contains tainted data.
-=item setlogmask $mask_priority
+=item B<setlogmask($mask_priority)>
-Sets log mask I<$mask_priority> and returns the old mask.
+Sets log mask C<$mask_priority> and returns the old mask.
-=item setlogsock $sock_type [$stream_location] (added in 5.004_02)
+=item B<setlogsock($sock_type)>
+
+=item B<setlogsock($sock_type, $stream_location)> (added in 5.004_02)
Sets the socket type to be used for the next call to
-C<openlog()> or C<syslog()> and returns TRUE on success,
-undef on failure.
+C<openlog()> or C<syslog()> and returns true on success,
+C<undef> on failure.
-A value of 'unix' will connect to the UNIX domain socket (in some
+A value of C<"unix"> will connect to the UNIX domain socket (in some
systems a character special device) returned by the C<_PATH_LOG> macro
(if your system defines it), or F</dev/log> or F</dev/conslog>,
whatever is writable. A value of 'stream' will connect to the stream
indicated by the pathname provided as the optional second parameter.
-(For example Solaris and IRIX require 'stream' instead of 'unix'.)
-A value of 'inet' will connect to an INET socket (either tcp or udp,
-tried in that order) returned by getservbyname(). 'tcp' and 'udp' can
-also be given as values. The value 'console' will send messages
-directly to the console, as for the 'cons' option in the logopts in
-openlog().
+(For example Solaris and IRIX require C<"stream"> instead of C<"unix">.)
+A value of C<"inet"> will connect to an INET socket (either C<tcp> or C<udp>,
+tried in that order) returned by C<getservbyname()>. C<"tcp"> and C<"udp"> can
+also be given as values. The value C<"console"> will send messages
+directly to the console, as for the C<"cons"> option in the logopts in
+C<openlog()>.
A reference to an array can also be passed as the first parameter.
When this calling method is used, the array should contain a list of
sock_types which are attempted in order.
-The default is to try tcp, udp, unix, stream, console.
+The default is to try C<tcp>, C<udp>, C<unix>, C<stream>, C<console>.
-Giving an invalid value for sock_type will croak.
+Giving an invalid value for C<$sock_type> will croak.
-=item closelog
+=item B<closelog()>
Closes the log file.
=back
-Note that C<openlog> now takes three arguments, just like C<openlog(3)>.
=head1 EXAMPLES
openlog($program, 'ndelay', 'user');
syslog('info', 'something happened over here');
+
+=head1 CONSTANTS
+
+=head2 Facilities
+
+=over 4
+
+=item *
+
+C<LOG_AUTH> - security/authorization messages
+
+=item *
+
+C<LOG_AUTHPRIV> - security/authorization messages (private)
+
+=item *
+
+C<LOG_CRON> - clock daemon (B<cron> and B<at>)
+
+=item *
+
+C<LOG_DAEMON> - system daemons without separate facility value
+
+=item *
+
+C<LOG_FTP> - ftp daemon
+
+=item *
+
+C<LOG_KERN> - kernel messages
+
+=item *
+
+C<LOG_LOCAL0> through C<LOG_LOCAL7> - reserved for local use
+
+=item *
+
+C<LOG_LPR> - line printer subsystem
+
+=item *
+
+C<LOG_MAIL> - mail subsystem
+
+=item *
+
+C<LOG_NEWS> - USENET news subsystem
+
+=item *
+
+C<LOG_SYSLOG> - messages generated internally by B<syslogd>
+
+=item *
+
+C<LOG_USER> (default) - generic user-level messages
+
+=item *
+
+C<LOG_UUCP> - UUCP subsystem
+
+=back
+
+
+=head2 Levels
+
+=over 4
+
+=item *
+
+C<LOG_EMERG> - system is unusable
+
+=item *
+
+C<LOG_ALERT> - action must be taken immediately
+
+=item *
+
+C<LOG_CRIT> - critical conditions
+
+=item *
+
+C<-LOG_ERR> - error conditions
+
+=item *
+
+C<LOG_WARNING> - warning conditions
+
+=item *
+
+C<LOG_NOTICE> - normal, but significant, condition
+
+=item *
+
+C<LOG_INFO> - informational message
+
+=item *
+
+C<LOG_DEBUG> - debug-level message
+
+=back
+
+
+=head1 DIAGNOSTICS
+
+=over 4
+
+=item Invalid argument passed to setlogsock
+
+B<(F)> You gave C<setlogsock()> an invalid value for C<$sock_type>.
+
+=item no connection to syslog available
+
+B<(F)> C<syslog()> failed to connect to the specified socket.
+
+=item stream passed to setlogsock, but %s is not writable
+
+B<(F)> You asked C<setlogsock()> to use a stream socket, but the given
+path is not writable.
+
+=item stream passed to setlogsock, but could not find any device
+
+B<(F)> You asked C<setlogsock()> to use a stream socket, but didn't
+provide a path, and C<Sys::Syslog> was unable to find an appropriate one.
+
+=item tcp passed to setlogsock, but tcp service unavailable
+
+B<(F)> You asked C<setlogsock()> to use a TCP socket, but the service
+is not available on the system.
+
+=item syslog: expecting argument %s
+
+B<(F)> You forgot to give C<syslog()> the indicated argument.
+
+=item syslog: invalid level/facility: %s
+
+B<(F)> You specified an invalid level or facility, like C<LOG_KERN>
+(which is reserved to the kernel).
+
+=item syslog: too many levels given: %s
+
+B<(F)> You specified too many levels.
+
+=item syslog: too many facilities given: %s
+
+B<(F)> You specified too many facilities.
+
+=item syslog: level must be given
+
+B<(F)> You forgot to specify a level.
+
+=item udp passed to setlogsock, but udp service unavailable
+
+B<(F)> You asked C<setlogsock()> to use a UDP socket, but the service
+is not available on the system.
+
+=item unix passed to setlogsock, but path not available
+
+B<(F)> You asked C<setlogsock()> to use a UNIX socket, but C<Sys::Syslog>
+was unable to find an appropriate an appropriate device.
+
+=back
+
+
=head1 SEE ALSO
L<syslog(3)>
+
=head1 AUTHOR
Tom Christiansen E<lt>F<tchrist@perl.com>E<gt> and Larry Wall
UNIX domain sockets added by Sean Robinson
E<lt>F<robinson_s@sc.maricopa.edu>E<gt> with support from Tim Bunce
-E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and the perl5-porters mailing list.
+E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and the C<perl5-porters> mailing list.
Dependency on F<syslog.ph> replaced with XS code by Tom Hughes
E<lt>F<tom@compton.nu>E<gt>.
-Code for constant()s regenerated by Nicholas Clark E<lt>F<nick@ccl4.org>E<gt>.
+Code for C<constant()>s regenerated by Nicholas Clark E<lt>F<nick@ccl4.org>E<gt>.
Failover to different communication modes by Nick Williams
E<lt>F<Nick.Williams@morganstanley.com>E<gt>.
+Extracted from core distribution for publishing on the CPAN by
+SE<eacute>bastien Aperghis-Tramoni E<lt>sebastien@aperghis.netE<gt>.
+
+
+=head1 BUGS
+
+Please report any bugs or feature requests to
+C<bug-sys-syslog at rt.cpan.org>, or through the web interface at
+L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sys-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 Sys::Syslog
+
+You can also look for information at:
+
+=over 4
+
+=item * AnnoCPAN: Annotated CPAN documentation
+
+L<http://annocpan.org/dist/Sys-Syslog>
+
+=item * CPAN Ratings
+
+L<http://cpanratings.perl.org/d/Sys-Syslog>
+
+=item * RT: CPAN's request tracker
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Syslog>
+
+=item * Search CPAN
+
+L<http://search.cpan.org/dist/Sys-Syslog>
+
+=back
+
+
+=head1 LICENSE
+
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
=cut
sub AUTOLOAD {
last;
}
}
- carp "stream passed to setlogsock, but could not find any device"
+ croak "stream passed to setlogsock, but could not find any device"
unless defined $syslog_path;
}
unless (-w $syslog_path) {
- carp "stream passed to setlogsock, but $syslog_path is not writable";
+ croak "stream passed to setlogsock, but $syslog_path is not writable";
return undef;
} else {
@connectMethods = ( 'stream' );
$syslog_path = _PATH_LOG();
@connectMethods = ( 'unix' );
} else {
- carp 'unix passed to setlogsock, but path not available';
+ croak 'unix passed to setlogsock, but path not available';
return undef;
}
} elsif (lc($setsock) eq 'tcp') {
if (getservbyname('syslog', 'tcp') || getservbyname('syslogng', 'tcp')) {
@connectMethods = ( 'tcp' );
} else {
- carp "tcp passed to setlogsock, but tcp service unavailable";
+ croak "tcp passed to setlogsock, but tcp service unavailable";
return undef;
}
} elsif (lc($setsock) eq 'udp') {
if (getservbyname('syslog', 'udp')) {
@connectMethods = ( 'udp' );
} else {
- carp "udp passed to setlogsock, but udp service unavailable";
+ croak "udp passed to setlogsock, but udp service unavailable";
return undef;
}
} elsif (lc($setsock) eq 'inet') {
} elsif (lc($setsock) eq 'console') {
@connectMethods = ( 'console' );
} else {
- carp "Invalid argument passed to setlogsock; must be 'stream', 'unix', 'tcp', 'udp' or 'inet'";
+ croak "Invalid argument passed to setlogsock; must be 'stream', 'unix', 'tcp', 'udp' or 'inet'";
}
return 1;
}
# To be correct, it should use a STREAMS API, but perl doesn't have one.
return syswrite(SYSLOG, $buf, length($buf));
}
+
sub _syslog_send_socket {
my ($buf) = @_;
return syswrite(SYSLOG, $buf, length($buf));
projects / p5sagit/p5-mst-13.2.git / blobdiff