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

NAME

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

SYNOPSIS

9        use Unix::Syslog qw(:macros);  # Syslog macros
10        use Unix::Syslog qw(:subs);    # Syslog functions
11
12        openlog $ident, $option, $facility;
13        syslog $priority, $format, @formatargs;
14        closelog;
15        $oldmask = setlogmask $mask_priority;
16

DESCRIPTION

18       This module provides an interface to the system logger syslogd(8) via
19       Perl's XSUBs. The implementation attempts to resemble the native libc-
20       functions of your system, so that anyone being familiar with syslog.h
21       should be able to use this module right away.
22
23       In contrary to Sys::Syslog(3), this modules does not open a network
24       connection to send the messages. This can help you to avoid opening
25       security holes in your computer (see "FAQ").
26
27       The subs imported by the tag "macros" are simply wrappers around the
28       most important "#defines" in your system's C header file syslog.h. The
29       macros return integer values that are used to specify options,
30       facilities and priorities in a more or less portable way. They also
31       provide general information about your local syslog mechanism. Check
32       syslog(3) and your local syslog.h for information about the macros,
33       options and facilities available on your system.
34
35       The following functions are provided:
36
37       openlog $ident, $option, $facility
38           opens a connection to the system logger.  $ident is an identifier
39           string that syslogd(8) prints into every message. It usually equals
40           the process name. $option is an integer value that is the result of
41           ORed options. $facility is an integer value that specifies the part
42           of the system the message should be associated with (e.g. kernel
43           message, mail subsystem).
44
45       syslog $priority, $format, @formatargs
46           Generates a log message and passes it to the system logger. If
47           "syslog()" is called without calling "openlog()" first, probably
48           system dependent default values will be used as arguments for an
49           implicit call to "openlog()".
50
51           $priority is an integer value that specifies the priority of the
52           message. Alternatively $priority can be the ORed value of a
53           priority and a facility. In that case a previously selected
54           facility will be overridden.
55
56           In the case that "syslog()" is called without calling "openlog()"
57           first and priority does not specify both a priority and a facility,
58           a default facility will be used. This behaviour is most likely
59           system dependent and the user should not rely on any particular
60           value in that case.
61
62           $format is a format string in the style of printf(3). Additionally
63           to the usual printf directives %m can be specified in the string.
64           It will be replaced implicitly by the contents of the Perl variable
65           $! ($ERRNO). @formatargs is a list of values that the format
66           directives will be replaced with subsequently.
67
68       closelog
69           closes the connection to the system logger.
70
71       setlogmask $mask_priority
72           sets the priority mask and returns the old mask. Logging is enabled
73           for the priorities indicated by the bits in the mask that are set
74           and is disabled where the bits are not set. Macros are provided to
75           specify valid and portable arguments to "setlogmask()". Usually the
76           default log mask allows all messages to be logged.
77
78       priorityname $priority
79           returns a string containing the name of $priority as string. If
80           this functionality has not been enabled at installation, the
81           function returns undef.
82
83       facilityname $facility
84           returns a string containing the name of $facility as string. If
85           this functionality has not been enabled at installation, the
86           function returns undef.
87
88       NOTE: The behaviour of this module is system dependent. It is highly
89       recommended to consult your system manual for available macros and the
90       behaviour of the provided functions.
91

RETURN VALUES

93       The functions openlog(), syslog() and closelog() return the undefined
94       value. The function setlogmask returns the previous mask value.
95

EXAMPLES

97       Open a channel to syslogd specifying an identifier (usually the process
98       name) some options and the facility:
99         "openlog "test.pl", LOG_PID | LOG_PERROR, LOG_LOCAL7;"
100
101       Generate log message of specified priority using a printf-type
102       formatted string:
103         "syslog LOG_INFO, "This is message number %d", 42;"
104
105       Set log priority mask to block all messages but those of priority
106       "LOG_DEBUG":
107         "$oldmask = setlogmask(LOG_MASK(LOG_DEBUG))"
108
109       Set log priority mask to block all messages with a higher priority than
110       "LOG_ERR":
111         "$oldmask = setlogmask(LOG_UPTO(LOG_ERR))"
112
113       Close channel to syslogd:
114         "closelog;"
115

FAQ

117       1.  What is the benefit of using this module instead of Sys::Syslog?
118
119           Sys::Syslog always opens a network connection to the syslog
120           service. At least on Linux systems this may lead to some trouble,
121           because
122
123           ·   Linux syslogd (from package sysklogd) does not listen to the
124               network by default. Most people working on stand-alone machines
125               (including me) didn't see any reason why to enable this option.
126               Others didn't enable it for security reasons.
127
128               OS-independent, some sysadmins may run a firewall on their
129               network that blocks connections to port 514/udp.
130
131           ·   By default Linux syslogd doesn't forward messages which have
132               already already received from the network to other log hosts.
133               There are reasons not to enable this option unless it is really
134               necessary. Looping messages resulting from a misconfiguration
135               may break down your (log-)system.
136
137           Peter Stamfest <peter.stamfest@eunet.at> pointed out some other
138           advantages of Unix::Syslog, I didn't came across my self.
139
140           ·   LOG_PERROR works.
141
142           ·   works with perl -Tw without warnings and problems due to
143               tainted data as it is the case for Sys::Syslog in some special
144               applications. [Especially when running a script as root]
145
146       2.  Well, is there any reason to use Sys::Syslog any longer?
147
148           Yes! In contrary to Unix::Syslog, Sys::Syslog works even if you
149           don't have a syslog daemon running on your system as long as you
150           are connected to a log host via a network and have access to the
151           syslog.h header file of your log host to generate the initial files
152           for Sys::Syslog (see Sys::Syslog(3) for details). Unix::Syslog only
153           logs to your local syslog daemon which in turn may be configured to
154           distribute the message over the network.
155
156       3.  Are calls to the functions provided by Unix::Syslog compatible to
157           those of Sys::Syslog?
158
159           Currently not. Sys::Syslog requires strings to specify many of the
160           arguments to the functions, while Unix::Syslog uses numeric
161           constants accessed via macros as defined in syslog.h. Although the
162           strings used by Sys::Syslog are also defined in syslog.h, it seems
163           that most people got used to the numeric arguments. I will
164           implement the string based calls if there are enough people
165           ($min_people > 10**40) complaining about the lack of compatibility.
166

SEE ALSO

168       syslog(3), Sys::Syslog(3), syslogd(8), perl(1)
169

AUTHOR

171       Marcus Harnisch <marcus.harnisch@gmx.net>
172
173
174
175perl v5.30.1                      2020-01-30                         Syslog(3)
Impressum