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

<h2>lock_handoff</h2>\r<hr>\r<p>\r<strong>Function</strong> - Hand-off ownership of a lock.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   lock_handoff</strong>\r                <strong>(lock_set_t</strong>                            <var>lock_set</var>,\r                 <strong>int</strong>                                    <var>lock_id</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>lock_set</var>\r<dd>\r[in send right] The port naming the lock set which represents the\rlock.\r<p>\r<dt> <var>lock_id</var>\r<dd>\r[in scalar] The lock, represented by the lock set, to be handed off.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>lock_handoff</strong> function passes lock ownership from the calling\rthread to an anonymous accepting thread. The lock must be owned by the\rcalling thread. If the accepting thread is not waiting to receive the\rlock, the calling thread will block until the hand-off is accepted.\r<h3>RETURN VALUES</h3>\r<dl>\r<p>\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>\r<dd>\rThe specified lock_set is invalid, or the lock_id is out of range.\r<p>\r<dt> <strong>KERN_INVALID_RIGHT</strong>\r<dd>\rThe calling thread does not own the lock being handed off.\r<p>\r<dt> <strong>KERN_SUCCESS</strong>\r<dd>\rThe lock hand-off was successful.\r<p>\r<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>\r<dd>\rThe specified lock has been destroyed.\r<p>\r<dt> <strong>KERN_ABORTED</strong>\r<dd>\rWhile blocked to wait for the accepting thread to assume the lock's ownership,\r     the calling thread was awoken by an unrelated event;\r     the lock's handoff state is cleared.\r</dl>\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,\r<a href="lock_release.html"><strong>lock_release</strong></a>,\r<a href="lock_try.html"><strong>lock_try</strong></a>,\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,\r<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,\r<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,\r<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.\r