strlog(7)strlog(7)NAME
strlog, log - STREAMS log driver
SYNOPSIS
#include <sys/strlog.h>
int strlog(
short mid,
short sid,
char level,
ushort flags,
char fmt,
[,value]... );
PARAMETERS
Specifies the STREAMS module ID number for the driver or module submit‐
ting the log message. Specifies the sub-ID number of a minor device
associated with the STREAMS module or driver identified by mid. Speci‐
fies a level for screening lower-level event messages from a tracer.
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 is for the console logger. 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. The strlog interface does
not use these flags: The message is a warning. The message is a
note. A printf style format string. This accepts the %x, %l,
%o, %u, %d, %c, and %s conversion specifications. Numeric or
character arguments for process-specific information. There is
no maximum number of arguments that can be specified.
DESCRIPTION
The STREAMS log driver allows user-level processes, and STREAMS drivers
and modules, to perform error logging and event tracing. This is done
via a user interface and a kernel interface.
The interface that this driver presents to user-level processes is a
subset of the ioctl() system calls and STREAMS message formats. These
processes 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.
Kernel Interface
STREAMS drivers and modules generate log messages by calls to the str‐
log() function. Definitions used in these calls are contained in the
log_ctl structure in the </sys/strlog.h> header file. The SYNOPSIS
section describes the kernel interface.
User Interface
User processes access the log driver with an open() call to
/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 an error logger or trace logger. It does this by issuing an I_STR
ioctl() system call containing the appropriate data and control infor‐
mation in a trace_ids structure. 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 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.
Otherwise, strlog only accepts messages only if the values of mid and
sid are the same as their counterparts in the trace_ids structure, and
if the message's level is equal to or less than the level value in the
trace_ids structure.
Once the logger process has sent the I_STR ioctl() 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
getmsg(2) system call. The control part of the messages passed in this
call includes a log_ctl structure, which indicates the mid, sid and
level, time in ticks since the boot time that the message was submit‐
ted, 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. In addition to the information con‐
tained in the log_ctl structure, there is also a priority indication.
The priority indication consists of a priority code and a facility code
(found in /sys/syslog.h). The valid values for priority codes are the
following, based on the setting(s) in flags: If SL_CONSOLE is set in
flags. If SL_CONSOLE and SL_WARN are set in flags. If SL_CONSOLE and
SL_FATAL are set in flags. If SL_CONSOLE and SL_ERROR are set in
flags. If SL_CONSOLE and SL_NOTE are set in flags. If SL_CONSOLE and
SL_TRACE are set in flags.
The valid values for facility codes are the following: If the message
originates from the kernel. If the message originates from a user
process. However, these processes may sometimes set another facility
code value instead.
A user process, other than an error or trace logger, can send a log
message to strlog(). The driver will accept only the flags and level
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.
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 the strace and strerr command reference pages for more informa‐
tion). 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.
NOTES
Tru64 UNIX does not provide a console logger. Note, however, that
other systems may provide console loggers.
ERRORS
If any of the following conditions occurs, strlog() driver's ioctl()
command sets errno to the corresponding value: The I_TRCLOG ioctl()
call did not contain any trace_ids structures. The I_STR ioctl() 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 how to use the strlog interface for
some basic uses. This code example segment illustrates how a STREAMS
module can generate a console log message:
strlog(TMUX,minor(mydev),0,SL_CONSOLE|SL_FATAL,
"TMUX driver (minor:%d) suffers resource shortage.",
minor(mydev)); This code example illustrates how a user
process can register itself with the STREAMS log driver using
the ioctl() command, I_ERRLOG.
struct strioctl iocerr:
iocerr.ic_cmd = I_ERRLOG; iocerr.ic_timout = 0; iocerr.ic_len =
0; iocerr.ic_dp = NULL; ioctl(logfd, I_STR, &iocerr)
FILES
Specifies the clone interface. Specifies the header file for STREAMS
logging. Specifies the header file for STREAMS options and ioctl()
commands.
SEE ALSO
Commands: strace(8), strerr(8)
Interfaces clone(7), streamio(7)
Functions: getmsg(2), putmsg(2), write(2)strlog(7)
