log(7) DG/UX 5.4R3.00 log(7)
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(1M), strace(1M)). 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(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.
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(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.
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.
Licensed material--property of copyright holder(s) 1
log(7) DG/UX 5.4R3.00 log(7)
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(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 will result in the error ENXIO being
returned. Similarly, ENXIO is returned for I_TRCLOG ioctl calls
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.iccmd = IERRLOG;
ioc.ictimout = 0; /* default timeout (15 secs.) */
ioc.iclen = 0;
ioc.icdp = NULL;
ioctl(log, ISTR, &ioc);
Example of I_TRCLOG notification.
struct traceids tid[2];
tid[0].timid = 2;
Licensed material--property of copyright holder(s) 2
log(7) DG/UX 5.4R3.00 log(7)
tid[0].tisid = 0;
tid[0].tilevel = 1;
tid[1].timid = 1002;
tid[1].tisid = -1; /* any sub-id will be allowed */
tid[1].tilevel = -1; /* any level will be allowed */
ioc.iccmd = ITRCLOG;
ioc.ictimout = 0;
ioc.iclen = 2 * sizeof(struct traceids);
ioc.icdp = (char *)tid;
ioctl(log, ISTR, &ioc);
Example of submitting a log message (no arguments).
struct strbuf ctl, dat;
struct logctl 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) + 1;
dat.buf = message;
lc.level = 0;
lc.flags = SLERROR|SLNOTIFY;
putmsg(log, &ctl, &dat, 0);
FILES
/dev/log, <sys/log.h>, <sys/strlog.h>
SEE ALSO
strace(1M), strerr(1M), clone(7).
intro(2), getmsg(2), putmsg(2).
STREAMS Programmer's Guide for the DG/UX System.
Licensed material--property of copyright holder(s) 3