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 34 is a STREAMS software device driver that provides an interface for console 35 logging and for the STREAMS error logging and event tracing processes 36 .Po see 37 .Xr strerr 8 , 38 and 39 .Xr strace 8 40 .Pc . 41 .Nm 42 presents two separate interfaces: a function call interface in the kernel 43 through which STREAMS drivers and modules submit log messages; and a set of 44 .Xr ioctl 2 45 requests and STREAMS messages for interaction with a user level console logger, 46 an error logger, a trace logger, or processes that need to submit their own 47 log messages. 48 .Ss Kernel Interface 49 Log messages are generated within the kernel by calls to the function 50 .Xr strlog 9F . 51 .Ss User Interface 52 .Nm 53 is implemented as a cloneable device, it clones itself without intervention from 54 the system clone device. 55 Each open of 56 .Pa /dev/log 57 obtains a separate stream to 58 .Nm . 59 In order to receive log messages, a process must first notify 60 .Nm 61 whether it is an error logger, trace logger, or console logger using a STREAMS 62 .Dv I_STR 63 .Xr ioctl 2 64 call (see below). 65 For the console logger, the 66 .Dv I_STR 67 .Xr ioctl 2 68 has an 69 .Va ic_cmd 70 field of 71 .Dv I_CONSLOG , 72 with no accompanying data. 73 For the error logger, the 74 .Dv I_STR 75 .Xr ioctl 2 76 has an 77 .Va ic_cmd 78 field of 79 .Dv I_ERRLOG , 80 with no accompanying data. 81 For the trace logger, the 82 .Xr ioctl 2 83 has an 84 .Va ic_cmd 85 field of 86 .Dv I_TRCLOG , 87 and must be accompanied by a data buffer containing an array of one or more 88 struct 89 .Vt trace_ids 90 elements. 91 .Bd -literal -offset indent 92 struct trace_ids { 93 short ti_mid; 94 short ti_sid; 95 char ti_level; 96 }; 97 .Ed 98 .Pp 99 Each 100 .Va trace_ids 101 structure specifies a 102 .Va mid , 103 .Va sid , 104 and 105 .Va level 106 from which messages will be accepted. 107 .Xr strlog 9F 108 will accept messages whose 109 .Fa mid 110 and 111 .Fa sid 112 exactly match those in the 113 .Va trace_ids 114 structure, and whose level is less than or equal to the level given in the 115 .Va trace_ids 116 structure. 117 A value of -1 in any of the fields of the 118 .Va trace_ids 119 structure indicates that any value is accepted for that field. 120 .Pp 121 Once the logger process has identified itself using the 122 .Xr ioctl 2 123 call, 124 .Nm 125 will begin sending up messages subject to the restrictions noted above. 126 These messages are obtained using the 127 .Xr getmsg 2 128 function. 129 The control part of this message contains a 130 .Va log_ctl 131 structure, which specifies the 132 .Va mid , 133 .Va sid , 134 .Va level , 135 .Va flags , 136 time in ticks since boot that the message was submitted, the corresponding time 137 in seconds since Jan. 1, 1970, a sequence number, and a priority. 138 The time in seconds since 1970 is provided so that the date and time of the 139 message can be easily computed, and the time in ticks since boot is provided so 140 that the relative timing of log messages can be determined. 141 .Bd -literal -offset indent 142 struct 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 159 The priority consists of a priority code and a facility code, found in 160 .In sys/syslog.h . 161 If 162 .Dv SL_CONSOLE 163 is set in 164 .Va flags , 165 the priority code is set as follows: 166 .Pp 167 .Bl -bullet -compact 168 .It 169 If 170 .Dv SL_WARN 171 is set, the priority code is set to 172 .Dv LOG_WARNING 173 .It 174 If 175 .Dv SL_FATAL 176 is set, the priority code is set to 177 .Dv LOG_CRIT 178 .It 179 If 180 .Dv SL_ERROR 181 is set, the priority code is set to 182 .Dv LOG_ERR 183 .It 184 If 185 .Dv SL_NOTE 186 is set, the priority code is set to 187 .Dv LOG_NOTICE 188 .It 189 If 190 .Dv SL_TRACE 191 is set, the priority code is set to 192 .Dv LOG_DEBUG 193 .It 194 If only 195 .Dv SL_CONSOLE 196 is set, the priority code is set to 197 .Dv LOG_INFO 198 .El 199 .Pp 200 Messages originating from the kernel have the facility code set to 201 .Dv LOG_KERN . 202 Most messages originating from user processes will have the facility code set to 203 .Dv LOG_USER . 204 .Pp 205 Different sequence numbers are maintained for the error and trace logging 206 streams, and are provided so that gaps in the sequence of messages can be 207 determined (during times of high message traffic some messages may not be 208 delivered by the logger to avoid hogging system resources). 209 The data part of the message contains the unexpanded text of the format string 210 (null terminated), followed by 211 .Dv NLOGARGS 212 words for the arguments to the format string, aligned on the first word boundary 213 following the format string. 214 .Pp 215 A process may also send a message of the same structure to 216 .Nm , 217 even if it is not an error or trace logger. 218 The only fields of the 219 .Va log_ctl 220 structure in the control part of the message that are accepted are the 221 .Va level , 222 .Va flags , 223 and 224 .Va pri 225 fields; all other fields are filled in by 226 .Nm 227 before being forwarded to the appropriate logger. 228 The data portion must contain a null terminated format string, and any arguments 229 .Po up to 230 .Dv NLOGARGS 231 .Pc 232 must be packed, 32-bits each, on the next 32-bit boundary following the end of 233 the format string. 234 .Pp 235 .Er ENXIO 236 is returned for 237 .Dv I_TRCLOG 238 .Xr ioctl 2 239 without any 240 .Va trace_ids 241 structures, or for any unrecognized 242 .Xr ioctl 2 243 calls. 244 The driver silently ignores incorrectly formatted log messages sent to the 245 driver by a user process (no error results). 246 .Pp 247 Processes that wish to write a message to the console logger may direct their 248 output to 249 .Pa /dev/conslog , 250 using either 251 .Xr write 2 252 or 253 .Xr putmsg 2 . 254 .Ss Driver Configuration 255 The following driver configuration properties may be defined in the 256 .Pa log.conf 257 file: 258 .Bl -tag -width "msgid=1" 259 .It Cm msgid Ns = Ns Cm 1 260 Each message will be preceded by a message ID as described in 261 .Xr syslogd 8 . 262 .It Cm msgid Ns = Ns Cm 0 263 Message IDs will not be generated. 264 .El 265 .Sh FILES 266 .Bl -tag -width "/kernel/drv/log.conf" 267 .It Pa /dev/log 268 Log driver. 269 .It Pa /dev/conslog 270 Write only instance of the log driver, for console logging. 271 .It Pa /kernel/drv/log.conf 272 Log 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 278 struct strioctl ioc; 279 ioc.ic_cmd = I_ERRLOG; 280 ioc.ic_timout = 0; /* default timeout (15 secs.) */ 281 ioc.ic_len = 0; 282 ioc.ic_dp = NULL; 283 ioctl(log, I_STR, &ioc); 284 .Ed 285 .It Sy Example 2 Dv I_TRCLOG No registration . 286 .Bd -literal 287 struct trace_ids tid[2]; 288 tid[0].ti_mid = 2; 289 tid[0].ti_sid = 0; 290 tid[0].ti_level = 1; 291 tid[1].ti_mid = 1002; 292 tid[1].ti_sid = -1; /* any sub-id will be allowed */ 293 tid[1].ti_level = -1; /* any level will be allowed */ 294 ioc.ic_cmd = I_TRCLOG; 295 ioc.ic_timout = 0; 296 ioc.ic_len = 2 * sizeof(struct trace_ids); 297 ioc.ic_dp = (char *)tid; 298 ioctl(log, I_STR, &ioc); 299 .Ed 300 .It Sy Example 3 No Submitting a log message (no arguments) 301 .Bd -literal 302 struct strbuf ctl, dat; 303 struct log_ctl lc; 304 char *message = "Don't forget to pick up some milk " 305 "on the way home"; 306 ctl.len = ctl.maxlen = sizeof(lc); 307 ctl.buf = (char *)&lc; 308 dat.len = dat.maxlen = strlen(message); 309 dat.buf = message; 310 lc.level = 0; 311 lc.flags = SL_ERROR|SL_NOTIFY; 312 putmsg(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