.\"
.\" 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
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;
};
.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 */
#else
	clock_t		ltime;
	time_t		ttime;
#endif
	int		seq_no;	/* sequence number */
	int		pri;	/* priority = (facility|level) */
};
.Ed
.Pp
The priority consists of a priority code and a facility code, found in
.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
.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
.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
.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
.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_len = 0;
ioc.ic_dp = NULL;
ioctl(log, I_STR, &ioc);
.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 = -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);
.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";
ctl.len = ctl.maxlen = sizeof(lc);
ctl.buf = (char *)&lc;
dat.len = dat.maxlen = strlen(message);
dat.buf = message;
lc.level = 0;
lc.flags = SL_ERROR|SL_NOTIFY;
putmsg(log, &ctl, &dat, 0);
.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