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

   1 '\" te
   2 .\" Copyright (c) 1993, 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 QWRITER 9F "Mar 1, 1993"
   7 .SH NAME
   8 qwriter \- asynchronous STREAMS perimeter upgrade
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/stream.h>
  13 #include <sys/ddi.h>
  14
  15
  16
  17 \fBvoid\fR \fBqwriter\fR(\fBqueue_t *\fR\fIqp\fR, \fBmblk_t *\fR\fImp\fR, \fBvoid (*\fR\fIfunc\fR)(), \fBint\fR \fIperimeter\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Solaris DDI specific (Solaris DDI).
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIqp\fR \fR
  29 .ad
  30 .RS 14n
  31 Pointer to the queue.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fImp\fR \fR
  38 .ad
  39 .RS 14n
  40 Pointer to a message that will be passed in to the callback function.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIfunc\fR \fR
  47 .ad
  48 .RS 14n
  49 A function that will be called when exclusive (writer) access has been acquired
  50 at the specified perimeter.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIperimeter\fR \fR
  57 .ad
  58 .RS 14n
  59 Either \fBPERIM_INNER\fR or \fBPERIM_OUTER\fR.
  60 .RE
  61
  62 .SH DESCRIPTION
  63 .sp
  64 .LP
  65 \fBqwriter()\fR is used to upgrade the access at either the inner or the outer
  66 perimeter from shared to exclusive and call the specified callback function
  67 when the upgrade has succeeded. See \fBmt-streams\fR(9F). The callback function
  68 is called as:
  69 .sp
  70 .in +2
  71 .nf
  72 \fB(*func)(queue_t *\fR\fIqp\fR\fB, mblk_t *\fR\fImp\fR\fB);\fR
  73 .fi
  74 .in -2
  75
  76 .sp
  77 .LP
  78 \fBqwriter()\fR will acquire exclusive access immediately if possible, in which
  79 case the specified callback function will be executed before \fBqwriter()\fR
  80 returns. If this is not possible, \fBqwriter()\fR will defer the upgrade until
  81 later and return before the callback function has been executed. Modules should
  82 not assume that the callback function has been executed when \fBqwriter()\fR
  83 returns. One way to avoid dependencies on the execution of the callback
  84 function is to immediately return after calling \fBqwriter()\fR and let the
  85 callback function finish the processing of the message.
  86 .sp
  87 .LP
  88 When \fBqwriter()\fR defers calling the callback function, the STREAMS
  89 framework will prevent other messages from entering the inner perimeter
  90 associated with the queue until the upgrade has completed and the callback
  91 function has finished executing.
  92 .SH CONTEXT
  93 .sp
  94 .LP
  95 \fBqwriter()\fR can only be called from an \fBput\fR(9E) or \fBsrv\fR(9E)
  96 routine, or from a \fBqwriter()\fR, \fBqtimeout\fR(9F), or \fBqbufcall\fR(9F)
  97 callback function.
  98 .SH SEE ALSO
  99 .sp
 100 .LP
 101 \fBput\fR(9E), \fBsrv\fR(9E), \fBmt-streams\fR(9F), \fBqbufcall\fR(9F),
 102 \fBqtimeout\fR(9F)
 103 .sp
 104 .LP
 105 \fISTREAMS Programming Guide\fR
 106 .sp
 107 .LP
 108 \fIWriting Device Drivers\fR