       Unix::Syslog -- Perl interface to the UNIX system logger
       ========================================================

Copyright (C) 1999 Marcus Harnisch <marcus@harnisch.isdn.cs.tu-berlin.de>

Introduction
============

This Module provides access to the system logger available on most
UNIX system via Perl's XSUBs (Perl's C interface).

I wrote this module because of some features I missed in Sys:Syslog
(see FAQ below) and also to do my first steps into the secrets of
Perl's XSUBs.

Copyright and distribution
==========================

This program is free software; you can redistribute it and/or modify
it under the terms of the Artistic License. A copy of the license (see
file Artistic in this directory) must be included in the package.

Installation
============

Unix::Syslog is a Perl module that makes use of XSUBs and hence
requires a working C compiler and library. Execute the following
commands to install this package (`make test' prints the results of a
test suite. Execute `make install' only if the required tests finished
successfully or if you know what you are doing):

perl Makefile.PL
make test
make install

Note: Some tests may fail because the respective constants are not
available on certain systems. You should be able to distinguish these
tests from those that fail because of a malfunction by carefully
reading the output of the test routines.

OS dependent behaviour and portability
======================================

This package uses system specific functions. Programs that uses this
package may not be portable in any case. If you plan to write portable
code using this package, please consult the manuals of the systems you
wish to run the software on. Then modify your program accordingly.

Known bugs
==========

OS	Description				Workaround
---------------------------------------------------------------------------
Linux	On systems using glibc2, setting the    None possible.
	log mask does not change the behaviour
	of syslog() as expected until recent
	versions of glibc (> version 2.1)


Frequently Asked Questions
==========================

1. What is the benefit I get from using this module instead of
   Sys::Syslog?

   Sys::Syslog always opens a network connection to the syslog
   service. At least on Linux systems this leads into some trouble,
   because

   - Linux syslogd (from package sysklogd) does not listen to the
     network by default. Most people working on stand-alone machines
     (including me) don't see any reason to enable this option just to
     make a single application work. Others don't enable it for
     security reasons.

   - By default Linux syslogd doesn't forward messages to other log
     hosts which have already been received from the network. There
     are reasons not to enable this option unless it is really 
     neccessary. Looping messages resulting from a faulty
     configuration may break down your (log-)system.

   - The interface resembles that of the syslog(3) routines.

2. Is there any reason to use Sys:Syslog any longer?

   Yes! In contrary to Unix::Syslog, Sys::Syslog works even if you are
   not running a syslog daemon on your system as long as you are
   connected to a log host via a network and have access to the
   syslog.h header file of your log host to generate the header files
   for Sys::Syslog (see Sys::Syslog(3) for details). Unix::Syslog only
   logs to your local syslog daemon which in turn may be configured to
   distribute the message over the network.

3. Are calls to the functions provided by Unix::Syslog compatible to
   those of Sys::Syslog?

   Currently not. Sys::Syslog requires strings to specify many of the
   arguments to the functions, while Unix::Syslog uses numeric constants
   accessed via macros as defined in syslog.h. Although the strings
   used by Sys::Syslog are also defined in syslog.h, it seems that most
   people got used to the numeric arguments. I will implement
   the string based calls if there are enough people ($min_people >
   10**40) complaining about the lack of compatibility. However,
   patches are welcome.

Comments, Bug reports and Suggestions
=====================================

Please direct anything you wish to tell me about this package to the
address given below.

Have fun,
     Marcus Harnisch <marcus@harnisch.isdn.cs.tu-berlin.de>
