xref: /illumos-gate/usr/src/man/man4d/log.4d (revision cb1bb6c32d034ea24e8549ef763c9c2b79413eb8)
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