STREAMS Programming Guide

Chapter 15 Debugging

Overview of Debugging Facilities

Thischapter describes some of the tools available to assist in debugging STREAMS-based applications.

The basic categories available for debugging can be broken into these areas:

Kernel Debug Printing

Console Messages

The kernel routine cmn_err(9F) allows printing of formatted strings on a system console. It displays a specified message on the console and/or stores it in the msgbuf that is a circular array in the kernel and contains output from cmn_err(9F). Its format is:

#include <sys/cmn_err.h>

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

where level can take the following values:

STREAMS Error Logging

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

crash(1M) Command

crash(1M) examines kernel structures interactively. It can be used on a system dump and on an active system. The following crash functions are related to STREAMS:

adb(1) Command

adb(1) 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.

kadb(1M) Command

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