Install Perl 5.8.8
[msysgit.git] / mingw / html / ext / Sys / Syslog / Syslog.html
blob129c1b023dbc4813106081851e67981385bfa0fb
1 <?xml version="1.0" ?>
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">
4 <head>
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:" />
8 </head>
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">&nbsp;Sys::Syslog - Perl interface to the UNIX syslog calls</span></strong></big>
14 </td></tr>
15 </table>
17 <p><a name="__index__"></a></p>
18 <!-- INDEX BEGIN -->
20 <ul>
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>
30 <ul>
32 <li><a href="#facilities">Facilities</a></li>
33 <li><a href="#levels">Levels</a></li>
34 </ul>
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>
42 </ul>
43 <!-- INDEX END -->
45 <hr />
46 <p>
47 </p>
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>
50 <p>
51 </p>
52 <hr />
53 <h1><a name="version">VERSION</a></h1>
54 <p>Version 0.13</p>
55 <p>
56 </p>
57 <hr />
58 <h1><a name="synopsis">SYNOPSIS</a></h1>
59 <pre>
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>
63 <pre>
64 setlogsock $sock_type;
65 openlog $ident, $logopt, $facility; # don't forget this
66 syslog $priority, $format, @args;
67 $oldmask = setlogmask $mask_priority;
68 closelog;</pre>
69 <p>
70 </p>
71 <hr />
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>
76 <p>
77 </p>
78 <hr />
79 <h1><a name="exports">EXPORTS</a></h1>
80 <p><code>Sys::Syslog</code> exports the following <code>Exporter</code> tags:</p>
81 <ul>
82 <li>
83 <p><code>:standard</code> exports the standard <a href="#item_syslog"><code>syslog(3)</code></a> functions:</p>
84 <pre>
85 openlog closelog setlogmask syslog</pre>
86 </li>
87 <li>
88 <p><code>:extended</code> exports the Perl specific functions for <a href="#item_syslog"><code>syslog(3)</code></a>:</p>
89 <pre>
90 setlogsock</pre>
91 </li>
92 <li>
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>
95 </li>
96 </ul>
97 <p>By default, <code>Sys::Syslog</code> exports the symbols from the <code>:standard</code> tag.</p>
98 <p>
99 </p>
100 <hr />
101 <h1><a name="functions">FUNCTIONS</a></h1>
102 <dl>
103 <dt><strong><a name="item_openlog"><strong>openlog($ident, $logopt, $facility)</strong></a></strong>
105 <dd>
106 <p>Opens the syslog.
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>
114 </dd>
115 <dd>
116 <p>This function will croak if it can't connect to the syslog daemon.</p>
117 </dd>
118 <dd>
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>
120 </dd>
121 <dd>
122 <p><strong>You should use openlog() before calling syslog().</strong></p>
123 </dd>
124 <dd>
125 <p><strong>Options</strong></p>
126 </dd>
127 <ul>
128 <li>
129 <p><code>ndelay</code> - Open the connection immediately (normally, the connection is
130 opened when the first message is logged).</p>
131 </li>
132 <li>
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>
136 </li>
137 <li>
138 <p><code>pid</code> - Include PID with each message.</p>
139 </li>
140 </ul>
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>
143 <pre>
144 openlog($name, &quot;ndelay,pid&quot;, &quot;local0&quot;);</pre>
145 <p>Same thing, but this time using the macro corresponding to <code>LOCAL0</code>:</p>
146 <pre>
147 openlog($name, &quot;ndelay,pid&quot;, 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>
152 <dd>
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>&quot;$!&quot;</code> (the latest error message).</p>
156 </dd>
157 <dd>
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>
160 </dd>
161 <dd>
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>&quot;:&quot;</code>.</p>
165 </dd>
166 <dd>
167 <p><strong>Examples</strong></p>
168 </dd>
169 <dd>
170 <pre>
171 syslog(&quot;info&quot;, $message); # informational level
172 syslog(LOG_INFO, $message); # informational level</pre>
173 </dd>
174 <dd>
175 <pre>
176 syslog(&quot;info|local0&quot;, $message); # information level, Local0 facility
177 syslog(LOG_INFO|LOG_LOCAL0, $message); # information level, Local0 facility</pre>
178 </dd>
179 <dl>
180 <dt><strong><a name="item_note"><strong>Note</strong></a></strong>
182 <dd>
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, &quot;%s&quot;, $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>
190 </dd>
191 </li>
192 </dl>
193 <dt><strong><a name="item_setlogmask"><strong>setlogmask($mask_priority)</strong></a></strong>
195 <dd>
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>
199 </dd>
200 <dd>
201 <p><strong>Examples</strong></p>
202 </dd>
203 <dd>
204 <p>Only log errors:</p>
205 </dd>
206 <dd>
207 <pre>
208 setlogmask(LOG_ERR);</pre>
209 </dd>
210 <dd>
211 <p>Log critical messages, errors and warnings:</p>
212 </dd>
213 <dd>
214 <pre>
215 setlogmask(LOG_CRIT|LOG_ERR|LOG_WARNING);</pre>
216 </dd>
217 </li>
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>
222 <dd>
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>
226 </dd>
227 <dd>
228 <p>A value of <code>&quot;unix&quot;</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>&quot;stream&quot;</code> instead of <code>&quot;unix&quot;</code>.)
234 A value of <code>&quot;inet&quot;</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>&quot;tcp&quot;</code> and <code>&quot;udp&quot;</code> can
236 also be given as values. The value <code>&quot;console&quot;</code> will send messages
237 directly to the console, as for the <code>&quot;cons&quot;</code> option in the logopts in
238 <a href="#item_openlog"><code>openlog()</code></a>.</p>
239 </dd>
240 <dd>
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>
244 </dd>
245 <dd>
246 <p>The default is to try <code>tcp</code>, <code>udp</code>, <code>unix</code>, <code>stream</code>, <code>console</code>.</p>
247 </dd>
248 <dd>
249 <p>Giving an invalid value for <code>$sock_type</code> will croak.</p>
250 </dd>
251 </li>
252 <dt><strong><a name="item_closelog"><strong>closelog()</strong></a></strong>
254 <dd>
255 <p>Closes the log file and return true on success.</p>
256 </dd>
257 </li>
258 </dl>
260 </p>
261 <hr />
262 <h1><a name="examples">EXAMPLES</a></h1>
263 <pre>
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);
267 closelog();</pre>
268 <pre>
269 syslog('debug', 'this is the last test');</pre>
270 <pre>
271 setlogsock('unix');
272 openlog(&quot;$program $$&quot;, 'ndelay', 'user');
273 syslog('notice', 'fooprogram: this is really done');</pre>
274 <pre>
275 setlogsock('inet');
276 $! = 55;
277 syslog('info', 'problem was %m'); # %m == $! in syslog(3)</pre>
278 <pre>
279 # Log to UDP port on $remotehost instead of logging locally
280 setlogsock('udp');
281 $Sys::Syslog::host = $remotehost;
282 openlog($program, 'ndelay', 'user');
283 syslog('info', 'something happened over here');</pre>
285 </p>
286 <hr />
287 <h1><a name="constants">CONSTANTS</a></h1>
289 </p>
290 <h2><a name="facilities">Facilities</a></h2>
291 <ul>
292 <li>
293 <p><code>LOG_AUTH</code> - security/authorization messages</p>
294 </li>
295 <li>
296 <p><code>LOG_AUTHPRIV</code> - security/authorization messages (private)</p>
297 </li>
298 <li>
299 <p><code>LOG_CRON</code> - clock daemon (<strong>cron</strong> and <strong>at</strong>)</p>
300 </li>
301 <li>
302 <p><code>LOG_DAEMON</code> - system daemons without separate facility value</p>
303 </li>
304 <li>
305 <p><code>LOG_FTP</code> - ftp daemon</p>
306 </li>
307 <li>
308 <p><code>LOG_KERN</code> - kernel messages</p>
309 </li>
310 <li>
311 <p><code>LOG_LOCAL0</code> through <code>LOG_LOCAL7</code> - reserved for local use</p>
312 </li>
313 <li>
314 <p><code>LOG_LPR</code> - line printer subsystem</p>
315 </li>
316 <li>
317 <p><code>LOG_MAIL</code> - mail subsystem</p>
318 </li>
319 <li>
320 <p><code>LOG_NEWS</code> - USENET news subsystem</p>
321 </li>
322 <li>
323 <p><code>LOG_SYSLOG</code> - messages generated internally by <strong>syslogd</strong></p>
324 </li>
325 <li>
326 <p><code>LOG_USER</code> (default) - generic user-level messages</p>
327 </li>
328 <li>
329 <p><code>LOG_UUCP</code> - UUCP subsystem</p>
330 </li>
331 </ul>
333 </p>
334 <h2><a name="levels">Levels</a></h2>
335 <ul>
336 <li>
337 <p><code>LOG_EMERG</code> - system is unusable</p>
338 </li>
339 <li>
340 <p><code>LOG_ALERT</code> - action must be taken immediately</p>
341 </li>
342 <li>
343 <p><code>LOG_CRIT</code> - critical conditions</p>
344 </li>
345 <li>
346 <p><code>LOG_ERR</code> - error conditions</p>
347 </li>
348 <li>
349 <p><code>LOG_WARNING</code> - warning conditions</p>
350 </li>
351 <li>
352 <p><code>LOG_NOTICE</code> - normal, but significant, condition</p>
353 </li>
354 <li>
355 <p><code>LOG_INFO</code> - informational message</p>
356 </li>
357 <li>
358 <p><code>LOG_DEBUG</code> - debug-level message</p>
359 </li>
360 </ul>
362 </p>
363 <hr />
364 <h1><a name="diagnostics">DIAGNOSTICS</a></h1>
365 <dl>
366 <dt><strong><a name="item_invalid_argument_passed_to_setlogsock">Invalid argument passed to setlogsock</a></strong>
368 <dd>
369 <p><strong>(F)</strong> You gave <a href="#item_setlogsock"><code>setlogsock()</code></a> an invalid value for <code>$sock_type</code>.</p>
370 </dd>
371 </li>
372 <dt><strong><a name="item_no_connection_to_syslog_available">no connection to syslog available</a></strong>
374 <dd>
375 <p><strong>(F)</strong> <a href="#item_syslog"><code>syslog()</code></a> failed to connect to the specified socket.</p>
376 </dd>
377 </li>
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>
380 <dd>
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>
383 </dd>
384 </li>
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>
387 <dd>
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>
390 </dd>
391 </li>
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>
394 <dd>
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>
397 </dd>
398 </li>
399 <dt><strong><a name="item_syslog_3a_expecting_argument__25s">syslog: expecting argument %s</a></strong>
401 <dd>
402 <p><strong>(F)</strong> You forgot to give <a href="#item_syslog"><code>syslog()</code></a> the indicated argument.</p>
403 </dd>
404 </li>
405 <dt><strong><a name="item_syslog_3a_invalid_level_2ffacility_3a__25s">syslog: invalid level/facility: %s</a></strong>
407 <dd>
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>
410 </dd>
411 </li>
412 <dt><strong><a name="item_syslog_3a_too_many_levels_given_3a__25s">syslog: too many levels given: %s</a></strong>
414 <dd>
415 <p><strong>(F)</strong> You specified too many levels.</p>
416 </dd>
417 </li>
418 <dt><strong><a name="item_syslog_3a_too_many_facilities_given_3a__25s">syslog: too many facilities given: %s</a></strong>
420 <dd>
421 <p><strong>(F)</strong> You specified too many facilities.</p>
422 </dd>
423 </li>
424 <dt><strong><a name="item_syslog_3a_level_must_be_given">syslog: level must be given</a></strong>
426 <dd>
427 <p><strong>(F)</strong> You forgot to specify a level.</p>
428 </dd>
429 </li>
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>
432 <dd>
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>
435 </dd>
436 </li>
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>
439 <dd>
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>
442 </dd>
443 </li>
444 </dl>
446 </p>
447 <hr />
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>
452 </p>
453 <hr />
454 <h1><a name="author">AUTHOR</a></h1>
455 <p>Tom Christiansen &lt;<em><a href="mailto:tchrist@perl.com">tchrist@perl.com</a></em>&gt; and Larry Wall
456 &lt;<em><a href="mailto:larry@wall.org">larry@wall.org</a></em>&gt;.</p>
457 <p>UNIX domain sockets added by Sean Robinson
458 &lt;<em><a href="mailto:robinson_s@sc.maricopa.edu">robinson_s@sc.maricopa.edu</a></em>&gt; with support from Tim Bunce
459 &lt;<em><a href="mailto:Tim.Bunce@ig.co.uk">Tim.Bunce@ig.co.uk</a></em>&gt; 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 &lt;<em><a href="mailto:tom@compton.nu">tom@compton.nu</a></em>&gt;.</p>
462 <p>Code for <code>constant()</code>s regenerated by Nicholas Clark &lt;<em><a href="mailto:nick@ccl4.org">nick@ccl4.org</a></em>&gt;.</p>
463 <p>Failover to different communication modes by Nick Williams
464 &lt;<em><a href="mailto:Nick.Williams@morganstanley.com">Nick.Williams@morganstanley.com</a></em>&gt;.</p>
465 <p>Extracted from core distribution for publishing on the CPAN by
466 S&eacute;bastien Aperghis-Tramoni &lt;<a href="mailto:sebastien@aperghis.net">sebastien@aperghis.net</a>&gt;.</p>
468 </p>
469 <hr />
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>
477 </p>
478 <hr />
479 <h1><a name="support">SUPPORT</a></h1>
480 <p>You can find documentation for this module with the perldoc command.</p>
481 <pre>
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>
484 <ul>
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>
488 </li>
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>
492 </li>
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>
496 </li>
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>
500 </li>
501 </ul>
503 </p>
504 <hr />
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">&nbsp;Sys::Syslog - Perl interface to the UNIX syslog calls</span></strong></big>
511 </td></tr>
512 </table>
514 </body>
516 </html>