'\" te
.\" Copyright (c) 1993, Sun Microsystems, Inc., All Rights Reserved
.TH qwriter 9F "1 Mar 1993" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
qwriter \- asynchronous STREAMS perimeter upgrade
.SH SYNOPSIS
.LP
.nf
#include <sys/stream.h>
#include <sys/ddi.h> 

\fBvoid\fR \fBqwriter\fR(\fBqueue_t *\fR\fIqp\fR, \fBmblk_t *\fR\fImp\fR, \fBvoid (*\fR\fIfunc\fR)(), \fBint\fR \fIperimeter\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIqp\fR \fR
.ad
.RS 14n
.rt  
Pointer to the queue.
.RE

.sp
.ne 2
.mk
.na
\fB\fImp\fR \fR
.ad
.RS 14n
.rt  
Pointer to a message that will be passed in to the callback function.
.RE

.sp
.ne 2
.mk
.na
\fB\fIfunc\fR \fR
.ad
.RS 14n
.rt  
A function that will be called when exclusive (writer) access has been acquired at the specified perimeter.
.RE

.sp
.ne 2
.mk
.na
\fB\fIperimeter\fR \fR
.ad
.RS 14n
.rt  
Either \fBPERIM_INNER\fR or \fBPERIM_OUTER\fR. 
.RE

.SH DESCRIPTION
.sp
.LP
\fBqwriter()\fR is used to upgrade the access at either the inner or the outer perimeter from shared to exclusive and call the specified callback function when the upgrade has succeeded. See \fBmt-streams\fR(9F). The callback function is called as:
.sp
.in +2
.nf
\fB(*func)(queue_t *\fR\fIqp\fR\fB, mblk_t *\fR\fImp\fR\fB);\fR
.fi
.in -2

.sp
.LP
\fBqwriter()\fR will acquire exclusive access immediately if possible, in which case the specified callback function will be executed before \fBqwriter()\fR returns. If this is not possible, \fBqwriter()\fR will defer the upgrade until later and return before the callback function has been executed. Modules should not assume that the callback function has been executed when \fBqwriter()\fR returns. One way to avoid dependencies on the execution of the callback function is to immediately return after calling \fBqwriter()\fR and let the callback function finish the processing of the message.
.sp
.LP
When \fBqwriter()\fR defers calling the callback function, the STREAMS framework will prevent other messages from entering the inner perimeter associated with the queue until the upgrade has completed and the callback function has finished executing.
.SH CONTEXT
.sp
.LP
\fBqwriter()\fR can only be called from an \fBput\fR(9E) or \fBsrv\fR(9E) routine, or from a \fBqwriter()\fR, \fBqtimeout\fR(9F), or \fBqbufcall\fR(9F) callback function.
.SH SEE ALSO
.sp
.LP
\fBput\fR(9E), \fBsrv\fR(9E), \fBmt-streams\fR(9F), \fBqbufcall\fR(9F), \fBqtimeout\fR(9F) 
.sp
.LP
\fISTREAMS Programming Guide\fR 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR