Sys::Syslog(3pm)

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
23       like 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.
38           See "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
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

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
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

HISTORY

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

AUTHORS & ACKNOWLEDGEMENTS

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

BUGS

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

SUPPORT

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

COPYRIGHT

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

LICENSE

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.34.0                      2022-01-21                         Syslog(3)