Debian Codegraph @

README

raw
1 Unix::Syslog -- Perl interface to the UNIX system logger
2 ========================================================
3
4 Copyright (c) 1999,2000,2001,2002,2007 Marcus Harnisch
5
6 Disclaimer
7 ==========
8
9 The text below hasn't really changed in ages and unless someone points
10 me to outdated or otherwise wrong information, I will not re-verify
11 the statements. What you find here is historic and may or may not have
12 any value to you. In particular statements about Sys::Syslog may be
13 completely outdated -- or not.
14
15 Introduction
16 ============
17
18 This Module provides access to the system logger available on most
19 UNIX system via Perl's XSUBs (Perl's C interface).
20
21 I wrote this module because of some features I missed in Sys::Syslog
22 (see FAQ below) and also to do my first steps into the secrets of
23 Perl's XSUBs.
24
25 Copyright and distribution
26 ==========================
27
28 This program is free software; you can redistribute it and/or modify
29 it under the terms of the Artistic License 2.0 (see file Artistic in
30 this directory).
31
32 Check clause (4) for your rights to distribute this software.
33
34 Installation
35 ============
36
37 Unix::Syslog is a Perl module that makes use of XSUBs and hence
38 requires a working C compiler and library. Execute the following
39 commands to install this package (`make test' prints the results of a
40 test suite. Execute `make install' only if the required tests finished
41 successfully or if you know what you are doing):
42
43 perl Makefile.PL
44 make test
45 make install
46
47 Notes about the test suite
48 ==========================
49
50 Some of the tests may fail because the respective constants are not
51 available on certain systems. You should be able to distinguish these
52 tests from those that fail because of a malfunction by carefully
53 reading the output of the test routines.
54
55 The tests that write messages to syslog cannot return a success status
56 since the underlying libc functions don't return appropriate
57 information. To verify that these tests work correctly, you should
58 configure syslogd so that the facility `local7' and priority `info'
59 will be written to a file.
60
61 OS dependent behaviour and portability
62 ======================================
63
64 This package uses system specific functions. Programs that uses this
65 package may not be portable in any case. If you plan to write portable
66 code using this package, please consult the manuals of the systems you
67 wish to run the software on. Then modify your program accordingly.
68
69 As of version 0.99 Unix::Syslog provides two functions priorityname()
70 and facilityname() that return the names of priority and facility,
71 respectively. This functionality is only enabled if an according
72 `#define' is enabled through Makefile.PL. By default this statement is
73 commented out.
74
75 Known bugs
76 ==========
77
78 OS Description Workaround
79 ---------------------------------------------------------------------------
80 Linux On systems using glibc2 (<= version 2.1), None possible.
81 setting the log mask has no effect.
82
83 Frequently Asked Questions
84 ==========================
85
86 1. What is the benefit of using this module instead of Sys::Syslog?
87
88 Sys::Syslog always opens a network connection to the syslog
89 service. At least on Linux systems this may lead to some
90 trouble, because
91
92 o Linux syslogd (from package sysklogd) does not listen to the
93 network by default. Most people working on stand-alone
94 machines (including me) didn't see any reason why to
95 enable this option. Others didn't enable it for security
96 reasons.
97
98 OS-independent, some sysadmins may run a firewall on
99 their network that blocks connections to port 514/udp.
100
101 o By default Linux syslogd doesn't forward messages which have
102 already already received from the network to other log
103 hosts. There are reasons not to enable this option
104 unless it is really necessary. Looping messages
105 resulting from a misconfiguration may break down your
106 (log-)system.
107
108 Peter Stamfest pointed out some other advantages of Unix::Syslog,
109 I didn't came across my self.
110
111 o LOG_PERROR works.
112
113 o works with perl -Tw without warnings and problems due to
114 tainted data as it is the case for Sys::Syslog in some
115 special applications. [Especially when running a script
116 as root]
117
118 2. Well, is there any reason to use Sys::Syslog any longer?
119
120 Yes! In contrary to Unix::Syslog, Sys::Syslog works even if
121 you don't have a syslog daemon running on your system as
122 long as you are connected to a log host via a network and
123 have access to the syslog.h header file of your log host to
124 generate the initial files for Sys::Syslog (see
125 Sys::Syslog(3) for details). Unix::Syslog only logs to your
126 local syslog daemon which in turn may be configured to
127 distribute the message over the network.
128
129 3. Are calls to the functions provided by Unix::Syslog compatible
130 to those of Sys::Syslog?
131
132 Currently not. Sys::Syslog requires strings to specify many
133 of the arguments to the functions, while Unix::Syslog uses
134 numeric constants accessed via macros as defined in
135 syslog.h. Although the strings used by Sys::Syslog are also
136 defined in syslog.h, it seems that most people got used to
137 the numeric arguments. I will implement the string based
138 calls if there are enough people ($min_people > 10**40)
139 complaining about the lack of compatibility.
140
141 Comments, Bug reports and Suggestions
142 =====================================
143
144 Please direct anything you wish to tell me about this package to the
145 address given below.
146
147 Have fun,
148 Marcus Harnisch <[email protected]>