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.33
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               buggy syslog daemons.
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.
75
76           ·   "nonul" - When set to true, no "NUL" character ("\0") will be
77               appended to the message. This can be useful for some buggy
78               syslog daemons.
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.2
467              0.29         5.16.0, 5.16.1
468

SEE ALSO

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

AUTHORS & ACKNOWLEDGEMENTS

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

BUGS

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

SUPPORT

560       You can find documentation for this module with the perldoc command.
561
562           perldoc Sys::Syslog
563
564       You can also look for information at:
565
566       ·   AnnoCPAN: Annotated CPAN documentation
567
568           <http://annocpan.org/dist/Sys-Syslog>
569
570       ·   CPAN Ratings
571
572           <http://cpanratings.perl.org/d/Sys-Syslog>
573
574       ·   RT: CPAN's request tracker
575
576           <http://rt.cpan.org/Dist/Display.html?Queue=Sys-Syslog>
577
578       ·   Search CPAN
579
580           <http://search.cpan.org/dist/Sys-Syslog/>
581
582       ·   MetaCPAN
583
584           <https://metacpan.org/module/Sys::Syslog>
585
586       ·   Perl Documentation
587
588           <http://perldoc.perl.org/Sys/Syslog.html>
589

COPYRIGHT

591       Copyright (C) 1990-2012 by Larry Wall and others.
592

LICENSE

594       This program is free software; you can redistribute it and/or modify it
595       under the same terms as Perl itself.
596
597
598
599perl v5.16.3                      2013-05-24                         Syslog(3)