closelog.3p (7870B)
- '\" et
- .TH CLOSELOG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- closelog,
- openlog,
- setlogmask,
- syslog
- \(em control system log
- .SH SYNOPSIS
- .LP
- .nf
- #include <syslog.h>
- .P
- void closelog(void);
- void openlog(const char *\fIident\fP, int \fIlogopt\fP, int \fIfacility\fP);
- int setlogmask(int \fImaskpri\fP);
- void syslog(int \fIpriority\fP, const char *\fImessage\fP, ... /* \fIarguments\fP */);
- .fi
- .SH DESCRIPTION
- The
- \fIsyslog\fR()
- 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.
- .P
- The message body is generated from the
- .IR message
- and following arguments in the same manner as if these were arguments
- to
- \fIprintf\fR(),
- except that the additional conversion specification
- .BR %m
- shall be recognized; it shall convert no arguments, shall cause the
- output of the error message string associated with the value of
- .IR errno
- on entry to
- \fIsyslog\fR(),
- and may be mixed with argument specifications of the \fR"%\fIn\fR$"\fR
- form. If a complete conversion specification with the
- .BR m
- conversion specifier character is not just
- .BR %m ,
- the behavior is undefined. A trailing
- <newline>
- may be added if needed.
- .P
- Values of the
- .IR priority
- 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.
- .P
- Possible values of severity level include:
- .IP LOG_EMERG 12
- A panic condition.
- .IP LOG_ALERT 12
- A condition that should be corrected immediately, such as a corrupted
- system database.
- .IP LOG_CRIT 12
- Critical conditions, such as hard device errors.
- .IP LOG_ERR 12
- Errors.
- .IP LOG_WARNING 12
- .br
- Warning messages.
- .IP LOG_NOTICE 12
- Conditions that are not error conditions, but that may require special
- handling.
- .IP LOG_INFO 12
- Informational messages.
- .IP LOG_DEBUG 12
- Messages that contain information normally of use only when debugging a
- program.
- .P
- The facility indicates the application or system component generating
- the message. Possible facility values include:
- .IP LOG_USER 12
- Messages generated by arbitrary processes. This is the default facility
- identifier if none is specified.
- .IP LOG_LOCAL0 12
- Reserved for local use.
- .IP LOG_LOCAL1 12
- Reserved for local use.
- .IP LOG_LOCAL2 12
- Reserved for local use.
- .IP LOG_LOCAL3 12
- Reserved for local use.
- .IP LOG_LOCAL4 12
- Reserved for local use.
- .IP LOG_LOCAL5 12
- Reserved for local use.
- .IP LOG_LOCAL6 12
- Reserved for local use.
- .IP LOG_LOCAL7 12
- Reserved for local use.
- .P
- The
- \fIopenlog\fR()
- function shall set process attributes that affect subsequent calls to
- \fIsyslog\fR().
- The
- .IR ident
- argument is a string that is prepended to every message. The
- .IR logopt
- argument indicates logging options. Values for
- .IR logopt
- are constructed by a bitwise-inclusive OR of zero or more of the
- following:
- .IP LOG_PID 12
- Log the process ID with each message. This is useful for identifying
- specific processes.
- .IP LOG_CONS 12
- Write messages to the system console if they cannot be sent to the
- logging facility. The
- \fIsyslog\fR()
- function ensures that the process does not acquire the console as a
- controlling terminal in the process of writing the message.
- .IP LOG_NDELAY 12
- 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.
- .IP LOG_ODELAY 12
- Delay open until
- \fIsyslog\fR()
- is called.
- .IP LOG_NOWAIT 12
- 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\fR()
- may otherwise block waiting for a child whose exit status has already
- been collected.
- .P
- The
- .IR facility
- 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.
- .P
- The
- \fIopenlog\fR()
- and
- \fIsyslog\fR()
- functions may allocate a file descriptor. It is not necessary to call
- \fIopenlog\fR()
- prior to calling
- \fIsyslog\fR().
- .P
- The
- \fIcloselog\fR()
- function shall close any open file descriptors allocated by previous
- calls to
- \fIopenlog\fR()
- or
- \fIsyslog\fR().
- .P
- The
- \fIsetlogmask\fR()
- function shall set the log priority mask for the current process to
- .IR maskpri
- and return the previous mask. If the
- .IR maskpri
- argument is 0, the current log mask is not modified. Calls by the
- current process to
- \fIsyslog\fR()
- with a priority not set in
- .IR maskpri
- shall be rejected. The default log mask allows all priorities to be
- logged. A call to
- \fIopenlog\fR()
- is not required prior to calling
- \fIsetlogmask\fR().
- .P
- Symbolic constants for use as values of the
- .IR logopt ,
- .IR facility ,
- .IR priority ,
- and
- .IR maskpri
- arguments are defined in the
- .IR <syslog.h>
- header.
- .SH "RETURN VALUE"
- The
- \fIsetlogmask\fR()
- function shall return the previous log priority mask. The
- \fIcloselog\fR(),
- \fIopenlog\fR(),
- and
- \fIsyslog\fR()
- functions shall not return a value.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Using openlog(\|)"
- .P
- The following example causes subsequent calls to
- \fIsyslog\fR()
- 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 4
- .nf
- #include <syslog.h>
- .P
- char *ident = "Process demo";
- int logopt = LOG_PID | LOG_CONS;
- int facility = LOG_USER;
- \&...
- openlog(ident, logopt, facility);
- .fi
- .P
- .RE
- .SS "Using setlogmask(\|)"
- .P
- The following example causes subsequent calls to
- \fIsyslog\fR()
- to accept error messages, and to reject all other messages.
- .sp
- .RS 4
- .nf
- #include <syslog.h>
- .P
- int result;
- int mask = LOG_MASK (LOG_ERR);
- \&...
- result = setlogmask(mask);
- .fi
- .P
- .RE
- .SS "Using syslog"
- .P
- The following example sends the message
- .BR \(dqThis is a message\(dq
- to the default logging facility, marking the message as an error
- message generated by random processes.
- .sp
- .RS 4
- .nf
- #include <syslog.h>
- .P
- char *message = "This is a message";
- int priority = LOG_ERR | LOG_USER;
- \&...
- syslog(priority, message);
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIfprintf\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<syslog.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .