1 LOG(7D) Devices LOG(7D)
2
3
4
5 NAME
6 log - interface to STREAMS error logging and event tracing
7
8 SYNOPSIS
9 #include <sys/strlog.h>
10
11
12 #include <sys/log.h>
13
14
15 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.
24
25 Kernel Interface
26 log messages are generated within the kernel by calls to the function
27 strlog():
28
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 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.
66
67 struct trace_ids {
68 short ti_mid;
69 short ti_sid;
70 char ti_level;
71 };
72
73
74
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.
81
82
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.
93
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 };
109
110
111
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.
122
123
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 Driver Configuration
154 The following driver configuration properties may be defined in the
155 log.conf file.
156
157 msgid=1
158 If msgid=1, each message will be preceded by a message ID as
159 described in syslogd(1M).
160
161
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.
165
166
167 EXAMPLES
168 Example 1 I_ERRLOG registration.
169
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);
176
177
178 Example 2 I_TRCLOG registration.
179
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);
192
193
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 SEE ALSO
226 strace(1M), strerr(1M), Intro(3), getmsg(2), ioctl(2), putmsg(2),
227 write(2), printf(3C), strlog(9F)
228
229
230 STREAMS Programming Guide
231
232
233
234 March 11, 1998 LOG(7D)
|
1 LOG(7D) Devices LOG(7D)
2
3 NAME
4 log - interface to STREAMS error logging and event tracing
5
6 SYNOPSIS
7 #include <sys/strlog.h>
8 #include <sys/log.h>
9
10 DESCRIPTION
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.
19
20 Kernel Interface
21 Log messages are generated within the kernel by calls to the function
22 strlog(9F).
23
24 User Interface
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.
36
37 struct trace_ids {
38 short ti_mid;
39 short ti_sid;
40 char ti_level;
41 };
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.
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.
60
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 };
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:
80
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
87
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.
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.
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.
109
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).
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).
117
118 Driver Configuration
119 The following driver configuration properties may be defined in the
120 log.conf file:
121
122 msgid=1 Each message will be preceded by a message ID as described in
123 syslogd(1M).
124
125 msgid=0 Message IDs will not be generated.
126
127 FILES
128 /dev/log Log driver.
129
130 /dev/conslog Write only instance of the log driver, for console
131 logging.
132
133 /kernel/drv/log.conf Log configuration file.
134
135 EXAMPLES
136 Example 1 I_ERRLOG registration.
137
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);
144
145 Example 2 I_TRCLOG registration.
146
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);
159
160 Example 3 Submitting a log message (no arguments)
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);
173
174 SEE ALSO
175 strace(1M), strerr(1M), getmsg(2), ioctl(2), putmsg(2), write(2),
176 strlog(9F)
177
178 STREAMS Programming Guide
179
180 illumos January 20, 2018 illumos
|