STREAMS-UX Programmer's Guide (February 2007)

Modules and Drivers

STREAMS Module

Chapter 4

STREAMS Module

A STREAMS module is essentially a pair of queues and a defined set of kernel-level routines and data

structures used to process messages as they flow through them in a stream. A stream may have zero or more

modules and pushing and popping of these modules happens in a Last In First Out (LIFO) manner.

Flow Control in Modules

Module flow control is advised and when used helps in limiting the amount of data that can be placed on a

modules’ queue. STREAMS modules must define a service procedure to utilize the STREAMS flow control

mechanism; invoking canput()/canputnext() before calling putnext() and using appropriate high and low

water marks for the queues. In addition to canput(), the streams utilities getq(), putq() and putbq() are

also used in implementing the module’s flow control.

In a module implementing the flow control:

• The put procedure queues the data using putq() (but forwards all the high priority messages regardless

of flow control).

•The putq() in turn increments the q_count appropriately (sets the QFULL flag if q_count exceeds the

high water mark) and enables the service procedure.

• When the STREAMS scheduler runs the service procedure, data is retrieved by using getq().

•The getq() decrements the q_count by an appropriate value (unsets the QFULL flag if q_count drops

below the low water mark and enables the nearest back queue with a service procedure).

• The service procedure must verify if the next component in the stream is flow controlled by doing a

canputnext() and do a putnext() if not flow controlled. If canput()/canputnext() fails, the module

should put back the message on it’s own queue by doing a putbq().

• If the module ahead is not flow controlled, the service procedure must process all the messages on it’s

queue before it returns.

Sample Module

The various data structures and routines required to define a STREAMS module have already been described

in the previous sections. In this section code examples have been given to substantiate the same.

NOTE There is no major number associated with a module, hence a value of “-1” needs to be specified

in a module’s streams_info_t struct.

Module Declaration

/* Sample Module inclusions */

#include <sys/types.h>

#include <sys/errno.h>

#include <sys/stream.h>

#include <sys/stropts.h>