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

<h2>device_open</h2>\r<hr>\r<p>\r<strong>Function</strong> - Establish a connection to a device.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>#include&ltdevice/device.h&gt</strong>\r\r<strong>kern_return_t   device_open</strong>\r                <strong>(mach_port_t</strong>                        <var>master_port</var>,\r                 <strong>mach_port_t</strong>                             <var>ledger</var>,\r                 <strong>dev_mode_t</strong>                                <var>mode</var>,\r                 <strong>security_token_t</strong>                   <var>security_id</var>,\r                 <strong>dev_name_t</strong>                                <var>name</var>,\r                 <strong>mach_port_t</strong>                             <var>device</var><strong>);</strong>\r\r\r<strong>#include&ltdevice/device_request.h&gt</strong>\r\r<strong>kern_return_t   device_open_request</strong>\r                <strong>(mach_port_t</strong>                        <var>master_port</var>,\r                 <strong>mach_port_t</strong>                         <var>reply_port</var>,\r                 <strong>mach_port_t</strong>                             <var>ledger</var>,\r                 <strong>dev_mode_t</strong>                                <var>mode</var>,\r                 <strong>security_token_t</strong>                   <var>security_id</var>,\r                 <strong>dev_name_t</strong>                                <var>name</var><strong>);</strong>\r\r\r<strong>kern_return_t   ds_device_open_reply</strong>\r                <strong>(mach_port_t</strong>                         <var>reply_port</var>,\r                 <strong>kern_return_t</strong>                      <var>return_code</var>,\r                 <strong>mach_port_t</strong>                             <var>device</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>master_port</var> \r<dd>\r[in device-master send right]\rThe master device port.  This port is\rprovided to the bootstrap task.\r<p>\r<dt> <var>reply_port</var> \r<dd>\r[in reply receive (to be converted to send-once) right]\rThe port to \rwhich a reply is to be sent when the device is open.\r<p>\r<dt> <var>ledger</var> \r<dd>\r[pointer to a ledger send right]\rResource ledger from which the device will draw its resources.\r<p>\r<dt> <var>mode</var> \r<dd>\r[in scalar]\rOpening mode.  This is the bit-wise <strong>OR</strong> of the following\rvalues:\r<dl>\r<p>\r<dt> <strong>D_READ</strong>\r<dd>\rRead access\r<p>\r<dt> <strong>D_WRITE</strong>\r<dd>\rWrite access\r<p>\r<dt> <strong>D_NODELAY</strong>\r<dd>\rDo not delay on open\r</dl>\r<p>\r<dt> <var>security_id</var> \r<dd>\r[in scalar]\rThe security ID that tasks attempting to use this device port \rmust have.  A zero value indicates all identities.\r<p>\r<dt> <var>name</var> \r<dd>\r[pointer to in array of <var>char</var>]\rName of the device to open.\r<p>\r<dt> <var>return_code</var> \r<dd>\r[in scalar]\rStatus of the open.\r<p>\r<dt> <var>device</var> \r<dd>\r[out device send right, in for asynchronous form]\rThe returned device \rport.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>device_open</strong> function opens a device object.  The\ropen operation of the\rdevice is invoked, if the device is not already open.  The open\rcount for the device \ris incremented.  Each open for a device returns a port, the allowed\roperations upon which being governed by <var>mode</var>.  The port is not\rdistinct.\r<h3>RETURN VALUES</h3>\r<p>\rOnly generic errors apply.\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="device_close.html"><strong>device_close</strong></a>,\r<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.\r