mirror of https://github.com/mkerrisk/man-pages
262 lines
7.4 KiB
Plaintext
262 lines
7.4 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "CLOSELOG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" closelog
|
|
.SH NAME
|
|
closelog, openlog, setlogmask, syslog \- control system log
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <syslog.h>
|
|
.br
|
|
.sp
|
|
void closelog(void);
|
|
.br
|
|
void openlog(const char *\fP\fIident\fP\fB, int\fP \fIlogopt\fP\fB,
|
|
int\fP \fIfacility\fP\fB);
|
|
.br
|
|
int setlogmask(int\fP \fImaskpri\fP\fB);
|
|
.br
|
|
void syslog(int\fP \fIpriority\fP\fB, const char *\fP\fImessage\fP\fB,
|
|
\&... /*\fP \fIarguments\fP \fB*/); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIsyslog\fP() function shall send a message to an implementation-defined
|
|
logging facility, which may log it in an
|
|
implementation-defined system log, write it to the system console,
|
|
forward it to a list of users, or forward it to the logging
|
|
facility on another host over the network. The logged message shall
|
|
include a message header and a message body. The message header
|
|
contains at least a timestamp and a tag string.
|
|
.LP
|
|
The message body is generated from the \fImessage\fP and following
|
|
arguments in the same manner as if these were arguments to
|
|
\fIprintf\fP(), except that the additional conversion specification
|
|
\fB%m\fP shall be
|
|
recognized; it shall convert no arguments, shall cause the output
|
|
of the error message string associated with the value of
|
|
\fIerrno\fP on entry to \fIsyslog\fP(), and may be mixed with argument
|
|
specifications of the \fB"%\fP\fIn\fP\fB$"\fP form.
|
|
If a complete conversion specification with the \fBm\fP conversion
|
|
specifier character is not just \fB%m\fP , the behavior is
|
|
undefined. A trailing <newline> may be added if needed.
|
|
.LP
|
|
Values of the \fIpriority\fP argument are formed by OR'ing together
|
|
a severity-level value and an optional facility value. If
|
|
no facility value is specified, the current default facility value
|
|
is used.
|
|
.LP
|
|
Possible values of severity level include:
|
|
.TP 7
|
|
LOG_EMERG
|
|
A panic condition.
|
|
.TP 7
|
|
LOG_ALERT
|
|
A condition that should be corrected immediately, such as a corrupted
|
|
system database.
|
|
.TP 7
|
|
LOG_CRIT
|
|
Critical conditions, such as hard device errors.
|
|
.TP 7
|
|
LOG_ERR
|
|
Errors.
|
|
.TP 7
|
|
LOG_WARNING
|
|
.sp
|
|
Warning messages.
|
|
.TP 7
|
|
LOG_NOTICE
|
|
Conditions that are not error conditions, but that may require special
|
|
handling.
|
|
.TP 7
|
|
LOG_INFO
|
|
Informational messages.
|
|
.TP 7
|
|
LOG_DEBUG
|
|
Messages that contain information normally of use only when debugging
|
|
a program.
|
|
.sp
|
|
.LP
|
|
The facility indicates the application or system component generating
|
|
the message. Possible facility values include:
|
|
.TP 7
|
|
LOG_USER
|
|
Messages generated by arbitrary processes. This is the default facility
|
|
identifier if none is specified.
|
|
.TP 7
|
|
LOG_LOCAL0
|
|
Reserved for local use.
|
|
.TP 7
|
|
LOG_LOCAL1
|
|
Reserved for local use.
|
|
.TP 7
|
|
LOG_LOCAL2
|
|
Reserved for local use.
|
|
.TP 7
|
|
LOG_LOCAL3
|
|
Reserved for local use.
|
|
.TP 7
|
|
LOG_LOCAL4
|
|
Reserved for local use.
|
|
.TP 7
|
|
LOG_LOCAL5
|
|
Reserved for local use.
|
|
.TP 7
|
|
LOG_LOCAL6
|
|
Reserved for local use.
|
|
.TP 7
|
|
LOG_LOCAL7
|
|
Reserved for local use.
|
|
.sp
|
|
.LP
|
|
The \fIopenlog\fP() function shall set process attributes that affect
|
|
subsequent calls to \fIsyslog\fP(). The \fIident\fP
|
|
argument is a string that is prepended to every message. The \fIlogopt\fP
|
|
argument indicates logging options. Values for
|
|
\fIlogopt\fP are constructed by a bitwise-inclusive OR of zero or
|
|
more of the following:
|
|
.TP 7
|
|
LOG_PID
|
|
Log the process ID with each message. This is useful for identifying
|
|
specific processes.
|
|
.TP 7
|
|
LOG_CONS
|
|
Write messages to the system console if they cannot be sent to the
|
|
logging facility. The \fIsyslog\fP() function ensures that
|
|
the process does not acquire the console as a controlling terminal
|
|
in the process of writing the message.
|
|
.TP 7
|
|
LOG_NDELAY
|
|
Open the connection to the logging facility immediately. Normally
|
|
the open is delayed until the first message is logged. This
|
|
is useful for programs that need to manage the order in which file
|
|
descriptors are allocated.
|
|
.TP 7
|
|
LOG_ODELAY
|
|
Delay open until \fIsyslog\fP() is called.
|
|
.TP 7
|
|
LOG_NOWAIT
|
|
Do not wait for child processes that may have been created during
|
|
the course of logging the message. This option should be used
|
|
by processes that enable notification of child termination using SIGCHLD,
|
|
since \fIsyslog\fP() may otherwise block waiting for a
|
|
child whose exit status has already been collected.
|
|
.sp
|
|
.LP
|
|
The \fIfacility\fP argument encodes a default facility to be assigned
|
|
to all messages that do not have an explicit facility
|
|
already encoded. The initial default facility is LOG_USER.
|
|
.LP
|
|
The \fIopenlog\fP() and \fIsyslog\fP() functions may allocate a file
|
|
descriptor. It is not necessary to call \fIopenlog\fP()
|
|
prior to calling \fIsyslog\fP().
|
|
.LP
|
|
The \fIcloselog\fP() function shall close any open file descriptors
|
|
allocated by previous calls to \fIopenlog\fP() or
|
|
\fIsyslog\fP().
|
|
.LP
|
|
The \fIsetlogmask\fP() function shall set the log priority mask for
|
|
the current process to \fImaskpri\fP and return the
|
|
previous mask. If the \fImaskpri\fP argument is 0, the current log
|
|
mask is not modified. Calls by the current process to
|
|
\fIsyslog\fP() with a priority not set in \fImaskpri\fP shall be rejected.
|
|
The default log mask allows all priorities to be
|
|
logged. A call to \fIopenlog\fP() is not required prior to calling
|
|
\fIsetlogmask\fP().
|
|
.LP
|
|
Symbolic constants for use as values of the \fIlogopt\fP, \fIfacility\fP,
|
|
\fIpriority\fP, and \fImaskpri\fP arguments are
|
|
defined in the \fI<syslog.h>\fP header.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
The \fIsetlogmask\fP() function shall return the previous log priority
|
|
mask. The \fIcloselog\fP(), \fIopenlog\fP(), and
|
|
\fIsyslog\fP() functions shall not return a value.
|
|
.SH ERRORS
|
|
.LP
|
|
No errors are defined.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Using openlog()
|
|
.LP
|
|
The following example causes subsequent calls to \fIsyslog\fP() to
|
|
log the process ID with each message, and to write messages
|
|
to the system console if they cannot be sent to the logging facility.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <syslog.h>
|
|
.sp
|
|
|
|
char *ident = "Process demo";
|
|
int logopt = LOG_PID | LOG_CONS;
|
|
int facility = LOG_USER;
|
|
\&...
|
|
openlog(ident, logopt, facility);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SS Using setlogmask()
|
|
.LP
|
|
The following example causes subsequent calls to \fIsyslog\fP() to
|
|
accept error messages, and to reject all other messages.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <syslog.h>
|
|
.sp
|
|
|
|
int result;
|
|
int mask = LOG_MASK (LOG_ERR);
|
|
\&...
|
|
result = setlogmask(mask);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SS Using syslog
|
|
.LP
|
|
The following example sends the message \fB"This is a message"\fP
|
|
to the default logging facility, marking the message as an
|
|
error message generated by random processes.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <syslog.h>
|
|
.sp
|
|
|
|
char *message = "This is a message";
|
|
int priority = LOG_ERR | LOG_USER;
|
|
\&...
|
|
syslog(priority, message);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIprintf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<syslog.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|