'\" te
.\" Copyright (C) 1992 Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PIPEMOD 4M "Aug 21, 1992"
.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