strlog(7) Miscellaneous Information Manual strlog(7)
NAME
strlog - STREAMS log driver
DESCRIPTION
The STREAMS log driver allows user-level processes and STREAMS drivers and modules to perform error logging and event tracing. These tasks
are done via a user interface and a kernel interface. Further, the STREAMS log driver delivers error logging and event tracing messages to
the Network Tracing and Logging Facility (NetTL) (see nettl(1M), netfmt(1M), and nettlconf(1M)).
The interface that this driver presents to user-level processes is a subset of the system calls and STREAMS message formats. These pro-
cesses can be error loggers, trace loggers, or other user processes, that generate error or event messages. The user interface collects
log messages from the log driver, and also generates log messages from user processes.
The driver also accepts log messages from STREAMS drivers and modules in the kernel via its function call interface. The kernel interface
enters requests or calls from STREAMS drivers and modules into log messages.
The log messages accepted by the log driver are also delivered to NetTL. NetTL can be used to control which types of messages to log, and
to format and filter the logged messages.
Kernel Interface
STREAMS drivers and modules generate log messages by calls to the function.
#include <sys/strlog.h>
int strlog (mid, sid, level, flags, fmt [, value ]...);
short mid;
short sid;
char level;
ushort flags;
char *fmt;
int value;
mid specifies the STREAMS module ID number for the driver or module submitting the log message.
sid specifies the sub-ID number of a minor device associated with the STREAMS module or driver identified by mid.
level specifies a level for screening lower-level event messages from a tracer.
flags contains several flags that can be set in various combinations. The flags are as follows:
The message is for the error logger.
The message is for the tracer.
The message will be printed to the console.
Provides a notification of a fatal error.
Makes a request to
mail a copy of a message to the system administrator.
The following are additional flags. These flags are not used by or However, they are used to map STREAMS messages to NetTL
messages as described below in section.
The message is a warning.
The message is a note.
fmt is a style format string. This accepts the and conversion specifications.
values are numeric or character arguments for the format string. There is no maximum number of arguments that can be specified.
User Interface
User processes access the log driver with an call to Each open to the device will obtain a separate stream. After a process opens it indi-
cates whether it is an error logger or trace logger. It does this by issuing an system call with the appropriate value in the field of the
structure, and the appropriate data and control information in a structure:
struct trace_ids {
short ti_mid;
short ti_sid;
char ti_level;
short ti_flags;
};
The values for are:
Indicates an error logger.
No data is needed.
Indicates a trace logger.
A data buffer consisting of an array of one or more structures must be included.
If any of the fields of the structure contain a value of -1, will accept whatever value it receives in that field. Otherwise, only accepts
messages only if the values of mid and sid are the same as their counterparts in the structure, and if the message's level is equal to or
less than the value in the structure.
Once the logger process has sent the call, 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 system call. The control part of the messages passed in this call includes a
structure:
struct log_ctl {
short mid;
short sid;
char level;
short flags;
long ltime;
long ttime;
int seq_no;
};
The structure indicates the mid, sid, and level time in ticks since the boot time that the message was submitted, the corresponding time in
seconds since January 1, 1970, and a sequence number. The time in seconds since January 1, 1970 is provided so that the date and time of
the message can be easily computed. The time in ticks since boot time is provided so that the relative timing of log messages can be
determined.
A user process, other than an error or trace logger, can send a log message to The driver will accept only the and fields of the 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 up to three arguments packed one word each after the end of the string.
A different series of sequence numbers is provided for error and trace logging streams. These sequence numbers are intended to help track
the delivery of the messages. A gap in a sequence of numbers indicates that the logger process did not successfully deliver them. This
can happen if the logger process stops sending messages for one reason or another (see strace(1M) and strerr(1M) command reference pages
for more information). The data part of messages contains text of the format string (null terminated), followed by up to three arguments.
STREAMS-NetTL Link
Both STREAMS error logging and event tracing messages are mapped to NetTL logging messages, and are delivered to NetTL. NetTL classifies
messages into four log classes: DISASTER, ERROR, WARNING, and INFORMATIVE. The NetTL log class is determined by the according to the fol-
lowing rule:
If (flags & SL_ERROR) NetTL log class
then
if (flags & SL_FATAL) ====> DISASTER
if (flags & SL_WARN) ====> WARNING
if (flags & SL_NOTE) ====> INFORMATIVE
otherwise ====> ERROR
else
all messages ====> INFORMATIVE
As a default, only DISASTER and ERROR messages are logged. This setting can be altered by the command or the command (see nettl(1M) and
nettlconf(1M)).
The STREAMS subsystem ID used by NetTL is
The messages logged by NetTL facility can be formatted to a readable form by the command (see netfmt(1M)). The accepts a filter configura-
tion file, which can be used to filter on STREAMS module ID and sub-ID. The filter configuration file syntax for STREAMS is the following:
module_id and sub_id can be a decimal number or as a wild card.
RETURN VALUE
Unless specified otherwise, upon successful completion, the commands return a value of 0 (zero). Otherwise, a value of -1 is returned.
ERRORS
If any of the following conditions occurs, driver's command sets to the corresponding value:
The call did not contain any structures.
The call could not be recognized.
The driver does not return any errors for incorrectly formatted messages that user processes send.
EXAMPLES
The following examples illustrate some basic uses for the interface.
This code example segment shows how a STREAMS module causes a message to be printed to the console:
strlog(TMUX,minor(mydev),0,SL_CONSOLE|SL_FATAL,
"TMUX driver (minor:%d) suffers resource shortage.",
minor(mydev));
This code example shows how a user process registers itself with the STREAMS log driver using the command,
struct strioctl iocerr:
int logfd;
if ((logfd = open("/dev/strlog", O_RDWR)) == -1) {
printf("Cannot open /dev/strlog
");
exit(1);
}
iocerr.ic_cmd = I_ERRLOG;
iocerr.ic_timout = 0;
iocerr.ic_len = 0;
iocerr.ic_dp = NULL;
ioctl(logfd, I_STR, &iocerr);
This code example shows a user-level process sending a message to the driver.
struct strbuf control, data;
struct log_ctl log;
char *warning = "Fatal error for user level process";
int logfd;
if ((logfd = open("/dev/strlog", O_RDWR)) == -1) {
printf("Cannot open /dev/strlog
");
exit(1);
}
control.len = control.maxlen = sizeof(log);
control.buf = (char *)&lc;
data.len = data.maxlen = strlen(warning);
data.buf = warning;
lc.level = 2;
lc.flags = SL_FATAL|SL_CONSOLE;
putmsg(logfd, &control, &data, 0);
The following examples illustrate how to use the NetTL facility for the STREAMS. See nettl(1M), netfmt(1M), nettlconf(1M) for the general
NetTL usage. The STREAMS subsystem ID used by NetTL is
The accepts a filter configuration file as a command argument. The following filter configuration file example is used to format the mes-
sages whose module ID is 1 and sub-ID is 100:
STREAMS 1 100
This filter configuration file example can be used to display all the messages whose module ID is 2 and all the messages whose sub-ID is
101:
STREAMS 2 *
STREAMS * 101
FILES
specifies the clone interface.
specifies the header file for streams logging.
specifies the header file for STREAMS options and
commands.
SEE ALSO
netfmt(1M), nettl(1M), nettlconf(1M), strace(1M), strerr(1M), getmsg(2), ioctl(2), open(2), putmsg(2), write(2), clone(7), streamio(7).
strlog(7)