xnu-3789.1.32.tar.gz

[apple/xnu.git] / osfmk / man / device_open.html

<h2>device_open</h2>
<hr>
<p>
<strong>Function</strong> - Establish a connection to a device.
<h3>SYNOPSIS</h3>
<pre>
<strong>#include&ltdevice/device.h&gt</strong>

<strong>kern_return_t   device_open</strong>
                <strong>(mach_port_t</strong>                        <var>master_port</var>,
                 <strong>mach_port_t</strong>                             <var>ledger</var>,
                 <strong>dev_mode_t</strong>                                <var>mode</var>,
                 <strong>security_token_t</strong>                   <var>security_id</var>,
                 <strong>dev_name_t</strong>                                <var>name</var>,
                 <strong>mach_port_t</strong>                             <var>device</var><strong>);</strong>


<strong>#include&ltdevice/device_request.h&gt</strong>

<strong>kern_return_t   device_open_request</strong>
                <strong>(mach_port_t</strong>                        <var>master_port</var>,
                 <strong>mach_port_t</strong>                         <var>reply_port</var>,
                 <strong>mach_port_t</strong>                             <var>ledger</var>,
                 <strong>dev_mode_t</strong>                                <var>mode</var>,
                 <strong>security_token_t</strong>                   <var>security_id</var>,
                 <strong>dev_name_t</strong>                                <var>name</var><strong>);</strong>


<strong>kern_return_t   ds_device_open_reply</strong>
                <strong>(mach_port_t</strong>                         <var>reply_port</var>,
                 <strong>kern_return_t</strong>                      <var>return_code</var>,
                 <strong>mach_port_t</strong>                             <var>device</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>master_port</var> 
<dd>
[in device-master send right]
The master device port.  This port is
provided to the bootstrap task.
<p>
<dt> <var>reply_port</var> 
<dd>
[in reply receive (to be converted to send-once) right]
The port to 
which a reply is to be sent when the device is open.
<p>
<dt> <var>ledger</var> 
<dd>
[pointer to a ledger send right]
Resource ledger from which the device will draw its resources.
<p>
<dt> <var>mode</var> 
<dd>
[in scalar]
Opening mode.  This is the bit-wise <strong>OR</strong> of the following
values:
<dl>
<p>
<dt> <strong>D_READ</strong>
<dd>
Read access
<p>
<dt> <strong>D_WRITE</strong>
<dd>
Write access
<p>
<dt> <strong>D_NODELAY</strong>
<dd>
Do not delay on open
</dl>
<p>
<dt> <var>security_id</var> 
<dd>
[in scalar]
The security ID that tasks attempting to use this device port 
must have.  A zero value indicates all identities.
<p>
<dt> <var>name</var> 
<dd>
[pointer to in array of <var>char</var>]
Name of the device to open.
<p>
<dt> <var>return_code</var> 
<dd>
[in scalar]
Status of the open.
<p>
<dt> <var>device</var> 
<dd>
[out device send right, in for asynchronous form]
The returned device 
port.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>device_open</strong> function opens a device object.  The
open operation of the
device is invoked, if the device is not already open.  The open
count for the device 
is incremented.  Each open for a device returns a port, the allowed
operations upon which being governed by <var>mode</var>.  The port is not
distinct.
<h3>RETURN VALUES</h3>
<p>
Only generic errors apply.
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="device_close.html"><strong>device_close</strong></a>,
<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.