1log(7D) Devices log(7D)
2
6 log - interface to STREAMS error logging and event tracing
7
9 #include <sys/strlog.h>
10 #include <sys/log.h>
13
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 sub‐
23 mit their own log messages.
24 Kernel Interface
26 log messages are generated within the kernel by calls to the function
27 strlog():
28 strlog(short mid,
30 short sid,
31 char level,
32 ushort_t flags,
33 char *fmt,
34 unsigned arg1...
35 );
36 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 pri‐
44 ority messages from the tracer. flags are any combination of SL_ERROR
45 (the message is for the error logger), SL_TRACE (the message is for
46 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 administra‐
49 tor). fmt is a printf(3C) style format string, except that %s, %e,
50 %E, %g, and %G conversion specifications are not handled. Up to NLOG‐
51 ARGS (in this release, three) numeric or character arguments can be
52 provided.
53 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 log‐
59 ger, or console logger using a STREAMS I_STR ioctl call (see below).
60 For the console logger, the I_STR ioctl has an ic_cmd field of
61 I_CONSLOG, with no accompanying data. For the error logger, the I_STR
62 ioctl has an ic_cmd field of I_ERRLOG, with no accompanying data. For
63 the trace logger, the ioctl has an ic_cmd field of I_TRCLOG, and
64 must be accompanied by a data buffer containing an array of one or more
65 struct trace_ids elements.
66 struct trace_ids {
68 short ti_mid;
69 short ti_sid;
70 char ti_level;
71 };
72 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 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 pro‐
90 vided so that the date and time of the message can be easily computed,
91 and the time in ticks since boot is provided so that the relative tim‐
92 ing of log messages can be determined.
93 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 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
119 code is set to LOG_INFO. Messages originating from the kernel have the
120 facility code set to LOG_KERN. Most messages originating from user pro‐
121 cesses will have the facility code set to LOG_USER.
122 Different sequence numbers are maintained for the error and trace log‐
125 ging streams, and are provided so that gaps in the sequence of messages
126 can be determined (during times of high message traffic some messages
127 may not be delivered by the logger to avoid hogging system resources).
128 The data part of the message contains the unexpanded text of the format
129 string (null terminated), followed by NLOGARGS words for the arguments
130 to the format string, aligned on the first word boundary following the
131 format string.
132 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 NLOG‐
140 ARGS) must be packed, 32-bits each, on the next 32-bit boundary fol‐
141 lowing the end of the format string.
142 ENXIO is returned for I_TRCLOG ioctls without any trace_ids struc‐
145 tures, or for any unrecognized ioctl calls. The driver silently ignores
146 incorrectly formatted log messages sent to the driver by a user process
147 (no error results).
148 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 Driver Configuration
154 The following driver configuration properties may be defined in the
155 log.conf file.
156 msgid=1 If msgid=1, each message will be preceded by a message ID as
158 described in syslogd(1M).
159 msgid=0 If msgid=0, message IDs will not be generated. This prop‐
162 erty is unstable and may be removed in a future release.
163
166 Example 1 I_ERRLOG registration.
167 struct strioctl ioc;
169 ioc.ic_cmd = I_ERRLOG;
170 ioc.ic_timout = 0; /* default timeout (15 secs.) */
171 ioc.ic_len = 0;
172 ioc.ic_dp = NULL;
173 ioctl(log, I_STR, &ioc);
174 Example 2 I_TRCLOG registration.
177 struct trace_ids tid[2];
179 tid[0].ti_mid = 2;
180 tid[0].ti_sid = 0;
181 tid[0].ti_level = 1;
182 tid[1].ti_mid = 1002;
183 tid[1].ti_sid = −1; /* any sub-id will be allowed */
184 tid[1].ti_level = −1; /* any level will be allowed */
185 ioc.ic_cmd = I_TRCLOG;
186 ioc.ic_timout = 0;
187 ioc.ic_len = 2 * sizeof(struct trace_ids);
188 ioc.ic_dp = (char *)tid;
189 ioctl(log, I_STR, &ioc);
190 Example of submitting a log message (no arguments):
194 struct strbuf ctl, dat;
197 struct log_ctl lc;
198 char *message = "Don't forget to pick up some milk
199 on the way home";
200 ctl.len = ctl.maxlen = sizeof(lc);
201 ctl.buf = (char *)&lc;
202 dat.len = dat.maxlen = strlen(message);
203 dat.buf = message;
204 lc.level = 0;
205 lc.flags = SL_ERROR|SL_NOTIFY;
206 putmsg(log, &ctl, &dat, 0);
207
210 /dev/log Log driver.
211 /dev/conslog Write only instance of the log driver, for con‐
214 sole logging.
215 /kernel/drv/log.conf Log configuration file.
218
221 strace(1M), strerr(1M), Intro(3), getmsg(2), ioctl(2), putmsg(2),
222 write(2), printf(3C), strlog(9F)
223 STREAMS Programming Guide
226SunOS 5.11 11 Mar 1998 log(7D)