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 inter-
faces: a function call interface in the kernel through which STREAMS
drivers and modules submit log messages; and a subset of ioctl(2) sys-
tem calls and STREAMS messages for interaction with a user level con-
sole 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 pro-
vided.
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 traceids structure specifies an mid,
sid, and level from which message will be accepted. strlog will accept
Page 1 Reliant UNIX 5.44 Printed 11/98
log(7) log(7)
messages whose mid and sid exactly match those in the traceids struc-
ture, 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 log-
ging streams, and are provided so that gaps in the sequence of mes-
sages 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 fol-
lowing the end of the format string.
ENXIO is returned for ITRCLOG ioctls without any traceids struc-
tures, or for any unrecognized ISTR ioctl calls. Incorrectly format-
ted log messages sent to the driver by a user process are silently
ignored (no error results).
Page 2 Reliant UNIX 5.44 Printed 11/98
log(7) log(7)
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);
Page 3 Reliant UNIX 5.44 Printed 11/98
log(7) log(7)
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);
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), introprm2(2), putmsg(2), write(2),
clone(7).
Programmer's Guide: STREAMS
Page 4 Reliant UNIX 5.44 Printed 11/98