log(7) CLIX log(7)
NAME
log - STREAMS error logging and event tracing interface
DESCRIPTION
The log driver is a STREAMS software device driver that provides an
interface for the STREAMS error logging and event tracing processes
(strerr, strace). The log driver 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() 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
The log driver messages are generated within the kernel by calls to the
strlog() function:
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>. The
mid parameter is the STREAMS module ID number for the module or driver
submitting the log message. The sid parameter is an internal sub-ID
number usually used to identify a particular minor device of a driver.
The level parameter is a tracing level that allows for selective screening
out of low priority messages from the tracer. The flags parameter
represents 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). The fmt parameter is a
printf() 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
The log is opened with 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 through 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. The
2/94 - Intergraph Corporation 1
log(7) CLIX log(7)
strlog() function 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 with the ioctl() call, log
begins sending up messages subject to the restrictions noted above. These
messages are obtained through the getmsg() function. 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
1. 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;
2 Intergraph Corporation - 2/94
log(7) CLIX log(7)
ioctl(log, I_STR, &ioc);
2. 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);
3. 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 Interface to STREAMS error logging and event tracing.
RELATED INFORMATION
Commands: strace(8), strerr(8)
Functions: intro(2), getmsg(2), putmsg(2)
2/94 - Intergraph Corporation 3
log(7) CLIX log(7)
Files: clone(7)
4 Intergraph Corporation - 2/94