usr/src/man/man9e/mc_ioctl.9e

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd May 31, 2016
  15 .Dt MC_IOCTL 9E
  16 .Os
  17 .Sh NAME
  18 .Nm mc_ioctl
  19 .Nd device specific I/O control operation
  20 .Sh SYNOPSIS
  21 .In sys/types.h
  22 .In sys/stream.h
  23 .In sys/stropts.h
  24 .In sys/ddi.h
  25 .In sys/sunddi.h
  26 .Ft void
  27 .Fo prefix_m_ioctl
  28 .Fa "void *driver"
  29 .Fa "queue_t *wq"
  30 .Fa "mblk_t *mp"
  31 .Fc
  32 .Sh INTERFACE LEVEL
  33 illumos DDI Specific
  34 .Sh PARAMETERS
  35 .Bl -tag -width Ds
  36 .It Fa driver
  37 A pointer to the driver's private data that was passed in via the
  38 .Sy m_pdata
  39 member of the
  40 .Xr mac_register 9S
  41 structure to the
  42 .Xr mac_register 9F
  43 function.
  44 .It Fa wq
  45 A pointer to a STREAMS write-side queue that the ioctl request was
  46 received upon.
  47 .It Fa mp
  48 A pointer to a message block structure that contains the I/O control
  49 request.
  50 .El
  51 .Sh DESCRIPTION
  52 The
  53 .Fn mc_ioctl
  54 entry point is an optional GLDv3 entry point.
  55 It provides a means for device-specific I/O control operations to be initiated.
  56 In general, this entry point is not recommended for most devices and is
  57 unimplemented.
  58 .Pp
  59 The I/O control interface is not like a traditional character or block
  60 device's
  61 .Xr ioctl 9E
  62 entry point, rather it is a STREAMS-based I/O control operation.
  63 The data pointer of the
  64 .Fa mp
  65 argument is a
  66 .Xr iocblk 9S
  67 structure.
  68 After handling the message, the driver will need to reply to the message, which
  69 is usually done by using the
  70 .Xr miocack 9F
  71 and
  72 .Xr miocnak 9F
  73 functions to prepare
  74 .Fa mp .
  75 .Pp
  76 The device driver can access its soft state by casting the value pointed
  77 to in
  78 .Fa driver .
  79 The driver should be careful and ensure that it performs any necessary
  80 locking to access members of that structure while processing the I/O
  81 control operation.
  82 .Sh RETURN VALUES
  83 Return information is not conveyed by the return value of this function, rather
  84 it is encoded in the
  85 .Xr iocblk 9S
  86 structure in the
  87 .Fa mp
  88 argument.
  89 .Sh EXAMPLES
  90 The following example shows how a device driver might structure its
  91 .Fn mc_ioctl
  92 entry point.
  93 .Bd -literal
  94 #include <sys/types.h>
  95 #include <sys/stream.h>
  96 #include <sys/stropts.h>
  97 #include <sys/ddi.h>
  98 #include <sys/sunddi.h>
  99
 100 /*
 101  * Note, this example merely shows the structure of this function. It does not
 102  * actively handle any device-specific ioctls and instead returns failure for
 103  * every one. This is the most common case. Note, miocnak(9F) takes care of
 104  * calling putnext(9F) for us.
 105  */
 106 static void
 107 example_m_ioctl(void *arg, queue_t *wq, mblk_t *mp)
 108 {
 109         miocnak(wq, mp, 0, EINVAL);
 110 }
 111 .Ed
 112 .Sh SEE ALSO
 113 .Xr ioctl 9E ,
 114 .Xr mac 9E ,
 115 .Xr put 9E ,
 116 .Xr mac_register 9F ,
 117 .Xr miocack 9F ,
 118 .Xr miocnak 9F ,
 119 .Xr putnext 9F ,
 120 .Xr iocblk 9S ,
 121 .Xr mac_register 9S
 122 .Rs
 123 .%T Writing Device Drivers
 124 .Re
 125 .Rs
 126 .%T STREAMS Programming Guide
 127 .Re