mirror of
git://sourceware.org/git/glibc.git
synced 2025-03-19 13:40:59 +08:00
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>
This commit is contained in:
Ulrich Drepper
parent
bcad2c29c2
commit
d52b6462c9
13
ChangeLog
13
ChangeLog
@ -1,3 +1,16 @@
|
||||
2000-04-23 Ulrich Drepper <drepper@redhat.com>
|
||||
|
||||
* 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>
|
||||
|
||||
* nss/Makefile (libnss_db-dbs): Remove stry backslash.
|
||||
|
||||
@ -54,9 +54,9 @@ mkinstalldirs = $(..)scripts/mkinstalldirs
|
||||
chapters = $(addsuffix .texi, \
|
||||
intro errno memory ctype string charset locale \
|
||||
message search pattern io stdio llio filesys \
|
||||
pipe socket terminal math arith time resource \
|
||||
setjmp signal startup process job nss users \
|
||||
sysinfo conf crypt)
|
||||
pipe socket terminal syslog math arith time \
|
||||
resource setjmp signal startup process job nss \
|
||||
users sysinfo conf crypt)
|
||||
add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
|
||||
appendices = lang.texi header.texi install.texi maint.texi contrib.texi
|
||||
|
||||
|
||||
@ -27,7 +27,7 @@
|
||||
@end ifnottex
|
||||
@end ifclear
|
||||
|
||||
@node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
|
||||
@node Mathematics, Arithmetic, Syslog, Top
|
||||
@c %MENU% Math functions, useful constants, random numbers
|
||||
@chapter Mathematics
|
||||
|
||||
|
||||
477
manual/syslog.texi
Normal file
477
manual/syslog.texi
Normal file
@ -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
|
||||
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
@node Low-Level Terminal Interface, Mathematics, Sockets, Top
|
||||
@node Low-Level Terminal Interface, Syslog, Sockets, Top
|
||||
@c %MENU% How to change the characteristics of a terminal device
|
||||
@chapter Low-Level Terminal Interface
|
||||
|
||||
|
||||
@ -35,7 +35,7 @@ typedef __pid_t pid_t;
|
||||
#endif
|
||||
|
||||
/* These macros could also be defined int <stdlib.h>. */
|
||||
#ifndef _STDLIB_H
|
||||
#if !defined _STDLIB_H || !defined __USE_XOPEN
|
||||
/* This will define the `W*' macros for the flag
|
||||
bits to `waitpid', `wait3', and `wait4'. */
|
||||
# include <bits/waitflags.h>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user