Name
log - interface to STREAMS error logging and event tracing
Description
log is a STREAMS software device driver that provides an
interface for the STREAMS error logging and event tracing
processes [strerr(ADM), strace(ADM)]. log presents two
separate interfaces: a function call interface in the kernel
through which STREAMS drivers and modules submit log
messages; and a subset of ioctl(S) system calls and STREAMS
messages for interaction with a user level error logger, a
trace logger, or processes that need to submit their own log
messages.
Kernel Interface
log messages are generated within the kernel by calls to the
function strlog:
strlog(mid, sid, level, flags, fmt, arg1, ...)
short mid, sid;
char level;
ushort flags;
char *fmt;
unsigned arg1;
Required definitions are contained in <sys/strlog.h> and
<sys/log.h>. mid is the STREAMS module id number for the
module or driver submitting the log message. sid is an
internal sub-id number usually used to identify a particular
minor device of a driver. level is a tracing level that
allows for selective screening out of low priority messages
from the tracer. flags are any combination of SL_ERROR (the
message is for the error logger), SL_TRACE (the message is
for the tracer), SL_FATAL (advisory notification of a fatal
error), and SL_NOTIFY (request that a copy of the message be
mailed to the system administrator). fmt is a printf(S)
style format string, except that %s, %e, %E, %g, and %G
conversion specifications are not handled. Up to NLOGARGS
(currently 3) numeric or character arguments can be
provided.
User Interface
log is opened via the clone interface, /dev/log. Each open
of /dev/log obtains a separate stream to log. In order to
receive log messages, a process must first notify log
whether it is an error logger or trace logger via a STREAMS
I_STR ioctl call (see below). For the error logger, the
I_STR ioctl has an ic_cmd field of I_ERRLOG with no
accompanying data. For the trace logger, the ioctl has an
ic_cmd field of I_TRCLOG, and must be accompanied by a data
buffer containing an array of one or more struct trace_ids
elements. Each trace_ids structure specifies an mid, sid,
and level from which message will be accepted. strlog will
accept messages whose mid and sid exactly match those in the
trace_ids structure, and whose level is less than or equal
to the level given in the trace_ids structure. A value of
-1 in any of the fields of the trace_ids structure indicates
that any value is accepted for that field.
At most one trace logger and one error logger can be active
at a time. Once the logger process has identified itself
via the ioctl call, log will begin sending up messages
subject to the restrictions noted above. These messages are
obtained via the getmsg(S) system call. The control part of
this message contains a log_ctl structure, which specifies
the mid, sid, level, flags, time in ticks since boot that
the message was submitted, the corresponding time in seconds
since Jan. 1, 1970, and a sequence number. The time in
seconds since 1970 is provided so that the date and time of
the message can be easily computed, and the time in ticks
since boot is provided so that the relative timing of log
messages can be determined.
Different sequence numbers are maintained for the error and
trace logging streams, and are provided so that gaps in the
sequence of messages can be determined (during times of high
message traffic, some messages may not be delivered by the
logger to avoid hogging system resources). The data part of
the message contains the unexpanded text of the format
string (null terminated), followed by NLOGARGS words for the
arguments to the format string, aligned on the first word
boundary following the format string.
A process may also send a message of the same structure to
log, even if it is not an error or trace logger. The only
fields of the log_ctl structure in the control part of the
message that are accepted are the level and flags fields;
all other fields are filled in by log before being forwarded
to the appropriate logger. The data portion must contain a
null terminated format string, and any arguments (up to
NLOGARGS) must be packed one word each, on the next word
boundary following the end of the format string.
Attempting to issue an I_TRCLOG or I_ERRLOG when a logging
process of the given type already exists will result in the
error ENXIO being returned. Similarly, ENXIO is returned
for I_TRCLOG ioctls without any trace_ids structures, or for
any unrecognized I_STR ioctl calls. Incorrectly formatted
log messages sent to the driver by a user process are
silently ignored (no error results).
Examples
Example of I_ERRLOG notification.
struct strioctl ioc;
ioc.ic_cmd = I_ERRLOG;
ioc.ic_timout = 0; /* default timeout (15 secs.) */
ioc.ic_len = 0;
ioc.ic_dp = NULL;
ioctl(log, I_STR, &ioc);
Example of I_TRCLOG notification.
struct trace_ids tid[2];
tid[0].ti_mid = 2;
tid[0].ti_sid = 0;
tid[0].ti_level = 1;
tid[1].ti_mid = 1002;
tid[1].ti_sid = -1; /* any sub-id will be allowed */
tid[1].ti_level = -1; /* any level will be allowed */
ioc.ic_cmd = I_TRCLOG;
ioc.ic_timout = 0;
ioc.ic_len = 2 * sizeof(struct trace_ids);
ioc.ic_dp = (char *)tid;
ioctl(log, I_STR, &ioc);
Example of submitting a log message (no arguments).
struct strbuf ctl, dat;
struct log_ctl lc;
char *message = "Don't forget to pick up some milk on the way home";
ctl.len = ctl.maxlen = sizeof(lc);
ctl.buf = (char *)&lc;
dat.len = dat.maxlen = strlen(message);
dat.buf = message;
lc.level = 0;
lc.flags = SL_ERROR|SL_NOTIFY;
putmsg(log, &ctl, &dat, 0);
Files
/dev/log, <sys/log.h>, <sys/strlog.h>
See Also
clone(STR).
strace(ADM), strerr(ADM), intro(S), getmsg(S), putmsg(S) in
the UNIX Reference.
STREAMS Programmer's Guide.
(printed 6/18/89)