From 22642968d3fd2566a6ff95ebc98f189f2e879a82 Mon Sep 17 00:00:00 2001 From: sperber Date: Mon, 11 Jun 2001 13:07:00 +0000 Subject: [PATCH] Very preliminary draft syslog documentation. --- doc/syslog.txt | 186 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 doc/syslog.txt diff --git a/doc/syslog.txt b/doc/syslog.txt new file mode 100644 index 0000000..28da2aa --- /dev/null +++ b/doc/syslog.txt @@ -0,0 +1,186 @@ +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.