Print this page
NEX-15926 msgids make log entries harder to read
Reviewed by: Dan Fields <dan.fields@nexenta.com>
Reviewed by: Roman Strashkin <roman.strashkin@nexenta.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7d/log.7d
+++ new/usr/src/man/man7d/log.7d
1 -'\" te
2 -.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved
3 -.\" 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.
4 -.\" 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.
5 -.\" 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]
6 -.TH LOG 7D "Mar 11, 1998"
7 -.SH NAME
8 -log \- interface to STREAMS error logging and event tracing
9 -.SH SYNOPSIS
10 -.LP
11 -.nf
12 -\fB#include <sys/strlog.h>\fR
13 -.fi
14 -
15 -.LP
16 -.nf
17 -\fB#include <sys/log.h>\fR
18 -.fi
19 -
20 -.SH DESCRIPTION
21 -.sp
22 -.LP
23 -\fBlog\fR is a STREAMS software device driver that provides an interface for
24 -console logging and for the STREAMS error logging and event tracing processes
25 -(see \fBstrerr\fR(1M), and \fBstrace\fR(1M)). \fBlog\fR presents two separate
26 -interfaces: a function call interface in the kernel through which STREAMS
27 -drivers and modules submit \fBlog\fR messages; and a set of \fBioctl\fR(2)
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 2018 Nexenta Systems, Inc.
21 +.\"
22 +.Dd January 20, 2018
23 +.Dt LOG 7D
24 +.Os
25 +.Sh NAME
26 +.Nm log
27 +.Nd interface to STREAMS error logging and event tracing
28 +.Sh SYNOPSIS
29 +.In sys/strlog.h
30 +.In sys/log.h
31 +.Sh DESCRIPTION
32 +.Nm
33 +is a STREAMS software device driver that provides an interface for console
34 +logging and for the STREAMS error logging and event tracing processes
35 +.Po see
36 +.Xr strerr 1M ,
37 +and
38 +.Xr strace 1M
39 +.Pc .
40 +.Nm
41 +presents two separate interfaces: a function call interface in the kernel
42 +through which STREAMS drivers and modules submit log messages; and a set of
43 +.Xr ioctl 2
28 44 requests and STREAMS messages for interaction with a user level console logger,
29 45 an error logger, a trace logger, or processes that need to submit their own
30 -\fBlog\fR messages.
31 -.SS "Kernel Interface"
32 -.sp
33 -.LP
34 -\fBlog\fR messages are generated within the kernel by calls to the function
35 -\fBstrlog()\fR:
36 -.sp
37 -.in +2
38 -.nf
39 -strlog(short \fImid\fR,
40 - short \fIsid\fR,
41 - char \fIlevel\fR,
42 - ushort_t \fIflags\fR,
43 - char *\fBfmt\fR,
44 - unsigned \fIarg1\fR\fB\|.\|.\|.\|
45 -);\fR
46 -.fi
47 -.in -2
48 -
49 -.sp
50 -.LP
51 -Required definitions are contained in \fB<sys/strlog.h>\fR, \fB<sys/log.h>\fR,
52 -and \fB<sys/syslog.h>\fR\&. \fImid\fR is the STREAMS module id number for the
53 -module or driver submitting the \fBlog\fR message. \fIsid\fR is an internal
54 -sub-id number usually used to identify a particular minor device of a driver.
55 -\fIlevel\fR is a tracing level that allows for selective screening out of low
56 -priority messages from the tracer. \fIflags\fR are any combination of
57 -\fBSL_ERROR\fR (the message is for the error logger), \fBSL_TRACE\fR (the
58 -message is for the tracer), \fBSL_CONSOLE\fR (the message is for the console
59 -logger), \fBSL_FATAL\fR (advisory notification of a fatal error), and
60 -\fBSL_NOTIFY\fR (request that a copy of the message be mailed to the system
61 -administrator). \fIfmt\fR is a \fBprintf\fR(3C) style format string, except
62 -that \fB%s\fR, \fB%e\fR, \fB%E\fR, \fB%g\fR, and \fB%G\fR conversion
63 -specifications are not handled. Up to \fBNLOGARGS\fR (in this release, three)
64 -numeric or character arguments can be provided.
65 -.SS "User Interface"
66 -.sp
67 -.LP
68 -\fBlog\fR is implemented as a cloneable device, it clones itself without
69 -intervention from the system clone device. Each open of \fB/dev/log\fR obtains
70 -a separate stream to \fBlog\fR. In order to receive \fBlog\fR messages, a
71 -process must first notify \fBlog\fR whether it is an error logger, trace
72 -logger, or console logger using a STREAMS \fBI_STR ioctl\fR call (see below).
73 -For the console logger, the \fBI_STR ioctl\fR has an \fBic_cmd\fR field of
74 -\fBI_CONSLOG\fR, with no accompanying data. For the error logger, the \fBI_STR
75 -ioctl\fR has an \fBic_cmd\fR field of \fBI_ERRLOG\fR, with no accompanying
76 -data. For the trace logger, the \fBioctl\fR has an \fBic_cmd\fR field of
77 -\fBI_TRCLOG\fR, and must be accompanied by a data buffer containing an array of
78 -one or more struct \fBtrace_ids\fR elements.
79 -.sp
80 -.in +2
81 -.nf
46 +log messages.
47 +.Ss Kernel Interface
48 +Log messages are generated within the kernel by calls to the function
49 +.Xr strlog 9F .
50 +.Ss User Interface
51 +.Nm
52 +is implemented as a cloneable device, it clones itself without intervention from
53 +the system clone device.
54 +Each open of
55 +.Pa /dev/log
56 +obtains a separate stream to
57 +.Nm .
58 +In order to receive log messages, a process must first notify
59 +.Nm
60 +whether it is an error logger, trace logger, or console logger using a STREAMS
61 +.Dv I_STR
62 +.Xr ioctl 2
63 +call (see below).
64 +For the console logger, the
65 +.Dv I_STR
66 +.Xr ioctl 2
67 +has an
68 +.Va ic_cmd
69 +field of
70 +.Dv I_CONSLOG ,
71 +with no accompanying data.
72 +For the error logger, the
73 +.Dv I_STR
74 +.Xr ioctl 2
75 +has an
76 +.Va ic_cmd
77 +field of
78 +.Dv I_ERRLOG ,
79 +with no accompanying data.
80 +For the trace logger, the
81 +.Xr ioctl 2
82 +has an
83 +.Va ic_cmd
84 +field of
85 +.Dv I_TRCLOG ,
86 +and must be accompanied by a data buffer containing an array of one or more
87 +struct
88 +.Vt trace_ids
89 +elements.
90 +.Bd -literal -offset indent
82 91 struct trace_ids {
83 - short ti_mid;
84 - short ti_sid;
85 - char ti_level;
92 + short ti_mid;
93 + short ti_sid;
94 + char ti_level;
86 95 };
87 -.fi
88 -.in -2
89 -
90 -.sp
91 -.LP
92 -Each \fBtrace_ids\fR structure specifies a \fImid\fR, \fIsid\fR, and
93 -\fIlevel\fR from which messages will be accepted. \fBstrlog\fR(9F) will accept
94 -messages whose \fImid\fR and \fIsid\fR exactly match those in the
95 -\fBtrace_ids\fR structure, and whose level is less than or equal to the level
96 -given in the \fBtrace_ids\fR structure. A value of \(mi1 in any of the fields
97 -of the \fBtrace_ids\fR structure indicates that any value is accepted for that
98 -field.
99 -.sp
100 -.LP
101 -Once the logger process has identified itself using the \fBioctl\fR call,
102 -\fBlog\fR will begin sending up messages subject to the restrictions noted
103 -above. These messages are obtained using the \fBgetmsg\fR(2) function. The
104 -control part of this message contains a \fBlog_ctl\fR structure, which
105 -specifies the \fImid\fR, \fIsid\fR, \fIlevel\fR, \fIflags\fR, time in ticks
106 -since boot that the message was submitted, the corresponding time in seconds
107 -since Jan. 1, 1970, a sequence number, and a priority. The time in seconds
108 -since 1970 is provided so that the date and time of the message can be easily
109 -computed, and the time in ticks since boot is provided so that the relative
110 -timing of \fBlog\fR messages can be determined.
111 -.sp
112 -.in +2
113 -.nf
96 +.Ed
97 +.Pp
98 +Each
99 +.Va trace_ids
100 +structure specifies a
101 +.Va mid ,
102 +.Va sid ,
103 +and
104 +.Va level
105 +from which messages will be accepted.
106 +.Xr strlog 9F
107 +will accept messages whose
108 +.Fa mid
109 +and
110 +.Fa sid
111 +exactly match those in the
112 +.Va trace_ids
113 +structure, and whose level is less than or equal to the level given in the
114 +.Va trace_ids
115 +structure.
116 +A value of -1 in any of the fields of the
117 +.Va trace_ids
118 +structure indicates that any value is accepted for that field.
119 +.Pp
120 +Once the logger process has identified itself using the
121 +.Xr ioctl 2
122 +call,
123 +.Nm
124 +will begin sending up messages subject to the restrictions noted above.
125 +These messages are obtained using the
126 +.Xr getmsg 2
127 +function.
128 +The control part of this message contains a
129 +.Va log_ctl
130 +structure, which specifies the
131 +.Va mid ,
132 +.Va sid ,
133 +.Va level ,
134 +.Va flags ,
135 +time in ticks since boot that the message was submitted, the corresponding time
136 +in seconds since Jan. 1, 1970, a sequence number, and a priority.
137 +The time in seconds since 1970 is provided so that the date and time of the
138 +message can be easily computed, and the time in ticks since boot is provided so
139 +that the relative timing of log messages can be determined.
140 +.Bd -literal -offset indent
114 141 struct log_ctl {
115 - short mid;
116 - short sid;
117 - char level; /* level of message for tracing */
118 - short flags; /* message disposition */
119 -#if defined(_LP64) || defined(_I32LPx)
120 - clock32_t ltime; /* time in machine ticks since boot */
121 - time32_t ttime; /* time in seconds since 1970 */
142 + short mid;
143 + short sid;
144 + char level; /* level of message for tracing */
145 + short flags; /* message disposition */
146 +#if defined(_LP64) || defined(_I32LPx)
147 + clock32_t ltime; /* time in machine ticks since boot */
148 + time32_t ttime; /* time in seconds since 1970 */
122 149 #else
123 - clock_t ltime;
124 - time_t ttime;
150 + clock_t ltime;
151 + time_t ttime;
125 152 #endif
126 - int seq_no; /* sequence number */
127 - int pri; /* priority = (facility|level) */
153 + int seq_no; /* sequence number */
154 + int pri; /* priority = (facility|level) */
128 155 };
129 -.fi
130 -.in -2
131 -
132 -.sp
133 -.LP
156 +.Ed
157 +.Pp
134 158 The priority consists of a priority code and a facility code, found in
135 -\fB<sys/syslog.h>\fR\&. If \fBSL_CONSOLE\fR is set in \fIflags\fR, the priority
136 -code is set as follows: If \fBSL_WARN\fR is set, the priority code is set to
137 -\fBLOG_WARNING\fR; If \fBSL_FATAL\fR is set, the priority code is set to
138 -\fBLOG_CRIT\fR; If \fBSL_ERROR\fR is set, the priority code is set to
139 -\fBLOG_ERR\fR; If \fBSL_NOTE\fR is set, the priority code is set to
140 -\fBLOG_NOTICE\fR; If \fBSL_TRACE\fR is set, the priority code is set to
141 -\fBLOG_DEBUG\fR; If only \fBSL_CONSOLE\fR is set, the priority code is set to
142 -\fBLOG_INFO\fR. Messages originating from the kernel have the facility code set
143 -to \fBLOG_KERN\fR. Most messages originating from user processes will have the
144 -facility code set to \fBLOG_USER\fR.
145 -.sp
146 -.LP
159 +.In sys/syslog.h .
160 +If
161 +.Dv SL_CONSOLE
162 +is set in
163 +.Va flags ,
164 +the priority code is set as follows:
165 +.Pp
166 +.Bl -bullet -compact
167 +.It
168 +If
169 +.Dv SL_WARN
170 +is set, the priority code is set to
171 +.Dv LOG_WARNING
172 +.It
173 +If
174 +.Dv SL_FATAL
175 +is set, the priority code is set to
176 +.Dv LOG_CRIT
177 +.It
178 +If
179 +.Dv SL_ERROR
180 +is set, the priority code is set to
181 +.Dv LOG_ERR
182 +.It
183 +If
184 +.Dv SL_NOTE
185 +is set, the priority code is set to
186 +.Dv LOG_NOTICE
187 +.It
188 +If
189 +.Dv SL_TRACE
190 +is set, the priority code is set to
191 +.Dv LOG_DEBUG
192 +.It
193 +If only
194 +.Dv SL_CONSOLE
195 +is set, the priority code is set to
196 +.Dv LOG_INFO
197 +.El
198 +.Pp
199 +Messages originating from the kernel have the facility code set to
200 +.Dv LOG_KERN .
201 +Most messages originating from user processes will have the facility code set to
202 +.Dv LOG_USER .
203 +.Pp
147 204 Different sequence numbers are maintained for the error and trace logging
148 205 streams, and are provided so that gaps in the sequence of messages can be
149 206 determined (during times of high message traffic some messages may not be
150 -delivered by the logger to avoid hogging system resources). The data part of
151 -the message contains the unexpanded text of the format string (null
152 -terminated), followed by \fBNLOGARGS\fR words for the arguments to the format
153 -string, aligned on the first word boundary following the format string.
154 -.sp
155 -.LP
156 -A process may also send a message of the same structure to \fBlog\fR, even if
157 -it is not an error or trace logger. The only fields of the \fBlog_ctl\fR
207 +delivered by the logger to avoid hogging system resources).
208 +The data part of the message contains the unexpanded text of the format string
209 +(null terminated), followed by
210 +.Dv NLOGARGS
211 +words for the arguments to the format string, aligned on the first word boundary
212 +following the format string.
213 +.Pp
214 +A process may also send a message of the same structure to
215 +.Nm ,
216 +even if it is not an error or trace logger.
217 +The only fields of the
218 +.Va log_ctl
158 219 structure in the control part of the message that are accepted are the
159 -\fIlevel\fR, \fIflags\fR, and \fIpri\fR fields; all other fields are filled in
160 -by \fBlog\fR before being forwarded to the appropriate logger. The data portion
161 -must contain a null terminated format string, and any arguments (up to
162 -\fBNLOGARGS\fR) must be packed, 32-bits each, on the next 32-bit boundary
163 -following the end of the format string.
164 -.sp
165 -.LP
166 -\fBENXIO\fR is returned for \fBI_TRCLOG\fR ioctls without any \fBtrace_ids\fR
167 -structures, or for any unrecognized \fBioctl\fR calls. The driver silently
168 -ignores incorrectly formatted \fBlog\fR messages sent to the driver by a user
169 -process (no error results).
170 -.sp
171 -.LP
220 +.Va level ,
221 +.Va flags ,
222 +and
223 +.Va pri
224 +fields; all other fields are filled in by
225 +.Nm
226 +before being forwarded to the appropriate logger.
227 +The data portion must contain a null terminated format string, and any arguments
228 +.Po up to
229 +.Dv NLOGARGS
230 +.Pc
231 +must be packed, 32-bits each, on the next 32-bit boundary following the end of
232 +the format string.
233 +.Pp
234 +.Er ENXIO
235 +is returned for
236 +.Dv I_TRCLOG
237 +.Xr ioctl 2
238 +without any
239 +.Va trace_ids
240 +structures, or for any unrecognized
241 +.Xr ioctl 2
242 +calls.
243 +The driver silently ignores incorrectly formatted log messages sent to the
244 +driver by a user process (no error results).
245 +.Pp
172 246 Processes that wish to write a message to the console logger may direct their
173 -output to \fB/dev/conslog\fR, using either \fBwrite\fR(2) or \fBputmsg\fR(2).
174 -.SS "Driver Configuration"
175 -.sp
176 -.LP
247 +output to
248 +.Pa /dev/conslog ,
249 +using either
250 +.Xr write 2
251 +or
252 +.Xr putmsg 2 .
253 +.Ss Driver Configuration
177 254 The following driver configuration properties may be defined in the
178 -\fBlog.conf\fR file.
179 -.sp
180 -.ne 2
181 -.na
182 -\fBmsgid=1\fR
183 -.ad
184 -.RS 11n
185 -If \fBmsgid=1\fR, each message will be preceded by a message ID as described in
186 -\fBsyslogd\fR(1M).
187 -.RE
188 -
189 -.sp
190 -.ne 2
191 -.na
192 -\fBmsgid=0\fR
193 -.ad
194 -.RS 11n
195 - If \fBmsgid=0\fR, message IDs will not be generated. This property is unstable
196 -and may be removed in a future release.
197 -.RE
198 -
199 -.SH EXAMPLES
200 -.LP
201 -\fBExample 1 \fR\fBI_ERRLOG\fR registration.
202 -.sp
203 -.in +2
204 -.nf
255 +.Pa log.conf
256 +file:
257 +.Bl -tag -width "msgid=1"
258 +.It Cm msgid Ns = Ns Cm 1
259 +Each message will be preceded by a message ID as described in
260 +.Xr syslogd 1M .
261 +.It Cm msgid Ns = Ns Cm 0
262 +Message IDs will not be generated.
263 +.El
264 +.Sh FILES
265 +.Bl -tag -width "/kernel/drv/log.conf"
266 +.It Pa /dev/log
267 +Log driver.
268 +.It Pa /dev/conslog
269 +Write only instance of the log driver, for console logging.
270 +.It Pa /kernel/drv/log.conf
271 +Log configuration file.
272 +.El
273 +.Sh EXAMPLES
274 +.Bl -tag -width Ds
275 +.It Sy Example 1 Dv I_ERRLOG No registration.
276 +.Bd -literal
205 277 struct strioctl ioc;
206 278 ioc.ic_cmd = I_ERRLOG;
207 -ioc.ic_timout = 0; /* default timeout (15 secs.) */
279 +ioc.ic_timout = 0; /* default timeout (15 secs.) */
208 280 ioc.ic_len = 0;
209 281 ioc.ic_dp = NULL;
210 282 ioctl(log, I_STR, &ioc);
211 -.fi
212 -.in -2
213 -
214 -.LP
215 -\fBExample 2 \fR\fBI_TRCLOG\fR registration.
216 -.sp
217 -.in +2
218 -.nf
283 +.Ed
284 +.It Sy Example 2 Dv I_TRCLOG No registration.
285 +.Bd -literal
219 286 struct trace_ids tid[2];
220 287 tid[0].ti_mid = 2;
221 288 tid[0].ti_sid = 0;
222 289 tid[0].ti_level = 1;
223 290 tid[1].ti_mid = 1002;
224 -tid[1].ti_sid = \(mi1; /* any sub-id will be allowed */
225 -tid[1].ti_level = \(mi1; /* any level will be allowed */
291 +tid[1].ti_sid = -1; /* any sub-id will be allowed */
292 +tid[1].ti_level = -1; /* any level will be allowed */
226 293 ioc.ic_cmd = I_TRCLOG;
227 294 ioc.ic_timout = 0;
228 295 ioc.ic_len = 2 * sizeof(struct trace_ids);
229 296 ioc.ic_dp = (char *)tid;
230 297 ioctl(log, I_STR, &ioc);
231 -.fi
232 -.in -2
233 -
234 -.sp
235 -.LP
236 -Example of submitting a \fBlog\fR message (no arguments):
237 -
238 -.sp
239 -.in +2
240 -.nf
298 +.Ed
299 +.It Sy Example 3 No Submitting a log message (no arguments)
300 +.Bd -literal
241 301 struct strbuf ctl, dat;
242 302 struct log_ctl lc;
243 -char *message = "Don't forget to pick up some milk
244 - on the way home";
303 +char *message = "Don't forget to pick up some milk "
304 + "on the way home";
245 305 ctl.len = ctl.maxlen = sizeof(lc);
246 306 ctl.buf = (char *)&lc;
247 307 dat.len = dat.maxlen = strlen(message);
248 308 dat.buf = message;
249 309 lc.level = 0;
250 310 lc.flags = SL_ERROR|SL_NOTIFY;
251 311 putmsg(log, &ctl, &dat, 0);
252 -.fi
253 -.in -2
254 -
255 -.SH FILES
256 -.sp
257 -.ne 2
258 -.na
259 -\fB\fB/dev/log\fR\fR
260 -.ad
261 -.RS 24n
262 -Log driver.
263 -.RE
264 -
265 -.sp
266 -.ne 2
267 -.na
268 -\fB\fB/dev/conslog\fR\fR
269 -.ad
270 -.RS 24n
271 -Write only instance of the log driver, for console logging.
272 -.RE
273 -
274 -.sp
275 -.ne 2
276 -.na
277 -\fB\fB/kernel/drv/log.conf\fR\fR
278 -.ad
279 -.RS 24n
280 -Log configuration file.
281 -.RE
282 -
283 -.SH SEE ALSO
284 -.sp
285 -.LP
286 -\fBstrace\fR(1M), \fBstrerr\fR(1M), \fBIntro\fR(3), \fBgetmsg\fR(2),
287 -\fBioctl\fR(2), \fBputmsg\fR(2), \fBwrite\fR(2), \fBprintf\fR(3C),
288 -\fBstrlog\fR(9F)
289 -.sp
290 -.LP
291 -\fISTREAMS Programming Guide\fR
312 +.Ed
313 +.El
314 +.Sh SEE ALSO
315 +.Xr strace 1M ,
316 +.Xr strerr 1M ,
317 +.Xr getmsg 2 ,
318 +.Xr ioctl 2 ,
319 +.Xr putmsg 2 ,
320 +.Xr write 2 ,
321 +.Xr strlog 9F
322 +.Pp
323 +.Em STREAMS Programming Guide
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX