STRLOG

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

strlog, vstrlog - pass a message to the STREAMS logger

SYNOPSIS

#include <sys/stream.h>
#include <sys/strlog.h>

int strlog(short mid, short sid, char level, unsigned short flags, char *fmt, ...);
int vstrlog(short mid, short sid, char level, unsigned short flags, char *fmt, va_list args);

ARGUMENTS

mid: specifies the STREAMS module id
sid: specifies the STREAMS minor device number associated with the module.
level: specifies a priority level.
flags: log flags specifying the severity and options associated with the STREAMS log.
fmt: provides the printf(3) style format string.
...: provides the arguments for the printf(3) style format string for strlog().
args: provides the arguments for the printf(3) style format string for vstrlog().

vstrlog() is a va_list version of strlog().

INTERFACE

STREAMS.

DESCRIPTION

strlog() is the kernel interface to the STREAMS log(4) error and trace logger. By default, when the log(4) driver is not loaded on the system, strlog() instead prints messages to the Linux system logs ala printk(). See NOTICES , below. When the log(4) driver loads, however, it uses the register_strlog(9) utility to alter the behaviour of strlog(). When the log(4) driver is loaded, log messages will be passed to the log(4) driver as described in strlog(4).

strlog() formulates and passes a STREAMS message to the STREAMS logger, log(4), to be passed to active strerr(8) and strace(8) logging processes listening on the log(4) device.

vstrlog() is a va_list version of strlog() that accepts all of the same arguments, with the exception of the variable arguments list, which is formatted as the va_list args argument.

mid identifies the STREAMS module id associated with the STREAMS driver or module generating the log. sid is the minor device node within the STREAMS driver or module to which the log applies. level indicates the priority level of the log message with respect to other log messages in the same class. flags can contain a bitwise OR of zero or more of the following flags:

SL_FATAL: log with syslog(3) level of LOG_CRIT.
SL_ERROR: log with syslog(3) level of LOG_ERR.
SL_WARN: log with syslog(3) level of LOG_WARNING.
SL_NOTE: log with syslog(3) level of LOG_NOTICE.
SL_CONSOLE: log with syslog(3) level of LOG_INFO.
SL_TRACE: log with syslog(3) level of LOG_DEBUG.
SL_NOTIFY: indicates that a copy of the log should be mailed to the system administrator.
SL_NOPUTBUF: indicates that the log should not be buffered.

These arguments are placed into the corresponding fields of the STREAMS message to be passed to error and trace loggers as described in strlog(4).

USAGE

strlog() is a high performance alternative to cmn_err(9) that permits statements to be placed throughout a STREAMS driver or module, yet only generate messages to be logged to strerr(8) error or strace(8) trace logging processes when the a process is actually listening for the specific error or trace message. This allows running STREAMS modules to be traced at the discretion of a user level process.

strlog() impacts driver performance less than cmn_err(9) in a number of ways:

1.: strlog() provides the ability to filter messages of interest early making the only cost of discarded messages the cost of stacking parameters in the call to strlog(). In contrast, cmn_err(9) must format and output every message that it is passed.
2.: strlog() does not incur the penalty of formatting output strings within the strlog() call, but, rather quickly packages the format string and parameter pointers and passes them to the console, error or trace logger Stream, which then passes them to a user process that formats the output string. In contrast, cmn_err(9) must format the message that it was passed before returning.
3.: strlog() provides the ability to specify module identifier, stream instance identifier, logging levels and logger flags. Trace logs have a more sophiticated filtering mechanism that can filter on module module calling cmn_err(9).
4.: Trace logs have a more sophisticated filtering mechanism that can filter on module identifier, stream trace (debugging) logs have a more sophisticated filtering mechanism that can filter on module identifier, stream identifier level and flags, allowing a user level trace logger (see strace(9)) to chose a narrow range of messages without assistance from the driver. In contrast, cmn_err(9) must deliver every message it is passed, making selection of appopriate debugging messages difficult and module specific.

strlog() is one excellent diagnotic tool that is applicable to running systems, instead instead of crashed systems. Where possible, STREAMS drivers and module should use strlog() and vstrlog() in place of cmn_err(9) and vcmv_err(9).

RETURN

Upon success, strlog() and vstrlog() dispatch the log to the logger and return one (1). Upon failure, strlog() and vstrlog() return zero (0). strlog() or vstrlog() fail whenever the message is not seen by all the readers.

register_strlog() returns the previously registered vstrlog_t function pointer. register_strlog() always succeeds.

ERRORS

When strlog() or vstrlog() fail, they return zero (0). strlog() or vstrlog() fail when they cannot dispatch the log message to the logger.

CONTEXT

strlog() or vstrlog() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines.

MP-STREAMS

strlog() is MP-safe, however, the default behaviour takes global spin locks to accomplish this. See ``NOTICES'', below.

NOTICES

By default, strlog() and vstrlog() always logs with syslog(3) facility of LOG_KERN.

Default Logger

Linux Fast-STREAMS does not provide a STREAMS-based logger. Instead it logs all messages sent to strlog() to the kernel logger with printk(9). Following are additional considerations for this default logger:

---: Because the default logger uses printk(9), the only conversion specifiers supported are: %c, %s, %p, %n, %%, %o, %X, %x, %d, %i.
---: strlog() prefixes the string: ``strlog(xxx)[yyy,zzz]: '' onto the beginning of log messages, where: xxx is the level argument, yyy is the mid argument, and zzz is the sid argument.
---: As Linux does not have a default STREAMS logger, the BSD syslog(8) facilities apply. This default logger takes global spin locks to protect internal static buffers. This can be overly consumptive of system resources. Therefore, messages are only logged to the system logger when flags contains SL_CONSOLE. When the default logger is used, strlog() always returns success (and is always delivered) when flags contains SL_CONSOLE; and always returns failure (and never delivers) when flags does not contain SL_CONSOLE.

Linux Fast-STREAMS has an implementation of a full STREAMS logger, the log(4) driver. This full STREAMS logger filters properly as described under strlog(4). It is recommended that users of the kernel interfaces strlog() or vstrlog() use the full strlog(4) driver in conjunction with strace(8) and strerr(8) utilities. Following are additional considerations for the full STREAMS-based logger:

---: The STREAMS-based logger only supports the following conversion specifiers: %c, %s, %p, %%, %o, %X, %x, %d, %i and %u. The only printk(9) supported conversion specifier that is not supported by the STREAMS-based logger is %n.
---: Unlike the default logger, the STREAMS-based logger uses the strace(8) and strerr(8) facilities to transfer log events to the system logs.
---: Unlinke the default logger, that always returns success, the STREAMS-based logger filters trace messages with trace ids requested by the strace(8) trace logger, and returns failure if no error or trace logger was found to accept the message. The STREAMS-based logger also returns failure when the message band corresponding to the priority of the message is flow controlled. Because the STREAMS-based logger filters messages passed from strlog(), it is more efficient in the utilization of system resources when performing trace debugging of STREAMS modules and drivers.
---: Unlinke the default logger, which formats the message string in the kernel using the calling thread, the STREAMS-based logger passes the format string an argument to the userspace error or trace logger daemon which then formats the message. This is more efficient in the utilization of system resources.

BUGS

The SL_NOTIFY and SL_NOPUTBUF flags do not always function as described with the default logger. See ``COMPATIBILITY'', below.

COMPATIBILITY

strlog() is compatible with SVR 4.2 MP DDI/DKI[1], and implementations based on SVR 4[2] with the following portability considerations:

---: strlog() supports the following printf(3) conversion specifiers in the format string: %c, %s, %p, %%, %o, %X, %x, %d, %i and %u. strlog() does not support the following printf(3) conversion specifiers in the format string: %e, %E, %f, %F, %g, %G, %a, %A, %n. AIX® states that conversion specifiers %s, %f, %e, %E, %g and %G are not handled in the format string[3]. HP-UX® states that conversion specifiers %x, %l, %o, %u, %d, %c and %s are handled in the format string[4]. IRIX® and OSF/1® state that conversion specifiers %s, %e, %g and %G are not allowed in the format string[5, 6]. Solaris® states that conversion specifiers %s, %e, %E, %g and %G are not handled in the format string in the log(7) manual page, but states that %e, %g and %G are not allowed, but %s is supported in the strlog(9F) manual page[7]. UnixWare® states that conversion specifiers %s, %e, %g and %G are not handled in the format string in the log(7) manual page, but states that %s, %e, %E, %g and %G are not handled in the format string in the strlog(D3str) manual page[8]. UXP/V® states that conversion specifiers %s, %e, %E, %g and %G are not handled in the format string[9].
: Portable STREAMS drivers and modules will not use %s, %f, %e, %E, %g or %G conversion specifiers in the format string.
---: AIX® states that no more than NLOGARGS arguments can be passed, and that NLOGARGS defaults to four (4)[3]. IRIX®, Solaris® and UnixWare® state that no more than NLOGARGS arguments can be passed, and that NLOGARGS defaults to three (3)[5, 7, 8]. UXP/V® states that no more than NLOGARGS argumnets can be passed, but does not state a default for NLOGARGS[9].
: Portable STREAMS drivers and modules will pass more than NLOGARGS arguments to strlog(), and will not expect a NLOGARGS value of greater than three (3).
---: AIX®, HP-UX®, IRIX®, OSF/1®, Solaris® and UXP/V® do not document the SL_NOPUTBUF flag[3..7, 9]. The SL_NOPUTBUF flag is provided for UnixWare® source compatibility[8]. The default strlog() ignores this flag. The log(4) driver passes the resulting STREAMS message to the log driver as a M_PCPROTO(9) message instead of a M_PROTO(9) message.
: Portable STREAMS drivers and modules will not use the SL_NOPUTBUF flag.
---: OSF/1® does not document the SL_FATAL, SL_WARN, SL_NOTE, SL_NOTIFY or SL_NOPUTBUF flags.
---: The SL_NOTIFY flags is supposed to send a copy of the log to the system administrator. As Linux does not actually have a STREAMS based default logger (although it does use ``/dev/log''), when the default logger is used, the syslogd(8) facilities under Linux should be used instead. The default strlog(), therefore, ignores this flag. With the log(4) driver and the strerr(8) daemon running, the SL_NOTIFY flag behaves as described in strlog(4).
: Portable STREAMS drivers and modules will consider that additional configuration may be necessary for messages logged with the SL_NOTIFY flag to the system administrator.
---: The default strlog() logger takes a global spin lock to protect generation of the log buffer and printk(9) does the same. Under AIX®, HP-UX®, OSF/1®, Solaris®, UnixWare® and UXP/V®, strlog() does not take global locks and can be executed concurrently. This is one thing that normally distinguishes strlog() from cmn_err(9). With the log(4) driver loaded, no global spin locks are taken.
: Portable STREAMS drivers and modules will use the log(4) logger instead of the default logger.
---: LiS[10] does not provide this function, nor a STREAMS logger.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[11] instead of LiS.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1].

HISTORY

strlog() first appeared in SVR 4.0 STREAMS[12].

REFERENCES

[1]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: SVR 4 DDI/DKI, UNIX® System V Release 4 Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[4]: HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[5]: IRIX® 6.5.17, IRIX 6.5 Manual Pages, 2003, (Mountainview, California), Silicon Graphics, Inc., SGI Technical Publications. <http://techpubs.sgi.com/>
[6]: Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[7]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[8]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[9]: UXP/V® V10L10, UXP/V V10L10 Documentation, 1997, Fujitsu Limited, Fujitsu.
[10]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[11]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[12]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.