usr/src/man/man7m/pipemod.7m

   1 '\" te
   2 .\" Copyright (C) 1992 Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PIPEMOD 7M "Aug 21, 1992"
   7 .SH NAME
   8 pipemod \- STREAMS pipe flushing module
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 The typical stream is composed of a stream head connected to modules and
  13 terminated by a driver. Some stream configurations such as pipes and
  14 \fBFIFOs\fR do not have a driver and hence certain features commonly supported
  15 by the driver need to be provided by other means. Flushing is one such feature,
  16 and it is provided by the \fBpipemod\fR module.
  17 .sp
  18 .LP
  19 Pipes and \fBFIFOs\fR in their simplest configurations only have stream heads.
  20 A write side is connected to a read side. This remains true when modules are
  21 pushed. The twist occurs at a point known as the mid-point. When an
  22 \fBM_FLUSH\fR message is passed from a write queue to a read queue the
  23 \fBFLUSHR\fR and/or \fBFLUSHW\fR bits have to be switched. The mid-point of a
  24 pipe is not always easily detectable, especially if there are numerous modules
  25 pushed on either end of the pipe. In that case there needs to be a mechanism to
  26 intercept all message passing through the stream. If the message is an
  27 \fBM_FLUSH\fR message and it is at the mid-point, the flush bits need to be
  28 switched. This bit switching is handled by the \fBpipemod\fR module.
  29 .sp
  30 .LP
  31 \fBpipemod\fR should be pushed onto a pipe or \fBFIFO\fR where flushing of any
  32 kind will take place. The \fBpipemod\fR module can be pushed on either end of
  33 the pipe. The only requirement is that it is pushed onto an end that previously
  34 did not have modules on it. That is, pipemod must be the first module pushed
  35 onto a pipe so that it is at the mid-point of the pipe itself.
  36 .sp
  37 .LP
  38 The \fBpipemod\fR module handles only \fBM_FLUSH\fR messages. All other
  39 messages are passed on to the next module using the \fBputnext()\fR utility
  40 routine. If an \fBM_FLUSH\fR message is passed to \fBpipemod\fR and the
  41 \fBFLUSHR\fR and \fBFLUSHW\fR bits are set, the message is not processed but is
  42 passed to the next module using the \fBputnext()\fR routine. If only the
  43 \fBFLUSHR\fR bit is set, the \fBFLUSHR\fR bit is turned off and the
  44 \fBFLUSHW\fR bit is set. The message is then passed on to the next module using
  45 \fBputnext()\fR. Similarly, if the \fBFLUSHW\fR bit is the only bit set in the
  46 \fBM_FLUSH\fR message, the \fBFLUSHW\fR bit is turned off and the \fBFLUSHR\fR
  47 bit is turned on. The message is then passed to the next module on the stream.
  48 .sp
  49 .LP
  50 The \fBpipemod\fR module can be pushed on any stream that desires the bit
  51 switching. It must be pushed onto a pipe or \fBFIFO\fR if any form of flushing
  52 must take place.
  53 .SH SEE ALSO
  54 .sp
  55 .LP
  56 \fISTREAMS Programming Guide\fR