1Syslog(3)             User Contributed Perl Documentation            Syslog(3)
2
3
4

NAME

6       Sys::Syslog - Perl interface to the UNIX syslog(3) calls
7

VERSION

9       This is the documentation of version 0.36
10

SYNOPSIS

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

DESCRIPTION

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 like
23       syslog(3).
24

EXPORTS

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.  See
38           "CONSTANTS" for the supported constants and their meaning.
39
40       By default, "Sys::Syslog" exports the symbols from the ":standard" tag.
41

FUNCTIONS

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 only
73               emit warnings instead of dying if the connection to the syslog
74               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() will
114           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 up
142           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 it
273               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

THE RULES OF SYS::SYSLOG

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

EXAMPLES

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

CONSTANTS

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

DIAGNOSTICS

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 is
421           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 is
440           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 "Sys::Syslog"
444           was unable to find an appropriate an appropriate device.
445

HISTORY

447       "Sys::Syslog" is a core module, part of the standard Perl distribution
448       since 1990.  At this time, modules as we know them didn't exist, the
449       Perl library was a collection of .pl files, and the one for sending
450       syslog messages with was simply lib/syslog.pl, included with Perl 3.0.
451       It was converted as a module with Perl 5.0, but had a version number
452       only starting with Perl 5.6.  Here is a small table with the matching
453       Perl and "Sys::Syslog" versions.
454
455           Sys::Syslog     Perl
456           -----------     ----
457              undef        5.0.0 ~ 5.5.4
458              0.01         5.6.*
459              0.03         5.8.0
460              0.04         5.8.1, 5.8.2, 5.8.3
461              0.05         5.8.4, 5.8.5, 5.8.6
462              0.06         5.8.7
463              0.13         5.8.8
464              0.22         5.10.0
465              0.27         5.8.9, 5.10.1 ~ 5.14.*
466              0.29         5.16.*
467              0.32         5.18.*
468              0.33         5.20.*
469              0.33         5.22.*
470

SEE ALSO

472   Other modules
473       Log::Log4perl - Perl implementation of the Log4j API
474
475       Log::Dispatch - Dispatches messages to one or more outputs
476
477       Log::Report - Report a problem, with exceptions and language support
478
479   Manual Pages
480       syslog(3)
481
482       SUSv3 issue 6, IEEE Std 1003.1, 2004 edition,
483       <http://www.opengroup.org/onlinepubs/000095399/basedefs/syslog.h.html>
484
485       GNU C Library documentation on syslog,
486       <http://www.gnu.org/software/libc/manual/html_node/Syslog.html>
487
488       FreeBSD documentation on syslog,
489       <https://www.freebsd.org/cgi/man.cgi?query=syslog>
490
491       Solaris 11 documentation on syslog,
492       <https://docs.oracle.com/cd/E53394_01/html/E54766/syslog-3c.html>
493
494       Mac OS X documentation on syslog,
495       <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man3/syslog.3.html>
496
497       IRIX documentation on syslog,
498       <http://nixdoc.net/man-pages/IRIX/man3/syslog.3c.html>
499
500       AIX 5L 5.3 documentation on syslog,
501       <http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.basetechref/doc/basetrf2/syslog.htm>
502
503       HP-UX 11i documentation on syslog,
504       <http://docs.hp.com/en/B2355-60130/syslog.3C.html>
505
506       Tru64 documentation on syslog,
507       <http://nixdoc.net/man-pages/Tru64/man3/syslog.3.html>
508
509       Stratus VOS 15.1,
510       <http://stratadoc.stratus.com/vos/15.1.1/r502-01/wwhelp/wwhimpl/js/html/wwhelp.htm?context=r502-01&file=ch5r502-01bi.html>
511
512   RFCs
513       RFC 3164 - The BSD syslog Protocol,
514       <http://www.faqs.org/rfcs/rfc3164.html> -- Please note that this is an
515       informational RFC, and therefore does not specify a standard of any
516       kind.
517
518       RFC 3195 - Reliable Delivery for syslog,
519       <http://www.faqs.org/rfcs/rfc3195.html>
520
521   Articles
522       Syslogging with Perl, <http://lexington.pm.org/meetings/022001.html>
523
524   Event Log
525       Windows Event Log,
526       <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wes/wes/windows_event_log.asp>
527

AUTHORS & ACKNOWLEDGEMENTS

529       Tom Christiansen <tchrist (at) perl.com> and Larry Wall <larry (at)
530       wall.org>.
531
532       UNIX domain sockets added by Sean Robinson <robinson_s (at)
533       sc.maricopa.edu> with support from Tim Bunce <Tim.Bunce (at) ig.co.uk>
534       and the "perl5-porters" mailing list.
535
536       Dependency on syslog.ph replaced with XS code by Tom Hughes <tom (at)
537       compton.nu>.
538
539       Code for constant()s regenerated by Nicholas Clark <nick (at)
540       ccl4.org>.
541
542       Failover to different communication modes by Nick Williams
543       <Nick.Williams (at) morganstanley.com>.
544
545       Extracted from core distribution for publishing on the CPAN by
546       Sébastien Aperghis-Tramoni <sebastien (at) aperghis.net>.
547
548       XS code for using native C functions borrowed from "Unix::Syslog",
549       written by Marcus Harnisch <marcus.harnisch (at) gmx.net>.
550
551       Yves Orton suggested and helped for making "Sys::Syslog" use the native
552       event logger under Win32 systems.
553
554       Jerry D. Hedden and Reini Urban provided greatly appreciated help to
555       debug and polish "Sys::Syslog" under Cygwin.
556

BUGS

558       Please report any bugs or feature requests to "bug-sys-syslog (at)
559       rt.cpan.org", or through the web interface at
560       <http://rt.cpan.org/Public/Dist/Display.html?Name=Sys-Syslog>.  I will
561       be notified, and then you'll automatically be notified of progress on
562       your bug as I make changes.
563

SUPPORT

565       You can find documentation for this module with the perldoc command.
566
567           perldoc Sys::Syslog
568
569       You can also look for information at:
570
571       •   Perl Documentation
572
573           <http://perldoc.perl.org/Sys/Syslog.html>
574
575       •   MetaCPAN
576
577           <https://metacpan.org/module/Sys::Syslog>
578
579       •   Search CPAN
580
581           <http://search.cpan.org/dist/Sys-Syslog/>
582
583       •   AnnoCPAN: Annotated CPAN documentation
584
585           <http://annocpan.org/dist/Sys-Syslog>
586
587       •   CPAN Ratings
588
589           <http://cpanratings.perl.org/d/Sys-Syslog>
590
591       •   RT: CPAN's request tracker
592
593           <http://rt.cpan.org/Dist/Display.html?Queue=Sys-Syslog>
594
595       The source code is available on Git Hub:
596       <https://github.com/maddingue/Sys-Syslog/>
597

COPYRIGHT

599       Copyright (C) 1990-2012 by Larry Wall and others.
600

LICENSE

602       This program is free software; you can redistribute it and/or modify it
603       under the same terms as Perl itself.
604
605
606
607perl v5.36.0                      2023-01-20                         Syslog(3)