STREAMS Programming Guide

Inserting Modules

An application can insert various modules into a stream to process and manipulate data that pass between a user process and the driver. In the example, the character conversion module receives a command and a corresponding string of characters from the user. All data passing through the module is inspected for instances of characters in this string. Whatever operation the command requires is performed on all characters that match the string. Code fragments with explanations follow in Example 2-1.

Example 2-1 Header Definition

#include <string.h>
#include <fcntl.h>
#include <stropts.h>
#define				BUFLEN				1024
 * These definitions would typically be
 * found in a header file for the module
#define		XCASE				 	 1 /* change alphabetic case of char */
#define			DELETE				 2 /* delete char */
#define			DUPLICATE				 3 /* duplicate char */
 	char buf[BUFLEN];
 	int fd, count;
 	struct strioctl strioctl;

The first step is to establish a stream to the communications driver and insert the character conversion module. This is accomplished by first opening (fd = open) then calling ioctl(2) to push the chconv module, as shown in the sequence of system calls in Example 2-2.

Example 2-2 Pushing a Module

if ((fd = open("/dev/term/a", O_RDWR)) < 0) {
 	perror("open failed");
if (ioctl(fd, I_PUSH, "chconv") < 0) {
 	perror("ioctl I_PUSH failed");

The I_PUSH ioctl(2) call directs the stream head to insert the character conversion module between the driver and the stream head. The example illustrates an important difference between STREAMS drivers and modules. Drivers are accessed through a node or nodes in the file system, in this case /dev/term/a, and are opened just like other devices. Modules, on the other hand, are not devices. Identify modules through a separate naming convention, and insert them into a stream using I_PUSH or autopush. Figure 2-1 shows creation of the stream.

Figure 2-1 Pushing the Character Conversion Module


Modules are stacked onto a stream and removed from a stream in last-in, first-out (LIFO) order. Therefore, if a second module is pushed onto this stream, it is inserted between the stream head and the character conversion module.