HPUX strlog[7]
strlog(7) 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. 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(2) 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
STREAMS drivers and modules generate log messages by calls to the
strlog 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:
SL_ERROR The message is for the error logger.
SL_TRACE The message is for the tracer.
SL_CONSOLE The message will be printed to the console.
SL_FATAL Provides a notification of a fatal error.
SL_NOTIFY Makes a request to mail a copy of a message to the
system administrator.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: October 1992
strlog(7) strlog(7)
The following are additional flags. The strlog interface does not use
these flags:
SL_WARN The message is a warning.
SL_NOTE The message is a note.
fmt is a printf style format string. This accepts the %x, %l, %o, %u,
%d, %c, and %s 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 open(2) call to
/dev/strlog. Each open to the device will obtain a separate stream.
After a process opens /dev/strlog, it indicates whether it is an error
logger or trace logger. It does this by issuing an I_STR ioctl(2)
system call with the appropriate value in the ic_cmd field of the
strioctl structure, and the appropriate data and control information
in a trace_ids structure:
struct trace_ids {
short ti_mid;
short ti_sid;
char ti_level;
short ti_flags;
};
The values for ic_cmd are:
I_ERRLOG Indicates an error logger. No trace_ids data is
needed.
I_TRCLOG Indicates a trace logger. A data buffer consisting of
an array of one or more trace_ids structures must be
included.
If any of the fields of the trace_ids structure contain a value of -1,
/dev/strlog 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(2) 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:
struct log_ctl {
Hewlett-Packard Company - 2 - HP-UX Release 9.0: October 1992
strlog(7) strlog(7)
short mid;
short sid;
char level;
short flags;
long ltime;
long ttime;
int seq_no;
};
The log_ctl 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 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(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 any arguments.
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 cause 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 illustrates how a user process can register itself
with the STREAMS log driver using the ioctl(2) command, I_ERRLOG.
struct strioctl iocerr:
int logfd;
Hewlett-Packard Company - 3 - HP-UX Release 9.0: October 1992
strlog(7) strlog(7)
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 is an example of a user-level process sending a message to
the strlog 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);
ERRORS
If any of the following conditions occurs, strlog driver's ioctl(2)
command sets errno to the corresponding value:
[ENXIO] The I_TRCLOG ioctl(2) call did not contain any
trace_ids structures.
[ENXIO] The I_STR ioctl(2) call could not be recognized.
The driver does not return any errors for incorrectly formatted
messages that user processes send.
RETURN VALUES
Unless specified otherwise, upon successful completion, the strlog
ioctl(2) commands return a value of 0 (zero). Otherwise, a value of
-1 is returned.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: October 1992
strlog(7) strlog(7)
FILES
/dev/strlog specifies the clone interface.
<sys/strlog.h> specifies the header file for streams logging.
<stropts.h> specifies the header file for streams options and ioctl(2)
commands.
SEE ALSO
strace(1m), strerr(1m), clone(7), streamio(7), getmsg(2), putmsg(2),
write(2), open(2), ioctl(2).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: October 1992