Very preliminary draft syslog documentation.

2001-06-11 13:07:00 +00:00 · 2001-06-11 13:07:00 +00:00 · 22642968d3
parent 98de22054e
commit 22642968d3
1 changed files with 186 additions and 0 deletions
--- a/doc/syslog.txt
+++ 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.