path: root/usr/src/man/man3c/syslog.3c

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at  http://www.opengroup.org/bookstore/.
.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
.\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
.\"  This notice shall appear on any product containing this material.
.TH syslog 3C "16 Mar 2009" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
syslog, openlog, closelog, setlogmask \- control system log
.SH SYNOPSIS
.LP
.nf
#include <syslog.h>

\fBvoid\fR \fBopenlog\fR(\fBconst char *\fR\fIident\fR, \fBint\fR \fIlogopt\fR, \fBint\fR \fIfacility\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsyslog\fR(\fBint\fR \fIpriority\fR, \fBconst char *\fR\fImessage\fR, \fB\&.../*\fR \fIarguments\fR */);
.fi

.LP
.nf
\fBvoid\fR \fBcloselog\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBint\fR \fBsetlogmask\fR(\fBint\fR \fImaskpri\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsyslog()\fR function sends a message to \fBsyslogd\fR(1M), which,
depending on the configuration of \fB/etc/syslog.conf\fR, logs it in an
appropriate system log, writes it to the system console, forwards it to a list
of users, or forwards it to \fBsyslogd\fR on another host over the network.
The logged message includes a message header and a message body.  The message
header consists of a facility indicator, a severity level indicator, a
timestamp, a tag string, and optionally the process ID.
.sp
.LP
The message body is generated from the \fImessage\fR and following arguments in
the same manner as if these were arguments to \fBprintf\fR(3UCB), except that
occurrences of \fB%m\fR in the format string pointed to by the \fImessage\fR
argument are replaced by the error message string associated with the current
value of \fBerrno\fR.  A trailing \fBNEWLINE\fR character is added if needed.
.sp
.LP
Symbolic constants for use as values of the \fIlogopt\fR, \fIfacility\fR,
\fIpriority\fR, and \fImaskpri\fR arguments are defined in the <\fBsyslog.h\fR>
header.
.sp
.LP
Values of the \fIpriority\fR argument are formed by ORing together a
\fIseverity level\fR value and an optional \fIfacility\fR value.  If no
facility value is specified, the current default facility value is used.
.sp
.LP
Possible values of severity level include, in decreasing order:
.sp
.ne 2
.mk
.na
\fB\fBLOG_EMERG\fR\fR
.ad
.RS 15n
.rt  
A panic condition.  This is normally broadcast to all users.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_ALERT\fR\fR
.ad
.RS 15n
.rt  
A condition that should be corrected immediately, such as a corrupted system
database.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_CRIT\fR\fR
.ad
.RS 15n
.rt  
Critical conditions, such as hard device errors.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_ERR\fR\fR
.ad
.RS 15n
.rt  
Errors.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_WARNING\fR\fR
.ad
.RS 15n
.rt  
Warning messages.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_NOTICE\fR\fR
.ad
.RS 15n
.rt  
Conditions that are not error conditions, but that may require special
handling.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_INFO\fR\fR
.ad
.RS 15n
.rt  
Informational messages.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_DEBUG\fR\fR
.ad
.RS 15n
.rt  
Messages that contain information normally of use only when debugging a
program.
.RE

.sp
.LP
The facility indicates the application or system component generating the
message.  Possible facility values include:
.sp
.ne 2
.mk
.na
\fB\fBLOG_KERN\fR\fR
.ad
.RS 14n
.rt  
Messages generated by the kernel. These cannot be generated by any user
processes.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_USER\fR\fR
.ad
.RS 14n
.rt  
Messages generated by random user processes. This is the default facility
identifier if none is specified.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_MAIL\fR\fR
.ad
.RS 14n
.rt  
The mail system.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_DAEMON\fR\fR
.ad
.RS 14n
.rt  
System daemons, such as \fBin.ftpd\fR(1M).
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_AUTH\fR\fR
.ad
.RS 14n
.rt  
The authentication / security / authorization system: \fBlogin\fR(1),
\fBsu\fR(1M), \fBgetty\fR(1M).
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LPR\fR\fR
.ad
.RS 14n
.rt  
The line printer spooling system: \fBlpr\fR(1B), \fBlpc\fR(1B).
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_NEWS\fR\fR
.ad
.RS 14n
.rt  
Designated for the \fBUSENET\fR network news system.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_UUCP\fR\fR
.ad
.RS 14n
.rt  
Designated for the \fBUUCP\fR system; it does not currently use \fBsyslog()\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_CRON\fR\fR
.ad
.RS 14n
.rt  
The \fBcron\fR/\fBat\fR facility; \fBcrontab\fR(1), \fBat\fR(1),
\fBcron\fR(1M).
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_AUDIT\fR\fR
.ad
.RS 14n
.rt  
The audit facility, for example, \fBauditd\fR(1M).
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL0\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL1\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL2\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL3\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL4\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL5\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL6\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_LOCAL7\fR\fR
.ad
.RS 14n
.rt  
Designated for local use.
.RE

.sp
.LP
The \fBopenlog()\fR function sets process attributes that affect subsequent
calls to \fBsyslog()\fR. The \fIident\fR argument is a string that is prepended
to every message. The \fBopenlog()\fR function uses the passed-in \fIident\fR
argument directly, rather than making a private copy of it. The \fIlogopt\fR
argument indicates logging options.  Values for \fIlogopt\fR are constructed by
a bitwise-inclusive OR of zero or more of the following:
.sp
.ne 2
.mk
.na
\fB\fBLOG_PID\fR\fR
.ad
.RS 14n
.rt  
Log the process \fBID\fR with each message.  This is useful for identifying
specific daemon processes (for daemons that fork).
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_CONS\fR\fR
.ad
.RS 14n
.rt  
Write messages to the system console if they cannot be sent to
\fBsyslogd\fR(1M). This option is safe to use in daemon processes that have no
controlling terminal, since \fBsyslog()\fR forks before opening the console.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_NDELAY\fR\fR
.ad
.RS 14n
.rt  
Open the connection to \fBsyslogd\fR(1M) 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.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_ODELAY\fR\fR
.ad
.RS 14n
.rt  
Delay open until \fBsyslog()\fR is called.
.RE

.sp
.ne 2
.mk
.na
\fB\fBLOG_NOWAIT\fR\fR
.ad
.RS 14n
.rt  
Do not wait for child processes that have been forked to log messages onto the
console.  This option should be used by processes that enable notification of
child termination using \fBSIGCHLD\fR, since \fBsyslog()\fR may otherwise block
waiting for a child whose exit status has already been collected.
.RE

.sp
.LP
The \fIfacility\fR 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 \fBLOG_USER\fR.
.sp
.LP
The \fBopenlog()\fR and \fBsyslog()\fR functions may allocate a file
descriptor.  It is not necessary to call \fBopenlog()\fR prior to calling
\fBsyslog()\fR.
.sp
.LP
The \fBcloselog()\fR function closes any open file descriptors allocated by
previous calls to \fBopenlog()\fR or \fBsyslog()\fR.
.sp
.LP
The \fBsetlogmask()\fR function sets the log priority mask for the current
process to \fImaskpri\fR and returns the previous mask.  If the \fImaskpri\fR
argument is 0, the current log mask is not modified.  Calls by the current
process to \fBsyslog()\fR with a priority not set in \fImaskpri\fR are
rejected.  The mask for an individual priority \fIpri\fR is calculated by the
macro \fBLOG_MASK(\fIpri\fR)\fR; the mask for all priorities up to and
including \fItoppri\fR is given by the macro \fBLOG_UPTO(\fItoppri\fR)\fR. The
default log mask allows all priorities to be logged.
.SH RETURN VALUES
.sp
.LP
The \fBsetlogmask()\fR function returns the previous log priority mask. The
\fBcloselog()\fR, \fBopenlog()\fR and \fBsyslog()\fR functions return no value.
.SH ERRORS
.sp
.LP
No errors are defined.
.SH EXAMPLES
.LP
\fBExample 1 \fRExample of \fBLOG_ALERT\fR message.
.sp
.LP
This call logs a message at priority \fBLOG_ALERT\fR:

.sp
.in +2
.nf
\fBsyslog(LOG_ALERT, "who: internal error 23")\fR;
.fi
.in -2
.sp

.sp
.LP
The \fBFTP\fR daemon \fBftpd\fR would make this call to \fBopenlog()\fR to
indicate that all messages it logs should have an identifying string of
\fBftpd\fR, should be treated by \fBsyslogd\fR(1M) as other messages from
system daemons are, should include the process \fBID\fR of the process logging
the message:

.sp
.in +2
.nf
\fBopenlog("ftpd", LOG_PID, LOG_DAEMON)\fR;
.fi
.in -2
.sp

.sp
.LP
Then it would make the following call to \fBsetlogmask()\fR to indicate that
messages at priorities from \fBLOG_EMERG\fR through \fBLOG_ERR\fR should be
logged, but that no messages at any other priority should be logged:

.sp
.in +2
.nf
\fBsetlogmask(LOG_UPTO(LOG_ERR))\fR;
.fi
.in -2
.sp

.sp
.LP
Then, to log a message at priority \fBLOG_INFO\fR, it would make the following
call to \fBsyslog\fR:

.sp
.in +2
.nf
\fBsyslog(LOG_INFO, "Connection from host %d", CallingHost)\fR;
.fi
.in -2
.sp

.sp
.LP
A locally-written utility could use the following call to \fBsyslog()\fR to log
a message at priority \fBLOG_INFO\fR to be treated by \fBsyslogd\fR(1M) as
other messages to the facility  \fBLOG_LOCAL2\fR are:

.sp
.in +2
.nf
\fBsyslog(LOG_INFO|LOG_LOCAL2, "error: %m")\fR;
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
_
StandardSee \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBat\fR(1), \fBcrontab\fR(1), \fBlogger\fR(1), \fBlogin\fR(1), \fBlpc\fR(1B),
\fBlpr\fR(1B), \fBauditd\fR(1M), \fBcron\fR(1M), \fBgetty\fR(1M),
\fBin.ftpd\fR(1M), \fBsu\fR(1M), \fBsyslogd\fR(1M), \fBprintf\fR(3UCB),
\fBsyslog.conf\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)