usr/src/man/man9f/qwait.9f

   1 '\" te
   2 .\" Copyright (c) 2003, 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 QWAIT 9F "Dec 15, 2003"
   7 .SH NAME
   8 qwait, qwait_sig \- STREAMS wait routines
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/stream.h>
  13 #include <sys/ddi.h>
  14
  15
  16
  17 \fBvoid\fR \fBqwait\fR(\fBqueue_t *\fR\fIq\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBqwait_sig\fR(\fBqueue_t *\fR\fIq\fR);
  23 .fi
  24
  25 .SH INTERFACE LEVEL
  26 .sp
  27 .LP
  28 Solaris DDI specific (Solaris DDI).
  29 .SH PARAMETERS
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fIqp\fR\fR
  34 .ad
  35 .RS 6n
  36 Pointer to the queue that is being opened or closed.
  37 .RE
  38
  39 .SH DESCRIPTION
  40 .sp
  41 .LP
  42 \fBqwait()\fR and \fBqwait_sig()\fR are used to wait for a message to arrive to
  43 the \fBput\fR(9E) or \fBsrv\fR(9E) procedures. \fBqwait()\fR and
  44 \fBqwait_sig()\fR can also be used to wait for \fBqbufcall\fR(9F) or
  45 \fBqtimeout\fR(9F) callback procedures to execute. These routines can be used
  46 in the \fBopen\fR(9E) and \fBclose\fR(9E) procedures in a STREAMS driver or
  47 module.
  48 .sp
  49 .LP
  50 The thread that calls \fBclose()\fR does not necessarily have the ability to
  51 receive signals, particularly when called by \fBexit\fR(2). In this case,
  52 \fBqwait_sig()\fR behaves exactly as \fBqwait()\fR. Driver writers may use
  53 \fBddi_can_receive_sig\fR(9F) to determine when this is the case, and, if so,
  54 arrange some means to avoid blocking indefinitely (for example, by using
  55 \fBqtimeout\fR(9F).
  56 .sp
  57 .LP
  58 \fBqwait()\fR and \fBqwait_sig()\fR atomically exit the inner and outer
  59 perimeters associated with the queue, and wait for a thread to leave the
  60 module's \fBput\fR(9E), \fBsrv\fR(9E), or \fBqbufcall\fR(9F) /
  61 \fBqtimeout\fR(9F) callback procedures. Upon return they re-enter the inner and
  62 outer perimeters.
  63 .sp
  64 .LP
  65 This can be viewed as there being an implicit wakeup when a thread leaves a
  66 \fBput\fR(9E) or \fBsrv\fR(9E) procedure or after a \fBqtimeout\fR(9F) or
  67 \fBqbufcall\fR(9F) callback procedure has been run in the same perimeter.
  68 .sp
  69 .LP
  70 \fBqprocson\fR(9F) must be called before calling \fBqwait()\fR or
  71 \fBqwait_sig()\fR.
  72 .sp
  73 .LP
  74 \fBqwait()\fR is not interrupted by a signal, whereas \fBqwait_sig()\fR is
  75 interrupted by a signal. \fBqwait_sig()\fR normally returns non-zero, and
  76 returns zero when the waiting was interrupted by a signal.
  77 .sp
  78 .LP
  79 \fBqwait()\fR and \fBqwait_sig()\fR are similar to \fBcv_wait()\fR and
  80 \fBcv_wait_sig()\fR except that the mutex is replaced by the inner and outer
  81 perimeters and the signalling is implicit when a thread leaves the inner
  82 perimeter. See \fBcondvar\fR(9F).
  83 .SH RETURN VALUES
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fB0\fR\fR
  88 .ad
  89 .RS 5n
  90 For \fBqwait_sig()\fR, indicates that the condition was not necessarily
  91 signaled, and the function returned because a signal was pending.
  92 .RE
  93
  94 .SH CONTEXT
  95 .sp
  96 .LP
  97 These functions can only be called from an \fBopen\fR(9E) or \fBclose\fR(9E)
  98 routine.
  99 .SH EXAMPLES
 100 .LP
 101 \fBExample 1 \fRUsing \fBqwait()\fR
 102 .sp
 103 .LP
 104 The open routine sends down a \fBT_INFO_REQ\fR message and waits for the
 105 \fBT_INFO_ACK\fR. The arrival of the \fBT_INFO_ACK\fR is recorded by resetting
 106 a flag in the unit structure (\fBWAIT_INFO_ACK\fR). The example assumes that
 107 the module is \fBD_MTQPAIR\fR or \fBD_MTPERMOD\fR.
 108
 109 .sp
 110 .in +2
 111 .nf
 112 xxopen(qp, .\|.\|.)
 113        queue_t *qp;
 114 {
 115               struct xxdata *xx;
 116                /* Allocate xxdata structure */
 117        qprocson(qp);
 118        /* Format T_INFO_ACK in mp */
 119        putnext(qp, mp);
 120        xx->xx_flags |= WAIT_INFO_ACK;
 121        while (xx->xx_flags & WAIT_INFO_ACK)
 122                             qwait(qp);
 123               return (0);
 124 }
 125 xxrput(qp, mp)
 126        queue_t *qp;
 127        mblk_t *mp;
 128 {
 129        struct xxdata *xx = (struct xxdata *)q->q_ptr;
 130
 131               ...
 132
 133               case T_INFO_ACK:
 134                             if (xx->xx_flags & WAIT_INFO_ACK) {
 135                                       /* Record information from info ack */
 136                                       xx->xx_flags &= ~WAIT_INFO_ACK;
 137                                       freemsg(mp);
 138                                       return;
 139                             }
 140
 141               ...
 142 }
 143 .fi
 144 .in -2
 145
 146 .SH SEE ALSO
 147 .sp
 148 .LP
 149 \fBclose\fR(9E), \fBopen\fR(9E), \fBput\fR(9E), \fBsrv\fR(9E),
 150 \fBcondvar\fR(9F), \fBddi_can_receive_sig\fR(9F), \fBmt-streams\fR(9F),
 151 \fBqbufcall\fR(9F), \fBqprocson\fR(9F), \fBqtimeout\fR(9F)
 152 .sp
 153 .LP
 154 \fISTREAMS Programming Guide\fR
 155 .sp
 156 .LP
 157 \fIWriting Device Drivers\fR