macro and text revision (-mdoc version 3)

[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 ea411ca..0d1f43c 100644 (file)
--- a/usr/src/lib/libc/gen/syslog.3
+++ b/usr/src/lib/libc/gen/syslog.3
@@ -1,162 +1,238 @@
-.\" 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, 1991 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)syslog.3    6.2 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH SYSLOG 3 ""
-.UC 5
-.SH NAME
-syslog, openlog, closelog, setlogmask \- control system log
-.SH SYNOPSIS
-.B "#include <syslog.h>
-.PP
-.B "openlog(ident, logopt, facility)
-.br
-.B "char *ident;
-.PP
-.B "syslog(priority, message, parameters ... )
-.br
-.B "char *message;
-.PP
-.B "closelog()
-.PP
-.B "setlogmask(maskpri)
-.SH DESCRIPTION
-.I Syslog
-arranges to write
-.I message
-onto the system log maintained by
-.IR syslogd (8).
+.\"     @(#)syslog.3   6.17 (Berkeley) %G%
+.\"
+.Dd 
+.Dt SYSLOG 3
+.Os BSD 4.2
+.Sh NAME
+.Nm syslog ,
+.Nm vsyslog ,
+.Nm openlog ,
+.Nm closelog ,
+.Nm setlogmask
+.Nd control system log
+.Sh SYNOPSIS
+.Fd #include <syslog.h>
+.Fd #include <varargs.h>
+.Ft void
+.Fn syslog "int priority" "const char *message" "..."
+.Ft void
+.Fn vsyslog "int priority" "const char *message" "va_list args"
+.Ft void
+.Fn openlog "const char *ident" "int logopt" "int facility"
+.Ft void
+.Fn closelog void
+.Ft int
+.Fn setlogmask "int maskpri"
+.Sh DESCRIPTION
+The
+.Fn syslog
+function
+writes
+.Fa message
+to the system message logger.
+The message is then written to the system console, log files,
+logged-in users, or forwarded to other machines as appropriate. (See
+.Xr syslogd 8 . )
+.Pp
+The message is identical to a
+.Xr printf 3
+format string, except that
+.Ql %m
+is replaced by the current error
+message. (As denoted by the global variable
+.Va errno ;
+see
+.Xr strerror 3 . )
+A trailing newline is added if none is present.
+.Pp
+The
+.Fn vsyslog
+function
+is an alternate form in which the arguments have already been captured
+using the variable-length argument facilities of
+.Xr varargs 3 .
+.Pp

 The message is tagged with
 The message is tagged with

-.IR priority .
-The message looks like a
-.IR printf (3)
-string except that
-.B %m
-is replaced by the current error message (collected from
-.IR errno ).
-A trailing newline is added if needed.
-This message will be read by
-.IR syslogd (8)
-and written to the system console, log files, or forwarded to
-.I syslogd
-on another host as appropriate.
-.PP
+.Fa priority .

 Priorities are encoded as a
 Priorities are encoded as a

-.I facility
+.Fa facility

 and a
 and a

-.IR level .
+.Em level .

 The facility describes the part of the system
 generating the message.
 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
+The level is selected from the following
+.Em ordered
+(high to low) list:
+.Bl -tag -width LOG_AUTHPRIV
+.It Dv 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
-A condition that should be corrected immediately,
-such as a corrupted system database.
-.IP LOG_CRIT \w'LOG_WARNING'u+3
-Critical conditions,
-e.g., hard device errors.
-.IP LOG_ERR \w'LOG_WARNING'u+3
+.It Dv LOG_ALERT
+A condition that should be corrected immediately, such as a corrupted
+system database.
+.It Dv LOG_CRIT
+Critical conditions, e.g., hard device errors.
+.It Dv LOG_ERR

 Errors.
 Errors.

-.IP LOG_WARNING \w'LOG_WARNING'u+3
+.It Dv LOG_WARNING

 Warning messages.
 Warning messages.

-.IP LOG_NOTICE \w'LOG_WARNING'u+3
+.It Dv 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
+.It Dv LOG_INFO

 Informational messages.
 Informational messages.

-.IP LOG_DEBUG \w'LOG_WARNING'u+3
+.It Dv LOG_DEBUG

 Messages that contain information
 normally of use only when debugging a program.
 Messages that contain information
 normally of use only when debugging a program.

-.PP
+.El
+.Pp
+The
+.Fn openlog
+function
+provides for more specialized processing of the messages sent
+by
+.Fn syslog
+and
+.Fn vsyslog .
+The parameter
+.Fa ident
+is a string that will be prepended to every message.
+The
+.Fa logopt
+argument
+is a bit field specifying logging options, which is formed by
+.Tn OR Ns 'ing
+one or more of the following values:
+.Bl -tag -width LOG_AUTHPRIV
+.It Dv LOG_CONS

 If
 If

-.I syslog
+.Fn syslog

 cannot pass the message to
 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.
-.PP
-If special processing is needed,
-.I 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:
-.IP LOG_PID \w'LOG_WARNING'u+3
-log the process id with each message:
-useful for identifying instantiations of daemons.
-.IP LOG_CONS \w'LOG_WARNING'u+3
-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_ODELAY \w'LOG_WARNING'u+3
-Delay opening the connection to
-.I syslogd
-until the first message is logged.
-Useful for programs that need to manage the
-order in which file descriptors are allocated.
-.PP
+.Xr syslogd
+it will attempt to write the message to the console
+.Pq Dq Pa /dev/console.
+.It Dv LOG_NDELAY 
+Open the connection to
+.Xr 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.
+.It Dv LOG_PERROR
+Write the message to standard error output as well to the system log.
+.It Dv LOG_PID
+Log the process id with each message: useful for identifying
+instantiations of daemons.
+.El
+.Pp

 The
 The

-.I facility
-parameter is encodes a default facility to be assigned to all messages
+.Fa facility
+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
+.Bl -tag -width LOG_AUTHPRIV
+.It Dv LOG_AUTH
+The authorization system:
+.Xr login 1 ,
+.Xr su 1 ,
+.Xr getty 8 ,
+etc.
+.It Dv LOG_AUTHPRIV
+The same as
+.Dv LOG_AUTH ,
+but logged to a file readable only by
+selected individuals.
+.It Dv LOG_CRON
+The clock daemon.
+.It Dv LOG_DAEMON
+System daemons, such as
+.Xr ftpd 8 ,
+.Xr routed 8 ,
+etc., that are not provided for explicitly by other facilities.
+.It Dv 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
-Messages generated by random user processes.
-This is the default if none is specified.
-.IP LOG_MAIL \w'LOG_WARNING'u+3
-The mail system.
-.IP LOG_DAEMON \w'LOG_WARNING'u+3
-System daemons, such as
-.IR lpd (8),
-.IR routed (8),
-etc.
-.IP LOG_AUTH \w'LOG_WARNING'u+3
-The authorization system:
-.IR login (1),
-.IR su (1),
-.IR getty (8),
+.It Dv LOG_LPR
+The line printer spooling system:
+.Xr lpr 1 ,
+.Xr lpc 8 ,
+.Xr lpd 8 ,

 etc.
 etc.

-.IP LOG_LOCAL0 \w'LOG_WARNING'u+3
+.It Dv LOG_MAIL
+The mail system.
+.It Dv LOG_NEWS
+The network news system.
+.It Dv LOG_SYSLOG
+Messages generated internally by
+.Xr syslogd 8 .
+.It Dv LOG_USER
+Messages generated by random user processes.
+This is the default facility identifier if none is specified.
+.It Dv LOG_UUCP
+The uucp system.
+.It Dv LOG_LOCAL0

 Reserved for local use.
 Reserved for local use.

-Similarly for LOG_LOCAL1 through LOG_LOCAL7.
-.PP
-.I Closelog
+Similarly for
+.Dv LOG_LOCAL1
+through
+.Dv LOG_LOCAL7 .
+.El 
+.Pp
+The
+.Fn closelog
+function

 can be used to close the log file.
 can be used to close the log file.

-.PP
-.I Setlogmask
+.Pp
+The
+.Fn setlogmask
+function

 sets the log priority mask to
 sets the log priority mask to

-.I maskpri
+.Fa maskpri

 and returns the previous mask.
 Calls to
 and returns the previous mask.
 Calls to

-.I syslog
-with a priority lower than
-.I maskpri
+.Fn syslog
+with a priority not set in
+.Fa maskpri

 are rejected.
 are rejected.

+The mask for an individual priority
+.Fa pri
+is calculated by the macro
+.Fn LOG_MASK pri ;
+the mask for all priorities up to and including
+.Fa toppri
+is given by the macro
+.Fn LOG_UPTO toppri ; .

 The default allows all priorities to be logged.
 The default allows all priorities to be logged.

-.SH EXAMPLES
-.nf
+.Sh RETURN VALUES
+The routines
+.Fn closelog ,
+.Fn openlog ,
+.Fn syslog
+and
+.Fn vsyslog
+return no value.
+.Pp
+The routine
+.Fn setlogmask
+always returns the previous log mask level.
+.Sh EXAMPLES
+.Bd -literal -offset indent -compact

 syslog(LOG_ALERT, "who: internal error 23");
 
 openlog("ftpd", LOG_PID, LOG_DAEMON);
 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");

-.fi
-.SH "SEE ALSO"
-logger(1),
-syslogd(8)
+.Ed
+.Sh SEE ALSO
+.Xr logger 1 ,
+.Xr syslogd 8
+.Sh HISTORY
+These
+functions appeared in 
+.Bx 4.2 .