qassociate(9F)

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).  This  entry  point  is
     required for drivers which export cb_ops(9S) entry points.

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 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  associ-
     ated  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

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

RETURN VALUES

     0     Success.
     -1    Failure.

EXAMPLES

     A Style-2 network driver's DL_ATTACH_REQ code would specify:

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

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

     A Style-2 network driver's DL_DETACH code would specify:

     (void) qassociate(q, -1);

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

     A Style-2 network driver's open(9E) code must call:

     qassociate(q, -1);

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

SEE ALSO

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