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)
28 requests and STREAMS messages for interaction with a user level console logger,
29 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
82 struct trace_ids {
83 short ti_mid;
84 short ti_sid;
85 char ti_level;
86 };
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
114 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 */
122 #else
123 clock_t ltime;
124 time_t ttime;
125 #endif
126 int seq_no; /* sequence number */
127 int pri; /* priority = (facility|level) */
128 };
129 .fi
130 .in -2
131
132 .sp
133 .LP
134 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
147 Different sequence numbers are maintained for the error and trace logging
148 streams, and are provided so that gaps in the sequence of messages can be
149 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
158 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
172 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
177 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
205 struct strioctl ioc;
206 ioc.ic_cmd = I_ERRLOG;
207 ioc.ic_timout = 0; /* default timeout (15 secs.) */
208 ioc.ic_len = 0;
209 ioc.ic_dp = NULL;
210 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
219 struct trace_ids tid[2];
220 tid[0].ti_mid = 2;
221 tid[0].ti_sid = 0;
222 tid[0].ti_level = 1;
223 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 */
226 ioc.ic_cmd = I_TRCLOG;
227 ioc.ic_timout = 0;
228 ioc.ic_len = 2 * sizeof(struct trace_ids);
229 ioc.ic_dp = (char *)tid;
230 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
241 struct strbuf ctl, dat;
242 struct log_ctl lc;
243 char *message = "Don't forget to pick up some milk
244 on the way home";
245 ctl.len = ctl.maxlen = sizeof(lc);
246 ctl.buf = (char *)&lc;
247 dat.len = dat.maxlen = strlen(message);
248 dat.buf = message;
249 lc.level = 0;
250 lc.flags = SL_ERROR|SL_NOTIFY;
251 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