Sys::Syslog(3pm)

1Sys::Syslog(3pm)       Perl Programmers Reference Guide       Sys::Syslog(3pm)
2
3
4

NAME

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

VERSION

9       Version 0.27
10

SYNOPSIS

12           use Sys::Syslog;                          # all except setlogsock(), or:
13           use Sys::Syslog qw(:DEFAULT setlogsock);  # default set, plus setlogsock()
14           use Sys::Syslog qw(:standard :macros);    # standard functions, plus macros
15
16           openlog $ident, $logopt, $facility;       # don't forget this
17           syslog $priority, $format, @args;
18           $oldmask = setlogmask $mask_priority;
19           closelog;
20

DESCRIPTION

22       "Sys::Syslog" is an interface to the UNIX syslog(3) program.  Call
23       "syslog()" with a string priority and a list of "printf()" args just
24       like syslog(3).
25
26       You can find a kind of FAQ in "THE RULES OF SYS::SYSLOG".  Please read
27       it before coding, and again before asking questions.
28

EXPORTS

30       "Sys::Syslog" exports the following "Exporter" tags:
31
32       ·   ":standard" exports the standard syslog(3) functions:
33
34               openlog closelog setlogmask syslog
35
36       ·   ":extended" exports the Perl specific functions for syslog(3):
37
38               setlogsock
39
40       ·   ":macros" exports the symbols corresponding to most of your
41           syslog(3) macros and the "LOG_UPTO()" and "LOG_MASK()" functions.
42           See "CONSTANTS" for the supported constants and their meaning.
43
44       By default, "Sys::Syslog" exports the symbols from the ":standard" tag.
45

FUNCTIONS

47       openlog($ident, $logopt, $facility)
48           Opens the syslog.  $ident is prepended to every message.  $logopt
49           contains zero or more of the options detailed below.  $facility
50           specifies the part of the system to report about, for example
51           "LOG_USER" or "LOG_LOCAL0": see "Facilities" for a list of well-
52           known facilities, and your syslog(3) documentation for the
53           facilities available in your system.  Check "SEE ALSO" for useful
54           links. Facility can be given as a string or a numeric macro.
55
56           This function will croak if it can't connect to the syslog daemon.
57
58           Note that "openlog()" now takes three arguments, just like
59           openlog(3).
60
61           You should use "openlog()" before calling "syslog()".
62
63           Options
64
65           ·   "cons" - This option is ignored, since the failover mechanism
66               will drop down to the console automatically if all other media
67               fail.
68
69           ·   "ndelay" - Open the connection immediately (normally, the
70               connection is opened when the first message is logged).
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           ·   "nowait" - Don't wait for child processes that may have been
77               created while logging the message.  (The GNU C library does not
78               create a child process, so this option has no effect on Linux.)
79
80           ·   "perror" - Write the message to standard error output as well
81               to the system log.
82
83           ·   "pid" - Include PID with each message.
84
85           Examples
86
87           Open the syslog with options "ndelay" and "pid", and with facility
88           "LOCAL0":
89
90               openlog($name, "ndelay,pid", "local0");
91
92           Same thing, but this time using the macro corresponding to
93           "LOCAL0":
94
95               openlog($name, "ndelay,pid", LOG_LOCAL0);
96
97       syslog($priority, $message)
98       syslog($priority, $format, @args)
99           If $priority permits, logs $message or "sprintf($format, @args)"
100           with the addition that %m in $message or $format is replaced with
101           "$!" (the latest error message).
102
103           $priority can specify a level, or a level and a facility.  Levels
104           and facilities can be given as strings or as macros.  When using
105           the "eventlog" mechanism, priorities "DEBUG" and "INFO" are mapped
106           to event type "informational", "NOTICE" and "WARNIN" to "warning"
107           and "ERR" to "EMERG" to "error".
108
109           If you didn't use "openlog()" before using "syslog()", "syslog()"
110           will try to guess the $ident by extracting the shortest prefix of
111           $format that ends in a ":".
112
113           Examples
114
115               syslog("info", $message);           # informational level
116               syslog(LOG_INFO, $message);         # informational level
117
118               syslog("info|local0", $message);        # information level, Local0 facility
119               syslog(LOG_INFO|LOG_LOCAL0, $message);  # information level, Local0 facility
120
121           Note
122               "Sys::Syslog" version v0.07 and older passed the $message as
123               the formatting string to "sprintf()" even when no formatting
124               arguments were provided.  If the code calling "syslog()" might
125               execute with older versions of this module, make sure to call
126               the function as "syslog($priority, "%s", $message)" instead of
127               "syslog($priority, $message)".  This protects against hostile
128               formatting sequences that might show up if $message contains
129               tainted data.
130
131       setlogmask($mask_priority)
132           Sets the log mask for the current process to $mask_priority and
133           returns the old mask.  If the mask argument is 0, the current log
134           mask is not modified.  See "Levels" for the list of available
135           levels.  You can use the "LOG_UPTO()" function to allow all levels
136           up to a given priority (but it only accept the numeric macros as
137           arguments).
138
139           Examples
140
141           Only log errors:
142
143               setlogmask( LOG_MASK(LOG_ERR) );
144
145           Log everything except informational messages:
146
147               setlogmask( ~(LOG_MASK(LOG_INFO)) );
148
149           Log critical messages, errors and warnings:
150
151               setlogmask( LOG_MASK(LOG_CRIT) | LOG_MASK(LOG_ERR) | LOG_MASK(LOG_WARNING) );
152
153           Log all messages up to debug:
154
155               setlogmask( LOG_UPTO(LOG_DEBUG) );
156
157       setlogsock($sock_type)
158       setlogsock($sock_type, $stream_location) (added in Perl 5.004_02)
159       setlogsock($sock_type, $stream_location, $sock_timeout) (added in 0.25)
160           Sets the socket type to be used for the next call to "openlog()" or
161           "syslog()" and returns true on success, "undef" on failure. The
162           available mechanisms are:
163
164           ·   "native" - use the native C functions from your syslog(3)
165               library (added in "Sys::Syslog" 0.15).
166
167           ·   "eventlog" - send messages to the Win32 events logger (Win32
168               only; added in "Sys::Syslog" 0.19).
169
170           ·   "tcp" - connect to a TCP socket, on the "syslog/tcp" or
171               "syslogng/tcp" service. If defined, the second parameter is
172               used as a hostname to connect to.
173
174           ·   "udp" - connect to a UDP socket, on the "syslog/udp" service.
175               If defined, the second parameter is used as a hostname to
176               connect to, and the third parameter as the timeout used to
177               check for UDP response.
178
179           ·   "inet" - connect to an INET socket, either TCP or UDP, tried in
180               that order.  If defined, the second parameter is used as a
181               hostname to connect to.
182
183           ·   "unix" - connect to a UNIX domain socket (in some systems a
184               character special device).  The name of that socket is the
185               second parameter or, if you omit the second parameter, the
186               value returned by the "_PATH_LOG" macro (if your system defines
187               it), or /dev/log or /dev/conslog, whatever is writable.
188
189           ·   "stream" - connect to the stream indicated by the pathname
190               provided as the optional second parameter, or, if omitted, to
191               /dev/conslog.  For example Solaris and IRIX system may prefer
192               "stream" instead of "unix".
193
194           ·   "pipe" - connect to the named pipe indicated by the pathname
195               provided as the optional second parameter, or, if omitted, to
196               the value returned by the "_PATH_LOG" macro (if your system
197               defines it), or /dev/log (added in "Sys::Syslog" 0.21).
198
199           ·   "console" - send messages directly to the console, as for the
200               "cons" option of "openlog()".
201
202           A reference to an array can also be passed as the first parameter.
203           When this calling method is used, the array should contain a list
204           of mechanisms which are attempted in order.
205
206           The default is to try "native", "tcp", "udp", "unix", "pipe",
207           "stream", "console".  Under systems with the Win32 API, "eventlog"
208           will be added as the first mechanism to try if "Win32::EventLog" is
209           available.
210
211           Giving an invalid value for $sock_type will "croak".
212
213           Examples
214
215           Select the UDP socket mechanism:
216
217               setlogsock("udp");
218
219           Select the native, UDP socket then UNIX domain socket mechanisms:
220
221               setlogsock(["native", "udp", "unix"]);
222
223           Note
224               Now that the "native" mechanism is supported by "Sys::Syslog"
225               and selected by default, the use of the "setlogsock()" function
226               is discouraged because other mechanisms are less portable
227               across operating systems.  Authors of modules and programs that
228               use this function, especially its cargo-cult form
229               "setlogsock("unix")", are advised to remove any occurence of it
230               unless they specifically want to use a given mechanism (like
231               TCP or UDP to connect to a remote host).
232
233       closelog()
234           Closes the log file and returns true on success.
235

THE RULES OF SYS::SYSLOG

237       The First Rule of Sys::Syslog is: You do not call "setlogsock".
238
239       The Second Rule of Sys::Syslog is: You do not call "setlogsock".
240
241       The Third Rule of Sys::Syslog is: The program crashes, "die"s, calls
242       "closelog", the log is over.
243
244       The Fourth Rule of Sys::Syslog is: One facility, one priority.
245
246       The Fifth Rule of Sys::Syslog is: One log at a time.
247
248       The Sixth Rule of Sys::Syslog is: No "syslog" before "openlog".
249
250       The Seventh Rule of Sys::Syslog is: Logs will go on as long as they
251       have to.
252
253       The Eighth, and Final Rule of Sys::Syslog is: If this is your first use
254       of Sys::Syslog, you must read the doc.
255

EXAMPLES

257       An example:
258
259           openlog($program, 'cons,pid', 'user');
260           syslog('info', '%s', 'this is another test');
261           syslog('mail|warning', 'this is a better test: %d', time);
262           closelog();
263
264           syslog('debug', 'this is the last test');
265
266       Another example:
267
268           openlog("$program $$", 'ndelay', 'user');
269           syslog('notice', 'fooprogram: this is really done');
270
271       Example of use of %m:
272
273           $! = 55;
274           syslog('info', 'problem was %m');   # %m == $! in syslog(3)
275
276       Log to UDP port on $remotehost instead of logging locally:
277
278           setlogsock("udp", $remotehost);
279           openlog($program, 'ndelay', 'user');
280           syslog('info', 'something happened over here');
281

CONSTANTS

283   Facilities
284       ·   "LOG_AUDIT" - audit daemon (IRIX); falls back to "LOG_AUTH"
285
286       ·   "LOG_AUTH" - security/authorization messages
287
288       ·   "LOG_AUTHPRIV" - security/authorization messages (private)
289
290       ·   "LOG_CONSOLE" - "/dev/console" output (FreeBSD); falls back to
291           "LOG_USER"
292
293       ·   "LOG_CRON" - clock daemons (cron and at)
294
295       ·   "LOG_DAEMON" - system daemons without separate facility value
296
297       ·   "LOG_FTP" - FTP daemon
298
299       ·   "LOG_KERN" - kernel messages
300
301       ·   "LOG_INSTALL" - installer subsystem (Mac OS X); falls back to
302           "LOG_USER"
303
304       ·   "LOG_LAUNCHD" - launchd - general bootstrap daemon (Mac OS X);
305           falls back to "LOG_DAEMON"
306
307       ·   "LOG_LFMT" - logalert facility; falls back to "LOG_USER"
308
309       ·   "LOG_LOCAL0" through "LOG_LOCAL7" - reserved for local use
310
311       ·   "LOG_LPR" - line printer subsystem
312
313       ·   "LOG_MAIL" - mail subsystem
314
315       ·   "LOG_NETINFO" - NetInfo subsystem (Mac OS X); falls back to
316           "LOG_DAEMON"
317
318       ·   "LOG_NEWS" - USENET news subsystem
319
320       ·   "LOG_NTP" - NTP subsystem (FreeBSD, NetBSD); falls back to
321           "LOG_DAEMON"
322
323       ·   "LOG_RAS" - Remote Access Service (VPN / PPP) (Mac OS X); falls
324           back to "LOG_AUTH"
325
326       ·   "LOG_REMOTEAUTH" - remote authentication/authorization (Mac OS X);
327           falls back to "LOG_AUTH"
328
329       ·   "LOG_SECURITY" - security subsystems (firewalling, etc.) (FreeBSD);
330           falls back to "LOG_AUTH"
331
332       ·   "LOG_SYSLOG" - messages generated internally by syslogd
333
334       ·   "LOG_USER" (default) - generic user-level messages
335
336       ·   "LOG_UUCP" - UUCP subsystem
337
338   Levels
339       ·   "LOG_EMERG" - system is unusable
340
341       ·   "LOG_ALERT" - action must be taken immediately
342
343       ·   "LOG_CRIT" - critical conditions
344
345       ·   "LOG_ERR" - error conditions
346
347       ·   "LOG_WARNING" - warning conditions
348
349       ·   "LOG_NOTICE" - normal, but significant, condition
350
351       ·   "LOG_INFO" - informational message
352
353       ·   "LOG_DEBUG" - debug-level message
354

DIAGNOSTICS

356       "Invalid argument passed to setlogsock"
357           (F) You gave "setlogsock()" an invalid value for $sock_type.
358
359       "eventlog passed to setlogsock, but no Win32 API available"
360           (W) You asked "setlogsock()" to use the Win32 event logger but the
361           operating system running the program isn't Win32 or does not
362           provides Win32 compatible facilities.
363
364       "no connection to syslog available"
365           (F) "syslog()" failed to connect to the specified socket.
366
367       "stream passed to setlogsock, but %s is not writable"
368           (W) You asked "setlogsock()" to use a stream socket, but the given
369           path is not writable.
370
371       "stream passed to setlogsock, but could not find any device"
372           (W) You asked "setlogsock()" to use a stream socket, but didn't
373           provide a path, and "Sys::Syslog" was unable to find an appropriate
374           one.
375
376       "tcp passed to setlogsock, but tcp service unavailable"
377           (W) You asked "setlogsock()" to use a TCP socket, but the service
378           is not available on the system.
379
380       "syslog: expecting argument %s"
381           (F) You forgot to give "syslog()" the indicated argument.
382
383       "syslog: invalid level/facility: %s"
384           (F) You specified an invalid level or facility.
385
386       "syslog: too many levels given: %s"
387           (F) You specified too many levels.
388
389       "syslog: too many facilities given: %s"
390           (F) You specified too many facilities.
391
392       "syslog: level must be given"
393           (F) You forgot to specify a level.
394
395       "udp passed to setlogsock, but udp service unavailable"
396           (W) You asked "setlogsock()" to use a UDP socket, but the service
397           is not available on the system.
398
399       "unix passed to setlogsock, but path not available"
400           (W) You asked "setlogsock()" to use a UNIX socket, but
401           "Sys::Syslog" was unable to find an appropriate an appropriate
402           device.
403

AUTHORS & ACKNOWLEDGEMENTS

452       Tom Christiansen <tchrist (at) perl.com> and Larry Wall <larry (at)
453       wall.org>.
454
455       UNIX domain sockets added by Sean Robinson <robinson_s (at)
456       sc.maricopa.edu> with support from Tim Bunce <Tim.Bunce (at) ig.co.uk>
457       and the "perl5-porters" mailing list.
458
459       Dependency on syslog.ph replaced with XS code by Tom Hughes <tom (at)
460       compton.nu>.
461
462       Code for "constant()"s regenerated by Nicholas Clark <nick (at)
463       ccl4.org>.
464
465       Failover to different communication modes by Nick Williams
466       <Nick.Williams (at) morganstanley.com>.
467
468       Extracted from core distribution for publishing on the CPAN by
469       Sebastien Aperghis-Tramoni <sebastien (at) aperghis.net>.
470
471       XS code for using native C functions borrowed from "Unix::Syslog",
472       written by Marcus Harnisch <marcus.harnisch (at) gmx.net>.
473
474       Yves Orton suggested and helped for making "Sys::Syslog" use the native
475       event logger under Win32 systems.
476
477       Jerry D. Hedden and Reini Urban provided greatly appreciated help to
478       debug and polish "Sys::Syslog" under Cygwin.
479

BUGS

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

SUPPORT

488       You can find documentation for this module with the perldoc command.
489
490           perldoc Sys::Syslog
491
492       You can also look for information at:
493
494       ·   AnnoCPAN: Annotated CPAN documentation
495
496           <http://annocpan.org/dist/Sys-Syslog>
497
498       ·   CPAN Ratings
499
500           <http://cpanratings.perl.org/d/Sys-Syslog>
501
502       ·   RT: CPAN's request tracker
503
504           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Syslog>
505
506       ·   Search CPAN
507
508           <http://search.cpan.org/dist/Sys-Syslog/>
509
510       ·   Kobes' CPAN Search
511
512           <http://cpan.uwinnipeg.ca/dist/Sys-Syslog>
513
514       ·   Perl Documentation
515
516           <http://perldoc.perl.org/Sys/Syslog.html>
517

COPYRIGHT

519       Copyright (C) 1990-2008 by Larry Wall and others.
520

LICENSE

522       This program is free software; you can redistribute it and/or modify it
523       under the same terms as Perl itself.
524
525
526
527perl v5.10.1                      2009-04-14                  Sys::Syslog(3pm)