date and time created 89/05/17 22:49:21 by bostic

[unix-history] / usr / src / lib / libc / gen / syslog.3

diff --git a/usr/src/lib/libc/gen/syslog.3 b/usr/src/lib/libc/gen/syslog.3
index b207685..b721afe 100644 (file)
--- a/usr/src/lib/libc/gen/syslog.3
+++ b/usr/src/lib/libc/gen/syslog.3
@@ -1,13 +1,24 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1985 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)syslog.3    6.3 (Berkeley) %G%
+.\" Redistribution and use in source and binary forms are permitted
+.\" provided that the above copyright notice and this paragraph are
+.\" duplicated in all such forms and that any documentation,
+.\" advertising materials, and other materials related to such
+.\" distribution and use acknowledge that the software was developed
+.\" by the University of California, Berkeley.  The name of the
+.\" University may not be used to endorse or promote products derived
+.\" from this software without specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\"    @(#)syslog.3    6.11 (Berkeley) %G%

 .\"
 .TH SYSLOG 3 ""
 .UC 5
 .SH NAME
 .\"
 .TH SYSLOG 3 ""
 .UC 5
 .SH NAME

-syslog, openlog, closelog, setlogmask \- control system log
+syslog, openlog, closelog, setlogmask, vsyslog \- control system log

 .SH SYNOPSIS
 .B "#include <syslog.h>
 .PP
 .SH SYNOPSIS
 .B "#include <syslog.h>
 .PP


@@ -17,7 +28,19 @@ syslog, openlog, closelog, setlogmask \- control system log
 .PP
 .B "syslog(priority, message, parameters ... )
 .br
 .PP
 .B "syslog(priority, message, parameters ... )
 .br

+.B "int priority;
+.br
+.B "char *message;
+.PP
+.B "#include <varargs.h>
+.br
+.B "vsyslog(priority, message, args)
+.br
+.B "int priority;
+.br

 .B "char *message;
 .B "char *message;

+.br
+.B "va_list args;

 .PP
 .B "closelog()
 .PP
 .PP
 .B "closelog()
 .PP


@@ -36,7 +59,13 @@ string except that
 .B %m
 is replaced by the current error message (collected from
 .IR errno ).
 .B %m
 is replaced by the current error message (collected from
 .IR errno ).

-A trailing newline is added if needed.
+A trailing newline is added if needed.  An alternate form,
+in which the arguments have already been captured using the
+variable-length argument facilities of
+.IR varargs (3),
+is available under the name
+.IR vsyslog .
+.PP

 This message will be read by
 .IR syslogd (8)
 and written to the system console, log files, or forwarded to
 This message will be read by
 .IR syslogd (8)
 and written to the system console, log files, or forwarded to


@@ -50,35 +79,43 @@ and a
 The facility describes the part of the system
 generating the message.
 The level is selected from an ordered list:
 The facility describes the part of the system
 generating the message.
 The level is selected from an ordered list:

-.IP LOG_EMERG \w'LOG_WARNING'u+3
+.TP
+LOG_EMERG

 A panic condition.
 This is normally broadcast to all users.
 A panic condition.
 This is normally broadcast to all users.

-.IP LOG_ALERT \w'LOG_WARNING'u+3
+.TP
+LOG_ALERT

 A condition that should be corrected immediately,
 such as a corrupted system database.
 A condition that should be corrected immediately,
 such as a corrupted system database.

-.IP LOG_CRIT \w'LOG_WARNING'u+3
+.TP
+LOG_CRIT

 Critical conditions,
 e.g., hard device errors.
 Critical conditions,
 e.g., hard device errors.

-.IP LOG_ERR \w'LOG_WARNING'u+3
+.TP
+LOG_ERR

 Errors.
 Errors.

-.IP LOG_WARNING \w'LOG_WARNING'u+3
+.TP
+LOG_WARNING

 Warning messages.
 Warning messages.

-.IP LOG_NOTICE \w'LOG_WARNING'u+3
+.TP
+LOG_NOTICE

 Conditions that are not error conditions,
 but should possibly be handled specially.
 Conditions that are not error conditions,
 but should possibly be handled specially.

-.IP LOG_INFO \w'LOG_WARNING'u+3
+.TP
+LOG_INFO

 Informational messages.
 Informational messages.

-.IP LOG_DEBUG \w'LOG_WARNING'u+3
+.TP
+LOG_DEBUG

 Messages that contain information
 normally of use only when debugging a program.
 .PP
 If
 .I syslog
 cannot pass the message to
 Messages that contain information
 normally of use only when debugging a program.
 .PP
 If
 .I syslog
 cannot pass the message to

-.I syslogd
-and the message is priority LOG_ERR or higher,
-it attempts to write the message on
-.IR /dev/console.
+.IR syslogd ,
+it will attempt to write the message on
+.I /dev/console
+if the LOG_CONS option is set (see below).

 .PP
 If special processing is needed,
 .I openlog
 .PP
 If special processing is needed,
 .I openlog


@@ -91,49 +128,89 @@ is a bit field indicating logging options.
 Current values for
 .I logopt
 are:
 Current values for
 .I logopt
 are:

-.IP LOG_PID \w'LOG_WARNING'u+3
-log the process id with each message:
+.TP
+LOG_PID
+Log the process id with each message:

 useful for identifying instantiations of daemons.
 useful for identifying instantiations of daemons.

-.IP LOG_CONS \w'LOG_WARNING'u+3
+.TP
+LOG_PERROR
+Write the message to stderr as well to the system log.
+.TP
+LOG_CONS

 Force writing messages to the console if unable to send it to
 .I syslogd.
 This option is safe to use in daemon processes that have no controlling
 terminal since
 .I syslog
 will fork before opening the console.
 Force writing messages to the console if unable to send it to
 .I syslogd.
 This option is safe to use in daemon processes that have no controlling
 terminal since
 .I syslog
 will fork before opening the console.

-.IP LOG_NDELAY \w'LOG_WARNING'u+3
-Opening the connection to
+.TP
+LOG_NDELAY 
+Open the connection to

 .I syslogd
 immediately.
 Normally the open is delayed
 until the first message is logged.
 Useful for programs that need to manage the
 order in which file descriptors are allocated.
 .I syslogd
 immediately.
 Normally the open is delayed
 until the first message is logged.
 Useful for programs that need to manage the
 order in which file descriptors are allocated.

+.TP
+LOG_NOWAIT
+Don't wait for children forked to log messages on the console.
+This option should be used by processes that enable notification
+of child termination via SIGCHLD, as
+.I syslog
+may otherwise block waiting for a child whose exit status has already
+been collected.

 .PP
 The
 .I facility
 .PP
 The
 .I facility

-parameter is encodes a default facility to be assigned to all messages
+parameter encodes a default facility to be assigned to all messages

 that do not have an explicit facility encoded:
 that do not have an explicit facility encoded:

-.IP LOG_KERN \w'LOG_WARNING'u+3
+.TP
+LOG_KERN

 Messages generated by the kernel.
 These cannot be generated by any user processes.
 Messages generated by the kernel.
 These cannot be generated by any user processes.

-.IP LOG_USER \w'LOG_WARNING'u+3
+.TP
+LOG_USER

 Messages generated by random user processes.
 Messages generated by random user processes.

-This is the default if none is specified.
-.IP LOG_MAIL \w'LOG_WARNING'u+3
+This is the default facility identifier if none is specified.
+.TP
+LOG_MAIL

 The mail system.
 The mail system.

-.IP LOG_DAEMON \w'LOG_WARNING'u+3
+.TP
+LOG_DAEMON

 System daemons, such as
 System daemons, such as

-.IR lpd (8),
+.IR ftpd (8),

 .IR routed (8),
 .IR routed (8),

-etc.
-.IP LOG_AUTH \w'LOG_WARNING'u+3
+etc, that are not provided for explicitly by other facilities.
+.TP
+LOG_AUTH

 The authorization system:
 .IR login (1),
 .IR su (1),
 .IR getty (8),
 etc.
 The authorization system:
 .IR login (1),
 .IR su (1),
 .IR getty (8),
 etc.

-.IP LOG_LOCAL0 \w'LOG_WARNING'u+3
+.TP
+LOG_SYSLOG
+Messages generated internally by
+.IR syslogd (8).
+.TP
+LOG_LPR
+The line printer spooling system:
+.IR lpr (1),
+.IR lpc (8),
+.IR lpd (8),
+etc.
+.TP
+LOG_NEWS
+The network news system.
+.TP
+LOG_UUCP
+The uucp system.
+.TP
+LOG_CRON
+The clock daemon.
+.TP
+LOG_LOCAL0

 Reserved for local use.
 Similarly for LOG_LOCAL1 through LOG_LOCAL7.
 .PP
 Reserved for local use.
 Similarly for LOG_LOCAL1 through LOG_LOCAL7.
 .PP


@@ -146,15 +223,22 @@ sets the log priority mask to
 and returns the previous mask.
 Calls to
 .I syslog
 and returns the previous mask.
 Calls to
 .I syslog

-with a priority lower than
+with a priority not set in

 .I maskpri
 are rejected.
 .I maskpri
 are rejected.

+The mask for an individual priority
+.I pri
+is calculated by the macro LOG_MASK(\fIpri\fP);
+the mask for all priorities up to and including
+.I toppri
+is given by the macro LOG_UPTO(\fItoppri\fP).

 The default allows all priorities to be logged.
 .SH EXAMPLES
 .nf
 syslog(LOG_ALERT, "who: internal error 23");
 
 openlog("ftpd", LOG_PID, LOG_DAEMON);
 The default allows all priorities to be logged.
 .SH EXAMPLES
 .nf
 syslog(LOG_ALERT, "who: internal error 23");
 
 openlog("ftpd", LOG_PID, LOG_DAEMON);

+setlogmask(LOG_UPTO(LOG_ERR));

 syslog(LOG_INFO, "Connection from host %d", CallingHost);
 
 syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m");
 syslog(LOG_INFO, "Connection from host %d", CallingHost);
 
 syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m");