log(M) 19 June 1992 log(M) 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 (see strerr(ADM), strace(ADM)). 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(S) system calls and STREAMS messages for interaction with a user level error logger, a trace logger, or pro- cesses 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 iden- tify 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), 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(C) style format string, except that %s, %e, %E, %g, and %G conver- sion 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 ISTR ioctl call (see below). 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 messages 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. 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(S) 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, 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 logctl 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 ITRCLOG or IERRLOG when a logging process of the given type already exists will result in the error ENXIO being returned. Similarly, ENXIO is returned for ITRCLOG ioctls without any traceids structures, or for any unrecognized ISTR ioctl calls. Incorrectly for- matted log messages sent to the driver by a user process are silently ignored (no error results). Examples Example of IERRLOG 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; ioctl(log, I_STR, &ioc); 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); 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 <sys/log.h> <sys/strlog.h> See also clone(M), getmsg(S), intro(S), putmsg(S), strace(ADM), strerr(ADM) STREAMS Programmer's Guide Value added log is an extension of AT&T System V provided by The Santa Cruz Opera- tion, Inc.