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