osfmk/man/device_read_overwrite.html

   1 <h2>device_read_overwrite</h2>
   2 <hr>
   3 <p><strong>System Trap</strong> -- Read a sequence of bytes from a specific device into my address space.
   4 <h3>SYNOPSIS</h3>
   5 <pre>
   6
   7 <strong>kern_return_t   device_read_overwrite</strong>
   8                 <strong>(mach_port_t</strong>                               <var>device</var>,
   9                  <strong>dev_mode_t</strong>                                <var>mode</var>,
  10                  <strong>recnum_t</strong>                                <var>recnum</var>,
  11                  <strong>io_buf_len_t</strong>                      <var>bytes_wanted</var>,
  12                  <strong>io_buf_pointer_t</strong>                          <var>data</var>,
  13                  <strong>mach_msg_type_number_t</strong>              <var>data_count</var><strong>);</strong>
  14
  15
  16
  17 <strong>kern_return_t   device_read_overwrite_request</strong>
  18                 <strong>(mach_port_t</strong>                             <var>device</var>,
  19                  <strong>mach_port_t</strong>                         <var>reply_port</var>,
  20                  <strong>dev_mode_t</strong>                                <var>mode</var>,
  21                  <strong>recnum_t</strong>                                <var>recnum</var>,
  22                  <strong>io_buf_len_t</strong>                      <var>bytes_wanted</var>,
  23                  <strong>io_buf_pointer_t</strong>                          <var>data</var><strong>);</strong>
  24
  25
  26
  27 <strong>kern_return_t   ds_device_read_reply_overwrite</strong>
  28                 <strong>(mach_port_t</strong>                        <var>reply_port</var>,
  29                  <strong>kern_return_t</strong>                      <var>return_code</var>,
  30                  <strong>io_buf_len_t</strong>                        <var>data_count</var><strong>);</strong>
  31 </pre>
  32 <h3>PARAMETERS</h3>
  33 <dl>
  34 <p>
  35 <dt> <var>device</var>
  36 <dd>
  37 [in device send right]
  38 A device port to the device to be read.
  39 <p>
  40 <dt> <var>reply_port</var>
  41 <dd>
  42 [in reply receive (to be converted to send-once) right]
  43 The port to
  44 which the reply message is to be sent.
  45 <p>
  46 <dt> <var>mode</var>
  47 <dd>
  48 [in scalar]
  49 I/O mode value.  Meaningful options are:
  50 <dl>
  51 <p>
  52 <dt> <strong>D_NOWAIT</strong>
  53 <dd>
  54 Do not wait if data is unavailable.
  55 </dl>
  56 <p>
  57 <dt> <var>recnum</var>
  58 <dd>
  59 [in scalar]
  60 Record number to be read.
  61 <p>
  62 <dt> <var>bytes_wanted</var>
  63 <dd>
  64 [in scalar]
  65 Size of data transfer.
  66 <p>
  67 <dt> <var>return_code</var>
  68 <dd>
  69 [in scalar]
  70 The return status code from the read.
  71 <p>
  72 <dt> <var>data</var>
  73 <dd>
  74 [pointer to in array of bytes]
  75 Data buffer to be overwritten.
  76 <p>
  77 <dt> <var>data_count</var>
  78 <dd>
  79 [out scalar, in for asynchronous form]
  80 Number of returned data bytes.
  81 </dl>
  82 <h3>DESCRIPTION</h3>
  83 <p>
  84 The <strong>device_read_overwrite</strong> system trap reads a sequence
  85 of bytes from a
  86 device object directly into the caller's address space.  The
  87 meaning of <var>recnum</var> as
  88 well as the specific operation performed is device dependent.
  89 <h3>NOTES</h3>
  90 <p>
  91 The <strong>device_read_overwrite_request</strong> and <strong>device_read_reply_overwrite</strong>
  92 calls may be removed from the interface in favor of new asynchronous support.
  93 <h3>RETURN VALUES</h3>
  94 <p>
  95 Only generic errors apply.
  96 <h3>RELATED INFORMATION</h3>
  97 <p>
  98 Functions:
  99 <a href="device_read.html"><strong>device_read</strong></a>,
 100 <a href="device_read_inband.html"><strong>device_read_inband</strong></a>,
 101 <a href="device_reply_server.html"><strong>device_reply_server</strong></a>.