LOG(7) Domain/OS SysV LOG(7)
NAME
log - interface to STREAMS error logging and event tracing
SYNOPSIS
log
DESCRIPTION
log is a STREAMS software device driver that provides an interface for
the STREAMS error logging and event tracing processes (strerr(1M),
strace(1M)). log presents two separate interfaces: a function call
interface through which STREAMS drivers and modules submit log messages;
and a subset of ioctl(2) 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.
STREAMS Interface
log messages are generated within STREAMS by calls to the function
strlog:
strlog(mid, sid, level, flags, fmt, arg1, ...)
short mid, sid;
char level;
ushort flags;
char *fmt;
unsigned arg1;
where: 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
- not implemented). fmt is a printf(3S) 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.
Required definitions are contained in <sys/strlog.h> and <sys/log.h>.
User Interface
log is opened via /dev/logd. Each open of /dev/logd obtains a separate
stream to log. 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 a mid, sid, and level from which
message will be accepted. strlog accepts 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
begins sending messages subject to the restrictions noted above. These
messages are obtained via the getmsg(2) 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 results 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 = "This is a message";
ctl.len = ctl.maxlen = sizeof(lc);
ctl.buf = (char *)&lc;
dat.len = dat.maxlen = strlen(message) + 1;
dat.buf = message;
lc.level = 0;
lc.flags = SL_ERROR|SL_NOTIFY;
putmsg(log, &ctl, &dat, 0);
FILES
/dev/logd, <sys/log.h>, <sys/strlog.h>
SEE ALSO
strace(1M), strerr(1M), tracem(7)
intro(2), getmsg(2), putmsg(2) in the SysV Programmer's Reference.
Programming with SysV STREAMS