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.13
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           setlogsock $sock_type;
17           openlog $ident, $logopt, $facility;       # don't forget this
18           syslog $priority, $format, @args;
19           $oldmask = setlogmask $mask_priority;
20           closelog;
21

DESCRIPTION

23       "Sys::Syslog" is an interface to the UNIX syslog(3) program.  Call
24       "syslog()" with a string priority and a list of "printf()" args just
25       like syslog(3).
26

EXPORTS

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

FUNCTIONS

45       openlog($ident, $logopt, $facility)
46           Opens the syslog.  $ident is prepended to every message.  $logopt
47           contains zero or more of the words "pid", "ndelay", "nowait".  The
48           "cons" option is ignored, since the failover mechanism will drop
49           down to the console automatically if all other media fail.  $facil‐
50           ity specifies the part of the system to report about, for example
51           "LOG_USER" or "LOG_LOCAL0": see your syslog(3) documentation for
52           the facilities available in your system. Facility can be given as a
53           string or a numeric macro.
54
55           This function will croak if it can't connect to the syslog daemon.
56
57           Note that "openlog()" now takes three arguments, just like open‐
58           log(3).
59
60           You should use openlog() before calling syslog().
61
62           Options
63
64           *   "ndelay" - Open the connection immediately (normally, the con‐
65               nection is opened when the first message is logged).
66
67           *   "nowait" - Don't wait for child processes that may have been
68               created while logging the message.  (The GNU C library does not
69               create a child process, so this option has no effect on Linux.)
70
71           *   "pid" - Include PID with each message.
72
73           Examples
74
75           Open the syslog with options "ndelay" and "pid", and with facility
76           "LOCAL0":
77
78               openlog($name, "ndelay,pid", "local0");
79
80           Same thing, but this time using the macro corresponding to
81           "LOCAL0":
82
83               openlog($name, "ndelay,pid", LOG_LOCAL0);
84
85       syslog($priority, $message)
86       syslog($priority, $format, @args)
87           If $priority permits, logs $message or "sprintf($format, @args)"
88           with the addition that %m in $message or $format is replaced with
89           "$!" (the latest error message).
90
91           $priority can specify a level, or a level and a facility.  Levels
92           and facilities can be given as strings or as macros.
93
94           If you didn't use "openlog()" before using "syslog()", "syslog()"
95           will try to guess the $ident by extracting the shortest prefix of
96           $format that ends in a ":".
97
98           Examples
99
100               syslog("info", $message);           # informational level
101               syslog(LOG_INFO, $message);         # informational level
102
103               syslog("info⎪local0", $message);        # information level, Local0 facility
104               syslog(LOG_INFO⎪LOG_LOCAL0, $message);  # information level, Local0 facility
105
106           Note
107               "Sys::Syslog" version v0.07 and older passed the $message as
108               the formatting string to "sprintf()" even when no formatting
109               arguments were provided.  If the code calling "syslog()" might
110               execute with older versions of this module, make sure to call
111               the function as "syslog($priority, "%s", $message)" instead of
112               "syslog($priority, $message)".  This protects against hostile
113               formatting sequences that might show up if $message contains
114               tainted data.
115
116       setlogmask($mask_priority)
117           Sets the log mask for the current process to $mask_priority and
118           returns the old mask.  If the mask argument is 0, the current log
119           mask is not modified.  See "Levels" for the list of available lev‐
120           els.
121
122           Examples
123
124           Only log errors:
125
126               setlogmask(LOG_ERR);
127
128           Log critical messages, errors and warnings:
129
130               setlogmask(LOG_CRIT⎪LOG_ERR⎪LOG_WARNING);
131
132       setlogsock($sock_type)
133       setlogsock($sock_type, $stream_location) (added in 5.004_02)
134           Sets the socket type to be used for the next call to "openlog()" or
135           "syslog()" and returns true on success, "undef" on failure.
136
137           A value of "unix" will connect to the UNIX domain socket (in some
138           systems a character special device) returned by the "_PATH_LOG"
139           macro (if your system defines it), or /dev/log or /dev/conslog,
140           whatever is writable.  A value of 'stream' will connect to the
141           stream indicated by the pathname provided as the optional second
142           parameter.  (For example Solaris and IRIX require "stream" instead
143           of "unix".)  A value of "inet" will connect to an INET socket
144           (either "tcp" or "udp", tried in that order) returned by "get‐
145           servbyname()". "tcp" and "udp" can also be given as values. The
146           value "console" will send messages directly to the console, as for
147           the "cons" option in the logopts in "openlog()".
148
149           A reference to an array can also be passed as the first parameter.
150           When this calling method is used, the array should contain a list
151           of sock_types which are attempted in order.
152
153           The default is to try "tcp", "udp", "unix", "stream", "console".
154
155           Giving an invalid value for $sock_type will croak.
156
157       closelog()
158           Closes the log file and return true on success.
159

EXAMPLES

161           openlog($program, 'cons,pid', 'user');
162           syslog('info', '%s', 'this is another test');
163           syslog('mail⎪warning', 'this is a better test: %d', time);
164           closelog();
165
166           syslog('debug', 'this is the last test');
167
168           setlogsock('unix');
169           openlog("$program $$", 'ndelay', 'user');
170           syslog('notice', 'fooprogram: this is really done');
171
172           setlogsock('inet');
173           $! = 55;
174           syslog('info', 'problem was %m'); # %m == $! in syslog(3)
175
176           # Log to UDP port on $remotehost instead of logging locally
177           setlogsock('udp');
178           $Sys::Syslog::host = $remotehost;
179           openlog($program, 'ndelay', 'user');
180           syslog('info', 'something happened over here');
181

CONSTANTS

183       Facilities
184
185       ·   "LOG_AUTH" - security/authorization messages
186
187       ·   "LOG_AUTHPRIV" - security/authorization messages (private)
188
189       ·   "LOG_CRON" - clock daemon (cron and at)
190
191       ·   "LOG_DAEMON" - system daemons without separate facility value
192
193       ·   "LOG_FTP" - ftp daemon
194
195       ·   "LOG_KERN" - kernel messages
196
197       ·   "LOG_LOCAL0" through "LOG_LOCAL7" - reserved for local use
198
199       ·   "LOG_LPR" - line printer subsystem
200
201       ·   "LOG_MAIL" - mail subsystem
202
203       ·   "LOG_NEWS" - USENET news subsystem
204
205       ·   "LOG_SYSLOG" - messages generated internally by syslogd
206
207       ·   "LOG_USER" (default) - generic user-level messages
208
209       ·   "LOG_UUCP" - UUCP subsystem
210
211       Levels
212
213       ·   "LOG_EMERG" - system is unusable
214
215       ·   "LOG_ALERT" - action must be taken immediately
216
217       ·   "LOG_CRIT" - critical conditions
218
219       ·   "LOG_ERR" - error conditions
220
221       ·   "LOG_WARNING" - warning conditions
222
223       ·   "LOG_NOTICE" - normal, but significant, condition
224
225       ·   "LOG_INFO" - informational message
226
227       ·   "LOG_DEBUG" - debug-level message
228

DIAGNOSTICS

230       Invalid argument passed to setlogsock
231           (F) You gave "setlogsock()" an invalid value for $sock_type.
232
233       no connection to syslog available
234           (F) "syslog()" failed to connect to the specified socket.
235
236       stream passed to setlogsock, but %s is not writable
237           (W) You asked "setlogsock()" to use a stream socket, but the given
238           path is not writable.
239
240       stream passed to setlogsock, but could not find any device
241           (W) You asked "setlogsock()" to use a stream socket, but didn't
242           provide a path, and "Sys::Syslog" was unable to find an appropriate
243           one.
244
245       tcp passed to setlogsock, but tcp service unavailable
246           (W) You asked "setlogsock()" to use a TCP socket, but the service
247           is not available on the system.
248
249       syslog: expecting argument %s
250           (F) You forgot to give "syslog()" the indicated argument.
251
252       syslog: invalid level/facility: %s
253           (F) You specified an invalid level or facility, like "LOG_KERN"
254           (which is reserved to the kernel).
255
256       syslog: too many levels given: %s
257           (F) You specified too many levels.
258
259       syslog: too many facilities given: %s
260           (F) You specified too many facilities.
261
262       syslog: level must be given
263           (F) You forgot to specify a level.
264
265       udp passed to setlogsock, but udp service unavailable
266           (W) You asked "setlogsock()" to use a UDP socket, but the service
267           is not available on the system.
268
269       unix passed to setlogsock, but path not available
270           (W) You asked "setlogsock()" to use a UNIX socket, but "Sys::Sys‐
271           log" was unable to find an appropriate an appropriate device.
272

AUTHOR

279       Tom Christiansen <tchrist@perl.com> and Larry Wall <larry@wall.org>.
280
281       UNIX domain sockets added by Sean Robinson <robinson_s@sc.maricopa.edu>
282       with support from Tim Bunce <Tim.Bunce@ig.co.uk> and the
283       "perl5-porters" mailing list.
284
285       Dependency on syslog.ph replaced with XS code by Tom Hughes <tom@comp‐
286       ton.nu>.
287
288       Code for "constant()"s regenerated by Nicholas Clark <nick@ccl4.org>.
289
290       Failover to different communication modes by Nick Williams
291       <Nick.Williams@morganstanley.com>.
292
293       Extracted from core distribution for publishing on the CPAN by
294       Sebastien Aperghis-Tramoni <sebastien@aperghis.net>.
295

BUGS

297       Please report any bugs or feature requests to "bug-sys-syslog at
298       rt.cpan.org", or through the web interface at
299       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sys-Syslog>.  I will be
300       notified, and then you'll automatically be notified of progress on your
301       bug as I make changes.
302

SUPPORT

304       You can find documentation for this module with the perldoc command.
305
306           perldoc Sys::Syslog
307
308       You can also look for information at:
309
310       * AnnoCPAN: Annotated CPAN documentation
311           <http://annocpan.org/dist/Sys-Syslog>
312
313       * CPAN Ratings
314           <http://cpanratings.perl.org/d/Sys-Syslog>
315
316       * RT: CPAN's request tracker
317           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Syslog>
318
319       * Search CPAN
320           <http://search.cpan.org/dist/Sys-Syslog>
321

LICENSE

323       This program is free software; you can redistribute it and/or modify it
324       under the same terms as Perl itself.
325
326
327
328perl v5.8.8                       2001-09-21                  Sys::Syslog(3pm)