te
Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
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.
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.
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]
QASSOCIATE 9F "Feb 01, 2007"
NAME
qassociate - associate STREAMS queue with driver instance
SYNOPSIS

#include <sys/types.h>
#include <sys/stream.h>
#include <sys/stropts.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

int qassociate(queue_t *q, int instance
INTERFACE LEVEL

Solaris DDI specific (Solaris DDI).

PARAMETERS
queue_t *q

Pointer to a queue(9S) structure. Either the read or write queue can be used.

int instance

Driver instance number or -1.

DESCRIPTION

The qassociate() function must be used by DLPI style 2 device drivers to manage the association between STREAMS queues and device instances. The gld(7D) does this automatically on behalf of drivers based on it. It is recommended that the gld(7D) be used for network device drivers whenever possible.

The qassociate() function associates the specified STREAMS queue with the specified instance of the bottom driver in the queue. Upon successful return, the stream is associated with the instance with any prior association dissolved.

A DLPI style 2 driver calls qassociate() while processing the DL_ATTACH_REQ message. The driver is also expected to call this interface while performing stream associations through other means, such as ndd(1M) ioctl commands.

If instance is -1, the stream is left unassociated with any hardware instance.

If the interface returns failure, the stream is not associated with the specified instance. Any prior association is left untouched.

The interface typically fails because of failure to locate and attach the device instance. The interface never fails if the specified instance is -1.

CONTEXT

The qassociate() function can be called from the stream's put(9E) entry point.

RETURN VALUES
0

Success.

-1

Failure.

EXAMPLES

DLPI style 2 network driver DL_ATTACH_REQ code specifies: 

if (qassociate(q, instance) != 0)
 goto fail;

The association prevents Dynamic Reconfiguration (DR) from detaching the instance.

DLPI style 2 network driver DL_DETACH code specifies: 

(void) qassociate(q, -1);

This dissolves the queue's association with any device instance.

DLPI style 2 network driver open(9E) code must call: 

qassociate(q, -1);

This informs the framework that this driver has been modified to be DDI-compliant.

SEE ALSO

dlpi(7P), gld(7D), open(9E), put(9E), ddi_no_info(9F), queue(9S)