diff --git a/doc/scsh-manual/miscprocs.tex b/doc/scsh-manual/miscprocs.tex index 4c76e9b..ebf0a29 100644 --- a/doc/scsh-manual/miscprocs.tex +++ b/doc/scsh-manual/miscprocs.tex @@ -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: