1.\" 2.\" The contents of this file are subject to the terms of the 3.\" Common Development and Distribution License (the "License"). 4.\" You may not use this file except in compliance with the License. 5.\" 6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 7.\" or http://www.opensolaris.org/os/licensing. 8.\" See the License for the specific language governing permissions 9.\" and limitations under the License. 10.\" 11.\" When distributing Covered Code, include this CDDL HEADER in each 12.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 13.\" If applicable, add the following below this CDDL HEADER, with the 14.\" fields enclosed by brackets "[]" replaced with your own identifying 15.\" information: Portions Copyright [yyyy] [name of copyright owner] 16.\" 17.\" 18.\" Copyright 1989 AT&T 19.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved 20.\" Copyright 2021 Tintri by DDN, Inc. All rights reserved. 21.\" Copyright 2022 Garrett D'Amore 22.\" 23.Dd July 8, 2022 24.Dt LOG 4D 25.Os 26.Sh NAME 27.Nm log 28.Nd interface to STREAMS error logging and event tracing 29.Sh SYNOPSIS 30.In sys/strlog.h 31.In sys/log.h 32.Sh DESCRIPTION 33.Nm 34is a STREAMS software device driver that provides an interface for console 35logging and for the STREAMS error logging and event tracing processes 36.Po see 37.Xr strerr 8 , 38and 39.Xr strace 8 40.Pc . 41.Nm 42presents two separate interfaces: a function call interface in the kernel 43through which STREAMS drivers and modules submit log messages; and a set of 44.Xr ioctl 2 45requests and STREAMS messages for interaction with a user level console logger, 46an error logger, a trace logger, or processes that need to submit their own 47log messages. 48.Ss Kernel Interface 49Log messages are generated within the kernel by calls to the function 50.Xr strlog 9F . 51.Ss User Interface 52.Nm 53is implemented as a cloneable device, it clones itself without intervention from 54the system clone device. 55Each open of 56.Pa /dev/log 57obtains a separate stream to 58.Nm . 59In order to receive log messages, a process must first notify 60.Nm 61whether it is an error logger, trace logger, or console logger using a STREAMS 62.Dv I_STR 63.Xr ioctl 2 64call (see below). 65For the console logger, the 66.Dv I_STR 67.Xr ioctl 2 68has an 69.Va ic_cmd 70field of 71.Dv I_CONSLOG , 72with no accompanying data. 73For the error logger, the 74.Dv I_STR 75.Xr ioctl 2 76has an 77.Va ic_cmd 78field of 79.Dv I_ERRLOG , 80with no accompanying data. 81For the trace logger, the 82.Xr ioctl 2 83has an 84.Va ic_cmd 85field of 86.Dv I_TRCLOG , 87and must be accompanied by a data buffer containing an array of one or more 88struct 89.Vt trace_ids 90elements. 91.Bd -literal -offset indent 92struct trace_ids { 93 short ti_mid; 94 short ti_sid; 95 char ti_level; 96}; 97.Ed 98.Pp 99Each 100.Va trace_ids 101structure specifies a 102.Va mid , 103.Va sid , 104and 105.Va level 106from which messages will be accepted. 107.Xr strlog 9F 108will accept messages whose 109.Fa mid 110and 111.Fa sid 112exactly match those in the 113.Va trace_ids 114structure, and whose level is less than or equal to the level given in the 115.Va trace_ids 116structure. 117A value of -1 in any of the fields of the 118.Va trace_ids 119structure indicates that any value is accepted for that field. 120.Pp 121Once the logger process has identified itself using the 122.Xr ioctl 2 123call, 124.Nm 125will begin sending up messages subject to the restrictions noted above. 126These messages are obtained using the 127.Xr getmsg 2 128function. 129The control part of this message contains a 130.Va log_ctl 131structure, which specifies the 132.Va mid , 133.Va sid , 134.Va level , 135.Va flags , 136time in ticks since boot that the message was submitted, the corresponding time 137in seconds since Jan. 1, 1970, a sequence number, and a priority. 138The time in seconds since 1970 is provided so that the date and time of the 139message can be easily computed, and the time in ticks since boot is provided so 140that the relative timing of log messages can be determined. 141.Bd -literal -offset indent 142struct log_ctl { 143 short mid; 144 short sid; 145 char level; /* level of message for tracing */ 146 short flags; /* message disposition */ 147#if defined(_LP64) || defined(_I32LPx) 148 clock32_t ltime; /* time in machine ticks since boot */ 149 time32_t ttime; /* time in seconds since 1970 */ 150#else 151 clock_t ltime; 152 time_t ttime; 153#endif 154 int seq_no; /* sequence number */ 155 int pri; /* priority = (facility|level) */ 156}; 157.Ed 158.Pp 159The priority consists of a priority code and a facility code, found in 160.In sys/syslog.h . 161If 162.Dv SL_CONSOLE 163is set in 164.Va flags , 165the priority code is set as follows: 166.Pp 167.Bl -bullet -compact 168.It 169If 170.Dv SL_WARN 171is set, the priority code is set to 172.Dv LOG_WARNING 173.It 174If 175.Dv SL_FATAL 176is set, the priority code is set to 177.Dv LOG_CRIT 178.It 179If 180.Dv SL_ERROR 181is set, the priority code is set to 182.Dv LOG_ERR 183.It 184If 185.Dv SL_NOTE 186is set, the priority code is set to 187.Dv LOG_NOTICE 188.It 189If 190.Dv SL_TRACE 191is set, the priority code is set to 192.Dv LOG_DEBUG 193.It 194If only 195.Dv SL_CONSOLE 196is set, the priority code is set to 197.Dv LOG_INFO 198.El 199.Pp 200Messages originating from the kernel have the facility code set to 201.Dv LOG_KERN . 202Most messages originating from user processes will have the facility code set to 203.Dv LOG_USER . 204.Pp 205Different sequence numbers are maintained for the error and trace logging 206streams, and are provided so that gaps in the sequence of messages can be 207determined (during times of high message traffic some messages may not be 208delivered by the logger to avoid hogging system resources). 209The data part of the message contains the unexpanded text of the format string 210(null terminated), followed by 211.Dv NLOGARGS 212words for the arguments to the format string, aligned on the first word boundary 213following the format string. 214.Pp 215A process may also send a message of the same structure to 216.Nm , 217even if it is not an error or trace logger. 218The only fields of the 219.Va log_ctl 220structure in the control part of the message that are accepted are the 221.Va level , 222.Va flags , 223and 224.Va pri 225fields; all other fields are filled in by 226.Nm 227before being forwarded to the appropriate logger. 228The data portion must contain a null terminated format string, and any arguments 229.Po up to 230.Dv NLOGARGS 231.Pc 232must be packed, 32-bits each, on the next 32-bit boundary following the end of 233the format string. 234.Pp 235.Er ENXIO 236is returned for 237.Dv I_TRCLOG 238.Xr ioctl 2 239without any 240.Va trace_ids 241structures, or for any unrecognized 242.Xr ioctl 2 243calls. 244The driver silently ignores incorrectly formatted log messages sent to the 245driver by a user process (no error results). 246.Pp 247Processes that wish to write a message to the console logger may direct their 248output to 249.Pa /dev/conslog , 250using either 251.Xr write 2 252or 253.Xr putmsg 2 . 254.Ss Driver Configuration 255The following driver configuration properties may be defined in the 256.Pa log.conf 257file: 258.Bl -tag -width "msgid=1" 259.It Cm msgid Ns = Ns Cm 1 260Each message will be preceded by a message ID as described in 261.Xr syslogd 8 . 262.It Cm msgid Ns = Ns Cm 0 263Message IDs will not be generated. 264.El 265.Sh FILES 266.Bl -tag -width "/kernel/drv/log.conf" 267.It Pa /dev/log 268Log driver. 269.It Pa /dev/conslog 270Write only instance of the log driver, for console logging. 271.It Pa /kernel/drv/log.conf 272Log configuration file. 273.El 274.Sh EXAMPLES 275.Bl -tag -width Ds 276.It Sy Example 1 Dv I_ERRLOG No registration . 277.Bd -literal 278struct strioctl ioc; 279ioc.ic_cmd = I_ERRLOG; 280ioc.ic_timout = 0; /* default timeout (15 secs.) */ 281ioc.ic_len = 0; 282ioc.ic_dp = NULL; 283ioctl(log, I_STR, &ioc); 284.Ed 285.It Sy Example 2 Dv I_TRCLOG No registration . 286.Bd -literal 287struct trace_ids tid[2]; 288tid[0].ti_mid = 2; 289tid[0].ti_sid = 0; 290tid[0].ti_level = 1; 291tid[1].ti_mid = 1002; 292tid[1].ti_sid = -1; /* any sub-id will be allowed */ 293tid[1].ti_level = -1; /* any level will be allowed */ 294ioc.ic_cmd = I_TRCLOG; 295ioc.ic_timout = 0; 296ioc.ic_len = 2 * sizeof(struct trace_ids); 297ioc.ic_dp = (char *)tid; 298ioctl(log, I_STR, &ioc); 299.Ed 300.It Sy Example 3 No Submitting a log message (no arguments) 301.Bd -literal 302struct strbuf ctl, dat; 303struct log_ctl lc; 304char *message = "Don't forget to pick up some milk " 305 "on the way home"; 306ctl.len = ctl.maxlen = sizeof(lc); 307ctl.buf = (char *)&lc; 308dat.len = dat.maxlen = strlen(message); 309dat.buf = message; 310lc.level = 0; 311lc.flags = SL_ERROR|SL_NOTIFY; 312putmsg(log, &ctl, &dat, 0); 313.Ed 314.El 315.Sh SEE ALSO 316.Xr getmsg 2 , 317.Xr ioctl 2 , 318.Xr putmsg 2 , 319.Xr write 2 , 320.Xr strace 8 , 321.Xr strerr 8 , 322.Xr strlog 9F 323.Pp 324.Em STREAMS Programming Guide 325