[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Communications Programming Concepts

log Device Driver

The log driver is a STREAMS software device driver that provides an interface for the STREAMS error-logging and event-tracing processes. The log driver presents two separate interfaces:

Kernel Interface

The log messages are generated within the kernel by calls to the strlog utility.

User Interface

The log driver is opened using the clone interface, /dev/slog. Each open of /dev/slog obtains a separate stream to log. In order to receive log messages, a process must first notify the log driver whether it is an error logger or trace logger by using an I_STR operation.

For the error logger, the I_STR operation has an ic_cmd parameter value of I_ERRLOG with no accompanying data.

For the trace logger, the I_STR operation has an ic_cmd parameter value of I_TRCLOG, and must be accompanied by a data buffer containing an array of one or more trace_ids structures. Each trace_ids structure specifies a mid, sid, and level field from which messages are accepted. The strlog subroutine accepts messages whose values in the mid and sid fields 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. After the logger process has identified itself by using the ioctl operation, the log driver will begin sending messages, subject to the restrictions previously noted. These messages are obtained by using the getmsg system call. The control part of this message contains a log_ctl structure, which specifies the mid, sid, level, and flags fields, as well as the 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; 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-logging and trace-logging streams 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 tying up system resources.) The data part of the message contains the unexpanded text of the format string (null-terminated), followed by the arguments to the format string (up to the number specified by the NLOGARGS value), aligned on the first word boundary following the format string.

A process may also send a message of the same structure to the log driver, 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 the log driver 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 operation when a logging process of the given type already exists results in the ENXIO error being returned. Similarly, ENXIO is returned for I_TRCLOG operations without any trace_ids structures, or for any unrecognized I_STR operations. Incorrectly formatted log messages sent to the driver by a user process are silently ignored (no error results).


  1. The following is an 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;
    ioctl(log, I_STR, &ioc);
  2. The following is an 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_timeout = 0;
    ioc.ic_len = 2 * sizeof(struct trace_ids);
    ioc.ic_dp = (char *)tid;
    ioctl(log, I_STR, &ioc);
  3. The following is an example of submitting a log message (no arguments):
    struct strbuf ctl, dat;
    struct log_ctl lc;
    char *message = "Honey, I'm working late again.";
    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_ERROS;
    putmsg(log, &ctl, &dat, 0);

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]