The Syslog Interface
====================

This is an interface to the syslog facility of most Unix systems.  Its
interface differs significantly from that of the Unix library
functionality in order to support multiple simultaneous connections to
the syslog facility.

The functionality is in a structure called SYSLOG.

This documentation is very preliminary.  Consult the syslog(3) manpage
alongside this document.

Log Options
===========

(syslog-option syslog-option-name) -> syslog-option
(make-syslog-options list) -> syslog-options
(syslog-options syslog-option-name ...) -> syslog-options
(syslog-options->list syslog-options) -> list of syslog-option
(syslog-options-on? syslog-options syslog-options) -> boolean
(syslog-options=? syslog-options syslog-options) -> boolean
(syslog-options? x) -> boolean

Here is a list of possible names of syslog options:

console
  If syslog cannot pass the message to syslogd it will attempt to
  write the message to the console.

delay
  Delay opening the connection to syslogd immediately until the first
  message is logged.

no-delay
  Open the connection to syslogd immediately.  Normally
  the open is delayed until the first message is logged.
  Useful for programs that need to manage the order in which
  file descriptors are allocated.

NOTA BENE: The delay and no-delay options are included for
  completeness, but do not have the expected effect in the present
  Scheme interface: Because the Scheme interface has to multiplex
  multiple simultaneous connections to the syslog facility over a
  single one, open and close operations on that facility happen at
  unpredictable times.

standard-error
  Write the log messages to standard error output as well to the
  system log.

log-pid
  Log the process id with each message: useful for identifying
  instantiations of daemons.


Log Facilities
==============

(syslog-facility syslog-facility-name) -> syslog-facility)
(syslog-facility? x) -> boolean)
(syslog-facility=? syslog-facility syslog-facility)

Here is a list of possible names of syslog facilities:

authorization
  The authorization system: login, su, getty, etc.

cron
  The cron daemon.

daemon
  System daemons, such as routed, that are not provided for explicitly
  by other facilities.

kernel
  Messages generated by the kernel.

lpr
  The line printer spooling system: lpr, lpc, lpd, etc.

mail
  The mail system.

news
  The network news system.

user
  Messages generated by random user processes.

uucp
  The uucp system.

local0 local1 local2 local3 local4 local5 local6 local7
  Reserved for local use.

Log Levels
==========

Here is a list of possible names of syslog levels:

(syslog-level syslog-level-name) -> syslog-level
(syslog-level? x) -> boolean
(syslog-level=? syslog-level syslog-level) -> boolean

emergency
  A panic condition.  This is normally broadcast to all users.

alert
  A condition that should be corrected immediately, such as a
  corrupted system database.

critical
  Critical conditions, e.g., hard device errors.

error
  Errors.

warning
  Warning messages.

notice
  Conditions that are not error conditions, but should possibly be
  handled specially.

info
  Informational messages.

debug
  Messages that contain information normally of use only when
  debugging a program.

Log Masks
=========

Log masks can mask out syslog messages at any set of levels.  A log
mask is constructed from a set of levels.

(syslog-mask syslog-level-name ...) -> syslog-mask
(levels->syslog-mask list) -> syslog-mask
(syslog-mask->levels syslog-mask) -> list of syslog-level
syslog-mask-all: syslog-mask
(syslog-mask-upto syslog-level) -> syslog-mask
(syslog-mask-levels-on? syslog-mask syslog-mask) -> boolean
(syslog-mask? x) -> boolean
(syslog-mask=? syslog-mask syslog-mask) -> boolean

Logging
=======

(open-syslog-channel string syslog-options syslog-facility syslog-mask)
  -> syslog-channel
(close-syslog-channel syslog-channel)

These two create and destroy a connection to the syslog facility,
respectively.  The first argument will be prepended to every message.
The other arguments belong to the categories mentioned above.  Note
that it is not necessary to explicitly open a syslog channel to do
logging; there is an implicit syslog channel which is already open and
whose parameters can be bound dynamically with WITH-SYSLOG-DESTINATION
below.

(with-syslog-destination maybe-string
                         maybe-syslog-options
                         maybe-syslog-facility
                         maybe-syslog-mask
                         thunk) -> values

This dynamically binds parameters of the implicit syslog channel and
runs THUNK within those parameter bindings, returning what THUNK
returns.  Each of the parameters may be #f in which case the previous
values will be used.

(syslog level message)
(syslog level message channel)
(syslog level message maybe-string)
(syslog level message maybe-string maybe-syslog-options)
(syslog level message maybe-string maybe-syslog-options
                      maybe-syslog-facility)
(syslog level message maybe-string maybe-syslog-options
                      maybe-syslog-facility maybe-syslog-mask)

SYSLOG actually logs a message, either to an explicitly specified
syslog channel, or to the implicit syslog channel.  Each of the
parameters of the implicit channel can be explicitly specified as
well, overriding the parameters of the channel.