1mkiocb(9F) Kernel Functions for Drivers mkiocb(9F)
2
6 mkiocb - allocates a STREAMS ioctl block for M_IOCTL messages in the
7 kernel.
8
10 #include <sys/stream.h>
11 mblk_t *mkiocb(uint_t command);
15
18 Solaris DDI specific (Solaris DDI).
19
21 command ioctl command for the ioc_cmd field.
22
25 STREAMS modules or drivers might need to issue an ioctl to a lower mod‐
26 ule or driver. The mkiocb() function tries to allocate (using
27 allocb(9F)) a STREAMS M_IOCTL message block (iocblk(9S)). Buffer allo‐
28 cation fails only when the system is out of memory. If no buffer is
29 available, the qbufcall(9F) function can help a module recover from an
30 allocation failure.
31 The mkiocb function returns a mblk_t structure which is large enough to
34 hold any of the ioctl messages (iocblk(9S), copyreq(9S) or copy‐
35 resp(9S)), and has the following special properties:
36 b_wptr Set to b_rptr + sizeof(struct iocblk).
38 b_cont Set to NULL..
41 b_datap->db_type Set to M_IOCTL.
44 The fields in the iocblk structure are initialized as follows:
48 ioc_cmd Set to the command value passed in.
50 ioc_id Set to a unique identifier.
53 ioc_cr Set to point to a credential structure encoding the maxi‐
56 mum system privilege and which does not need to be freed
57 in any fashion.
58 ioc_count Set to 0.
61 ioc_rval Set to 0.
64 ioc_error Set to 0.
67 ioc_flags Set to IOC_NATIVE to reflect that this is native to the
70 running kernel.
71
74 Upon success, the mkiocb() function returns a pointer to the allocated
75 mblk_t of type M_IOCTL.
76 On failure, it returns a null pointer.
79
81 The mkiocb() function can be called from user, interrupt, or kernel
82 context.
83
85 Example 1 M_IOCTL Allocation
86 The first example shows an M_IOCTL allocation with the ioctl command
89 TEST_CMD. If the iocblk(9S) cannot be allocated, NULL is returned,
90 indicating an allocation failure (line 5). In line 11, the putnext(9F)
91 function is used to send the message downstream.
92 1 test_function(queue_t *q, test_info_t *testinfo)
95 2 {
96 3 mblk_t *mp;
97 4
98 5 if ((mp = mkiocb(TEST_CMD)) == NULL)
99 6 return (0);
100 7
101 8 /* save off ioctl ID value */
102 9 testinfo->xx_iocid = ((struct iocblk *)mp->b_rptr)->ioc_id;
103 10
104 11 putnext(q, mp); /* send message downstream */
105 12 return (1);
106 13 }
107 Example 2 The ioctl ID Value
110 During the read service routine, the ioctl ID value for M_IOCACK or
113 M_IOCNAK should equal the ioctl that was previously sent by this module
114 before processing.
115 1 test_lrsrv(queue_t *q)
119 2 {
120 3 ...
121 4
122 5 switch (DB_TYPE(mp)) {
123 6 case M_IOCACK:
124 7 case M_IOCNAK:
125 8 /* Does this match the ioctl that this module sent */
126 9 ioc = (struct iocblk*)mp->b_rptr;
127 10 if (ioc->ioc_id == testinfo->xx_iocid) {
128 11 /* matches, so process the message */
129 12 ...
130 13 freemsg(mp);
131 14 }
132 15 break;
133 16 }
134 17 ...
135 18 }
136 Example 3 An iocblk Allocation Which Fails
139 The next example shows an iocblk allocation which fails. Since the open
142 routine is in user context, the caller may block using qbufcall(9F)
143 until memory is available.
144 1 test_open(queue_t *q, dev_t devp, int oflag, int sflag,
147 cred_t *credp)
148 2 {
149 3 while ((mp = mkiocb(TEST_IOCTL)) == NULL) {
150 4 int id;
151 5
152 6 id = qbufcall(q, sizeof (union ioctypes), BPRI_HI,
153 7 dummy_callback, 0);
154 8 /* Handle interrupts */
155 9 if (!qwait_sig(q)) {
156 10 qunbufcall(q, id);
157 11 return (EINTR);
158 12 }
159 13 }
160 14 putnext(q, mp);
161 15 }
162
165 allocb(9F), putnext(9F), qbufcall(9F), qwait_sig(9F), copyreq(9S),
166 copyresp(9S), iocblk(9S)
167 Writing Device Drivers
170 STREAMS Programming Guide
173
175 It is the module's responsibility to remember the ID value of the
176 M_IOCTL that was allocated. This will ensure proper cleanup and ID
177 matching when the M_IOCACK or M_IOCNAK is received.
178SunOS 5.11 16 Jan 2006 mkiocb(9F)