mirror of https://github.com/mkerrisk/man-pages
311 lines
7.1 KiB
Groff
311 lines
7.1 KiB
Groff
.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com)
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" Updated 1999.12.19 by Karl M. Hegbloom <karlheg@debian.org>
|
|
.\"
|
|
.\" Updated 13 Oct 2001, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added description of vsyslog
|
|
.\" Added descriptions of LOG_ODELAY and LOG_NOWAIT
|
|
.\" Added brief description of facility and option arguments
|
|
.\" Added CONFORMING TO section
|
|
.\" 2001-10-13, aeb, minor changes
|
|
.\" Modified 13 Dec 2001, Martin Schulze <joey@infodrom.org>
|
|
.\" Modified 3 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.TH SYSLOG 3 2007-07-26 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
closelog, openlog, syslog, vsyslog \- send messages to the system logger
|
|
.SH SYNOPSIS
|
|
.B #include <syslog.h>
|
|
.sp
|
|
.BI "void openlog(const char *" ident ", int " option ", int " facility );
|
|
.br
|
|
.BI "void syslog(int " priority ", const char *" format ", ...);"
|
|
.br
|
|
.B "void closelog(void);"
|
|
.sp
|
|
.B #include <stdarg.h>
|
|
.sp
|
|
.BI "void vsyslog(int " priority ", const char *" format ", va_list " ap );
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR vsyslog ():
|
|
_BSD_SOURCE
|
|
.SH DESCRIPTION
|
|
.BR closelog ()
|
|
closes the descriptor being used to write to the system logger.
|
|
The use of
|
|
.BR closelog ()
|
|
is optional.
|
|
.sp
|
|
.BR openlog ()
|
|
opens a connection to the system logger for a program.
|
|
The string pointed to by
|
|
.I ident
|
|
is prepended to every message, and is typically set to the program name.
|
|
The
|
|
.I option
|
|
argument specifies flags which control the operation of
|
|
.BR openlog ()
|
|
and subsequent calls to
|
|
.BR syslog ().
|
|
The
|
|
.I facility
|
|
argument establishes a default to be used if
|
|
none is specified in subsequent calls to
|
|
.BR syslog ().
|
|
Values for
|
|
.I option
|
|
and
|
|
.I facility
|
|
are given below.
|
|
The use of
|
|
.BR openlog ()
|
|
is optional; it will automatically be called by
|
|
.BR syslog ()
|
|
if necessary, in which case
|
|
.I ident
|
|
will default to NULL.
|
|
.sp
|
|
.BR syslog ()
|
|
generates a log message, which will be distributed by
|
|
.BR syslogd (8).
|
|
The
|
|
.I priority
|
|
argument is formed by ORing the
|
|
.I facility
|
|
and the
|
|
.I level
|
|
values (explained below).
|
|
The remaining arguments
|
|
are a
|
|
.IR format ,
|
|
as in
|
|
.BR printf (3)
|
|
and any arguments required by the
|
|
.IR format ,
|
|
except that the two character sequence
|
|
.B %m
|
|
will be replaced by
|
|
the error message string
|
|
.IR strerror ( errno ).
|
|
A trailing newline may be added if needed.
|
|
|
|
The function
|
|
.BR vsyslog ()
|
|
performs the same task as
|
|
.BR syslog ()
|
|
with the difference that it takes a set of arguments which have
|
|
been obtained using the
|
|
.BR stdarg (3)
|
|
variable argument list macros.
|
|
|
|
The subsections below lists the parameters used to set the values of
|
|
.IR option , " facility" ", and " priority .
|
|
.SS option
|
|
The
|
|
.I option
|
|
argument to
|
|
.BR openlog ()
|
|
is an OR of any of these:
|
|
.TP
|
|
.B LOG_CONS
|
|
Write directly to system console if there is an error while sending to
|
|
system logger.
|
|
.TP
|
|
.B LOG_NDELAY
|
|
Open the connection immediately (normally, the connection is opened when
|
|
the first message is logged).
|
|
.TP
|
|
.B LOG_NOWAIT
|
|
Don't wait for child processes that may have been created while logging
|
|
the message.
|
|
(The GNU C library does not create a child process, so this
|
|
option has no effect on Linux.)
|
|
.TP
|
|
.B LOG_ODELAY
|
|
The converse of
|
|
.BR LOG_NDELAY ;
|
|
opening of the connection is delayed until
|
|
.BR syslog ()
|
|
is called.
|
|
(This is the default, and need not be specified.)
|
|
.TP
|
|
.B LOG_PERROR
|
|
(Not in POSIX.1-2001.)
|
|
Print to \fIstderr\fP as well.
|
|
.TP
|
|
.B LOG_PID
|
|
Include PID with each message.
|
|
.SS facility
|
|
The
|
|
.I facility
|
|
argument is used to specify what type of program is logging the message.
|
|
This lets the configuration file specify that messages from different
|
|
facilities will be handled differently.
|
|
.TP
|
|
.B LOG_AUTH
|
|
security/authorization messages (DEPRECATED Use
|
|
.B LOG_AUTHPRIV
|
|
instead)
|
|
.TP
|
|
.B LOG_AUTHPRIV
|
|
security/authorization messages (private)
|
|
.TP
|
|
.B LOG_CRON
|
|
clock daemon
|
|
.RB ( cron " and " at )
|
|
.TP
|
|
.B LOG_DAEMON
|
|
system daemons without separate facility value
|
|
.TP
|
|
.B LOG_FTP
|
|
ftp daemon
|
|
.TP
|
|
.B LOG_KERN
|
|
kernel messages
|
|
.TP
|
|
.BR LOG_LOCAL0 " through " LOG_LOCAL7
|
|
reserved for local use
|
|
.TP
|
|
.B LOG_LPR
|
|
line printer subsystem
|
|
.TP
|
|
.B LOG_MAIL
|
|
mail subsystem
|
|
.TP
|
|
.B LOG_NEWS
|
|
USENET news subsystem
|
|
.TP
|
|
.B LOG_SYSLOG
|
|
messages generated internally by
|
|
.BR syslogd (8)
|
|
.TP
|
|
.BR LOG_USER " (default)"
|
|
generic user-level messages
|
|
.TP
|
|
.B LOG_UUCP
|
|
UUCP subsystem
|
|
.SS level
|
|
This determines the importance of the message.
|
|
The levels are, in order of decreasing importance:
|
|
.TP
|
|
.B LOG_EMERG
|
|
system is unusable
|
|
.TP
|
|
.B LOG_ALERT
|
|
action must be taken immediately
|
|
.TP
|
|
.B LOG_CRIT
|
|
critical conditions
|
|
.TP
|
|
.B LOG_ERR
|
|
error conditions
|
|
.TP
|
|
.B LOG_WARNING
|
|
warning conditions
|
|
.TP
|
|
.B LOG_NOTICE
|
|
normal, but significant, condition
|
|
.TP
|
|
.B LOG_INFO
|
|
informational message
|
|
.TP
|
|
.B LOG_DEBUG
|
|
debug-level message
|
|
.LP
|
|
The function
|
|
.BR setlogmask (3)
|
|
can be used to restrict logging to specified levels only.
|
|
.SH "CONFORMING TO"
|
|
The functions
|
|
.BR openlog (),
|
|
.BR closelog (),
|
|
and
|
|
.BR syslog ()
|
|
(but not
|
|
.BR vsyslog ())
|
|
are specified in SUSv2 and POSIX.1-2001.
|
|
POSIX.1-2001 specifies only the
|
|
.B LOG_USER
|
|
and
|
|
.B LOG_LOCAL*
|
|
values for
|
|
.IR facility .
|
|
However, with the exception of
|
|
.B LOG_AUTHPRIV
|
|
and
|
|
.BR LOG_FTP ,
|
|
the other
|
|
.I facility
|
|
values appear on most Unix systems.
|
|
The
|
|
.B LOG_PERROR
|
|
value for
|
|
.I option
|
|
is not specified by POSIX.1-2001, but is available
|
|
in most versions of Unix.
|
|
.\" .SH HISTORY
|
|
.\" A
|
|
.\" .BR syslog ()
|
|
.\" function call appeared in 4.2BSD.
|
|
.\" 4.3BSD documents
|
|
.\" .BR openlog (),
|
|
.\" .BR syslog (),
|
|
.\" .BR closelog (),
|
|
.\" and
|
|
.\" .BR setlogmask ().
|
|
.\" 4.3BSD-Reno also documents
|
|
.\" .BR vsyslog ().
|
|
.\" Of course early v* functions used the
|
|
.\" .I <varargs.h>
|
|
.\" mechanism, which is not compatible with
|
|
.\" .IR <stdarg.h> .
|
|
.SH NOTES
|
|
The parameter
|
|
.I ident
|
|
in the call of
|
|
.BR openlog ()
|
|
is probably stored as-is.
|
|
Thus, if the string it points to
|
|
is changed,
|
|
.BR syslog ()
|
|
may start prepending the changed string, and if the string
|
|
it points to ceases to exist, the results are undefined.
|
|
Most portable is to use a string constant.
|
|
.LP
|
|
Never pass a string with user-supplied data as a format,
|
|
use the following instead:
|
|
.nf
|
|
|
|
syslog(priority, "%s", string);
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
.BR logger (1),
|
|
.BR setlogmask (3),
|
|
.BR syslog.conf (5),
|
|
.BR syslogd (8)
|