% $Id: SYSLOG.TEX 1.1 2000/01/24 10:18:52 ska Exp ska $
\section{\label{sssyslog}\subsys{syslog}}

This subsystem offers an Unix-style \fct{syslog} capability, though,
because DOS is a non-multitasking environment, some limitations
are set.

No function of this subsystem is used by \subsys{debug}.

\subsection{Design}

In Unix the function \fct{syslog()} communicates with a daemon and
lets it write the message to the proper places. Provided that
the syslog daemon does not crash itself, this way is very stable and
gives the user a centralized way how to log messages.

In DOS a daemon would be implemented as a TSR, what would consume
conventional memory. The acceptance of such TSR would be rather small,
because it is the highest tendency in DOS to preserve memory.

Therefore this implementation of \fct{syslog()} formats the message,
and then passes it to a logfile itself. This limits the configuration
options known from Unix-syslogd, but DOS is not Unix, is it?

A short overview of the differences between the DOS and Unix-syslog:
\begin{itemize}
\item \fct{openlog()} {\em must} be called to enable \fct{syslog()}.
\item All messages are written into the file named \fnam{<appname>.LOG}
	in the current working directory, where \fnam{<appname>} is the
	filename of the executable of the current process -- the filename
	of \tok{argv[0]}.
\item The \tok{\quote{\%m}} token is not supported.
\item \tok{LOG\_CONS} and \tok{LOG\_NDELAY} are not implemented and
	are ignored.
\item Level and facility are ignored, because only one file is used to
	write the messages to. But they are included as a number.
\end{itemize}

\subsection{Implementation}

To call \fct{openlog()} is mandetory, but one call and intermix
\fct{closelog()} and \fct{openlog()} to open, close and reopen the
logfile any time. \fct{closelog()} must be called the same number of
times as \fct{openlog()}, in order to really close the logfile.

If the logfile was opened, closed and is to reopen, the new
messages are appended and do not erase prior messages; when the
logfile is opened the first time, any previously existing logfile
is truncated without user notice.

\fct{openlog()} calls the function \fct{appNameEx()} to aquire the
name of the current process and simply appends \fct{.LOG} to
generate the name of the logfile.

\subsubsections{Macros}

Flags passed as an ORed combination to \fct{openlog()}:
\begin{tabTS}
\fct{LOG\_CONS} & Write directly to system console -- {\bf not implemented,
	is silently ignored}. \\
\fct{LOG\_NDELAY} & Open the connection to syslogd immediately -- {\bf
	not implemented, is silently ignored}. \\
\fct{LOG\_PERROR} & Print to \tok{stderr} as well. \\
\fct{LOG\_PID} & Include the current PID with each message. \\
\fct{LOG\_NOTIME} & Do not prepend the current time -- {\bf
	unique to \suppl}. \\
\end{tabTS}

Facilities, cannot be combined:
\begin{tabTS}
\fct{LOG\_AUTH} & security/authorization  messages  (DEPRECATED   Use
              \tokfct{LOG\_AUTHPRIV} instead) \\
\fct{LOG\_AUTHPRIV} & security/authorization messages (private) \\
\fct{LOG\_CRON} & clock daemon (cron and at) \\
\fct{LOG\_DAEMON} & other system daemons \\
\fct{LOG\_KERN} & kernel messages \\
\fct{LOG\_LOCAL0} & reserved for local use \\
\fct{LOG\_LOCAL1} & reserved for local use \\
\fct{LOG\_LOCAL2} & reserved for local use \\
\fct{LOG\_LOCAL3} & reserved for local use \\
\fct{LOG\_LOCAL4} & reserved for local use \\
\fct{LOG\_LOCAL5} & reserved for local use \\
\fct{LOG\_LOCAL6} & reserved for local use \\
\fct{LOG\_LOCAL7} & reserved for local use \\
\fct{LOG\_LPR} & line printer subsystem \\
\fct{LOG\_MAIL} & mail subsystem \\
\fct{LOG\_NEWS} & USENET news subsystem \\
\fct{LOG\_SYSLOG} & messages generated internally by syslogd \\
\fct{LOG\_USER} & generic user-level messages \\
\fct{LOG\_UUCP} & UUCP subsystem \\
\end{tabTS}

Levels, can be ORed with facility to construct the priority:
\begin{tabTS}
\fct{LOG\_EMERG} & system is unusable \\
\fct{LOG\_ALERT} & action must be taken immediately \\
\fct{LOG\_CRIT} & critical conditions \\
\fct{LOG\_ERR} & error conditions \\
\fct{LOG\_WARNING} & warning conditions \\
\fct{LOG\_NOTICE} & normal, but significant, condition \\
\fct{LOG\_INFO} & informational message \\
\fct{LOG\_DEBUG} & debug-level message \\
\end{tabTS}

\subsubsection{Functions}

\begin{tabTS}
\fct{openlog} & Opens the logfile and enables \fct{syslog()}. \\
\fct{syslog} & Writes a message into the logfile. Ignored if
	the logfile is still closed. \\
\fct{syslogo} & If the logfile is still closed, \tok{openlog(0, 0, 0)}
	is called to open it. Then the message is written into the logfile. \\
\fct{syslogv} & \tok{<stdarg.h>}-variant of \fct{syslog()}. \\
\fct{closelog} & Closes the logfile, if it was called the same number
	of times as \fct{openlog()}. \\
\end{tabTS}
