share/man/man9f/qassociate.9f

   1 '\" te
   2 .\" Copyright (c) 2007, 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 QASSOCIATE 9F "Feb 01, 2007"
   7 .SH NAME
   8 qassociate \- associate STREAMS queue with driver instance
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/stream.h>
  14 #include <sys/stropts.h>
  15 #include <sys/ddi.h>
  16 #include <sys/sunddi.h>
  17
  18 \fBint\fR \fBqassociate\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fIinstance\fR
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fBqueue_t *\fIq\fR\fR
  30 .ad
  31 .RS 16n
  32 Pointer to a \fBqueue\fR(9S) structure. Either the read or write queue can be
  33 used.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fBint \fIinstance\fR\fR
  40 .ad
  41 .RS 16n
  42 Driver instance number or -1.
  43 .RE
  44
  45 .SH DESCRIPTION
  46 .sp
  47 .LP
  48 The \fBqassociate()\fR function must be used by \fBDLPI\fR style 2 device
  49 drivers to manage the association between STREAMS queues and device instances.
  50 The \fBgld\fR(7D) does this automatically on behalf of drivers based on it. It
  51 is recommended that the \fBgld\fR(7D) be used for network device drivers
  52 whenever possible.
  53 .sp
  54 .LP
  55 The \fBqassociate()\fR function associates the specified STREAMS queue with the
  56 specified instance of the bottom driver in the queue. Upon successful return,
  57 the stream is associated with the instance with any prior association
  58 dissolved.
  59 .sp
  60 .LP
  61 A DLPI style 2 driver calls \fBqassociate()\fR while processing the
  62 \fBDL_ATTACH_REQ\fR message. The driver is also expected to call this interface
  63 while performing stream associations through other means, such as \fBndd\fR(8)
  64 ioctl commands.
  65 .sp
  66 .LP
  67 If \fIinstance\fR is -1, the stream is left unassociated with any hardware
  68 instance.
  69 .sp
  70 .LP
  71 If the interface returns failure, the stream is not associated with the
  72 specified instance. Any prior association is left untouched.
  73 .sp
  74 .LP
  75 The interface typically fails because of failure to locate and attach the
  76 device instance. The interface never fails if the specified instance is -1.
  77 .SH CONTEXT
  78 .sp
  79 .LP
  80 The \fBqassociate()\fR function can be called from the stream's \fBput\fR(9E)
  81 entry point.
  82 .SH RETURN VALUES
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fB0\fR\fR
  87 .ad
  88 .RS 6n
  89 Success.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fB-1\fR\fR
  96 .ad
  97 .RS 6n
  98 Failure.
  99 .RE
 100
 101 .SH EXAMPLES
 102 .sp
 103 .LP
 104 DLPI style 2 network driver \fBDL_ATTACH_REQ\fR code specifies:
 105 .sp
 106 .in +2
 107 .nf
 108 if (qassociate(q, instance) != 0)
 109                 goto fail;
 110 .fi
 111 .in -2
 112
 113 .sp
 114 .LP
 115 The association prevents Dynamic Reconfiguration (DR) from detaching the
 116 instance.
 117 .sp
 118 .LP
 119 DLPI style 2 network driver \fBDL_DETACH\fR code specifies:
 120 .sp
 121 .in +2
 122 .nf
 123 (void) qassociate(q, -1);
 124 .fi
 125 .in -2
 126
 127 .sp
 128 .LP
 129 This dissolves the queue's association with any device instance.
 130 .sp
 131 .LP
 132 DLPI style 2 network driver \fBopen\fR(9E) code must call:
 133 .sp
 134 .in +2
 135 .nf
 136 qassociate(q, -1);
 137 .fi
 138 .in -2
 139
 140 .sp
 141 .LP
 142 This informs the framework that this driver has been modified to be
 143 DDI-compliant.
 144 .SH SEE ALSO
 145 .sp
 146 .LP
 147 \fBdlpi\fR(7P), \fBgld\fR(7D), \fBopen\fR(9E), \fBput\fR(9E),
 148 \fBddi_no_info\fR(9F), \fBqueue\fR(9S)