log(7) DEVICES AND MODULES 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 log-
ging and event tracing processes (strerr(1M), strace(1M)).
log presents two separate interfaces: a function call inter-
face 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 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 mes-
sage. 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 combina-
tion 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 administra-
tor). 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
1
log(7) DEVICES AND MODULES log(7)
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 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 res-
trictions 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
2
log(7) DEVICES AND MODULES log(7)
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 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;
3
log(7) DEVICES AND MODULES log(7)
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), intro(2), putmsg(2),
write(2), clone(7).
Programmer's Guide: STREAMS.
4