strlog(7)strlog(7)NAMEstrlog - 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 mes‐
sages.
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 func‐
tion.
#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 mod‐
ule 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 combina‐
tions. 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 mes‐
sages 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 speci‐
fied.
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 struc‐
ture:
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 sec‐
onds 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 INFORMA‐
TIVE. 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 set‐
ting 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 mes‐
sages 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\n");
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\n");
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 ALSOnetfmt(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)
