2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml">
5 <title>Sys::Syslog - Perl interface to the UNIX syslog calls
</title>
6 <meta http-equiv=
"content-type" content=
"text/html; charset=utf-8" />
7 <link rev=
"made" href=
"mailto:" />
10 <body style=
"background-color: white">
11 <table border=
"0" width=
"100%" cellspacing=
"0" cellpadding=
"3">
12 <tr><td class=
"block" style=
"background-color: #cccccc" valign=
"middle">
13 <big><strong><span class=
"block"> Sys::Syslog - Perl interface to the UNIX syslog calls
</span></strong></big>
17 <p><a name=
"__index__"></a></p>
22 <li><a href=
"#name">NAME
</a></li>
23 <li><a href=
"#version">VERSION
</a></li>
24 <li><a href=
"#synopsis">SYNOPSIS
</a></li>
25 <li><a href=
"#description">DESCRIPTION
</a></li>
26 <li><a href=
"#exports">EXPORTS
</a></li>
27 <li><a href=
"#functions">FUNCTIONS
</a></li>
28 <li><a href=
"#examples">EXAMPLES
</a></li>
29 <li><a href=
"#constants">CONSTANTS
</a></li>
32 <li><a href=
"#facilities">Facilities
</a></li>
33 <li><a href=
"#levels">Levels
</a></li>
36 <li><a href=
"#diagnostics">DIAGNOSTICS
</a></li>
37 <li><a href=
"#see_also">SEE ALSO
</a></li>
38 <li><a href=
"#author">AUTHOR
</a></li>
39 <li><a href=
"#bugs">BUGS
</a></li>
40 <li><a href=
"#support">SUPPORT
</a></li>
41 <li><a href=
"#license">LICENSE
</a></li>
48 <h1><a name=
"name">NAME
</a></h1>
49 <p>Sys::Syslog - Perl interface to the UNIX
<a href=
"#item_syslog"><code>syslog(
3)
</code></a> calls
</p>
53 <h1><a name=
"version">VERSION
</a></h1>
58 <h1><a name=
"synopsis">SYNOPSIS
</a></h1>
60 use Sys::Syslog; # all except setlogsock(), or:
61 use Sys::Syslog qw(:DEFAULT setlogsock); # default set, plus setlogsock()
62 use Sys::Syslog qw(:standard :macros); # standard functions, plus macros
</pre>
64 setlogsock $sock_type;
65 openlog $ident, $logopt, $facility; # don't forget this
66 syslog $priority, $format, @args;
67 $oldmask = setlogmask $mask_priority;
72 <h1><a name=
"description">DESCRIPTION
</a></h1>
73 <p><code>Sys::Syslog
</code> is an interface to the UNIX
<a href=
"#item_syslog"><code>syslog(
3)
</code></a> program.
74 Call
<a href=
"#item_syslog"><code>syslog()
</code></a> with a string priority and a list of
<a href=
"file://C|\msysgit\mingw\html/pod/perlfunc.html#item_printf"><code>printf()
</code></a> args
75 just like
<a href=
"#item_syslog"><code>syslog(
3)
</code></a>.
</p>
79 <h1><a name=
"exports">EXPORTS
</a></h1>
80 <p><code>Sys::Syslog
</code> exports the following
<code>Exporter
</code> tags:
</p>
83 <p><code>:standard
</code> exports the standard
<a href=
"#item_syslog"><code>syslog(
3)
</code></a> functions:
</p>
85 openlog closelog setlogmask syslog
</pre>
88 <p><code>:extended
</code> exports the Perl specific functions for
<a href=
"#item_syslog"><code>syslog(
3)
</code></a>:
</p>
93 <p><code>:macros
</code> exports the symbols corresponding to most of your
<a href=
"#item_syslog"><code>syslog(
3)
</code></a>
94 macros. See
<a href=
"#constants">CONSTANTS
</a> for the supported constants and their meaning.
</p>
97 <p>By default,
<code>Sys::Syslog
</code> exports the symbols from the
<code>:standard
</code> tag.
</p>
101 <h1><a name=
"functions">FUNCTIONS
</a></h1>
103 <dt><strong><a name=
"item_openlog"><strong>openlog($ident, $logopt, $facility)
</strong></a></strong>
107 <code>$ident
</code> is prepended to every message.
<code>$logopt
</code> contains zero or
108 more of the words
<code>pid
</code>,
<code>ndelay
</code>,
<code>nowait
</code>. The
<code>cons
</code> option is
109 ignored, since the failover mechanism will drop down to the console
110 automatically if all other media fail.
<code>$facility
</code> specifies the
111 part of the system to report about, for example
<code>LOG_USER
</code> or
<code>LOG_LOCAL0
</code>:
112 see your
<a href=
"#item_syslog"><code>syslog(
3)
</code></a> documentation for the facilities available in
113 your system. Facility can be given as a string or a numeric macro.
</p>
116 <p>This function will croak if it can't connect to the syslog daemon.
</p>
119 <p>Note that
<a href=
"#item_openlog"><code>openlog()
</code></a> now takes three arguments, just like
<a href=
"#item_openlog"><code>openlog(
3)
</code></a>.
</p>
122 <p><strong>You should use openlog() before calling syslog().
</strong></p>
125 <p><strong>Options
</strong></p>
129 <p><code>ndelay
</code> - Open the connection immediately (normally, the connection is
130 opened when the first message is logged).
</p>
133 <p><code>nowait
</code> - Don't wait for child processes that may have been created
134 while logging the message. (The GNU C library does not create a child
135 process, so this option has no effect on Linux.)
</p>
138 <p><code>pid
</code> - Include PID with each message.
</p>
141 <p><strong>Examples
</strong></p>
142 <p>Open the syslog with options
<code>ndelay
</code> and
<code>pid
</code>, and with facility
<code>LOCAL0
</code>:
</p>
144 openlog($name,
"ndelay,pid
",
"local0
");
</pre>
145 <p>Same thing, but this time using the macro corresponding to
<code>LOCAL0
</code>:
</p>
147 openlog($name,
"ndelay,pid
", LOG_LOCAL0);
</pre>
148 <dt><strong><a name=
"item_syslog"><strong>syslog($priority, $message)
</strong></a></strong>
150 <dt><strong><strong>syslog($priority, $format, @args)
</strong></strong>
153 <p>If
<code>$priority
</code> permits, logs
<code>$message
</code> or
<code>sprintf($format, @args)
</code>
154 with the addition that
<code>%m
</code> in $message or
<code>$format
</code> is replaced with
155 <code>"$!
"</code> (the latest error message).
</p>
158 <p><code>$priority
</code> can specify a level, or a level and a facility. Levels and
159 facilities can be given as strings or as macros.
</p>
162 <p>If you didn't use
<a href=
"#item_openlog"><code>openlog()
</code></a> before using
<a href=
"#item_syslog"><code>syslog()
</code></a>,
<a href=
"#item_syslog"><code>syslog()
</code></a> will
163 try to guess the
<code>$ident
</code> by extracting the shortest prefix of
164 <code>$format
</code> that ends in a
<code>":
"</code>.
</p>
167 <p><strong>Examples
</strong></p>
171 syslog(
"info
", $message); # informational level
172 syslog(LOG_INFO, $message); # informational level
</pre>
176 syslog(
"info|local0
", $message); # information level, Local0 facility
177 syslog(LOG_INFO|LOG_LOCAL0, $message); # information level, Local0 facility
</pre>
180 <dt><strong><a name=
"item_note"><strong>Note
</strong></a></strong>
183 <p><code>Sys::Syslog
</code> version v0.07 and older passed the
<code>$message
</code> as the
184 formatting string to
<code>sprintf()
</code> even when no formatting arguments
185 were provided. If the code calling
<a href=
"#item_syslog"><code>syslog()
</code></a> might execute with
186 older versions of this module, make sure to call the function as
187 <a href=
"#item_syslog"><code>syslog($priority,
"%s
", $message)
</code></a> instead of
<a href=
"#item_syslog"><code>syslog($priority,
188 $message)
</code></a>. This protects against hostile formatting sequences that
189 might show up if $message contains tainted data.
</p>
193 <dt><strong><a name=
"item_setlogmask"><strong>setlogmask($mask_priority)
</strong></a></strong>
196 <p>Sets the log mask for the current process to
<code>$mask_priority
</code> and
197 returns the old mask. If the mask argument is
0, the current log mask
198 is not modified. See
<a href=
"#levels">Levels
</a> for the list of available levels.
</p>
201 <p><strong>Examples
</strong></p>
204 <p>Only log errors:
</p>
208 setlogmask(LOG_ERR);
</pre>
211 <p>Log critical messages, errors and warnings:
</p>
215 setlogmask(LOG_CRIT|LOG_ERR|LOG_WARNING);
</pre>
218 <dt><strong><a name=
"item_setlogsock"><strong>setlogsock($sock_type)
</strong></a></strong>
220 <dt><strong><strong>setlogsock($sock_type, $stream_location)
</strong> (added in
5.004_02)
</strong>
223 <p>Sets the socket type to be used for the next call to
224 <a href=
"#item_openlog"><code>openlog()
</code></a> or
<a href=
"#item_syslog"><code>syslog()
</code></a> and returns true on success,
225 <a href=
"file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef
</code></a> on failure.
</p>
228 <p>A value of
<code>"unix
"</code> will connect to the UNIX domain socket (in some
229 systems a character special device) returned by the
<code>_PATH_LOG
</code> macro
230 (if your system defines it), or
<em>/dev/log
</em> or
<em>/dev/conslog
</em>,
231 whatever is writable. A value of 'stream' will connect to the stream
232 indicated by the pathname provided as the optional second parameter.
233 (For example Solaris and IRIX require
<code>"stream
"</code> instead of
<code>"unix
"</code>.)
234 A value of
<code>"inet
"</code> will connect to an INET socket (either
<code>tcp
</code> or
<code>udp
</code>,
235 tried in that order) returned by
<a href=
"file://C|\msysgit\mingw\html/pod/perlfunc.html#item_getservbyname"><code>getservbyname()
</code></a>.
<code>"tcp
"</code> and
<code>"udp
"</code> can
236 also be given as values. The value
<code>"console
"</code> will send messages
237 directly to the console, as for the
<code>"cons
"</code> option in the logopts in
238 <a href=
"#item_openlog"><code>openlog()
</code></a>.
</p>
241 <p>A reference to an array can also be passed as the first parameter.
242 When this calling method is used, the array should contain a list of
243 sock_types which are attempted in order.
</p>
246 <p>The default is to try
<code>tcp
</code>,
<code>udp
</code>,
<code>unix
</code>,
<code>stream
</code>,
<code>console
</code>.
</p>
249 <p>Giving an invalid value for
<code>$sock_type
</code> will croak.
</p>
252 <dt><strong><a name=
"item_closelog"><strong>closelog()
</strong></a></strong>
255 <p>Closes the log file and return true on success.
</p>
262 <h1><a name=
"examples">EXAMPLES
</a></h1>
264 openlog($program, 'cons,pid', 'user');
265 syslog('info', '%s', 'this is another test');
266 syslog('mail|warning', 'this is a better test: %d', time);
269 syslog('debug', 'this is the last test');
</pre>
272 openlog(
"$program $$
", 'ndelay', 'user');
273 syslog('notice', 'fooprogram: this is really done');
</pre>
277 syslog('info', 'problem was %m'); # %m == $! in syslog(
3)
</pre>
279 # Log to UDP port on $remotehost instead of logging locally
281 $Sys::Syslog::host = $remotehost;
282 openlog($program, 'ndelay', 'user');
283 syslog('info', 'something happened over here');
</pre>
287 <h1><a name=
"constants">CONSTANTS
</a></h1>
290 <h2><a name=
"facilities">Facilities
</a></h2>
293 <p><code>LOG_AUTH
</code> - security/authorization messages
</p>
296 <p><code>LOG_AUTHPRIV
</code> - security/authorization messages (private)
</p>
299 <p><code>LOG_CRON
</code> - clock daemon (
<strong>cron
</strong> and
<strong>at
</strong>)
</p>
302 <p><code>LOG_DAEMON
</code> - system daemons without separate facility value
</p>
305 <p><code>LOG_FTP
</code> - ftp daemon
</p>
308 <p><code>LOG_KERN
</code> - kernel messages
</p>
311 <p><code>LOG_LOCAL0
</code> through
<code>LOG_LOCAL7
</code> - reserved for local use
</p>
314 <p><code>LOG_LPR
</code> - line printer subsystem
</p>
317 <p><code>LOG_MAIL
</code> - mail subsystem
</p>
320 <p><code>LOG_NEWS
</code> - USENET news subsystem
</p>
323 <p><code>LOG_SYSLOG
</code> - messages generated internally by
<strong>syslogd
</strong></p>
326 <p><code>LOG_USER
</code> (default) - generic user-level messages
</p>
329 <p><code>LOG_UUCP
</code> - UUCP subsystem
</p>
334 <h2><a name=
"levels">Levels
</a></h2>
337 <p><code>LOG_EMERG
</code> - system is unusable
</p>
340 <p><code>LOG_ALERT
</code> - action must be taken immediately
</p>
343 <p><code>LOG_CRIT
</code> - critical conditions
</p>
346 <p><code>LOG_ERR
</code> - error conditions
</p>
349 <p><code>LOG_WARNING
</code> - warning conditions
</p>
352 <p><code>LOG_NOTICE
</code> - normal, but significant, condition
</p>
355 <p><code>LOG_INFO
</code> - informational message
</p>
358 <p><code>LOG_DEBUG
</code> - debug-level message
</p>
364 <h1><a name=
"diagnostics">DIAGNOSTICS
</a></h1>
366 <dt><strong><a name=
"item_invalid_argument_passed_to_setlogsock">Invalid argument passed to setlogsock
</a></strong>
369 <p><strong>(F)
</strong> You gave
<a href=
"#item_setlogsock"><code>setlogsock()
</code></a> an invalid value for
<code>$sock_type
</code>.
</p>
372 <dt><strong><a name=
"item_no_connection_to_syslog_available">no connection to syslog available
</a></strong>
375 <p><strong>(F)
</strong> <a href=
"#item_syslog"><code>syslog()
</code></a> failed to connect to the specified socket.
</p>
378 <dt><strong><a name=
"item_stream_passed_to_setlogsock_2c_but__25s_is_not_wri">stream passed to setlogsock, but %s is not writable
</a></strong>
381 <p><strong>(W)
</strong> You asked
<a href=
"#item_setlogsock"><code>setlogsock()
</code></a> to use a stream socket, but the given
382 path is not writable.
</p>
385 <dt><strong><a name=
"item_stream_passed_to_setlogsock_2c_but_could_not_find_">stream passed to setlogsock, but could not find any device
</a></strong>
388 <p><strong>(W)
</strong> You asked
<a href=
"#item_setlogsock"><code>setlogsock()
</code></a> to use a stream socket, but didn't
389 provide a path, and
<code>Sys::Syslog
</code> was unable to find an appropriate one.
</p>
392 <dt><strong><a name=
"item_tcp_passed_to_setlogsock_2c_but_tcp_service_unavai">tcp passed to setlogsock, but tcp service unavailable
</a></strong>
395 <p><strong>(W)
</strong> You asked
<a href=
"#item_setlogsock"><code>setlogsock()
</code></a> to use a TCP socket, but the service
396 is not available on the system.
</p>
399 <dt><strong><a name=
"item_syslog_3a_expecting_argument__25s">syslog: expecting argument %s
</a></strong>
402 <p><strong>(F)
</strong> You forgot to give
<a href=
"#item_syslog"><code>syslog()
</code></a> the indicated argument.
</p>
405 <dt><strong><a name=
"item_syslog_3a_invalid_level_2ffacility_3a__25s">syslog: invalid level/facility: %s
</a></strong>
408 <p><strong>(F)
</strong> You specified an invalid level or facility, like
<code>LOG_KERN
</code>
409 (which is reserved to the kernel).
</p>
412 <dt><strong><a name=
"item_syslog_3a_too_many_levels_given_3a__25s">syslog: too many levels given: %s
</a></strong>
415 <p><strong>(F)
</strong> You specified too many levels.
</p>
418 <dt><strong><a name=
"item_syslog_3a_too_many_facilities_given_3a__25s">syslog: too many facilities given: %s
</a></strong>
421 <p><strong>(F)
</strong> You specified too many facilities.
</p>
424 <dt><strong><a name=
"item_syslog_3a_level_must_be_given">syslog: level must be given
</a></strong>
427 <p><strong>(F)
</strong> You forgot to specify a level.
</p>
430 <dt><strong><a name=
"item_udp_passed_to_setlogsock_2c_but_udp_service_unavai">udp passed to setlogsock, but udp service unavailable
</a></strong>
433 <p><strong>(W)
</strong> You asked
<a href=
"#item_setlogsock"><code>setlogsock()
</code></a> to use a UDP socket, but the service
434 is not available on the system.
</p>
437 <dt><strong><a name=
"item_unix_passed_to_setlogsock_2c_but_path_not_availabl">unix passed to setlogsock, but path not available
</a></strong>
440 <p><strong>(W)
</strong> You asked
<a href=
"#item_setlogsock"><code>setlogsock()
</code></a> to use a UNIX socket, but
<code>Sys::Syslog
</code>
441 was unable to find an appropriate an appropriate device.
</p>
448 <h1><a name=
"see_also">SEE ALSO
</a></h1>
449 <p><a href=
"#item_syslog">syslog(
3)
</a></p>
450 <p><em>Syslogging with Perl
</em>,
<a href=
"http://lexington.pm.org/meetings/022001.html">http://lexington.pm.org/meetings/
022001.html
</a></p>
454 <h1><a name=
"author">AUTHOR
</a></h1>
455 <p>Tom Christiansen
<<em><a href=
"mailto:tchrist@perl.com">tchrist@perl.com
</a></em>> and Larry Wall
456 <<em><a href=
"mailto:larry@wall.org">larry@wall.org
</a></em>>.
</p>
457 <p>UNIX domain sockets added by Sean Robinson
458 <<em><a href=
"mailto:robinson_s@sc.maricopa.edu">robinson_s@sc.maricopa.edu
</a></em>> with support from Tim Bunce
459 <<em><a href=
"mailto:Tim.Bunce@ig.co.uk">Tim.Bunce@ig.co.uk
</a></em>> and the
<code>perl5-porters
</code> mailing list.
</p>
460 <p>Dependency on
<em>syslog.ph
</em> replaced with XS code by Tom Hughes
461 <<em><a href=
"mailto:tom@compton.nu">tom@compton.nu
</a></em>>.
</p>
462 <p>Code for
<code>constant()
</code>s regenerated by Nicholas Clark
<<em><a href=
"mailto:nick@ccl4.org">nick@ccl4.org
</a></em>>.
</p>
463 <p>Failover to different communication modes by Nick Williams
464 <<em><a href=
"mailto:Nick.Williams@morganstanley.com">Nick.Williams@morganstanley.com
</a></em>>.
</p>
465 <p>Extracted from core distribution for publishing on the CPAN by
466 S
ébastien Aperghis-Tramoni
<<a href=
"mailto:sebastien@aperghis.net">sebastien@aperghis.net
</a>>.
</p>
470 <h1><a name=
"bugs">BUGS
</a></h1>
471 <p>Please report any bugs or feature requests to
472 <code>bug-sys-syslog at rt.cpan.org
</code>, or through the web interface at
473 <a href=
"http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sys-Syslog">http://rt.cpan.org/NoAuth/ReportBug.html
</a>.
474 I will be notified, and then you'll automatically be notified of progress on
475 your bug as I make changes.
</p>
479 <h1><a name=
"support">SUPPORT
</a></h1>
480 <p>You can find documentation for this module with the perldoc command.
</p>
482 <a href=
"//C|\msysgit\mingw\html/pod/perldoc.html">perldoc
</a> Sys::Syslog
</pre>
483 <p>You can also look for information at:
</p>
485 <li><strong><a name=
"item_annocpan_3a_annotated_cpan_documentation">AnnoCPAN: Annotated CPAN documentation
</a></strong>
487 <p><a href=
"http://annocpan.org/dist/Sys-Syslog">http://annocpan.org/dist/Sys-Syslog
</a></p>
489 <li><strong><a name=
"item_cpan_ratings">CPAN Ratings
</a></strong>
491 <p><a href=
"http://cpanratings.perl.org/d/Sys-Syslog">http://cpanratings.perl.org/d/Sys-Syslog
</a></p>
493 <li><strong><a name=
"item_rt_3a_cpan_27s_request_tracker">RT: CPAN's request tracker
</a></strong>
495 <p><a href=
"http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Syslog">http://rt.cpan.org/NoAuth/Bugs.html
</a></p>
497 <li><strong><a name=
"item_search_cpan">Search CPAN
</a></strong>
499 <p><a href=
"http://search.cpan.org/dist/Sys-Syslog">http://search.cpan.org/dist/Sys-Syslog
</a></p>
505 <h1><a name=
"license">LICENSE
</a></h1>
506 <p>This program is free software; you can redistribute it and/or modify it
507 under the same terms as Perl itself.
</p>
508 <table border=
"0" width=
"100%" cellspacing=
"0" cellpadding=
"3">
509 <tr><td class=
"block" style=
"background-color: #cccccc" valign=
"middle">
510 <big><strong><span class=
"block"> Sys::Syslog - Perl interface to the UNIX syslog calls
</span></strong></big>