X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=ext%2FSys%2FSyslog%2FSyslog.pm;h=bb9b3edc3024c5382c1b45bb38dd9ecdeef9c871;hb=8168e71f67cd4bdb7731fc3633d09456af393dd3;hp=56cf18ad84330554377707a8b8bdb4e22e9a70bc;hpb=9903e4c84e85816608d5d27aaf47be642c39ddcd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/ext/Sys/Syslog/Syslog.pm b/ext/Sys/Syslog/Syslog.pm index 56cf18a..bb9b3ed 100644 --- a/ext/Sys/Syslog/Syslog.pm +++ b/ext/Sys/Syslog/Syslog.pm @@ -1,13 +1,13 @@ 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 @@ -28,12 +28,16 @@ use Sys::Hostname; =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 @@ -41,87 +45,102 @@ Sys::Syslog, openlog, closelog, setlogmask, syslog - Perl interface to the UNIX $oldmask = setlogmask $mask_priority; closelog; + =head1 DESCRIPTION -Sys::Syslog is an interface to the UNIX C program. +C is an interface to the UNIX C program. Call C with a string priority and a list of C args just like C. -Syslog provides the functions: + +=head1 EXPORTS + +By default, C exports the following symbols: + + openlog closelog setlogmask syslog + +as well as the symbols corresponding to most of your C macros. +The symbol C can be exported on demand. + + +=head1 FUNCTIONS =over 4 -=item openlog $ident, $logopt, $facility +=item B Opens the syslog. -I<$ident> is prepended to every message. I<$logopt> contains zero or -more of the words I, I, I. The cons option is +C<$ident> is prepended to every message. C<$logopt> contains zero or +more of the words C, C, C. The C 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 or C: see your C documentation for the facilities available in your system. This function will croak if it can't connect to the syslog daemon. +Note that C now takes three arguments, just like C. + B -=item syslog $priority, $message +=item B -=item syslog $priority, $format, @args +=item B -If I<$priority> permits, logs I<$message> or I -with the addition that I<%m> in $message or $format is replaced with +If C<$priority> permits, logs C<$message> or C +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 before using C, 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 version v0.07 and older passed the C<$message> +as the formatting string to C even when no formatting arguments +were provided. If the code calling C 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 instead of C. This protects against hostile formatting sequences that might show up if $message contains tainted data. -=item setlogmask $mask_priority +=item B + +Sets log mask C<$mask_priority> and returns the old mask. -Sets log mask I<$mask_priority> and returns the old mask. +=item B -=item setlogsock $sock_type [$stream_location] (added in 5.004_02) +=item B (added in 5.004_02) Sets the socket type to be used for the next call to -C or C and returns TRUE on success, -undef on failure. +C or C and returns true on success, +C 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 or F, 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 or C, +tried in that order) returned by C. 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. 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, C, C, C, C. -Giving an invalid value for sock_type will croak. +Giving an invalid value for C<$sock_type> will croak. -=item closelog +=item B Closes the log file. =back -Note that C now takes three arguments, just like C. =head1 EXAMPLES @@ -146,10 +165,173 @@ Note that C now takes three arguments, just like C. openlog($program, 'ndelay', 'user'); syslog('info', 'something happened over here'); + +=head1 CONSTANTS + +=head2 Facilities + +=over 4 + +=item * + +C - security/authorization messages + +=item * + +C - security/authorization messages (private) + +=item * + +C - clock daemon (B and B) + +=item * + +C - system daemons without separate facility value + +=item * + +C - ftp daemon + +=item * + +C - kernel messages + +=item * + +C through C - reserved for local use + +=item * + +C - line printer subsystem + +=item * + +C - mail subsystem + +=item * + +C - USENET news subsystem + +=item * + +C - messages generated internally by B + +=item * + +C (default) - generic user-level messages + +=item * + +C - UUCP subsystem + +=back + + +=head2 Levels + +=over 4 + +=item * + +C - system is unusable + +=item * + +C - action must be taken immediately + +=item * + +C - critical conditions + +=item * + +C<-LOG_ERR> - error conditions + +=item * + +C - warning conditions + +=item * + +C - normal, but significant, condition + +=item * + +C - informational message + +=item * + +C - debug-level message + +=back + + +=head1 DIAGNOSTICS + +=over 4 + +=item Invalid argument passed to setlogsock + +B<(F)> You gave C an invalid value for C<$sock_type>. + +=item no connection to syslog available + +B<(F)> C failed to connect to the specified socket. + +=item stream passed to setlogsock, but %s is not writable + +B<(F)> You asked C 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 to use a stream socket, but didn't +provide a path, and C was unable to find an appropriate one. + +=item tcp passed to setlogsock, but tcp service unavailable + +B<(F)> You asked C 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 the indicated argument. + +=item syslog: invalid level/facility: %s + +B<(F)> You specified an invalid level or facility, like C +(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 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 to use a UNIX socket, but C +was unable to find an appropriate an appropriate device. + +=back + + =head1 SEE ALSO L + =head1 AUTHOR Tom Christiansen EFE and Larry Wall @@ -157,16 +339,63 @@ EFE. UNIX domain sockets added by Sean Robinson EFE with support from Tim Bunce -EFE and the perl5-porters mailing list. +EFE and the C mailing list. Dependency on F replaced with XS code by Tom Hughes EFE. -Code for constant()s regenerated by Nicholas Clark EFE. +Code for Cs regenerated by Nicholas Clark EFE. Failover to different communication modes by Nick Williams EFE. +Extracted from core distribution for publishing on the CPAN by +SEbastien Aperghis-Tramoni Esebastien@aperghis.netE. + + +=head1 BUGS + +Please report any bugs or feature requests to +C, or through the web interface at +L. +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 + +=item * CPAN Ratings + +L + +=item * RT: CPAN's request tracker + +L + +=item * Search CPAN + +L + +=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 { @@ -232,11 +461,11 @@ sub setlogsock { 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' ); @@ -246,21 +475,21 @@ sub setlogsock { $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') { @@ -268,7 +497,7 @@ sub setlogsock { } 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; } @@ -328,7 +557,14 @@ sub syslog { $whoami .= "[$$]" if our $lo_pid; - $mask =~ s/(?