STREAMS Programming Guide

Chapter 5 STREAMS Administration

This chapter describes the tools available to administer STREAMS. It shows how to keep track of names, where to find modules, and how to monitor statistics. Kernel debugging is covered in Chapter 14, Debugging STREAMS-based Applications.

Administration Tools

Table 5-1 identifies some common tools available for monitoring, logging, and administering STREAMS.

Table 5–1 Tools Available for STREAMS Administration




Configures list of modules to be automatically pushed 


Examines system memory images 

Note –

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.


Detaches a name from a file descriptor 


Prints STREAMS trace messages 

strchg(1), strconf(1)

Changes or queries a stream configuration 


Logs STREAMS errors 


Loads a kernel module 


Unloads a kernel module 


Displays information about loaded kernel modules 

Autopush Facility

The autopush facility (see autopush(1M)) enables administrators to specify a list of modules to be automatically pushed onto the stream whenever a STREAMS device is opened. A prespecified list (/etc/iu.ap) of modules can be pushed onto the stream if the STREAMS device is not already open.

The STREAMS Administrative Driver (SAD) (see sad(7D)) provides an interface to the autopush mechanism. System administrators can open the SAD and set or get autopush information on other drivers. The SAD caches the list of modules to push for each driver. When the driver is opened, if not already open, the stream head checks the SAD's cache to determine if the device is configured to have modules automatically pushed. If an entry is found, the modules are pushed. If the device is open, another open does not cause the list of the prespecified modules to be pushed again.

The autopush SAD_SAP command ap_cmd field specifies the configuration options:


Configure each minor device (that is, a specific major and minor device number).


Configure a range of minor devices within a major device.


Configure all minor devices within a major device.


Undo configuration information for a driver.

In addition, when configuring the module list, an optional anchor can be placed within the list. (See STREAMS Anchors for more information.)

When the configuration list is cleared, a range of minor devices has to be cleared as a range and not in parts.

Application Interface

The SAD is accessed through /dev/sad/admin or /dev/sad/user. After the device is initialized, a program can be run to perform any needed autopush configuration. The program should open the SAD, read a configuration file to find out what modules must be configured for which devices, format the information into strapush structures, and perform the necessary SAD_SAP ioctl(2)s. See sad(7D) for more information.

All autopush operations are performed through an ioctl(2) command to set or get autopush information. Only the root user can set autopush information, but any user can get the autopush information for a device.

In the ioctl(2) call, the parameters are the file descriptor of the SAD, either SAD_SAP (set autopush information) or SAD_GAP (get autopush information), and a pointer to a strapush structure.

strapush is defined as:

 * maximum number of modules that can be pushed on a
 * Stream using the autopush feature should be no greater
 * than nstrpush
#define MAXAPUSH 8
/* autopush information common to user and kernel */
struct apcommon {
 	uint apc_cmd;          /* command - see below */
 	major_t apc_major;     /* major device number */
 	minor_t apc_minor;     /* minor device number */
 	minor_t apc_lastminor; /* last minor dev # for range */
 	uint apc_npush;        /* number of modules to push */
/* ap_cmd - various options of autopush */
#define SAP_CLEAR    0     /* remove configuration list */
#define SAP_ONE      1     /* configure one minor device*/
#define SAP_RANGE    2     /* config range of minor devices */
#define SAP_ALL      3     /* configure all minor devices */
/* format of autopush ioctls */
struct strapush {
 	struct apcommon sap_common;
 	char sap_list[MAXAPUSH] [FMNAMESZ + 1]; /* module list */
#define sap_cmd              sap_common.apc_cmd
#define sap_major            sap_common.apc_major
#define sap_minor            sap_common.apc_minor
#define sap_lastminor        sap_common.apc_lastminor
#define sap_npush            sap_common.apc_npush

A device is identified by its major device number, sap_major. A SAD_CMD ioctl(2) is one of the following commands:


Clears the previous settings by removing the entry with the matching sap_major and sap_minor fields


Configures a single minor device, sap_minor, of a driver


Configures a range of minor devices from sap_minor to sap_lastminor, inclusive


Configures all minor devices of a device

The list of modules is specified as a list of module names in sap_list. The maximum number of modules to push automatically is defined by MAXAPUSH.

A user can query the current configuration status of a given major or minor device by issuing the SAD_GAP ioctl(2) with sap_major and sap_minor values of the device set. On successful return from this system call, the strapush structure will be filled in with the corresponding information for that device. The maximum number of entries the SAD driver can cache is determined by the tunable parameter NAUTOPUSH found in the SAD driver's master file.

The following is an example of an autopush configuration file in /etc/iu.ap:

#	major    minor   lastminor   modules
		wc       0       0        ldterm ttcompat
		zs       0       1        ldterm ttcompat
		ptsl     0       15       ldterm ttcompat

The first line is the configuration of a single minor device whose major name is wc and minor numbers start at 0 and end at 0, creating only one minor number. The modules automatically pushed are ldterm and ttcompat. The second line represents the configuration of the zs driver. The minor device numbers are 0 and 1. The last line allows minor device numbers from 0 to 15 for the ptsl driver.

Administration Tool Description

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 the strlog(9F) function.

strace Command

strace(1M) is a utility that displays the messages in a specified STREAMS log. The log to display is identified by STREAMS module ID number, a sub-ID number, and the priority level.

strlog Command

strlog(9F) sends formatted text to log(7D) driver. Required definitions are contained in <sys/strlog.h> and <sys/log.h>. The call specifies the STREAMS module ID number, a sub-ID number, and the priority level. A flag parameter can specify any combination of:


The message is for the error logger


The message is for the tracer


Advisory notification of a fatal error


Modifies the SL_ERROR flag to request that a copy of the message be mailed to the system administrator


Log the message to the console


Warning message


Notice the message

The flags are followed by a printf(3C)-style format string, but %s, %e, %E, %g, and %G conversion specifications are not recognized. Up to NLOGARGS of numeric or character arguments can be specified.

strqget Command

strqget(9F) gets information about a queue or band of a queue. The information is returned in a long. The stream must be frozen by the caller when calling strqget.

strqset Command

strqset(9F) changes information about a queue or band of the queue. The updated information is provided in an int. If the field is read-only, EPERM is returned and the field is left unchanged. See <sys/stream.h> for valid values. The stream must be frozen by the caller when calling strqset(9F).

strerr Daemon

strerr(1M) is the STREAMS error logger daemon.