log(7) 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 console logging and 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 console logger, an 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>, <sys/log.h>,
and <sys/syslog.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 SLERROR (the message is for the error logger),
SLTRACE (the message is for the tracer), SLCONSOLE (the message is
for the console logger), SLFATAL (advisory notification of a fatal
error), and SLNOTIFY (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, trace logger, or console logger via a STREAMS ISTR ioctl
call (see below). For the console logger, the ISTR ioctl has an
iccmd field of ICONSLOG, with no accompanying data. For the error
logger, the ISTR ioctl has an iccmd field of IERRLOG, with no
accompanying data. For the trace logger, the ioctl has an iccmd
field of ITRCLOG, and must be accompanied by a data buffer
containing an array of one or more struct traceids elements. Each
8/91 Page 1
log(7) log(7)
traceids 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 traceids structure, and whose level
is less than or equal to the level given in the traceids structure.
A value of -1 in any of the fields of the traceids structure
indicates that any value is accepted for that field.
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 logctl 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, a sequence number, and a priority. 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.
The priority is comprised of a priority code and a facility code,
found in <sys/syslog.h>. If SLCONSOLE is set in flags, the priority
code is set as follows. If SLWARN is set, the priority code is set
to LOGWARNING. If SLFATAL is set, the priority code is set to
LOGCRIT. If SLERROR is set, the priority code is set to LOGERR.
If SLNOTE is set, the priority code is set to LOGNOTICE. If
SLTRACE is set, the priority code is set to LOGDEBUG. If only
SLCONSOLE is set, the priority code is set to LOGINFO. Messages
originating from the kernel have the facility code set to LOGKERN.
Most messages originating from user processes will have the facility
code set to LOGUSER.
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
logctl structure in the control part of the message that are
accepted are the level, flags, and pri 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.
ENXIO is returned for ITRCLOG ioctls without any traceids
structures, or for any unrecognized ISTR ioctl calls. Incorrectly
formatted log messages sent to the driver by a user process are
Page 2 8/91
log(7) log(7)
silently ignored (no error results).
Processes that wish to write a message to the console logger may
direct their output to /dev/conslog, using either write(2) or
putmsg(2).
EXAMPLES
Example of IERRLOG 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 ITRCLOG notification.
struct traceids tid[2];
tid[0].timid = 2;
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);
8/91 Page 3
log(7) log(7)
dat.buf = message;
lc.level = 0;
lc.flags = SLERROR|SLNOTIFY;
putmsg(log, &ctl, &dat, 0);
FILES
/dev/log
/dev/conslog
<sys/log.h>
<sys/strlog.h>
<sys/syslog.h>
SEE ALSO
strace(1M), strerr(1M), getmsg(2), intro(2), putmsg(2), write(2),
clone(7).
Programmer's Guide: STREAMS.
Page 4 8/91