Part III Advanced Topics

Chapter 14 Debugging STREAMS-based Applications

This chapter describes some of the tools available to assist in debugging STREAMS-based applications. It contains the following information:

• Kernel Debug Printing

• STREAMS Error and Trace Logging

• Kernel Examination Tools

Kernel Debug Printing

The kernel routine cmn_err(9F) enables printing of formatted strings on a system console. It displays a specified message on the console and can also store it in the msgbuf that is a circular array in the kernel. The format of cmn_err(9F) is:

#include <sys/cmn_err.h>

void cmn_err (int level, char *fmt, int args)

where level can take the following values:

• CE_CONT — may be used as simple printf(3C). It is used to continue another message or to display an informative message not associated with an error.

• CE_NOTE — reports system events. It is used to display a message preceded by NOTICE:. This message is used to report system events that do not necessarily require user action, but may interest the system administrator. An example is a sector on a disk needing to be accessed repeatedly before it can be accessed correctly.

• CE_WARN — reports system events that require user action. This is used to display a message preceded by WARNING:. This message is used to report system events that require immediate attention, such as those where, if an action is not taken, the system may panic. For example, when a peripheral device does not initialize correctly, this level should be used.

• CE_PANIC — reports system panic. This is used to display a message preceded with PANIC:. Drivers should specify this level only under the most severe conditions. A valid use of this level is when the system cannot continue to function. If the error is recoverable and not essential to continued system operation, do not panic the system. This level halts all processing.

fmt and args are passed to the kernel routine printf that runs at splhi and should be used sparingly. If the first character of fmt is ! (an exclamation point), output is directed to msgbuf. msgbuf can be accessed with the crash command. If the destination character begins with ^ (a caret) output goes to the console. If no destination character is specified, the message is directed to both the msgbuf array and the console.

cmn_err(9F) appends each fmt with “\n”, except for the CE_CONT level, even when a message is sent to the msgbuf array. args specifies a set of arguments passed when the message is displayed. Valid specifications are %s (string), %u (unsigned decimal), %d (decimal), %o (octal), and %x (hexadecimal). cmn_err(9F) does not accept length specifications in conversion specifications. For example, %3d is ignored.

crash has reached EOL and is not supported in the Solaris 9 operating environment. For information about how to transition from crash to mdb, see the Solaris Modular Debugger Guide.

STREAMS Error and Trace Logging

STREAMS error and trace loggers are provided for debugging and for administering STREAMS modules and drivers. This facility consists of log(7D), strace(1M), strclean(1M), strerr(1M), and strlog(9F).

Any module or driver in any stream can call the STREAMS logging function strlog(9F) (see also log(7D)). strlog(9F) sends formatted text to the error logger strerr(1M), the trace logger strace(1M), or the console logger.

strerr(1M) runs as a daemon process initiated at system startup. A call to strlog(9F) requesting an error to be logged causes an M_PROTO message to be sent to strerr(1M), which formats the contents and places them in a daily file. strclean(1M) purges daily log files that have not been modified for three days.

strlog(9F) also sends a similar M_PROTO message to strace(1M), which places it in a user-designated file. strace(1M) is initiated by a user. The user designates the modules and drivers and the severity level of the messages accepted for logging by strace(1M).

A user process can submit its own M_PROTO messages to the log driver for inclusion in the logger of its choice through putmsg(2). The messages must be in the same format required by the logging processes and are switched to the loggers requested in the message.

The output to the log files is formatted ASCII text. The files can be processed by standard system commands such as grep(1) or by developer-provided routines.

Kernel Examination Tools

Use crash, adb, and kadb(1M) to examine the kernel.

crash Command

crash examines kernel structures interactively. It can be used on a system dump and on an active system.

crash has reached EOL and is not supported in the Solaris 9 operating environment. For information about how to transition from crash to mdb, see the Solaris Modular Debugger Guide.

The following crash functions are related to STREAMS:

• dbfree — Print data block header free list.

• dblock — Print allocated STREAMS data block headers.

• linkblk — Print the linkblk(9S) table.

• mbfree — Print free STREAMS message block headers.

• mblock — Print allocated STREAMS message block headers.

• pty — Print pseudo-TTYs now configured. The l option gives information on the line discipline module. ldterm(7M), the h option provides information on the pseudo-TTY emulation module ptem(7M). The s option gives information on the packet module pckt(7M).

• qrun — Print a list of scheduled queues.

• queue — Print the STREAMS queues.

• stream — Print the stdata table.

• strstat — Print STREAMS statistics.

• tty — Print the tty table. The l option prints details about the line-discipline module.

  The crash functions dblock, linkblk, mblock, queue, and stream take an optional table entry argument or address that is the address of the data structure. The strstat command gives information about STREAMS event cells and linkblks in addition to message blocks, data blocks, queues, and streams. On the output report, the CONFIG column represents the number of structures currently configured. It may change because resources are allocated as needed.

adb Command

adb is an interactive general-purpose debugger. It can be used to examine files and provides a controlled environment for the execution of programs. It has no support built in for any STREAMS functionality.

adb has reached EOL and is not supported in the Solaris 9 operating environment. For information about how to transition from adb to mdb, see the Solaris Modular Debugger Guide.

kadb Command

kadb(1M) is an interactive debugger with a user interface similar to adb(1), but it runs in the same virtual address space as the program begin debugged. It also has no specific STREAMS support.