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.man.txt
+++ new/usr/src/man/man7d/log.7d.man.txt
1 1 LOG(7D) Devices LOG(7D)
2 2
3 -
4 -
5 3 NAME
6 - log - interface to STREAMS error logging and event tracing
4 + log - interface to STREAMS error logging and event tracing
7 5
8 6 SYNOPSIS
9 - #include <sys/strlog.h>
7 + #include <sys/strlog.h>
8 + #include <sys/log.h>
10 9
11 -
12 - #include <sys/log.h>
13 -
14 -
15 10 DESCRIPTION
16 - log is a STREAMS software device driver that provides an interface for
17 - console logging and for the STREAMS error logging and event tracing
18 - processes (see strerr(1M), and strace(1M)). log presents two separate
19 - interfaces: a function call interface in the kernel through which
20 - STREAMS drivers and modules submit log messages; and a set of ioctl(2)
21 - requests and STREAMS messages for interaction with a user level console
22 - logger, an error logger, a trace logger, or processes that need to
23 - submit their own log messages.
11 + log is a STREAMS software device driver that provides an interface for
12 + console logging and for the STREAMS error logging and event tracing
13 + processes (see strerr(1M), and strace(1M)). log presents two separate
14 + interfaces: a function call interface in the kernel through which STREAMS
15 + drivers and modules submit log messages; and a set of ioctl(2) requests
16 + and STREAMS messages for interaction with a user level console logger, an
17 + error logger, a trace logger, or processes that need to submit their own
18 + log messages.
24 19
25 20 Kernel Interface
26 - log messages are generated within the kernel by calls to the function
27 - strlog():
21 + Log messages are generated within the kernel by calls to the function
22 + strlog(9F).
28 23
29 - strlog(short mid,
30 - short sid,
31 - char level,
32 - ushort_t flags,
33 - char *fmt,
34 - unsigned arg1...
35 - );
36 -
37 -
38 -
39 - Required definitions are contained in <sys/strlog.h>, <sys/log.h>, and
40 - <sys/syslog.h>. mid is the STREAMS module id number for the module or
41 - driver submitting the log message. sid is an internal sub-id number
42 - usually used to identify a particular minor device of a driver. level
43 - is a tracing level that allows for selective screening out of low
44 - priority messages from the tracer. flags are any combination of
45 - SL_ERROR (the message is for the error logger), SL_TRACE (the message
46 - is for the tracer), SL_CONSOLE (the message is for the console logger),
47 - SL_FATAL (advisory notification of a fatal error), and SL_NOTIFY
48 - (request that a copy of the message be mailed to the system
49 - administrator). fmt is a printf(3C) style format string, except that
50 - %s, %e, %E, %g, and %G conversion specifications are not handled. Up
51 - to NLOGARGS (in this release, three) numeric or character arguments
52 - can be provided.
53 -
54 24 User Interface
55 - log is implemented as a cloneable device, it clones itself without
56 - intervention from the system clone device. Each open of /dev/log
57 - obtains a separate stream to log. In order to receive log messages, a
58 - process must first notify log whether it is an error logger, trace
59 - logger, or console logger using a STREAMS I_STR ioctl call (see
60 - below). For the console logger, the I_STR ioctl has an ic_cmd field
61 - of I_CONSLOG, with no accompanying data. For the error logger, the
62 - I_STR ioctl has an ic_cmd field of I_ERRLOG, with no accompanying
63 - data. For the trace logger, the ioctl has an ic_cmd field of
64 - I_TRCLOG, and must be accompanied by a data buffer containing an array
65 - of one or more struct trace_ids elements.
25 + log is implemented as a cloneable device, it clones itself without
26 + intervention from the system clone device. Each open of /dev/log obtains
27 + a separate stream to log. In order to receive log messages, a process
28 + must first notify log whether it is an error logger, trace logger, or
29 + console logger using a STREAMS I_STR ioctl(2) call (see below). For the
30 + console logger, the I_STR ioctl(2) has an ic_cmd field of I_CONSLOG, with
31 + no accompanying data. For the error logger, the I_STR ioctl(2) has an
32 + ic_cmd field of I_ERRLOG, with no accompanying data. For the trace
33 + logger, the ioctl(2) has an ic_cmd field of I_TRCLOG, and must be
34 + accompanied by a data buffer containing an array of one or more struct
35 + trace_ids elements.
66 36
67 - struct trace_ids {
68 - short ti_mid;
69 - short ti_sid;
70 - char ti_level;
71 - };
37 + struct trace_ids {
38 + short ti_mid;
39 + short ti_sid;
40 + char ti_level;
41 + };
72 42
43 + Each trace_ids structure specifies a mid, sid, and level from which
44 + messages will be accepted. strlog(9F) will accept messages whose mid and
45 + sid exactly match those in the trace_ids structure, and whose level is
46 + less than or equal to the level given in the trace_ids structure. A
47 + value of -1 in any of the fields of the trace_ids structure indicates
48 + that any value is accepted for that field.
73 49
50 + Once the logger process has identified itself using the ioctl(2) call,
51 + log will begin sending up messages subject to the restrictions noted
52 + above. These messages are obtained using the getmsg(2) function. The
53 + control part of this message contains a log_ctl structure, which
54 + specifies the mid, sid, level, flags, time in ticks since boot that the
55 + message was submitted, the corresponding time in seconds since Jan. 1,
56 + 1970, a sequence number, and a priority. The time in seconds since 1970
57 + is provided so that the date and time of the message can be easily
58 + computed, and the time in ticks since boot is provided so that the
59 + relative timing of log messages can be determined.
74 60
75 - Each trace_ids structure specifies a mid, sid, and level from which
76 - messages will be accepted. strlog(9F) will accept messages whose mid
77 - and sid exactly match those in the trace_ids structure, and whose level
78 - is less than or equal to the level given in the trace_ids structure. A
79 - value of -1 in any of the fields of the trace_ids structure indicates
80 - that any value is accepted for that field.
61 + struct log_ctl {
62 + short mid;
63 + short sid;
64 + char level; /* level of message for tracing */
65 + short flags; /* message disposition */
66 + #if defined(_LP64) || defined(_I32LPx)
67 + clock32_t ltime; /* time in machine ticks since boot */
68 + time32_t ttime; /* time in seconds since 1970 */
69 + #else
70 + clock_t ltime;
71 + time_t ttime;
72 + #endif
73 + int seq_no; /* sequence number */
74 + int pri; /* priority = (facility|level) */
75 + };
81 76
77 + The priority consists of a priority code and a facility code, found in
78 + <sys/syslog.h>. If SL_CONSOLE is set in flags, the priority code is set
79 + as follows:
82 80
83 - Once the logger process has identified itself using the ioctl call, log
84 - will begin sending up messages subject to the restrictions noted above.
85 - These messages are obtained using the getmsg(2) function. The control
86 - part of this message contains a log_ctl structure, which specifies the
87 - mid, sid, level, flags, time in ticks since boot that the message was
88 - submitted, the corresponding time in seconds since Jan. 1, 1970, a
89 - sequence number, and a priority. The time in seconds since 1970 is
90 - provided so that the date and time of the message can be easily
91 - computed, and the time in ticks since boot is provided so that the
92 - relative timing of log messages can be determined.
81 + o If SL_WARN is set, the priority code is set to LOG_WARNING
82 + o If SL_FATAL is set, the priority code is set to LOG_CRIT
83 + o If SL_ERROR is set, the priority code is set to LOG_ERR
84 + o If SL_NOTE is set, the priority code is set to LOG_NOTICE
85 + o If SL_TRACE is set, the priority code is set to LOG_DEBUG
86 + o If only SL_CONSOLE is set, the priority code is set to LOG_INFO
93 87
94 - struct log_ctl {
95 - short mid;
96 - short sid;
97 - char level; /* level of message for tracing */
98 - short flags; /* message disposition */
99 - #if defined(_LP64) || defined(_I32LPx)
100 - clock32_t ltime; /* time in machine ticks since boot */
101 - time32_t ttime; /* time in seconds since 1970 */
102 - #else
103 - clock_t ltime;
104 - time_t ttime;
105 - #endif
106 - int seq_no; /* sequence number */
107 - int pri; /* priority = (facility|level) */
108 - };
88 + Messages originating from the kernel have the facility code set to
89 + LOG_KERN. Most messages originating from user processes will have the
90 + facility code set to LOG_USER.
109 91
92 + Different sequence numbers are maintained for the error and trace logging
93 + streams, and are provided so that gaps in the sequence of messages can be
94 + determined (during times of high message traffic some messages may not be
95 + delivered by the logger to avoid hogging system resources). The data
96 + part of the message contains the unexpanded text of the format string
97 + (null terminated), followed by NLOGARGS words for the arguments to the
98 + format string, aligned on the first word boundary following the format
99 + string.
110 100
101 + A process may also send a message of the same structure to log, even if
102 + it is not an error or trace logger. The only fields of the log_ctl
103 + structure in the control part of the message that are accepted are the
104 + level, flags, and pri fields; all other fields are filled in by log
105 + before being forwarded to the appropriate logger. The data portion must
106 + contain a null terminated format string, and any arguments (up to
107 + NLOGARGS) must be packed, 32-bits each, on the next 32-bit boundary
108 + following the end of the format string.
111 109
112 - The priority consists of a priority code and a facility code, found in
113 - <sys/syslog.h>. If SL_CONSOLE is set in flags, the priority code is set
114 - as follows: If SL_WARN is set, the priority code is set to LOG_WARNING;
115 - If SL_FATAL is set, the priority code is set to LOG_CRIT; If SL_ERROR
116 - is set, the priority code is set to LOG_ERR; If SL_NOTE is set, the
117 - priority code is set to LOG_NOTICE; If SL_TRACE is set, the priority
118 - code is set to LOG_DEBUG; If only SL_CONSOLE is set, the priority code
119 - is set to LOG_INFO. Messages originating from the kernel have the
120 - facility code set to LOG_KERN. Most messages originating from user
121 - processes will have the facility code set to LOG_USER.
110 + ENXIO is returned for I_TRCLOG ioctl(2) without any trace_ids structures,
111 + or for any unrecognized ioctl(2) calls. The driver silently ignores
112 + incorrectly formatted log messages sent to the driver by a user process
113 + (no error results).
122 114
115 + Processes that wish to write a message to the console logger may direct
116 + their output to /dev/conslog, using either write(2) or putmsg(2).
123 117
124 - Different sequence numbers are maintained for the error and trace
125 - logging streams, and are provided so that gaps in the sequence of
126 - messages can be determined (during times of high message traffic some
127 - messages may not be delivered by the logger to avoid hogging system
128 - resources). The data part of the message contains the unexpanded text
129 - of the format string (null terminated), followed by NLOGARGS words for
130 - the arguments to the format string, aligned on the first word boundary
131 - following the format string.
132 -
133 -
134 - A process may also send a message of the same structure to log, even if
135 - it is not an error or trace logger. The only fields of the log_ctl
136 - structure in the control part of the message that are accepted are the
137 - level, flags, and pri fields; all other fields are filled in by log
138 - before being forwarded to the appropriate logger. The data portion must
139 - contain a null terminated format string, and any arguments (up to
140 - NLOGARGS) must be packed, 32-bits each, on the next 32-bit boundary
141 - following the end of the format string.
142 -
143 -
144 - ENXIO is returned for I_TRCLOG ioctls without any trace_ids
145 - structures, or for any unrecognized ioctl calls. The driver silently
146 - ignores incorrectly formatted log messages sent to the driver by a user
147 - process (no error results).
148 -
149 -
150 - Processes that wish to write a message to the console logger may direct
151 - their output to /dev/conslog, using either write(2) or putmsg(2).
152 -
153 118 Driver Configuration
154 - The following driver configuration properties may be defined in the
155 - log.conf file.
119 + The following driver configuration properties may be defined in the
120 + log.conf file:
156 121
157 - msgid=1
158 - If msgid=1, each message will be preceded by a message ID as
159 - described in syslogd(1M).
122 + msgid=1 Each message will be preceded by a message ID as described in
123 + syslogd(1M).
160 124
125 + msgid=0 Message IDs will not be generated.
161 126
162 - msgid=0
163 - If msgid=0, message IDs will not be generated. This
164 - property is unstable and may be removed in a future release.
127 +FILES
128 + /dev/log Log driver.
165 129
130 + /dev/conslog Write only instance of the log driver, for console
131 + logging.
166 132
133 + /kernel/drv/log.conf Log configuration file.
134 +
167 135 EXAMPLES
168 - Example 1 I_ERRLOG registration.
136 + Example 1 I_ERRLOG registration.
169 137
170 - struct strioctl ioc;
171 - ioc.ic_cmd = I_ERRLOG;
172 - ioc.ic_timout = 0; /* default timeout (15 secs.) */
173 - ioc.ic_len = 0;
174 - ioc.ic_dp = NULL;
175 - ioctl(log, I_STR, &ioc);
138 + struct strioctl ioc;
139 + ioc.ic_cmd = I_ERRLOG;
140 + ioc.ic_timout = 0; /* default timeout (15 secs.) */
141 + ioc.ic_len = 0;
142 + ioc.ic_dp = NULL;
143 + ioctl(log, I_STR, &ioc);
176 144
145 + Example 2 I_TRCLOG registration.
177 146
178 - Example 2 I_TRCLOG registration.
147 + struct trace_ids tid[2];
148 + tid[0].ti_mid = 2;
149 + tid[0].ti_sid = 0;
150 + tid[0].ti_level = 1;
151 + tid[1].ti_mid = 1002;
152 + tid[1].ti_sid = -1; /* any sub-id will be allowed */
153 + tid[1].ti_level = -1; /* any level will be allowed */
154 + ioc.ic_cmd = I_TRCLOG;
155 + ioc.ic_timout = 0;
156 + ioc.ic_len = 2 * sizeof(struct trace_ids);
157 + ioc.ic_dp = (char *)tid;
158 + ioctl(log, I_STR, &ioc);
179 159
180 - struct trace_ids tid[2];
181 - tid[0].ti_mid = 2;
182 - tid[0].ti_sid = 0;
183 - tid[0].ti_level = 1;
184 - tid[1].ti_mid = 1002;
185 - tid[1].ti_sid = -1; /* any sub-id will be allowed */
186 - tid[1].ti_level = -1; /* any level will be allowed */
187 - ioc.ic_cmd = I_TRCLOG;
188 - ioc.ic_timout = 0;
189 - ioc.ic_len = 2 * sizeof(struct trace_ids);
190 - ioc.ic_dp = (char *)tid;
191 - ioctl(log, I_STR, &ioc);
160 + Example 3 Submitting a log message (no arguments)
192 161
162 + struct strbuf ctl, dat;
163 + struct log_ctl lc;
164 + char *message = "Don't forget to pick up some milk "
165 + "on the way home";
166 + ctl.len = ctl.maxlen = sizeof(lc);
167 + ctl.buf = (char *)&lc;
168 + dat.len = dat.maxlen = strlen(message);
169 + dat.buf = message;
170 + lc.level = 0;
171 + lc.flags = SL_ERROR|SL_NOTIFY;
172 + putmsg(log, &ctl, &dat, 0);
193 173
194 -
195 - Example of submitting a log message (no arguments):
196 -
197 -
198 - struct strbuf ctl, dat;
199 - struct log_ctl lc;
200 - char *message = "Don't forget to pick up some milk
201 - on the way home";
202 - ctl.len = ctl.maxlen = sizeof(lc);
203 - ctl.buf = (char *)&lc;
204 - dat.len = dat.maxlen = strlen(message);
205 - dat.buf = message;
206 - lc.level = 0;
207 - lc.flags = SL_ERROR|SL_NOTIFY;
208 - putmsg(log, &ctl, &dat, 0);
209 -
210 -
211 -FILES
212 - /dev/log
213 - Log driver.
214 -
215 -
216 - /dev/conslog
217 - Write only instance of the log driver, for
218 - console logging.
219 -
220 -
221 - /kernel/drv/log.conf
222 - Log configuration file.
223 -
224 -
225 174 SEE ALSO
226 - strace(1M), strerr(1M), Intro(3), getmsg(2), ioctl(2), putmsg(2),
227 - write(2), printf(3C), strlog(9F)
175 + strace(1M), strerr(1M), getmsg(2), ioctl(2), putmsg(2), write(2),
176 + strlog(9F)
228 177
178 + STREAMS Programming Guide
229 179
230 - STREAMS Programming Guide
231 -
232 -
233 -
234 - March 11, 1998 LOG(7D)
180 +illumos January 20, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX