mirror of https://github.com/mkerrisk/man-pages
363 lines
8.3 KiB
Groff
363 lines
8.3 KiB
Groff
.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com)
|
|
.\" and Copyright 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" 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.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2016-03-15 "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
|
|
.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 ():
|
|
Since glibc 2.19:
|
|
_DEFAULT_SOURCE
|
|
Glibc 2.19 and earlier:
|
|
_BSD_SOURCE
|
|
.SH DESCRIPTION
|
|
.SS openlog()
|
|
.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.
|
|
If
|
|
.I ident
|
|
is NULL, the program name is used.
|
|
(POSIX.1-2008 does not specify the behavior when
|
|
.I ident
|
|
is NULL.)
|
|
|
|
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 ().
|
|
The values that may be specified for
|
|
.I option
|
|
and
|
|
.I facility
|
|
are described 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.
|
|
.\"
|
|
.SS syslog() and vsyslog()
|
|
.BR syslog ()
|
|
generates a log message, which will be distributed by
|
|
.BR syslogd (8).
|
|
|
|
The
|
|
.I priority
|
|
argument is formed by ORing together a
|
|
.I facility
|
|
value and a
|
|
.I level
|
|
value (described below).
|
|
If no
|
|
.I facility
|
|
value is ORed into
|
|
.IR priority ,
|
|
then the default value set by
|
|
.BR openlog ()
|
|
is used, or, if there was no preceding
|
|
.BR openlog ()
|
|
call, a default of
|
|
.BR LOG_USER
|
|
is employed.
|
|
|
|
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 ).
|
|
The format string need not include a terminating newline character.
|
|
|
|
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.
|
|
.\"
|
|
.SS closelog()
|
|
.BR closelog ()
|
|
closes the file descriptor being used to write to the system logger.
|
|
The use of
|
|
.BR closelog ()
|
|
is optional.
|
|
.\"
|
|
.SS Values for \fIoption\fP
|
|
The
|
|
.I option
|
|
argument to
|
|
.BR openlog ()
|
|
is a bit mask constructed by ORing together any of the following values:
|
|
.TP 15
|
|
.B LOG_CONS
|
|
Write directly to the system console if there is an error while sending to
|
|
the system logger.
|
|
.TP
|
|
.B LOG_NDELAY
|
|
Open the connection immediately (normally, the connection is opened when
|
|
the first message is logged).
|
|
This may be useful, for example, if a subsequent
|
|
.BR chroot (2)
|
|
would make the pathname used internally by the logging facility unreachable.
|
|
.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 or POSIX.1-2008.)
|
|
Also log the message to
|
|
.IR stderr .
|
|
.TP
|
|
.B LOG_PID
|
|
Include the caller's PID with each message.
|
|
.\"
|
|
.SS Values for \fIfacility\fP
|
|
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 15
|
|
.B LOG_AUTH
|
|
security/authorization messages
|
|
.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 (these can't be generated from user processes)
|
|
.\" LOG_KERN has the value 0; if used as a facility, zero translates to:
|
|
.\" "use the default facility".
|
|
.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 Values for \fIlevel\fP
|
|
This determines the importance of the message.
|
|
The levels are, in order of decreasing importance:
|
|
.TP 15
|
|
.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 ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lbw21 lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR openlog (),
|
|
.BR closelog ()
|
|
T} Thread safety MT-Safe
|
|
T{
|
|
.BR syslog (),
|
|
.BR vsyslog ()
|
|
T} Thread safety MT-Safe env locale
|
|
.TE
|
|
.SH CONFORMING TO
|
|
The functions
|
|
.BR openlog (),
|
|
.BR closelog (),
|
|
and
|
|
.BR syslog ()
|
|
(but not
|
|
.BR vsyslog ())
|
|
are specified in SUSv2, POSIX.1-2001, and POSIX.1-2008.
|
|
|
|
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 or POSIX.1-2008, 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 argument
|
|
.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 journalctl (1),
|
|
.BR setlogmask (3),
|
|
.BR syslog.conf (5),
|
|
.BR syslogd (8)
|