osfmk/man/device_open.html

   1 <h2>device_open</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Establish a connection to a device.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>#include&ltdevice/device.h&gt</strong>
   8
   9 <strong>kern_return_t   device_open</strong>
  10                 <strong>(mach_port_t</strong>                        <var>master_port</var>,
  11                  <strong>mach_port_t</strong>                             <var>ledger</var>,
  12                  <strong>dev_mode_t</strong>                                <var>mode</var>,
  13                  <strong>security_token_t</strong>                   <var>security_id</var>,
  14                  <strong>dev_name_t</strong>                                <var>name</var>,
  15                  <strong>mach_port_t</strong>                             <var>device</var><strong>);</strong>
  16
  17
  18 <strong>#include&ltdevice/device_request.h&gt</strong>
  19
  20 <strong>kern_return_t   device_open_request</strong>
  21                 <strong>(mach_port_t</strong>                        <var>master_port</var>,
  22                  <strong>mach_port_t</strong>                         <var>reply_port</var>,
  23                  <strong>mach_port_t</strong>                             <var>ledger</var>,
  24                  <strong>dev_mode_t</strong>                                <var>mode</var>,
  25                  <strong>security_token_t</strong>                   <var>security_id</var>,
  26                  <strong>dev_name_t</strong>                                <var>name</var><strong>);</strong>
  27
  28
  29 <strong>kern_return_t   ds_device_open_reply</strong>
  30                 <strong>(mach_port_t</strong>                         <var>reply_port</var>,
  31                  <strong>kern_return_t</strong>                      <var>return_code</var>,
  32                  <strong>mach_port_t</strong>                             <var>device</var><strong>);</strong>
  33 </pre>
  34 <h3>PARAMETERS</h3>
  35 <dl>
  36 <p>
  37 <dt> <var>master_port</var>
  38 <dd>
  39 [in device-master send right]
  40 The master device port.  This port is
  41 provided to the bootstrap task.
  42 <p>
  43 <dt> <var>reply_port</var>
  44 <dd>
  45 [in reply receive (to be converted to send-once) right]
  46 The port to
  47 which a reply is to be sent when the device is open.
  48 <p>
  49 <dt> <var>ledger</var>
  50 <dd>
  51 [pointer to a ledger send right]
  52 Resource ledger from which the device will draw its resources.
  53 <p>
  54 <dt> <var>mode</var>
  55 <dd>
  56 [in scalar]
  57 Opening mode.  This is the bit-wise <strong>OR</strong> of the following
  58 values:
  59 <dl>
  60 <p>
  61 <dt> <strong>D_READ</strong>
  62 <dd>
  63 Read access
  64 <p>
  65 <dt> <strong>D_WRITE</strong>
  66 <dd>
  67 Write access
  68 <p>
  69 <dt> <strong>D_NODELAY</strong>
  70 <dd>
  71 Do not delay on open
  72 </dl>
  73 <p>
  74 <dt> <var>security_id</var>
  75 <dd>
  76 [in scalar]
  77 The security ID that tasks attempting to use this device port
  78 must have.  A zero value indicates all identities.
  79 <p>
  80 <dt> <var>name</var>
  81 <dd>
  82 [pointer to in array of <var>char</var>]
  83 Name of the device to open.
  84 <p>
  85 <dt> <var>return_code</var>
  86 <dd>
  87 [in scalar]
  88 Status of the open.
  89 <p>
  90 <dt> <var>device</var>
  91 <dd>
  92 [out device send right, in for asynchronous form]
  93 The returned device
  94 port.
  95 </dl>
  96 <h3>DESCRIPTION</h3>
  97 <p>
  98 The <strong>device_open</strong> function opens a device object.  The
  99 open operation of the
 100 device is invoked, if the device is not already open.  The open
 101 count for the device
 102 is incremented.  Each open for a device returns a port, the allowed
 103 operations upon which being governed by <var>mode</var>.  The port is not
 104 distinct.
 105 <h3>RETURN VALUES</h3>
 106 <p>
 107 Only generic errors apply.
 108 <h3>RELATED INFORMATION</h3>
 109 <p>
 110 Functions:
 111 <a href="device_close.html"><strong>device_close</strong></a>,
 112 <a href="device_reply_server.html"><strong>device_reply_server</strong></a>.