Update.

	* manual/Makefile (chapters): Add syslog.
	* manual/syslog.texi: New file.
	* manual/math.texi: Fix references.
	* manual/terminal.texi: Likewise.
	Patch by Bryan Henderson <bryanh@giraffe-data.com>.

2000-04-18  Jakub Jelinek  <jakub@redhat.com>

	* posix/sys/wait.h: Define __WAIT_STATUS and the like either if
	stdlib.h was not included or __USE_XOPEN not defined.

2000-04-23  Ulrich Drepper  <drepper@redhat.com>

1 files changed, 477 insertions, 0 deletions

diff --git a/manual/syslog.texi b/manual/syslog.texi
new file mode 100644
index 0000000000..4c190d3239
--- /dev/null
+++ b/manual/syslog.texi
@@ -0,0 +1,477 @@
+@node Syslog, Mathematics, Low-Level Terminal Interface, Top
+@c %MENU% System logging and messaging
+@chapter Syslog
+
+
+This chapter describes facilities for issuing and logging messages of
+system administration interest.  This chapter has nothing to do with
+programs issuing messages to their own users or keeping private logs
+(One would typically do that with the facilities described in
+@ref{I/O on Streams}).
+
+Most systems have a facility called ``Syslog'' that allows programs to
+submit messages of interest to system administrators and can be
+configured to pass these messages on in various ways, such as printing
+on the console, mailing to a particular person, or recording in a log
+file for future reference.
+
+A program uses the facilities in this chapter to submit such messages.
+
+@menu
+* Overview of Syslog::           Overview of a system's Syslog facility
+* Submitting Syslog Messages::   Functions to submit messages to Syslog
+@end menu
+
+@node Overview of Syslog
+@section Overview of Syslog
+
+System administrators have to deal with lots of different kinds of
+messages from a plethora of subsystems within each system, and usually
+lots of systems as well.  For example, an FTP server might report every
+connection it gets.  The kernel might report hardware failures on a disk
+drive.  A DNS server might report usage statistics at regular intervals.
+
+Some of these messages need to be brought to a system administrator's
+attention immediately.  And it may not be just any system administrator
+-- there may be a particular system administrator who deals with a
+particular kind of message.  Other messages just need to be recorded for
+future reference if there is a problem.  Still others may need to have
+information extracted from them by an automated process that generates
+monthly reports.
+
+To deal with these messages, most Unix systems have a facility called
+"Syslog."  It is generally based on a daemon called ``Syslogd''
+Syslogd listens for messages on a Unix domain socket named
+@file{/dev/log}.  Based on classification information in the messages
+and its configuration file (usually @file{/etc/syslog.conf}), Syslogd
+routes them in various ways.  Some of the popular routings are:
+
+@itemize @bullet
+@item
+Write to the system console
+@item
+Mail to a specific user
+@item
+Write to a log file
+@item
+Pass to another daemon
+@item
+Discard
+@end itemize
+
+Syslogd can also handle messages from other systems.  It listens on the 
+@code{syslog} UDP port as well as the local socket for messages.
+
+Syslog can handle messages from the kernel itself.  But the kernel
+doesn't write to @file{/dev/log}; rather, another daemon (sometimes
+called ``Klogd'') extracts messages from the kernel and passes them on to
+Syslog as any other process would (and it properly identifies them as
+messages from the kernel).
+
+Syslog can even handle messages that the kernel issued before Syslogd or
+Klogd was running.  A Linux kernel, for example, stores startup messages
+in a kernel message ring and they are normally still there when Klogd
+later starts up.  Assuming Syslogd is running by the time Klogd starts,
+Klogd then passes everything in the message ring to it.
+
+In order to classify messages for disposition, Syslog requires any process
+that submits a message to it to provide two pieces of classification
+information with it:
+
+@table @asis
+@item facility
+This identifies who submitted the message.  There are a small number of
+facilities defined.  The kernel, the mail subsystem, and an FTP server
+are examples of recognized facilities.  For the complete list,
+@xref{syslog; vsyslog}.  Keep in mind that these are
+essentially arbitrary classifications.  "Mail subsystem" doesn't have any
+more meaning than the system administrator gives to it.
+
+@item priority
+This tells how important the content of the message is.  Examples of
+defined priority values are: debug, informational, warning, critical.
+For the complete list, @xref{syslog; vsyslog}.  Except for
+the fact that the priorities have a defined order, the meaning of each
+of these priorities is entirely determined by the system administrator.
+
+@end table
+
+A ``facility/priority'' is a number that indicates both the facility
+and the priority.
+
+@strong{Warning:} This terminology is not universal.  Some people use
+``level'' to refer to the priority and ``priority'' to refer to the
+combination of facility and priority.  A Linux kernel has a concept of a
+message ``level,'' which corresponds both to a Syslog priority and to a
+Syslog facility/priority (It can be both because the facility code for
+the kernel is zero, and that makes priority and facility/priority the
+same value).
+
+The GNU C library provides functions to submit messages to Syslog.  They
+do it by writing to the @file{/dev/log} socket.  @xref{Submitting Syslog
+Messages}.
+
+The GNU C library functions only work to submit messages to the Syslog
+facility on the same system.  To submit a message to the Syslog facility
+on another system, use the socket I/O functions to write a UDP datagram
+to the @code{syslog} UDP port on that system.  @xref{Sockets}.
+
+
+@node Submitting Syslog Messages
+@section Submitting Syslog Messages
+
+The GNU C library provides functions to submit messages to the Syslog
+facility:
+
+@menu
+* openlog::                      Open connection to Syslog
+* syslog; vsyslog::              Submit message to Syslog
+* closelog::                     Close connection to Syslog
+* setlogmask::                   Cause certain messages to be ignored
+* Syslog Example::               Example of all of the above
+@end menu
+
+These functions only work to submit messages to the Syslog facility on
+the same system.  To submit a message to the Syslog facility on another
+system, use the socket I/O functions to write a UDP datagram to the
+@code{syslog} UDP port on that system.  @xref{Sockets}.
+
+
+
+@node openlog
+@subsection openlog
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@comment syslog.h
+@comment BSD
+@deftypefun void openlog (char *@var{ident}, int @var{option},
+        int @var{facility})
+
+@code{openlog} opens or reopens a connection to Syslog in preparation
+for submitting messages.
+
+@var{ident} is an arbitrary identification string which future
+@code{syslog} invocations will prefix to each message.  This is intended
+to identify the source of the message, and people conventionally set it
+to the name of the program that will submit the messages.
+
+@code{openlog} may or may not open the @file{/dev/log} socket, depending
+on @var{option}.  If it does, it tries to open it and connect it as a 
+stream socket.  If that doesn't work, it tries to open it and connect it
+as a datagram socket.  The socket has the ``Close on Exec'' attribute,
+so the kernel will close it if the process performs an exec.
+
+You don't have to use @code{openlog}.  If you call @code{syslog} without
+having called @code{openlog}, @code{syslog} just opens the connection
+implicitly and uses defaults for the information in @var{ident} and
+@var{options}.  
+
+@var{options} is a bit string, with the bits as defined by the following
+single bit masks:
+
+@table @code
+@item LOG_PERROR
+If on, @code{openlog} sets up the connection so that any @code{syslog}
+on this connection writes its message to the calling process' Standard
+Error stream in addition to submitting it to Syslog.  If off, @code{syslog}
+does not write the message to Standard Error.
+
+@item LOG_CONS
+If on, @code{openlog} sets up the connection so that a @code{syslog} on
+this connection that fails to submit a message to Syslog writes the
+message instead to system console.  If off, @code{syslog} does not write
+to the system console (but of course Syslog may write messages it
+receives to the console).
+
+@item LOG_PID
+When on, @code{openlog} sets up the connection so that a @code{syslog}
+on this connection inserts the calling process' Process ID (PID) into
+the message.  When off, @code{openlog} does not insert the PID.
+
+@item LOG_NDELAY
+When on, @code{openlog} opens and connects the @file{/dev/log} socket.
+When off, a future @code{syslog} call must open and connect the socket.
+
+@strong{Portability note:}  In early systems, the sense of this bit was
+exactly the opposite.
+
+@item LOG_ODELAY
+This bit does nothing.  It exists for backward compatibility.
+
+@end table
+
+If any other bit in @var{options} is on, the result is undefined.
+
+@var{facility} is the default facility code for this connection.  A
+@code{syslog} on this connection that specifies default facility causes
+this facility to be associated with the message.  See @code{syslog} for
+possible values.  A value of zero means the default default, which is
+@code{LOG_USER}.
+
+If a Syslog connection is already open when you call @code{openlog},
+@code{openlog} ``reopens'' the connection.  Reopening is like opening
+except that if you specify zero for the default facility code, the
+default facility code simply remains unchanged and if you specify
+LOG_NDELAY and the socket is already open and connected, @code{openlog}
+just leaves it that way.
+
+@c There is a bug in closelog() (glibc 2.1.3) wherein it does not reset the
+@c default log facility to LOG_USER, which means the default default log
+@c facility could be whatever the default log facility was for a previous
+@c Syslog connection.  I have documented what the function should be rather
+@c than what it is because I think if anyone ever gets concerned, the code
+@c will change.
+
+@end deftypefun
+
+
+@node syslog; vsyslog
+@subsection syslog, vsyslog
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@c syslog() is implemented as a call to vsyslog().
+@comment syslog.h
+@comment BSD
+@deftypefun void syslog (int @var{facility_priority}, char *@var{format}, ...)
+
+@code{syslog} submits a message to the Syslog facility.  It does this by
+writing to the Unix domain socket @code{/dev/log}.
+
+@code{syslog} submits the message with the facility and priority indicated
+by @var{facility_priority}.  The macro @code{LOG_MAKEPRI} generates a
+facility/priority from a facility and a priority, as in the following 
+example:
+
+@smallexample
+LOG_MAKEPRI(LOG_USER, LOG_WARNING)
+@end smallexample
+
+The possible values for the facility code are (macros):
+
+@c Internally, there is also LOG_KERN, but LOG_KERN == 0, which means
+@c if you try to use it here, just selects default.
+
+@table @code
+@item LOG_USER
+A miscellaneous user process
+@item LOG_MAIL
+Mail
+@item LOG_DAEMON
+A miscellaneous system daemon
+@item LOG_AUTH
+Security (authorization)
+@item LOG_SYSLOG
+Syslog
+@item LOG_LPR
+Central printer
+@item LOG_NEWS
+Network news (e.g. Usenet)
+@item LOG_UUCP
+UUCP
+@item LOG_CRON
+Cron and At
+@item LOG_AUTHPRIV
+Private security (authorization)
+@item LOG_FTP
+Ftp server
+@item LOG_LOCAL0
+Locally defined
+@item LOG_LOCAL1
+Locally defined
+@item LOG_LOCAL2
+Locally defined
+@item LOG_LOCAL3
+Locally defined
+@item LOG_LOCAL4
+Locally defined
+@item LOG_LOCAL5
+Locally defined
+@item LOG_LOCAL6
+Locally defined
+@item LOG_LOCAL7
+Locally defined
+@end table
+
+Results are undefined if the facility code is anything else.
+
+@strong{note:} Syslog recognizes one other facility code: that of the
+kernel.  But you can't specify that facility code with these functions.
+If you try, it looks the same to @code{syslog} as if you are requesting
+the default facility.  But you wouldn't want to anyway, because any
+program that uses the GNU C library is not the kernel.
+
+You can use just a priority code as @var{facility_priority}.  In that
+case, @code{syslog} assumes the default facility established when the
+Syslog connection was opened.  @xref{Syslog Example}.
+
+The possible values for the priority code are (macros):
+
+@table @code
+@item LOG_EMERG
+The message says the system is unusable.
+@item LOG_ALERT
+Action on the message must be taken immediately.
+@item LOG_CRIT
+The message states a critical condition.
+@item LOG_ERR
+The message describes an error.
+@item LOG_WARNING
+The message is a warning.
+@item LOG_NOTICE
+The message describes a normal but important event.
+@item LOG_INFO
+The message is purely informational.
+@item LOG_DEBUG
+The message is only for debugging purposes.
+@end table
+
+Results are undefined if the priority code is anything else.
+
+If the process does not presently have a Syslog connection open (i.e.
+it did not call @code{openlog}), @code{syslog} implicitly opens the
+connection the same as @code{openlog} would, with the following defaults
+for information that would otherwise be included in an @code{openlog}
+call: The default identification string is the program name.  The
+default default facility is @code{LOG_USER}.  The default for all the
+connection options in @var{options} is as if those bits were off.
+@code{syslog} leaves the Syslog connection open.
+
+If the @file{dev/log} socket is not open and connected, @code{syslog}
+opens and connects it, the same as @code{openlog} with the
+@code{LOG_NDELAY} option would.
+
+@code{syslog} leaves @file{/dev/log} open and connected unless its attempt
+to send the message failed, in which case @code{syslog} closes it (with the
+hope that a future implicit open will restore the Syslog connection to a
+usable state).
+
+Example:
+
+@smallexample
+
+#include <syslog.h>
+syslog(LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR), 
+       "Unable to make network connection to %s.  Error=%m", host);
+
+@end smallexample
+
+@end deftypefun
+
+
+@comment syslog.h
+@comment BSD
+@deftypefun void vsyslog (int @var{facility_priority}, char *@var{format},
+         __gnuc_va_list arglist)
+
+This is functionally identical to @code{syslog}, with the BSD style variable
+length argument.
+
+@end deftypefun
+
+
+@node closelog
+@subsection closelog
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@comment syslog.h
+@comment BSD
+@deftypefun void closelog ()
+
+@code{closelog} closes the current Syslog connection, if there is one.
+This include closing the @file{dev/log} socket, if it is open.
+
+There is very little reason to use this function.  It does not flush any
+buffers; you can reopen a Syslog connection without closing it first;
+The connection gets closed automatically on exec or exit.
+@code{closelog} has primarily aesthetic value.
+
+@end deftypefun
+
+
+@node setlogmask
+@subsection setlogmask
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@comment syslog.h
+@comment BSD
+@deftypefun int setlogmask (int @var{mask})
+
+@code{setlogmask} sets a mask (the ``logmask'') that determines which
+future @code{syslog} calls shall be ignored.  If a program has not
+called @code{setlogmask}, @code{syslog} doesn't ignore any calls.  You
+can use @code{setlogmask} to specify that messages of particular
+priorities shall be ignored in the future.
+
+A @code{setlogmask} call overrides any previous @code{setlogmask} call.
+
+Note that the logmask exists entirely independently of opening and
+closing of Syslog connections.
+
+Setting the logmask has a similar effect to, but is not the same as,
+configuring Syslog.  The Syslog configuration may cause Syslog to
+discard certain messages it receives, but the logmask causes certain
+messages never to get submitted to Syslog in the first place.
+
+@var{mask} is a bit string with one bit corresponding to each of the
+possible message priorities.  If the bit is on, @code{syslog} handles
+messages of that priority normally.  If it is off, @code{syslog}
+discards messages of that priority.  Use the message priority macros
+described in @ref{syslog; vsyslog} and the @code{LOG_MASK} to construct
+an appropriate @var{mask} value, as in this example:
+
+@smallexample
+LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR)
+@end smallexample
+
+or
+
+@smallexample
+~(LOG_MASK(LOG_INFO))
+@end smallexample
+
+There is also a @code{LOG_UPTO} macro, which generates a mask with the bits
+on for a certain priority and all priorities above it:
+
+@smallexample
+LOG_UPTO(LOG_ERROR)
+@end smallexample
+
+The unfortunate naming of the macro is due to the fact that internally, 
+higher numbers are used for lower message priorities.
+
+@end deftypefun
+
+
+@node Syslog Example
+@subsection Syslog Example
+
+Here is an example of @code{openlog}, @code{syslog}, and @code{closelog}:
+
+This example sets the logmask so that debug and informational messages
+get discarded without ever reaching Syslog.  So the second @code{syslog}
+in the example does nothing.
+
+@smallexample
+#include <syslog.h>
+
+setlogmask(LOG_UPTO(LOG_NOTICE));
+
+openlog("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
+
+syslog(LOG_NOTICE, "Program started by User %d", getuid());
+syslog(LOG_INFO, "A tree falls in a forest");
+
+closelog();
+
+@end smallexample
+
+
+