1Syslog(3) User Contributed Perl Documentation Syslog(3)
2
3
4
6 Sys::Syslog - Perl interface to the UNIX syslog(3) calls
7
9 This is the documentation of version 0.35
10
12 use Sys::Syslog; # all except setlogsock()
13 use Sys::Syslog qw(:standard :macros); # standard functions & macros
14
15 openlog($ident, $logopt, $facility); # don't forget this
16 syslog($priority, $format, @args);
17 $oldmask = setlogmask($mask_priority);
18 closelog();
19
21 "Sys::Syslog" is an interface to the UNIX syslog(3) program. Call
22 "syslog()" with a string priority and a list of "printf()" args just
23 like syslog(3).
24
26 "Sys::Syslog" exports the following "Exporter" tags:
27
28 · ":standard" exports the standard syslog(3) functions:
29
30 openlog closelog setlogmask syslog
31
32 · ":extended" exports the Perl specific functions for syslog(3):
33
34 setlogsock
35
36 · ":macros" exports the symbols corresponding to most of your
37 syslog(3) macros and the "LOG_UPTO()" and "LOG_MASK()" functions.
38 See "CONSTANTS" for the supported constants and their meaning.
39
40 By default, "Sys::Syslog" exports the symbols from the ":standard" tag.
41
43 openlog($ident, $logopt, $facility)
44 Opens the syslog. $ident is prepended to every message. $logopt
45 contains zero or more of the options detailed below. $facility
46 specifies the part of the system to report about, for example
47 "LOG_USER" or "LOG_LOCAL0": see "Facilities" for a list of well-
48 known facilities, and your syslog(3) documentation for the
49 facilities available in your system. Check "SEE ALSO" for useful
50 links. Facility can be given as a string or a numeric macro.
51
52 This function will croak if it can't connect to the syslog daemon.
53
54 Note that "openlog()" now takes three arguments, just like
55 openlog(3).
56
57 You should use "openlog()" before calling "syslog()".
58
59 Options
60
61 · "cons" - This option is ignored, since the failover mechanism
62 will drop down to the console automatically if all other media
63 fail.
64
65 · "ndelay" - Open the connection immediately (normally, the
66 connection is opened when the first message is logged).
67
68 · "noeol" - When set to true, no end of line character ("\n")
69 will be appended to the message. This can be useful for some
70 syslog daemons. Added in "Sys::Syslog" 0.29.
71
72 · "nofatal" - When set to true, "openlog()" and "syslog()" will
73 only emit warnings instead of dying if the connection to the
74 syslog can't be established. Added in "Sys::Syslog" 0.15.
75
76 · "nonul" - When set to true, no "NUL" character ("\0") will be
77 appended to the message. This can be useful for some syslog
78 daemons. Added in "Sys::Syslog" 0.29.
79
80 · "nowait" - Don't wait for child processes that may have been
81 created while logging the message. (The GNU C library does not
82 create a child process, so this option has no effect on Linux.)
83
84 · "perror" - Write the message to standard error output as well
85 to the system log. Added in "Sys::Syslog" 0.22.
86
87 · "pid" - Include PID with each message.
88
89 Examples
90
91 Open the syslog with options "ndelay" and "pid", and with facility
92 "LOCAL0":
93
94 openlog($name, "ndelay,pid", "local0");
95
96 Same thing, but this time using the macro corresponding to
97 "LOCAL0":
98
99 openlog($name, "ndelay,pid", LOG_LOCAL0);
100
101 syslog($priority, $message)
102 syslog($priority, $format, @args)
103 If $priority permits, logs $message or "sprintf($format, @args)"
104 with the addition that %m in $message or $format is replaced with
105 "$!" (the latest error message).
106
107 $priority can specify a level, or a level and a facility. Levels
108 and facilities can be given as strings or as macros. When using
109 the "eventlog" mechanism, priorities "DEBUG" and "INFO" are mapped
110 to event type "informational", "NOTICE" and "WARNING" to "warning"
111 and "ERR" to "EMERG" to "error".
112
113 If you didn't use "openlog()" before using "syslog()", "syslog()"
114 will try to guess the $ident by extracting the shortest prefix of
115 $format that ends in a ":".
116
117 Examples
118
119 # informational level
120 syslog("info", $message);
121 syslog(LOG_INFO, $message);
122
123 # information level, Local0 facility
124 syslog("info|local0", $message);
125 syslog(LOG_INFO|LOG_LOCAL0, $message);
126
127 Note
128 "Sys::Syslog" version v0.07 and older passed the $message as
129 the formatting string to "sprintf()" even when no formatting
130 arguments were provided. If the code calling "syslog()" might
131 execute with older versions of this module, make sure to call
132 the function as "syslog($priority, "%s", $message)" instead of
133 "syslog($priority, $message)". This protects against hostile
134 formatting sequences that might show up if $message contains
135 tainted data.
136
137 setlogmask($mask_priority)
138 Sets the log mask for the current process to $mask_priority and
139 returns the old mask. If the mask argument is 0, the current log
140 mask is not modified. See "Levels" for the list of available
141 levels. You can use the "LOG_UPTO()" function to allow all levels
142 up to a given priority (but it only accept the numeric macros as
143 arguments).
144
145 Examples
146
147 Only log errors:
148
149 setlogmask( LOG_MASK(LOG_ERR) );
150
151 Log everything except informational messages:
152
153 setlogmask( ~(LOG_MASK(LOG_INFO)) );
154
155 Log critical messages, errors and warnings:
156
157 setlogmask( LOG_MASK(LOG_CRIT)
158 | LOG_MASK(LOG_ERR)
159 | LOG_MASK(LOG_WARNING) );
160
161 Log all messages up to debug:
162
163 setlogmask( LOG_UPTO(LOG_DEBUG) );
164
165 setlogsock()
166 Sets the socket type and options to be used for the next call to
167 "openlog()" or "syslog()". Returns true on success, "undef" on
168 failure.
169
170 Being Perl-specific, this function has evolved along time. It can
171 currently be called as follow:
172
173 · "setlogsock($sock_type)"
174
175 · "setlogsock($sock_type, $stream_location)" (added in Perl
176 5.004_02)
177
178 · "setlogsock($sock_type, $stream_location, $sock_timeout)"
179 (added in "Sys::Syslog" 0.25)
180
181 · "setlogsock(\%options)" (added in "Sys::Syslog" 0.28)
182
183 The available options are:
184
185 · "type" - equivalent to $sock_type, selects the socket type (or
186 "mechanism"). An array reference can be passed to specify
187 several mechanisms to try, in the given order.
188
189 · "path" - equivalent to $stream_location, sets the stream
190 location. Defaults to standard Unix location, or "_PATH_LOG".
191
192 · "timeout" - equivalent to $sock_timeout, sets the socket
193 timeout in seconds. Defaults to 0 on all systems except
194 Mac OS X where it is set to 0.25 sec.
195
196 · "host" - sets the hostname to send the messages to. Defaults
197 to the local host.
198
199 · "port" - sets the TCP or UDP port to connect to. Defaults to
200 the first standard syslog port available on the system.
201
202 The available mechanisms are:
203
204 · "native" - use the native C functions from your syslog(3)
205 library (added in "Sys::Syslog" 0.15).
206
207 · "eventlog" - send messages to the Win32 events logger (Win32
208 only; added in "Sys::Syslog" 0.19).
209
210 · "tcp" - connect to a TCP socket, on the "syslog/tcp" or
211 "syslogng/tcp" service. See also the "host", "port" and
212 "timeout" options.
213
214 · "udp" - connect to a UDP socket, on the "syslog/udp" service.
215 See also the "host", "port" and "timeout" options.
216
217 · "inet" - connect to an INET socket, either TCP or UDP, tried in
218 that order. See also the "host", "port" and "timeout" options.
219
220 · "unix" - connect to a UNIX domain socket (in some systems a
221 character special device). The name of that socket is given by
222 the "path" option or, if omitted, the value returned by the
223 "_PATH_LOG" macro (if your system defines it), /dev/log or
224 /dev/conslog, whichever is writable.
225
226 · "stream" - connect to the stream indicated by the "path"
227 option, or, if omitted, the value returned by the "_PATH_LOG"
228 macro (if your system defines it), /dev/log or /dev/conslog,
229 whichever is writable. For example Solaris and IRIX system may
230 prefer "stream" instead of "unix".
231
232 · "pipe" - connect to the named pipe indicated by the "path"
233 option, or, if omitted, to the value returned by the
234 "_PATH_LOG" macro (if your system defines it), or /dev/log
235 (added in "Sys::Syslog" 0.21). HP-UX is a system which uses
236 such a named pipe.
237
238 · "console" - send messages directly to the console, as for the
239 "cons" option of "openlog()".
240
241 The default is to try "native", "tcp", "udp", "unix", "pipe",
242 "stream", "console". Under systems with the Win32 API, "eventlog"
243 will be added as the first mechanism to try if "Win32::EventLog" is
244 available.
245
246 Giving an invalid value for $sock_type will "croak".
247
248 Examples
249
250 Select the UDP socket mechanism:
251
252 setlogsock("udp");
253
254 Send messages using the TCP socket mechanism on a custom port:
255
256 setlogsock({ type => "tcp", port => 2486 });
257
258 Send messages to a remote host using the TCP socket mechanism:
259
260 setlogsock({ type => "tcp", host => $loghost });
261
262 Try the native, UDP socket then UNIX domain socket mechanisms:
263
264 setlogsock(["native", "udp", "unix"]);
265
266 Note
267 Now that the "native" mechanism is supported by "Sys::Syslog"
268 and selected by default, the use of the "setlogsock()" function
269 is discouraged because other mechanisms are less portable
270 across operating systems. Authors of modules and programs that
271 use this function, especially its cargo-cult form
272 "setlogsock("unix")", are advised to remove any occurrence of
273 it unless they specifically want to use a given mechanism (like
274 TCP or UDP to connect to a remote host).
275
276 closelog()
277 Closes the log file and returns true on success.
278
280 The First Rule of Sys::Syslog is: You do not call "setlogsock".
281
282 The Second Rule of Sys::Syslog is: You do not call "setlogsock".
283
284 The Third Rule of Sys::Syslog is: The program crashes, "die"s, calls
285 "closelog", the log is over.
286
287 The Fourth Rule of Sys::Syslog is: One facility, one priority.
288
289 The Fifth Rule of Sys::Syslog is: One log at a time.
290
291 The Sixth Rule of Sys::Syslog is: No "syslog" before "openlog".
292
293 The Seventh Rule of Sys::Syslog is: Logs will go on as long as they
294 have to.
295
296 The Eighth, and Final Rule of Sys::Syslog is: If this is your first use
297 of Sys::Syslog, you must read the doc.
298
300 An example:
301
302 openlog($program, 'cons,pid', 'user');
303 syslog('info', '%s', 'this is another test');
304 syslog('mail|warning', 'this is a better test: %d', time);
305 closelog();
306
307 syslog('debug', 'this is the last test');
308
309 Another example:
310
311 openlog("$program $$", 'ndelay', 'user');
312 syslog('notice', 'fooprogram: this is really done');
313
314 Example of use of %m:
315
316 $! = 55;
317 syslog('info', 'problem was %m'); # %m == $! in syslog(3)
318
319 Log to UDP port on $remotehost instead of logging locally:
320
321 setlogsock("udp", $remotehost);
322 openlog($program, 'ndelay', 'user');
323 syslog('info', 'something happened over here');
324
326 Facilities
327 · "LOG_AUDIT" - audit daemon (IRIX); falls back to "LOG_AUTH"
328
329 · "LOG_AUTH" - security/authorization messages
330
331 · "LOG_AUTHPRIV" - security/authorization messages (private)
332
333 · "LOG_CONSOLE" - "/dev/console" output (FreeBSD); falls back to
334 "LOG_USER"
335
336 · "LOG_CRON" - clock daemons (cron and at)
337
338 · "LOG_DAEMON" - system daemons without separate facility value
339
340 · "LOG_FTP" - FTP daemon
341
342 · "LOG_KERN" - kernel messages
343
344 · "LOG_INSTALL" - installer subsystem (Mac OS X); falls back to
345 "LOG_USER"
346
347 · "LOG_LAUNCHD" - launchd - general bootstrap daemon (Mac OS X);
348 falls back to "LOG_DAEMON"
349
350 · "LOG_LFMT" - logalert facility; falls back to "LOG_USER"
351
352 · "LOG_LOCAL0" through "LOG_LOCAL7" - reserved for local use
353
354 · "LOG_LPR" - line printer subsystem
355
356 · "LOG_MAIL" - mail subsystem
357
358 · "LOG_NETINFO" - NetInfo subsystem (Mac OS X); falls back to
359 "LOG_DAEMON"
360
361 · "LOG_NEWS" - USENET news subsystem
362
363 · "LOG_NTP" - NTP subsystem (FreeBSD, NetBSD); falls back to
364 "LOG_DAEMON"
365
366 · "LOG_RAS" - Remote Access Service (VPN / PPP) (Mac OS X); falls
367 back to "LOG_AUTH"
368
369 · "LOG_REMOTEAUTH" - remote authentication/authorization (Mac OS X);
370 falls back to "LOG_AUTH"
371
372 · "LOG_SECURITY" - security subsystems (firewalling, etc.) (FreeBSD);
373 falls back to "LOG_AUTH"
374
375 · "LOG_SYSLOG" - messages generated internally by syslogd
376
377 · "LOG_USER" (default) - generic user-level messages
378
379 · "LOG_UUCP" - UUCP subsystem
380
381 Levels
382 · "LOG_EMERG" - system is unusable
383
384 · "LOG_ALERT" - action must be taken immediately
385
386 · "LOG_CRIT" - critical conditions
387
388 · "LOG_ERR" - error conditions
389
390 · "LOG_WARNING" - warning conditions
391
392 · "LOG_NOTICE" - normal, but significant, condition
393
394 · "LOG_INFO" - informational message
395
396 · "LOG_DEBUG" - debug-level message
397
399 "Invalid argument passed to setlogsock"
400 (F) You gave "setlogsock()" an invalid value for $sock_type.
401
402 "eventlog passed to setlogsock, but no Win32 API available"
403 (W) You asked "setlogsock()" to use the Win32 event logger but the
404 operating system running the program isn't Win32 or does not
405 provides Win32 compatible facilities.
406
407 "no connection to syslog available"
408 (F) "syslog()" failed to connect to the specified socket.
409
410 "stream passed to setlogsock, but %s is not writable"
411 (W) You asked "setlogsock()" to use a stream socket, but the given
412 path is not writable.
413
414 "stream passed to setlogsock, but could not find any device"
415 (W) You asked "setlogsock()" to use a stream socket, but didn't
416 provide a path, and "Sys::Syslog" was unable to find an appropriate
417 one.
418
419 "tcp passed to setlogsock, but tcp service unavailable"
420 (W) You asked "setlogsock()" to use a TCP socket, but the service
421 is not available on the system.
422
423 "syslog: expecting argument %s"
424 (F) You forgot to give "syslog()" the indicated argument.
425
426 "syslog: invalid level/facility: %s"
427 (F) You specified an invalid level or facility.
428
429 "syslog: too many levels given: %s"
430 (F) You specified too many levels.
431
432 "syslog: too many facilities given: %s"
433 (F) You specified too many facilities.
434
435 "syslog: level must be given"
436 (F) You forgot to specify a level.
437
438 "udp passed to setlogsock, but udp service unavailable"
439 (W) You asked "setlogsock()" to use a UDP socket, but the service
440 is not available on the system.
441
442 "unix passed to setlogsock, but path not available"
443 (W) You asked "setlogsock()" to use a UNIX socket, but
444 "Sys::Syslog" was unable to find an appropriate an appropriate
445 device.
446
448 "Sys::Syslog" is a core module, part of the standard Perl distribution
449 since 1990. At this time, modules as we know them didn't exist, the
450 Perl library was a collection of .pl files, and the one for sending
451 syslog messages with was simply lib/syslog.pl, included with Perl 3.0.
452 It was converted as a module with Perl 5.0, but had a version number
453 only starting with Perl 5.6. Here is a small table with the matching
454 Perl and "Sys::Syslog" versions.
455
456 Sys::Syslog Perl
457 ----------- ----
458 undef 5.0.0 ~ 5.5.4
459 0.01 5.6.*
460 0.03 5.8.0
461 0.04 5.8.1, 5.8.2, 5.8.3
462 0.05 5.8.4, 5.8.5, 5.8.6
463 0.06 5.8.7
464 0.13 5.8.8
465 0.22 5.10.0
466 0.27 5.8.9, 5.10.1 ~ 5.14.*
467 0.29 5.16.*
468 0.32 5.18.*
469 0.33 5.20.*
470 0.33 5.22.*
471
473 Other modules
474 Log::Log4perl - Perl implementation of the Log4j API
475
476 Log::Dispatch - Dispatches messages to one or more outputs
477
478 Log::Report - Report a problem, with exceptions and language support
479
480 Manual Pages
481 syslog(3)
482
483 SUSv3 issue 6, IEEE Std 1003.1, 2004 edition,
484 <http://www.opengroup.org/onlinepubs/000095399/basedefs/syslog.h.html>
485
486 GNU C Library documentation on syslog,
487 <http://www.gnu.org/software/libc/manual/html_node/Syslog.html>
488
489 FreeBSD documentation on syslog,
490 <https://www.freebsd.org/cgi/man.cgi?query=syslog>
491
492 Solaris 11 documentation on syslog,
493 <https://docs.oracle.com/cd/E53394_01/html/E54766/syslog-3c.html>
494
495 Mac OS X documentation on syslog,
496 <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man3/syslog.3.html>
497
498 IRIX documentation on syslog,
499 <http://nixdoc.net/man-pages/IRIX/man3/syslog.3c.html>
500
501 AIX 5L 5.3 documentation on syslog,
502 <http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.basetechref/doc/basetrf2/syslog.htm>
503
504 HP-UX 11i documentation on syslog,
505 <http://docs.hp.com/en/B2355-60130/syslog.3C.html>
506
507 Tru64 documentation on syslog,
508 <http://nixdoc.net/man-pages/Tru64/man3/syslog.3.html>
509
510 Stratus VOS 15.1,
511 <http://stratadoc.stratus.com/vos/15.1.1/r502-01/wwhelp/wwhimpl/js/html/wwhelp.htm?context=r502-01&file=ch5r502-01bi.html>
512
513 RFCs
514 RFC 3164 - The BSD syslog Protocol,
515 <http://www.faqs.org/rfcs/rfc3164.html> -- Please note that this is an
516 informational RFC, and therefore does not specify a standard of any
517 kind.
518
519 RFC 3195 - Reliable Delivery for syslog,
520 <http://www.faqs.org/rfcs/rfc3195.html>
521
522 Articles
523 Syslogging with Perl, <http://lexington.pm.org/meetings/022001.html>
524
525 Event Log
526 Windows Event Log,
527 <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wes/wes/windows_event_log.asp>
528
530 Tom Christiansen <tchrist (at) perl.com> and Larry Wall <larry (at)
531 wall.org>.
532
533 UNIX domain sockets added by Sean Robinson <robinson_s (at)
534 sc.maricopa.edu> with support from Tim Bunce <Tim.Bunce (at) ig.co.uk>
535 and the "perl5-porters" mailing list.
536
537 Dependency on syslog.ph replaced with XS code by Tom Hughes <tom (at)
538 compton.nu>.
539
540 Code for "constant()"s regenerated by Nicholas Clark <nick (at)
541 ccl4.org>.
542
543 Failover to different communication modes by Nick Williams
544 <Nick.Williams (at) morganstanley.com>.
545
546 Extracted from core distribution for publishing on the CPAN by
547 Sébastien Aperghis-Tramoni <sebastien (at) aperghis.net>.
548
549 XS code for using native C functions borrowed from "Unix::Syslog",
550 written by Marcus Harnisch <marcus.harnisch (at) gmx.net>.
551
552 Yves Orton suggested and helped for making "Sys::Syslog" use the native
553 event logger under Win32 systems.
554
555 Jerry D. Hedden and Reini Urban provided greatly appreciated help to
556 debug and polish "Sys::Syslog" under Cygwin.
557
559 Please report any bugs or feature requests to "bug-sys-syslog (at)
560 rt.cpan.org", or through the web interface at
561 <http://rt.cpan.org/Public/Dist/Display.html?Name=Sys-Syslog>. I will
562 be notified, and then you'll automatically be notified of progress on
563 your bug as I make changes.
564
566 You can find documentation for this module with the perldoc command.
567
568 perldoc Sys::Syslog
569
570 You can also look for information at:
571
572 · Perl Documentation
573
574 <http://perldoc.perl.org/Sys/Syslog.html>
575
576 · MetaCPAN
577
578 <https://metacpan.org/module/Sys::Syslog>
579
580 · Search CPAN
581
582 <http://search.cpan.org/dist/Sys-Syslog/>
583
584 · AnnoCPAN: Annotated CPAN documentation
585
586 <http://annocpan.org/dist/Sys-Syslog>
587
588 · CPAN Ratings
589
590 <http://cpanratings.perl.org/d/Sys-Syslog>
591
592 · RT: CPAN's request tracker
593
594 <http://rt.cpan.org/Dist/Display.html?Queue=Sys-Syslog>
595
596 The source code is available on Git Hub:
597 <https://github.com/maddingue/Sys-Syslog/>
598
600 Copyright (C) 1990-2012 by Larry Wall and others.
601
603 This program is free software; you can redistribute it and/or modify it
604 under the same terms as Perl itself.
605
606
607
608perl v5.28.0 2016-09-01 Syslog(3)