qassociate(9f)

1qassociate(9F)           Kernel Functions for Drivers           qassociate(9F)
2
3
4

NAME

6       qassociate - associate STREAMS queue with driver instance
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/stream.h>
11       #include <sys/stropts.h>
12       #include <sys/ddi.h>
13       #include <sys/sunddi.h>
14
15       int qassociate(queue_t *q, int instance
16
17

INTERFACE LEVEL

19       Solaris DDI specific (Solaris DDI).
20

PARAMETERS

22       queue_t *q      Pointer  to  a  queue(9S) structure. Either the read or
23                       write queue can be used.
24
25
26       int instance    Driver instance number or -1.
27
28

DESCRIPTION

30       The qassociate() function must be used by DLPI style 2  device  drivers
31       to  manage the association between STREAMS queues and device instances.
32       The gld(7D) does this automatically on behalf of drivers based  on  it.
33       It  is  recommended that the gld(7D) be used for network device drivers
34       whenever possible.
35
36
37       The qassociate() function associates the specified STREAMS  queue  with
38       the specified instance of the bottom driver in the queue. Upon success‐
39       ful return, the stream is associated with the instance with  any  prior
40       association dissolved.
41
42
43       A   DLPI  style  2  driver  calls  qassociate()  while  processing  the
44       DL_ATTACH_REQ message. The driver is also expected to call this  inter‐
45       face  while performing stream associations through other means, such as
46       ndd(1M) ioctl commands.
47
48
49       If instance is -1, the stream is left unassociated  with  any  hardware
50       instance.
51
52
53       If the interface returns failure, the stream is not associated with the
54       specified instance. Any prior association is left untouched.
55
56
57       The interface typically fails because of failure to locate  and  attach
58       the  device  instance.  The  interface  never  fails  if  the specified
59       instance is -1.
60

CONTEXT

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

RETURN VALUES

66       0     Success.
67
68
69       -1    Failure.
70
71

EXAMPLES

73       DLPI style 2 network driver DL_ATTACH_REQ code specifies:
74
75         if (qassociate(q, instance) != 0)
76                         goto fail;
77
78
79
80       The  association  prevents  Dynamic Reconfiguration (DR) from detaching
81       the instance.
82
83
84       DLPI style 2 network driver DL_DETACH code specifies:
85
86         (void) qassociate(q, -1);
87
88
89
90       This dissolves the queue's association with any device instance.
91
92
93       DLPI style 2 network driver open(9E) code must call:
94
95         qassociate(q, -1);
96
97
98
99       This informs the framework that this driver has  been  modified  to  be
100       DDI-compliant.
101