Add syslog documentation.
This commit is contained in:
sperber
parent
cb16f9966d
commit
dbf8eb6edf
|
|
@ -94,3 +94,252 @@ The \ex{with-dot-lock} special form is equivalent syntactic sugar.
|
|||
|
||||
|
||||
|
||||
\section{Syslog facility}
|
||||
\label{syslog-facility}
|
||||
|
||||
The procedures in this section provide access to the 4.2BSD syslog
|
||||
facility present in most POSIX systems. The functionality is in a
|
||||
structure called \ex{syslog}. There's an additional structure
|
||||
\ex{syslog-channels} documented below. The scsh interface to
|
||||
the syslog facility differs significantly from that of the Unix
|
||||
library functionality in order to support multiple simultaneous
|
||||
connections to the syslog facility.
|
||||
|
||||
Log messages carry a variety of parameters beside the text of the
|
||||
message itself, namely a set of options controlling the output format
|
||||
and destination, the facility identifying the class of programs the
|
||||
message is coming from, an identifier specifying the conrete program,
|
||||
and the level identifying the importance of the message. Moreover, a
|
||||
log mask can prevent messages at certain levels to be actually sent to
|
||||
the syslog daemon.
|
||||
|
||||
\subsection*{Log options}
|
||||
|
||||
A log option specifies details of the I/O behavior of the syslog
|
||||
facility. A syslog option is an element of a finite type (see
|
||||
the \scm~manual) constructed by the
|
||||
\ex{syslog-option} macro. The syslog facility works with sets of
|
||||
options which are represented as enum sets (see
|
||||
the \scm~manual).
|
||||
|
||||
\dfn{syslog-option}{option-name}{option}{syntax}
|
||||
|
||||
\defun{syslog-option?}{x}{boolean}
|
||||
|
||||
\defun{make-syslog-options}{list}{options}
|
||||
|
||||
\dfn{syslog-options}{option-name \ldots}{options}{syntax}
|
||||
|
||||
\defun{syslog-options?}{x}{boolean}
|
||||
|
||||
\begin{desc}
|
||||
\ex{Syslog-option} constructs a log option from the name of an
|
||||
option. (The possible names are listed below.) \ex{Syslog-option?}
|
||||
is a predicate for log options. Options are comparable using
|
||||
\ex{eq?}. \ex{Make-syslog-options} constructs a set of options
|
||||
from a list of options. \ex{Syslog-options} is a macro which
|
||||
expands into an expression returning a set of options from names.
|
||||
\ex{Syslog-options?} is a predicate for sets of options.
|
||||
\end{desc}
|
||||
%
|
||||
Here is a list of possible names of syslog options:
|
||||
|
||||
\begin{description}
|
||||
\item[\ex{console}]
|
||||
If syslog cannot pass the message to syslogd it will attempt to
|
||||
write the message to the console.
|
||||
|
||||
\item[\ex{delay}]
|
||||
Delay opening the connection to syslogd immediately until the first
|
||||
message is logged.
|
||||
|
||||
\item[\ex{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.
|
||||
|
||||
\noindent\textbf{NOTA BENE:}
|
||||
The \ex{delay} and \ex{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.
|
||||
|
||||
\item[\ex{log-pid}]
|
||||
Log the process id with each message: useful for identifying
|
||||
instantiations of daemons.
|
||||
\end{description}
|
||||
|
||||
\subsection*{Log facilities}
|
||||
|
||||
A log facility identifies the originator of a log message from a
|
||||
finite set known to the system. Each originator is identified by a
|
||||
name:
|
||||
|
||||
\dfn{syslog-facility}{facility-name}{facility}{syntax}
|
||||
\defun{syslog-facility?}{x}{boolean}
|
||||
|
||||
\begin{desc}
|
||||
\ex{Syslog-facility} is macro that expands into an expression
|
||||
returning a facility for a given name. \ex{Syslog-facility?} is a
|
||||
predicate for facilities. Facilities are comparable via \ex{eq?}.
|
||||
\end{desc}
|
||||
%
|
||||
Here is a list of possible names of syslog facilities:
|
||||
|
||||
\begin{description}
|
||||
\item[\ex{authorization}]
|
||||
The authorization system: login, su, getty, etc.
|
||||
|
||||
\item[\ex{cron}]
|
||||
The cron daemon.
|
||||
|
||||
\item[\ex{daemon}]
|
||||
System daemons, such as routed, that are not provided for explicitly
|
||||
by other facilities.
|
||||
|
||||
\item[\ex{kernel}]
|
||||
Messages generated by the kernel.
|
||||
|
||||
\item[\ex{lpr}]
|
||||
The line printer spooling system: lpr, lpc, lpd, etc.
|
||||
|
||||
\item[\ex{mail}]
|
||||
The mail system.
|
||||
|
||||
\item[\ex{news}]
|
||||
The network news system.
|
||||
|
||||
\item[\ex{user}]
|
||||
Messages generated by random user processes.
|
||||
|
||||
\item[\ex{uucp}]
|
||||
The uucp system.
|
||||
|
||||
\item[\ex{local0} \ex{local1} \ex{local2} \ex{local3} \ex{local4} \ex{local5} \ex{local6} \ex{local7}]
|
||||
Reserved for local use.
|
||||
\end{description}
|
||||
|
||||
\subsection*{Log levels}
|
||||
|
||||
A log level identifies the importance of a message from a fixed set
|
||||
of possible levels.
|
||||
|
||||
\dfn{syslog-level}{level-name}{level}{syntax}
|
||||
\defun{syslog-level?}{x}{boolean}
|
||||
%
|
||||
\begin{desc}
|
||||
\ex{Syslog-level} is macro that expands into an expression returning
|
||||
a facility for a given name. \ex{Syslog-level?} is a predicate for
|
||||
facilities. Levels are comparable via \ex{eq?}.
|
||||
\end{desc}
|
||||
%
|
||||
Here is a list of possible names of syslog levels:
|
||||
|
||||
\begin{description}
|
||||
\item[\ex{emergency}]
|
||||
A panic condition. This is normally broadcast to all users.
|
||||
|
||||
\item[\ex{alert}]
|
||||
A condition that should be corrected immediately, such as a
|
||||
corrupted system database.
|
||||
|
||||
\item[\ex{critical}]
|
||||
Critical conditions, e.g., hard device errors.
|
||||
|
||||
\item[\ex{error}]
|
||||
Errors.
|
||||
|
||||
\item[\ex{warning}]
|
||||
Warning messages.
|
||||
|
||||
\item[\ex{notice}]
|
||||
Conditions that are not error conditions, but should possibly be
|
||||
handled specially.
|
||||
|
||||
\item[\ex{info}]
|
||||
Informational messages.
|
||||
|
||||
\item[\ex{debug}]
|
||||
Messages that contain information normally of use only when
|
||||
debugging a program.
|
||||
\end{description}
|
||||
|
||||
\subsection*{Log masks}
|
||||
|
||||
A log masks can mask out log messages at a set of levels. A log
|
||||
mask is an enum set of log levels.
|
||||
|
||||
\defun{make-syslog-mask}{list}{mask}
|
||||
\dfn{syslog-mask}{level-name \ldots}{mask}{syntax}
|
||||
\defvar{syslog-mask-all}{mask}
|
||||
\defun{syslog-mask-upto}{level}{mask}
|
||||
\defun{syslog-mask?}{x}{boolean}
|
||||
|
||||
\begin{desc}
|
||||
\ex{Make-syslog-mask} constructs a mask from a list of levels.
|
||||
\ex{Syslog-mask} is a macro which constructs a mask from names of
|
||||
levels. \ex{Syslog-mask-all} is a predefined log mask containing
|
||||
all levels. \ex{Syslog-mask-upto} returns a mask consisting of all
|
||||
levels up to and including a certain level, starting with
|
||||
\ex{emergency}.
|
||||
\end{desc}
|
||||
|
||||
\subsection*{Logging}
|
||||
|
||||
Scheme~48 dynamically maintains implicit connections to the syslog
|
||||
facility specifying a current identifier, current options, a current
|
||||
facility and a current log mask. This implicit connection is held in
|
||||
a thread fluid (see
|
||||
Section~\ref{sec:ps_interac}). Hence, every thread
|
||||
maintains it own implicit connection to syslog. Note that the
|
||||
connection is not implicitly preserved across a \ex{spawn}, but it
|
||||
is preserved across a \ex{fork-thread}:
|
||||
|
||||
|
||||
\defun{with-syslog-destination}{string options facility mask thunk}{value}
|
||||
\defun{set-syslog-destination!}{string options facility mask}{undefined}
|
||||
%
|
||||
\begin{desc}
|
||||
\ex{With-syslog-destination} dynamically binds parameters of the
|
||||
implicit connection to the syslog facility and runs \var{thunk}
|
||||
within those parameter bindings, returning what \var{thunk}
|
||||
returns. Each of the parameters may be \ex{\#f} in which case the
|
||||
previous values will be used. \ex{Set-syslog-destination!} sets the
|
||||
parameters of the implicit connection of the current thread.
|
||||
\end{desc}
|
||||
|
||||
\defun{syslog}{level message}{undefined}
|
||||
\defun{syslog}{level message [string options syslog-facility]}{undefined}
|
||||
%
|
||||
\begin{desc}
|
||||
\ex{Syslog} actually logs a message. Each of the parameters of the
|
||||
implicit connection (except for the log mask) can be explicitly
|
||||
specified as well for the current call to \ex{syslog}, overriding
|
||||
the parameters of the channel. The parameters revert to their
|
||||
original values after the call.
|
||||
\end{desc}
|
||||
|
||||
\subsection*{Syslog channels}
|
||||
%
|
||||
The \ex{syslog-channels} structure allows direct manipulation of
|
||||
syslog channels, the objects that represent connections to the syslog
|
||||
facility. Note that it is
|
||||
not necessary to explicitly open a syslog channel to do logging.
|
||||
|
||||
\defun{open-syslog-channel}{string options facility mask}{channel}
|
||||
\defun{close-syslog-channel}{channel}{undefined}
|
||||
\defun{syslog}{level message channel}{undefined}
|
||||
%
|
||||
\begin{desc}
|
||||
\ex{Open-syslog-channel} and \ex{close-syslog-channel} create and
|
||||
destroy a connection to the syslog facility, respectively. The
|
||||
specified form of calling \ex{syslog} logs to the specified channel.
|
||||
\end{desc}
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "man"
|
||||
%%% End:
|
||||
|
|
|
|||
Loading…
Reference in New Issue