Kernel Functions for Drivers                       qassociate(9F)



NAME
     qassociate - associate STREAMS queue with driver instance

SYNOPSIS
     #include 
     #include 
     #include 
     #include 
     #include 

     int qassociate(queuet *q, int instance


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

PARAMETERS
     queuet *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  dev-
     ice 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  possi-
     ble.


     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  DLATACHREQ  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.



SunOS 5.11          Last change: 01 Feb 2007                    1






Kernel Functions for Drivers                       qassociate(9F)



     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 DLATACHREQ code specifies:

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



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


     DLPI style 2 network driver DLDETACH 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  modi-
     fied to be DI-compliant.

SEE ALSO
     dlpi(7P),  gld(7D),  open(9E),   put(9E),   ddinoinfo(9F),
     queue(9S)






SunOS 5.11          Last change: 01 Feb 2007                    2