7524 setting msgid=0 in log.conf makes all messages seem to come from "unix"

Reviewed by: Toomas Soome <tsoome@me.com>
Reviewed by: Garrett D'Amore <garrett@damore.org>
Approved by: Robert Mustacchi <rm@fingolfin.org>

1 files changed, 285 insertions, 258 deletions

diff --git a/usr/src/man/man4d/log.4d b/usr/src/man/man4d/log.4d
index 53c3feb6c8..033db362ac 100644
--- a/usr/src/man/man4d/log.4d
+++ b/usr/src/man/man4d/log.4d
@@ -1,247 +1,308 @@
-'\" te
-.\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
-.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
-.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
-.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH LOG 4D "Mar 11, 1998"
-.SH NAME
-log \- interface to STREAMS error logging and event tracing
-.SH SYNOPSIS
-.LP
-.nf
-\fB#include <sys/strlog.h>\fR
-.fi
-
-.LP
-.nf
-\fB#include <sys/log.h>\fR
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-\fBlog\fR is a STREAMS software device driver that provides an interface for
-console logging and for the STREAMS error logging and event tracing processes
-(see \fBstrerr\fR(8), and \fBstrace\fR(8)). \fBlog\fR presents two separate
-interfaces: a function call interface in the kernel through which STREAMS
-drivers and modules submit \fBlog\fR messages; and a set of  \fBioctl\fR(2)
+.\"
+.\" The contents of this file are subject to the terms of the
+.\" Common Development and Distribution License (the "License").
+.\" You may not use this file except in compliance with the License.
+.\"
+.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
+.\" or http://www.opensolaris.org/os/licensing.
+.\" See the License for the specific language governing permissions
+.\" and limitations under the License.
+.\"
+.\" When distributing Covered Code, include this CDDL HEADER in each
+.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+.\" If applicable, add the following below this CDDL HEADER, with the
+.\" fields enclosed by brackets "[]" replaced with your own identifying
+.\" information: Portions Copyright [yyyy] [name of copyright owner]
+.\"
+.\"
+.\" Copyright 1989 AT&T
+.\" Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
+.\" Copyright 2021 Tintri by DDN, Inc. All rights reserved.
+.\" Copyright 2022 Garrett D'Amore
+.\"
+.Dd July 8, 2022
+.Dt LOG 4D
+.Os
+.Sh NAME
+.Nm log
+.Nd interface to STREAMS error logging and event tracing
+.Sh SYNOPSIS
+.In sys/strlog.h
+.In sys/log.h
+.Sh DESCRIPTION
+.Nm
+is a STREAMS software device driver that provides an interface for console
+logging and for the STREAMS error logging and event tracing processes
+.Po see
+.Xr strerr 8 ,
+and
+.Xr strace 8
+.Pc .
+.Nm
+presents two separate interfaces: a function call interface in the kernel
+through which STREAMS drivers and modules submit log messages; and a set of
+.Xr ioctl 2
 requests and STREAMS messages for interaction with a user level console logger,
 an error logger, a trace logger, or processes that need to submit their own
-\fBlog\fR messages.
-.SS "Kernel Interface"
-.sp
-.LP
-\fBlog\fR messages are generated within the kernel by calls to the function
-\fBstrlog()\fR:
-.sp
-.in +2
-.nf
-strlog(short \fImid\fR,
-    short \fIsid\fR,
-    char \fIlevel\fR,
-    ushort_t \fIflags\fR,
-    char *\fBfmt\fR,
-    unsigned \fIarg1\fR\fB\|.\|.\|.\|
-);\fR
-.fi
-.in -2
-
-.sp
-.LP
-Required definitions are contained in \fB<sys/strlog.h>\fR, \fB<sys/log.h>\fR,
-and \fB<sys/syslog.h>\fR\&. \fImid\fR is the STREAMS module id number for the
-module or driver submitting the \fBlog\fR message. \fIsid\fR is an internal
-sub-id number usually used to identify a particular minor  device of a driver.
-\fIlevel\fR is a tracing level that allows for selective screening out of low
-priority messages from the tracer. \fIflags\fR are any combination of
-\fBSL_ERROR\fR (the message is for the error logger),  \fBSL_TRACE\fR (the
-message is for the tracer), \fBSL_CONSOLE\fR (the message is for the console
-logger), \fBSL_FATAL\fR (advisory notification of a fatal error), and
-\fBSL_NOTIFY\fR (request that a copy of the message be mailed to the system
-administrator). \fIfmt\fR is a  \fBprintf\fR(3C) style format string, except
-that  \fB%s\fR, \fB%e\fR, \fB%E\fR, \fB%g\fR, and  \fB%G\fR conversion
-specifications are not handled. Up to  \fBNLOGARGS\fR (in this release, three)
-numeric or character arguments can be provided.
-.SS "User Interface"
-.sp
-.LP
-\fBlog\fR is implemented as a cloneable device, it clones itself without
-intervention from the system clone device. Each open of \fB/dev/log\fR obtains
-a separate stream to \fBlog\fR. In order to receive \fBlog\fR messages, a
-process must first notify \fBlog\fR whether it is an error logger, trace
-logger, or console logger using a STREAMS  \fBI_STR ioctl\fR call (see below).
-For the console logger, the  \fBI_STR ioctl\fR has an  \fBic_cmd\fR field of
-\fBI_CONSLOG\fR, with no accompanying data. For the error logger, the  \fBI_STR
-ioctl\fR has an  \fBic_cmd\fR field of  \fBI_ERRLOG\fR, with no accompanying
-data. For the trace logger, the  \fBioctl\fR has an  \fBic_cmd\fR field of
-\fBI_TRCLOG\fR, and must be accompanied by a data buffer containing an array of
-one or more struct \fBtrace_ids\fR elements.
-.sp
-.in +2
-.nf
+log messages.
+.Ss Kernel Interface
+Log messages are generated within the kernel by calls to the function
+.Xr strlog 9F .
+.Ss User Interface
+.Nm
+is implemented as a cloneable device, it clones itself without intervention from
+the system clone device.
+Each open of
+.Pa /dev/log
+obtains a separate stream to
+.Nm .
+In order to receive log messages, a process must first notify
+.Nm
+whether it is an error logger, trace logger, or console logger using a STREAMS
+.Dv I_STR
+.Xr ioctl 2
+call (see below).
+For the console logger, the
+.Dv I_STR
+.Xr ioctl 2
+has an
+.Va ic_cmd
+field of
+.Dv I_CONSLOG ,
+with no accompanying data.
+For the error logger, the
+.Dv I_STR
+.Xr ioctl 2
+has an
+.Va ic_cmd
+field of
+.Dv I_ERRLOG ,
+with no accompanying data.
+For the trace logger, the
+.Xr ioctl 2
+has an
+.Va ic_cmd
+field of
+.Dv I_TRCLOG ,
+and must be accompanied by a data buffer containing an array of one or more
+struct
+.Vt trace_ids
+elements.
+.Bd -literal -offset indent
 struct trace_ids {
-    short ti_mid;
-    short ti_sid;
-    char  ti_level;
+	short	ti_mid;
+	short	ti_sid;
+	char	ti_level;
 };
-.fi
-.in -2
-
-.sp
-.LP
-Each \fBtrace_ids\fR structure specifies a \fImid\fR, \fIsid\fR, and
-\fIlevel\fR  from which messages will be accepted. \fBstrlog\fR(9F) will accept
-messages whose \fImid\fR and \fIsid\fR exactly match those in the
-\fBtrace_ids\fR structure, and whose level is less than or equal to the level
-given in the \fBtrace_ids\fR structure. A value of \(mi1 in any of the fields
-of the \fBtrace_ids\fR structure indicates that  any value is accepted for that
-field.
-.sp
-.LP
-Once the logger process has identified itself using the \fBioctl\fR call,
-\fBlog\fR will begin sending up messages subject to the restrictions noted
-above. These messages are obtained using the  \fBgetmsg\fR(2) function. The
-control part of this message contains a \fBlog_ctl\fR structure, which
-specifies the \fImid\fR, \fIsid\fR, \fIlevel\fR, \fIflags\fR, time in  ticks
-since boot that the message was submitted, the corresponding time in seconds
-since Jan. 1, 1970, a sequence number, and a priority. The time in seconds
-since 1970 is provided so that the date and time of the message can be easily
-computed, and the time in ticks since boot is provided so that the relative
-timing of \fBlog\fR messages can be determined.
-.sp
-.in +2
-.nf
+.Ed
+.Pp
+Each
+.Va trace_ids
+structure specifies a
+.Va mid ,
+.Va sid ,
+and
+.Va level
+from which messages will be accepted.
+.Xr strlog 9F
+will accept messages whose
+.Fa mid
+and
+.Fa sid
+exactly match those in the
+.Va trace_ids
+structure, and whose level is less than or equal to the level given in the
+.Va trace_ids
+structure.
+A value of -1 in any of the fields of the
+.Va trace_ids
+structure indicates that any value is accepted for that field.
+.Pp
+Once the logger process has identified itself using the
+.Xr ioctl 2
+call,
+.Nm
+will begin sending up messages subject to the restrictions noted above.
+These messages are obtained using the
+.Xr getmsg 2
+function.
+The control part of this message contains a
+.Va log_ctl
+structure, which specifies the
+.Va mid ,
+.Va sid ,
+.Va level ,
+.Va flags ,
+time in ticks since boot that the message was submitted, the corresponding time
+in seconds since Jan. 1, 1970, a sequence number, and a priority.
+The time in seconds since 1970 is provided so that the date and time of the
+message can be easily computed, and the time in ticks since boot is provided so
+that the relative timing of log messages can be determined.
+.Bd -literal -offset indent
 struct log_ctl {
-    short mid;
-    short sid;
-    char  level;     /* level of message for tracing */
-    short flags;     /* message disposition */
-#if defined(_LP64)  ||  defined(_I32LPx)
-    clock32_t ltime; /* time in machine ticks since boot */
-    time32_t ttime;  /* time in seconds since 1970 */
+	short		mid;
+	short		sid;
+	char		level;	/* level of message for tracing */
+	short		flags;	/* message disposition */
+#if defined(_LP64) || defined(_I32LPx)
+	clock32_t	ltime;	/* time in machine ticks since boot */
+	time32_t	ttime;	/* time in seconds since 1970 */
 #else
-    clock_t ltime;
-    time_t  ttime;
+	clock_t		ltime;
+	time_t		ttime;
 #endif
-    int  seq_no;     /* sequence number */
-    int  pri;        /* priority = (facility|level) */
+	int		seq_no;	/* sequence number */
+	int		pri;	/* priority = (facility|level) */
 };
-.fi
-.in -2
-
-.sp
-.LP
+.Ed
+.Pp
 The priority consists of a priority code and a facility code, found in
-\fB<sys/syslog.h>\fR\&. If \fBSL_CONSOLE\fR is set in \fIflags\fR, the priority
-code is set as follows: If \fBSL_WARN\fR is set, the priority code is set to
-\fBLOG_WARNING\fR; If \fBSL_FATAL\fR is set, the priority code is set to
-\fBLOG_CRIT\fR; If  \fBSL_ERROR\fR is set, the priority code is set to
-\fBLOG_ERR\fR; If  \fBSL_NOTE\fR is set, the priority code is set to
-\fBLOG_NOTICE\fR; If  \fBSL_TRACE\fR is set, the priority code is set to
-\fBLOG_DEBUG\fR; If only  \fBSL_CONSOLE\fR is set, the priority code is set to
-\fBLOG_INFO\fR. Messages originating from the kernel have the facility code set
-to \fBLOG_KERN\fR. Most messages originating from user processes will have the
-facility code set to \fBLOG_USER\fR.
-.sp
-.LP
+.In sys/syslog.h .
+If
+.Dv SL_CONSOLE
+is set in
+.Va flags ,
+the priority code is set as follows:
+.Pp
+.Bl -bullet -compact
+.It
+If
+.Dv SL_WARN
+is set, the priority code is set to
+.Dv LOG_WARNING
+.It
+If
+.Dv SL_FATAL
+is set, the priority code is set to
+.Dv LOG_CRIT
+.It
+If
+.Dv SL_ERROR
+is set, the priority code is set to
+.Dv LOG_ERR
+.It
+If
+.Dv SL_NOTE
+is set, the priority code is set to
+.Dv LOG_NOTICE
+.It
+If
+.Dv SL_TRACE
+is set, the priority code is set to
+.Dv LOG_DEBUG
+.It
+If only
+.Dv SL_CONSOLE
+is set, the priority code is set to
+.Dv LOG_INFO
+.El
+.Pp
+Messages originating from the kernel have the facility code set to
+.Dv LOG_KERN .
+Most messages originating from user processes will have the facility code set to
+.Dv LOG_USER .
+.Pp
 Different sequence numbers are maintained for the error and trace logging
 streams, and are provided so that gaps in the sequence of messages can be
 determined (during times of high message traffic some messages may not be
-delivered by the logger to avoid hogging system resources). The data part of
-the message contains the unexpanded text of the format string (null
-terminated), followed by  \fBNLOGARGS\fR words for the arguments to the format
-string, aligned on the first word boundary following the format string.
-.sp
-.LP
-A process may also send a message of the same structure to \fBlog\fR, even if
-it is not an error or trace logger. The only fields of the \fBlog_ctl\fR
+delivered by the logger to avoid hogging system resources).
+The data part of the message contains the unexpanded text of the format string
+(null terminated), followed by
+.Dv NLOGARGS
+words for the arguments to the format string, aligned on the first word boundary
+following the format string.
+.Pp
+A process may also send a message of the same structure to
+.Nm ,
+even if it is not an error or trace logger.
+The only fields of the
+.Va log_ctl
 structure in the control part of the message that are accepted are the
-\fIlevel\fR, \fIflags\fR, and \fIpri\fR fields; all other fields are filled in
-by \fBlog\fR before being forwarded to the appropriate logger. The data portion
-must contain a null terminated format string, and any arguments (up to
-\fBNLOGARGS\fR) must be packed, 32-bits each,  on the next 32-bit boundary
-following the end of the format string.
-.sp
-.LP
-\fBENXIO\fR is returned for  \fBI_TRCLOG\fR ioctls without any \fBtrace_ids\fR
-structures, or for any unrecognized \fBioctl\fR calls. The driver silently
-ignores incorrectly formatted \fBlog\fR messages sent to the driver by a user
-process (no error results).
-.sp
-.LP
+.Va level ,
+.Va flags ,
+and
+.Va pri
+fields; all other fields are filled in by
+.Nm
+before being forwarded to the appropriate logger.
+The data portion must contain a null terminated format string, and any arguments
+.Po up to
+.Dv NLOGARGS
+.Pc
+must be packed, 32-bits each, on the next 32-bit boundary following the end of
+the format string.
+.Pp
+.Er ENXIO
+is returned for
+.Dv I_TRCLOG
+.Xr ioctl 2
+without any
+.Va trace_ids
+structures, or for any unrecognized
+.Xr ioctl 2
+calls.
+The driver silently ignores incorrectly formatted log messages sent to the
+driver by a user process (no error results).
+.Pp
 Processes that wish to write a message to the console logger may direct their
-output to \fB/dev/conslog\fR, using either \fBwrite\fR(2) or \fBputmsg\fR(2).
-.SS "Driver Configuration"
-.sp
-.LP
+output to
+.Pa /dev/conslog ,
+using either
+.Xr write 2
+or
+.Xr putmsg 2 .
+.Ss Driver Configuration
 The following driver configuration properties may be defined in the
-\fBlog.conf\fR file.
-.sp
-.ne 2
-.na
-\fBmsgid=1\fR
-.ad
-.RS 11n
-If \fBmsgid=1\fR, each message will be preceded by a message ID as described in
-\fBsyslogd\fR(8).
-.RE
-
-.sp
-.ne 2
-.na
-\fBmsgid=0\fR
-.ad
-.RS 11n
- If \fBmsgid=0\fR, message IDs will not be generated. This property is unstable
-and may be removed in a future release.
-.RE
-
-.SH EXAMPLES
-.LP
-\fBExample 1 \fR\fBI_ERRLOG\fR registration.
-.sp
-.in +2
-.nf
+.Pa log.conf
+file:
+.Bl -tag -width "msgid=1"
+.It Cm msgid Ns = Ns Cm 1
+Each message will be preceded by a message ID as described in
+.Xr syslogd 8 .
+.It Cm msgid Ns = Ns Cm 0
+Message IDs will not be generated.
+.El
+.Sh FILES
+.Bl -tag -width "/kernel/drv/log.conf"
+.It Pa /dev/log
+Log driver.
+.It Pa /dev/conslog
+Write only instance of the log driver, for console logging.
+.It Pa /kernel/drv/log.conf
+Log configuration file.
+.El
+.Sh EXAMPLES
+.Bl -tag -width Ds
+.It Sy Example 1 Dv I_ERRLOG No registration .
+.Bd -literal
 struct strioctl ioc;
 ioc.ic_cmd = I_ERRLOG;
-ioc.ic_timout = 0;		/* default timeout (15 secs.) */
+ioc.ic_timout = 0;	/* default timeout (15 secs.) */
 ioc.ic_len = 0;
 ioc.ic_dp = NULL;
 ioctl(log, I_STR, &ioc);
-.fi
-.in -2
-
-.LP
-\fBExample 2 \fR\fBI_TRCLOG\fR registration.
-.sp
-.in +2
-.nf
+.Ed
+.It Sy Example 2 Dv I_TRCLOG No registration .
+.Bd -literal
 struct trace_ids tid[2];
 tid[0].ti_mid = 2;
 tid[0].ti_sid = 0;
 tid[0].ti_level = 1;
 tid[1].ti_mid = 1002;
-tid[1].ti_sid = \(mi1;               /* any sub-id will be allowed */
-tid[1].ti_level = \(mi1;             /* any level will be allowed */
+tid[1].ti_sid = -1;	/* any sub-id will be allowed */
+tid[1].ti_level = -1;	/* any level will be allowed */
 ioc.ic_cmd = I_TRCLOG;
 ioc.ic_timout = 0;
 ioc.ic_len = 2 * sizeof(struct trace_ids);
 ioc.ic_dp = (char *)tid;
 ioctl(log, I_STR, &ioc);
-.fi
-.in -2
-
-.sp
-.LP
-Example of submitting a \fBlog\fR message (no arguments):
-
-.sp
-.in +2
-.nf
+.Ed
+.It Sy Example 3 No Submitting a log message (no arguments)
+.Bd -literal
 struct strbuf ctl, dat;
 struct log_ctl lc;
-char *message = "Don't forget to pick up some milk
-                 on the way home";
+char *message = "Don't forget to pick up some milk "
+    "on the way home";
 ctl.len = ctl.maxlen = sizeof(lc);
 ctl.buf = (char *)&lc;
 dat.len = dat.maxlen = strlen(message);
@@ -249,49 +310,15 @@ dat.buf = message;
 lc.level = 0;
 lc.flags = SL_ERROR|SL_NOTIFY;
 putmsg(log, &ctl, &dat, 0);
-.fi
-.in -2
-
-.SH FILES
-.sp
-.ne 2
-.na
-\fB\fB/dev/log\fR\fR
-.ad
-.RS 24n
-Log driver.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/dev/conslog\fR\fR
-.ad
-.RS 24n
-Write only instance of the log driver, for console logging.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/kernel/drv/log.conf\fR\fR
-.ad
-.RS 24n
-Log configuration file.
-.RE
-
-.SH SEE ALSO
-.sp
-.LP
-.BR getmsg (2),
-.BR ioctl (2),
-.BR putmsg (2),
-.BR write (2),
-.BR Intro (3),
-.BR printf (3C),
-.BR strace (8),
-.BR strerr (8),
-.BR strlog (9F)
-.sp
-.LP
-\fISTREAMS Programming Guide\fR
+.Ed
+.El
+.Sh SEE ALSO
+.Xr getmsg 2 ,
+.Xr ioctl 2 ,
+.Xr putmsg 2 ,
+.Xr write 2 ,
+.Xr strace 8 ,
+.Xr strerr 8 ,
+.Xr strlog 9F
+.Pp
+.Em STREAMS Programming Guide