STREAMS Programming Guide

Adding and Removing Modules

As part of constructing a stream, a module can be added (pushed) with an I_PUSH ioctl(2) (see streamio(7I)) call. The push inserts a module beneath the stream head. Because of the similarity of STREAMS components, the push operation is similar to the driver open.

Each push of a module is independent, even in the same stream. If the same module is pushed more than once on a stream, there are multiple occurrences of the module in the stream. The total number of pushable modules that may be contained on any one stream is limited by the kernel parameter nstrpush.

An I_POP ioctl(2) (see streamio(7I))) system call removes (pops) the module immediately below the stream head. The pop calls the module close procedure. On return from the module close, any messages left on the module's message queues are freed (deallocated). The stream head then connects to the component previously below the popped module and releases the module's queue pair.

I_PUSH and I_POP enable a user process to dynamically alter the configuration of a stream by pushing and popping modules as required. For example, a module may be removed and a new one inserted below the stream head. Then the original module can be pushed back after the new module has been pushed.

You can also restrict which modules can be popped with I_POP calls by placing an anchor in the stream at any module you want to “lock down.” The I_ANCHOR ioctl prevents a module from being popped except by a privileged process. See STREAMS Anchors for more information about working with anchors.