STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Pushing and Popping Modules
Chapter 2
30
Pushing and Popping Modules
IOCTL Commands I_PUSH and I_POP
Modules are an optional component of a stream. A module performs intermediate operations on messages as
they pass between components in a stream. Modules are added into a stream by using the I_PUSH ioctl (2)
command. Modules are removed from a stream by using the I_POP ioctl (2) command.
Synopsis
#include <sys/types.h> #include <sys/stropts.h>
int ioctl(int fd, cmd ... /*, arg */);
Arguments
fd STREAMS File Descriptor
cmd IOCTL command, e.g., I_PUSH, I_POP
arg Additional argument(s), if any, required by the IOCTL command. For I_PUSH, this
argument contains a pointer to the name of the module to be pushed on to the stream. For
I_POP, the arg value must be zero.
Return Values
The ioctl (2) returns a 0 upon successful execution, and a -1 on failure. The errno values are appropriately
set, as with all UNIX File System I/O.
The I_PUSH command pushes the module pointed by arg on to the top of the current stream, and below the
stream head. If the stream is a pipe, the module will be placed between the stream heads of both ends of the
pipe. It will then invoke the open routine for the module.
The I_POP command removes the module just below the stream head. If the stream is a pipe, the I_POP
directive should be executed on the side of the pipe where the corresponding I_PUSH command was used.
The following example illustrates the I_PUSH command:
if (ioctl(fd, I_PUSH, “caseconvert”) < 0)
{
/*PUSH-ing Module Dynamically */
perror(“ioctl I_PUSH failed”);
exit(1);
}
The following code sample illustrates the I_POP directive.
if (ioctl(fd,I_POP, 0 ) < 0)
{
/* POP - ping Module Dynamically */
perror(“ioctl I_POP failed”);
exit(2);
}