'\" te
.\" Copyright (C) 1992 Sun Microsystems, Inc. All Rights Reserved
.TH pipemod 7M "21 Aug 1992" "SunOS 5.11" "STREAMS Modules"
.SH NAME
pipemod \- STREAMS pipe flushing module
.SH DESCRIPTION
.sp
.LP
The typical stream is composed of a stream head connected to modules and terminated by a driver. Some stream configurations such as pipes and \fBFIFOs\fR do not have a driver and hence certain features commonly supported by the driver need to be provided by other means. Flushing is one such feature, and it is provided by the \fBpipemod\fR module.
.sp
.LP
Pipes and \fBFIFOs\fR in their simplest configurations only have stream heads. A write side is connected to a read side. This remains true when modules are pushed. The twist occurs at a point known as the mid-point. When an \fBM_FLUSH\fR message is passed from a write queue to a read queue the \fBFLUSHR\fR and/or \fBFLUSHW\fR bits have to be switched. The mid-point of a pipe is not always easily detectable, especially if there are numerous modules pushed on either end of the pipe. In that case there needs to be a mechanism to intercept all message passing through the stream. If the message is an \fBM_FLUSH\fR message and it is at the mid-point, the flush bits need to be switched. This bit switching is handled by the \fBpipemod\fR module.
.sp
.LP
\fBpipemod\fR should be pushed onto a pipe or \fBFIFO\fR where flushing of any kind will take place. The \fBpipemod\fR module can be pushed on either end of the pipe. The only requirement is that it is pushed onto an end that previously did not have modules on it. That is, pipemod must be the first module pushed onto a pipe so that it is at the mid-point of the pipe itself.
.sp
.LP
The \fBpipemod\fR module handles only \fBM_FLUSH\fR messages. All other messages are passed on to the next module using the \fBputnext()\fR utility routine. If an \fBM_FLUSH\fR message is passed to \fBpipemod\fR and the \fBFLUSHR\fR and \fBFLUSHW\fR bits are set, the message is not processed but is passed to the next module using the \fBputnext()\fR routine. If only the \fBFLUSHR\fR bit is set, the \fBFLUSHR\fR bit is turned off and the \fBFLUSHW\fR bit is set. The message is then passed on to the next module using \fBputnext()\fR. Similarly, if the \fBFLUSHW\fR bit is the only bit set in the \fBM_FLUSH\fR message, the \fBFLUSHW\fR bit is turned off and the \fBFLUSHR\fR bit is turned on. The message is then passed to the next module on the stream.
.sp
.LP
The \fBpipemod\fR module can be pushed on any stream that desires the bit switching. It must be pushed onto a pipe or \fBFIFO\fR if any form of flushing must take place.
.SH SEE ALSO
.sp
.LP
\fISTREAMS Programming Guide\fR