strlog, log - STREAMS log driver
#include <sys/strlog.h>
int strlog(
short mid,
short sid,
char level,
ushort flags,
char fmt,
[,value]... );
Specifies the STREAMS module ID number for the driver or
module submitting the log message. Specifies the sub-ID
number of a minor device associated with the STREAMS module
or driver identified by mid. Specifies 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.
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 messages.
Kernel Interface [Toc] [Back]
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. The SYNOPSIS section describes the
kernel interface.
User Interface [Toc] [Back]
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 information 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 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. In addition to
the information contained 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 information). 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.
Tru64 UNIX does not provide a console logger. Note, however,
that other systems may provide console loggers.
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
messages that user processes send.
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)
Specifies the clone interface. Specifies the header file
for STREAMS logging. Specifies the header file for
STREAMS options and ioctl() commands.
Commands: strace(8), strerr(8)
Interfaces clone(7), streamio(7)
Functions: getmsg(2), putmsg(2), write(2)
strlog(7)
[ Back ] |
