usr/src/man/man9f/mkiocb.9f

   1 '\" te
   2 .\"  Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH MKIOCB 9F "Jan 16, 2006"
   7 .SH NAME
   8 mkiocb \- allocates a STREAMS ioctl block for M_IOCTL messages in the kernel.
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/stream.h>
  13
  14
  15
  16 \fBmblk_t *\fR\fBmkiocb\fR(\fBuint_t\fR \fIcommand\fR);
  17 .fi
  18
  19 .SH INTERFACE LEVEL
  20 .sp
  21 .LP
  22 Solaris DDI specific (Solaris DDI).
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIcommand\fR\fR
  28 .ad
  29 .RS 11n
  30 ioctl command for the \fBioc_cmd\fR field.
  31 .RE
  32
  33 .SH DESCRIPTION
  34 .sp
  35 .LP
  36 STREAMS modules or drivers might need to issue an ioctl to a lower module or
  37 driver. The \fBmkiocb()\fR function tries to allocate (using \fBallocb\fR(9F))
  38 a STREAMS \fBM_IOCTL\fR message block (\fBiocblk\fR(9S)). Buffer allocation
  39 fails only when the system is out of memory. If no buffer is available, the
  40 \fBqbufcall\fR(9F) function can help a module recover from an allocation
  41 failure.
  42 .sp
  43 .LP
  44 The \fBmkiocb\fR function returns a \fBmblk_t\fR structure which is large
  45 enough to hold any of the ioctl messages (\fBiocblk\fR(9S), \fBcopyreq\fR(9S)
  46 or \fBcopyresp\fR(9S)), and has the following special properties:
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fBb_wptr\fR\fR
  51 .ad
  52 .RS 20n
  53 Set to \fBb_rptr + sizeof(struct iocblk)\fR.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBb_cont\fR\fR
  60 .ad
  61 .RS 20n
  62 Set to \fINULL.\fR.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBb_datap->db_type\fR\fR
  69 .ad
  70 .RS 20n
  71 Set to \fBM_IOCTL\fR.
  72 .RE
  73
  74 .sp
  75 .LP
  76 The fields in the iocblk structure are initialized as follows:
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBioc_cmd\fR\fR
  81 .ad
  82 .RS 13n
  83 Set to the command value passed in.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBioc_id\fR\fR
  90 .ad
  91 .RS 13n
  92 Set to a unique identifier.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBioc_cr\fR\fR
  99 .ad
 100 .RS 13n
 101 Set to point to a credential structure encoding the maximum system privilege
 102 and which does not need to be freed in any fashion.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBioc_count\fR\fR
 109 .ad
 110 .RS 13n
 111 Set to 0.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBioc_rval\fR\fR
 118 .ad
 119 .RS 13n
 120 Set to 0.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBioc_error\fR\fR
 127 .ad
 128 .RS 13n
 129 Set to 0.
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBioc_flags\fR\fR
 136 .ad
 137 .RS 13n
 138 Set to \fBIOC_NATIVE\fR to reflect that this is native to the running kernel.
 139 .RE
 140
 141 .SH RETURN VALUES
 142 .sp
 143 .LP
 144 Upon success, the \fBmkiocb()\fR function returns a pointer to the allocated
 145 \fBmblk_t\fR of type \fBM_IOCTL\fR.
 146 .sp
 147 .LP
 148 On failure, it returns a null pointer.
 149 .SH CONTEXT
 150 .sp
 151 .LP
 152 The \fBmkiocb()\fR function can be called from user, interrupt, or kernel
 153 context.
 154 .SH EXAMPLES
 155 .LP
 156 \fBExample 1 \fR\fBM_IOCTL\fR Allocation
 157 .sp
 158 .LP
 159 The first example shows an \fBM_IOCTL\fR allocation with the ioctl command
 160 \fBTEST_CMD\fR. If the \fBiocblk\fR(9S) cannot be allocated, \fINULL\fR is
 161 returned, indicating an allocation failure (line 5). In line 11, the
 162 \fBputnext\fR(9F) function is used to send the message downstream.
 163
 164 .sp
 165 .in +2
 166 .nf
 167 1  test_function(queue_t *q, test_info_t *testinfo)
 168  2  {
 169  3   mblk_t *mp;
 170  4
 171  5   if ((mp = mkiocb(TEST_CMD)) == NULL)
 172  6       return (0);
 173  7
 174  8       /* save off ioctl ID value */
 175  9       testinfo->xx_iocid = ((struct iocblk *)mp->b_rptr)->ioc_id;
 176 10
 177 11       putnext(q, mp);       /* send message downstream */
 178 12       return (1);
 179 13  }
 180 .fi
 181 .in -2
 182
 183 .LP
 184 \fBExample 2 \fRThe ioctl \fBID \fRValue
 185 .sp
 186 .LP
 187 During the read service routine, the ioctl \fBID \fRvalue for \fBM_IOCACK\fR or
 188 \fBM_IOCNAK\fR should equal the ioctl that was previously sent by this module
 189 before processing.
 190
 191 .sp
 192 .in +2
 193 .nf
 194
 195  1  test_lrsrv(queue_t *q)
 196  2  {
 197  3      ...
 198  4
 199  5      switch (DB_TYPE(mp)) {
 200  6      case M_IOCACK:
 201  7      case M_IOCNAK:
 202  8          /* Does this match the ioctl that this module sent */
 203  9          ioc = (struct iocblk*)mp->b_rptr;
 204 10          if (ioc->ioc_id == testinfo->xx_iocid) {
 205 11              /* matches, so process the message */
 206 12              ...
 207 13              freemsg(mp);
 208 14          }
 209 15          break;
 210 16      }
 211 17      ...
 212 18  }
 213 .fi
 214 .in -2
 215
 216 .LP
 217 \fBExample 3 \fRAn iocblk Allocation Which Fails
 218 .sp
 219 .LP
 220 The next example shows an iocblk allocation which fails. Since the open routine
 221 is in user context, the caller may block using \fBqbufcall\fR(9F) until memory
 222 is available.
 223
 224 .sp
 225 .in +2
 226 .nf
 227 1  test_open(queue_t *q, dev_t devp, int oflag, int sflag,
 228                            cred_t *credp)
 229  2  {
 230  3       while ((mp = mkiocb(TEST_IOCTL)) == NULL) {
 231  4            int id;
 232  5
 233  6            id = qbufcall(q, sizeof (union ioctypes), BPRI_HI,
 234  7                dummy_callback, 0);
 235  8            /* Handle interrupts */
 236  9            if (!qwait_sig(q)) {
 237 10                qunbufcall(q, id);
 238 11                return (EINTR);
 239 12            }
 240 13       }
 241 14       putnext(q, mp);
 242 15  }
 243 .fi
 244 .in -2
 245
 246 .SH SEE ALSO
 247 .sp
 248 .LP
 249 \fBallocb\fR(9F), \fBputnext\fR(9F), \fBqbufcall\fR(9F), \fBqwait_sig\fR(9F),
 250 \fBcopyreq\fR(9S), \fBcopyresp\fR(9S), \fBiocblk\fR(9S)
 251 .sp
 252 .LP
 253 \fIWriting Device Drivers\fR
 254 .sp
 255 .LP
 256 \fISTREAMS Programming Guide\fR
 257 .SH WARNINGS
 258 .sp
 259 .LP
 260 It is the module's responsibility to remember the \fBID\fR value of the
 261 \fBM_IOCTL\fR that was allocated. This will ensure proper cleanup and \fBID\fR
 262 matching when the \fBM_IOCACK\fR or \fBM_IOCNAK\fR is received.