OSF

NAME

strlog, log − STREAMS error log driver driver

SYNOPSIS

#include <sys/strlog.h> int strlog (
short mid,
short sid,
char level,
ushort flags
char fmt,
unsigned arg1);

DESCRIPTION

The strlog interface tracks log messages that are used by STREAMS error logging and event tracing daemons.  The strerr daemon collects information from strlog and stores it in error log files (see sterr(8)).  The strace daemon collects STREAMS event race messages, and prints these messages to standard output (see strace(8)). 

The strlog driver interface is divided into two interfaces: the kernel interface and the user interface.  The kernel interface tracks log messages from STREAMS drivers and modules.  The user interface tracks messages from the console logger, an error logger, a trace logger, or processes that must generate their own log messages. 

The following sections describe both the kernel interface and the call interface in detail. 

Kernel Interface

STREAMS drivers and modules generate log messages by calls to the strlog function.  Definitions used in these calls are contained in the log_ctl structure in the /sys/strlog.h header file, where:

midSpecifies the STREAMS module id number for the driver or module submitting the log message. 

sidSpecifies the sub-id number of a  minor device associated with the STREAMS module or driver identified by mid. 

levelSpecifies a level for screening lower-level event messages from a tracer. 

flagsSpecifies the message types as follows:

SL_ERRORThe message is for the error logger. 

SL_TRACEThe message is for the tracer. 

SL_FATALNotification of a fatal error. 

SL_NOTIFY
Request to mail a copy of a message to the system administrator.

User Interface

User processes open strlog by via the clone driver’s interface, /dev/streams/log.  Each open to the device will obtain a separate stream.  After a process opens /dev/streams/log, it indicates whether it is a console logger, error logger, or trace logger.  It does this by issuing an I_STR ioctl system call containing the appropriate data and control information in a trace_ids structure. 

       •For a console logger, the I_STR ioctl contains an ic_cmd field of I_CONSLOG with no data. 

       •For an error logger the I_STR ioctl contains an ic_cmd field of I_ERRLOG with no data. 

       •For a trace logger, the I_STR ioctl contains an ic_cmd field of I_TRCLOG and a data buffer ic_dp consisting of an array of one or more trace_ids structures. 

If any of the fields of the trace_ids structure contain a value of -1, /dev/streams/log will accept whatever value it receives in that field.  Once the logger process has sent the I_STR ioctl command, the STREAMS log driver begins to send log messages matching the restrictions to the logger process.  The logger process obtains the log messages via the getmsg(2) system call.  The control part of the messages passed in this call include a log_ctl structure, which indicates the mid, sid, level, time in ticks since boot that the message was submitted, the corresponding time in seconds since January 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.  The time in ticks since boot is provided so that the relative timing of log messages can be determined.  The data part of messages contains unexpanded text of the format string (null terminated), followed by any arguments packed one word each after the end of the string. A user process, other than an error or trace logger, can send a log message to strlog.  The driver will accept only the flags, level, and pri fields of the log_ctl structure in the control part of the message, and a properly formatted data part of the message.  The data part of the message is properly formatted if it contains a null terminated format string, followed by any arguments packed one word each after the end of the string. 

EXAMPLES

     1.A user process wishing to notify the STREAMS log driver of error information (an I_ERRLOG ioctl command) should contain the following code:

struc strioctl ioc:
 ioc.ic_cmd = I_ERRLOG;
ioc.ic_timout = 0;   /∗ default timeout is 15 seconds. ∗/
ioc.ic_len = 0;
ioc.ic_dp = NULL;
ioctl(log, I_STR, &ioc)

     2.To submit a log message to strlog, a user process could contain:

struct strbuf ctl, dat;
struct log_ctl lc;
char ∗message = "Last edited by <username> on <date>";
 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);

ERRORS

On failure, strlog returns the following values in errno:

[ENXIO]The I_STR ioctl command could not be recognized. 

The driver does not return any errors for incorrectly formatted messages that user processes send.

FILES

/dev/log
/sys/strlog.h
/usr/include/sys/strlog.h

RELATED INFORMATION

Commands: strace(8), strerr(8) Interfaces clone(7), streamio(7) Functions: getmsg(2), putmsg(2), write(2)