312 lines
6.4 KiB
Groff
312 lines
6.4 KiB
Groff
.\" @(#)syslog.3 1.1 94/10/31 SMI; from UCB 4.3
|
|
.\" Copyright (c) 1983 Regents of the University of California.
|
|
.\" All rights reserved. The Berkeley software License Agreement
|
|
.\" specifies the terms and conditions for redistribution.
|
|
.\"
|
|
.TH SYSLOG 3 "22 November 1987"
|
|
.SH NAME
|
|
syslog, openlog, closelog, setlogmask \- control system log
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <syslog.h>
|
|
.LP
|
|
.B openlog(ident, logopt, facility)
|
|
.B char \(**ident;
|
|
.LP
|
|
.B syslog(priority, message, parameters \&.\|.\|. )
|
|
.B char \(**message;
|
|
.LP
|
|
.B closelog(\|)
|
|
.LP
|
|
.B setlogmask(maskpri)
|
|
.fi
|
|
.IX "syslog()" "" "\fLsyslog()\fP \(em write message to system log"
|
|
.IX "openlog()" "" "\fLopenlog()\fP \(em initialize system log file"
|
|
.IX "closelog()" "" "\fLcloselog()\fP \(em close system log file"
|
|
.IX "setlogmask()" "" "\fLcloselog()\fP \(em set log priority mask"
|
|
.IX "control system log" "write to system log \(em \fLsyslog()\fP"
|
|
.IX "control system log" "start system log \(em \fLopenlog()\fP"
|
|
.IX "control system log" "close system log \(em \fLcloselog()\fP"
|
|
.IX "control system log" "set log priority mask \(em \fLsetlogmask()\fP"
|
|
.IX "system log, control \(em \fLsyslog()\fR"
|
|
.SH DESCRIPTION
|
|
.LP
|
|
.B syslog(\|)
|
|
passes
|
|
.I message
|
|
to
|
|
.BR syslogd (8),
|
|
which logs it in an appropriate system log,
|
|
writes it to the system console, forwards it to a
|
|
list of users, or forwards it to the
|
|
.B syslogd
|
|
on another host over the network.
|
|
The message is tagged with a priority of
|
|
.IR priority .
|
|
The message looks like a
|
|
.BR printf (3V)
|
|
string except that
|
|
.B %m
|
|
is replaced by the current error message (collected from
|
|
.BR errno ).
|
|
A trailing
|
|
.SM NEWLINE
|
|
is added if needed.
|
|
.LP
|
|
Priorities are encoded as a
|
|
.I facility
|
|
and a
|
|
.IR level .
|
|
The facility describes the part of the system
|
|
generating the message.
|
|
The level is selected from an ordered list:
|
|
.RS
|
|
.TP 20
|
|
.SB LOG_EMERG
|
|
A panic condition. This is normally broadcast to all users.
|
|
.TP
|
|
.SB LOG_ALERT
|
|
A condition that should be corrected immediately,
|
|
such as a corrupted system database.
|
|
.TP
|
|
.SB LOG_CRIT
|
|
Critical conditions, such as hard device errors.
|
|
.TP
|
|
.SB LOG_ERR
|
|
Errors.
|
|
.TP
|
|
.SB LOG_WARNING
|
|
Warning messages.
|
|
.TP
|
|
.SB LOG_NOTICE
|
|
Conditions that are not error conditions,
|
|
but that may require special handling.
|
|
.TP
|
|
.SB LOG_INFO
|
|
Informational messages.
|
|
.TP
|
|
.SB LOG_DEBUG
|
|
Messages that contain information
|
|
normally of use only when debugging a program.
|
|
.RE
|
|
.LP
|
|
If special processing is needed,
|
|
.B openlog(\|)
|
|
can be called to initialize the log file.
|
|
The parameter
|
|
.I ident
|
|
is a string that is prepended to every message.
|
|
.I logopt
|
|
is a bit field indicating logging options.
|
|
Current values for
|
|
.I logopt
|
|
are:
|
|
.RS
|
|
.TP 20
|
|
.SB LOG_PID
|
|
Log the process
|
|
.SM ID
|
|
with each message. This is useful for identifying
|
|
specific daemon processes (for daemons that fork).
|
|
.TP
|
|
.SB LOG_CONS
|
|
Write messages to the system console if they
|
|
cannot be sent to
|
|
.BR syslogd .
|
|
This option is safe to use in daemon processes
|
|
that have no controlling terminal, since
|
|
.B syslog(\|)
|
|
forks before opening the console.
|
|
.TP
|
|
.SB LOG_NDELAY
|
|
Open the connection to
|
|
.B syslogd
|
|
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
|
|
.SB LOG_NOWAIT
|
|
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
|
|
.BR \s-1SIGCHLD\s0 ,
|
|
since
|
|
.B syslog(\|)
|
|
may otherwise block waiting for a child whose
|
|
exit status has already been collected.
|
|
.RE
|
|
.br
|
|
.ne 9
|
|
.LP
|
|
The
|
|
.I facility
|
|
parameter encodes a default facility to be
|
|
assigned to all messages
|
|
that do not have an explicit facility already encoded:
|
|
.RS
|
|
.TP 20
|
|
.SB LOG_KERN
|
|
Messages generated by the kernel.
|
|
These cannot be generated by any user processes.
|
|
.TP
|
|
.SB LOG_USER
|
|
Messages generated by random user processes.
|
|
This is the default facility identifier if none is specified.
|
|
.TP
|
|
.SB LOG_MAIL
|
|
The mail system.
|
|
.TP
|
|
.SB LOG_DAEMON
|
|
System daemons, such as
|
|
.BR ftpd (8C),
|
|
.BR routed (8C),
|
|
etc.
|
|
.TP
|
|
.SB LOG_AUTH
|
|
The authorization system:
|
|
.BR login (1),
|
|
.BR su (1V),
|
|
.BR getty (8),
|
|
etc.
|
|
.TP
|
|
.SB LOG_LPR
|
|
The line printer spooling system:
|
|
.BR lpr (1),
|
|
.BR lpc (8),
|
|
.BR lpd (8),
|
|
etc.
|
|
.TP
|
|
.SB LOG_NEWS
|
|
Reserved for the
|
|
.SM USENET
|
|
network news system.
|
|
.TP
|
|
.SB LOG_UUCP
|
|
Reserved for the
|
|
.SM UUCP
|
|
system; it does not currently use
|
|
.BR syslog .
|
|
.TP
|
|
.SB LOG_CRON
|
|
The
|
|
.BR cron / at
|
|
facility;
|
|
.BR crontab (1),
|
|
.BR at (1),
|
|
.BR cron (8),
|
|
etc.
|
|
.TP
|
|
.SB LOG_LOCAL0\-7
|
|
Reserved for local use.
|
|
.RE
|
|
.LP
|
|
.B closelog(\|)
|
|
can be used to close the log file.
|
|
.LP
|
|
.B setlogmask(\|)
|
|
sets the log priority mask to
|
|
.I maskpri
|
|
and returns the previous mask.
|
|
Calls to
|
|
.B syslog(\|)
|
|
with a priority not set in
|
|
.I maskpri
|
|
are rejected.
|
|
The mask for an individual priority
|
|
.I pri
|
|
is calculated by the macro
|
|
.SB LOG_MASK\c
|
|
.BR (\fIpri\fP);
|
|
the mask for all priorities up to and including
|
|
.I toppri
|
|
is given by the macro
|
|
.SB LOG_UPTO\c
|
|
.BR (\fItoppri\fP).
|
|
The default allows all priorities to be logged.
|
|
.SH EXAMPLES
|
|
This call logs a message at priority
|
|
.BR \s-1LOG_ALERT\s0 :
|
|
.LP
|
|
.RS
|
|
.B
|
|
syslog(\s-1LOG_ALERT\s0, "who: internal error 23");
|
|
.RE
|
|
.LP
|
|
The
|
|
.SM FTP
|
|
daemon
|
|
.B ftpd
|
|
would make this call to
|
|
.B openlog(\|)
|
|
to indicate that all messages it logs
|
|
should have an identifying string of
|
|
.BR ftpd ,
|
|
should be treated by
|
|
.B syslogd
|
|
as other messages from system daemons are,
|
|
should include the process
|
|
.SM ID
|
|
of the process logging the message:
|
|
.LP
|
|
.RS
|
|
.B
|
|
openlog("ftpd", \s-1LOG_PID\s0, \s-1LOG_DAEMON\s0);
|
|
.RE
|
|
.LP
|
|
Then it would make the following call to
|
|
.B setlogmask(\|)
|
|
to indicate that messages at priorities from
|
|
.SB LOG_EMERG
|
|
through
|
|
.SB LOG_ERR
|
|
should be logged, but that no messages at any
|
|
other priority should be logged:
|
|
.LP
|
|
.RS
|
|
.B
|
|
.BR setlogmask(\s-1LOG_UPTO\s0 (\s-1LOG_ERR\s0));
|
|
.RE
|
|
.LP
|
|
Then, to log a message at priority
|
|
.BR \s-1LOG_INFO\s0 ,
|
|
it would make the following call to
|
|
.BR syslog :
|
|
.LP
|
|
.RS
|
|
.B
|
|
syslog(\s-1LOG_INFO\s0, "Connection from host %d", CallingHost);
|
|
.RE
|
|
.LP
|
|
A locally-written utility could use the following call to
|
|
.B syslog(\|)
|
|
to log a message at priority
|
|
.SB LOG_INFO
|
|
to be treated by
|
|
.B syslogd
|
|
as other messages to the facility
|
|
.SB LOG_LOCAL2
|
|
are:
|
|
.LP
|
|
.RS
|
|
.B
|
|
syslog(\s-1LOG_INFO|LOG_LOCAL\s02, "error: %m");
|
|
.RE
|
|
.SH "SEE ALSO"
|
|
.BR at (1),
|
|
.BR crontab (1),
|
|
.BR logger (1),
|
|
.BR login (1),
|
|
.BR lpr (1),
|
|
.BR su (1V),
|
|
.BR printf (3V),
|
|
.BR syslog.conf (5),
|
|
.BR cron (8),
|
|
.BR ftpd (8C),
|
|
.BR getty (8),
|
|
.BR lpc (8),
|
|
.BR lpd (8),
|
|
.BR routed (8C),
|
|
.BR syslogd (8)
|