[rtems-docs commit] c-user: Document rtems_task_exit()

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    6a20bd2f4f92d39afd06fc0746fd3e8a74b75513
Changeset: http://git.rtems.org/rtems-docs/commit/?id=6a20bd2f4f92d39afd06fc0746fd3e8a74b75513

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Sep 28 10:29:49 2018 +0200

c-user: Document rtems_task_exit()

Close #3533.

---

 c-user/task_manager.rst | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst
index aff9185..f48aa13 100644
--- a/c-user/task_manager.rst
+++ b/c-user/task_manager.rst
@@ -27,6 +27,8 @@ and administer tasks.  The directives provided by the task manager are:
 
 - rtems_task_delete_ - Delete a task
 
+- rtems_task_exit_ - Delete the calling task
+
 - rtems_task_suspend_ - Suspend a task
 
 - rtems_task_resume_ - Resume a task
@@ -515,7 +517,8 @@ task, frees the task's control block, removes it from resource wait queues, and
 deallocates its stack as well as the optional floating point context.  The
 task's name and ID become inactive at this time, and any subsequent references
 to either of them is invalid.  In fact, RTEMS may reuse the task ID for another
-task which is created later in the application.
+task which is created later in the application.  A specialization of
+``rtems_task_delete`` is ``rtems_task_exit`` which deletes the calling task.
 
 Unexpired delay timers (i.e. those used by ``rtems_task_wake_after`` and
 ``rtems_task_wake_when``) and timeout timers associated with the task are
@@ -1005,6 +1008,48 @@ NOTES:
 
    \clearpage
 
+.. index:: deleting a task
+.. index:: rtems_task_exit
+
+.. _rtems_task_exit:
+
+TASK_EXIT - Delete the calling task
+-----------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        void rtems_task_exit( void ) RTEMS_NO_RETURN;
+
+DIRECTIVE STATUS CODES:
+    NONE - This function will not return to the caller.
+
+DESCRIPTION:
+    This directive deletes the calling task.
+
+NOTES:
+    This directive must be called from a regular task context with enabled
+    interrupts, otherwise one of the fatal errors
+
+    * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL <internal_errors>`, or
+    * :ref:`INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT <internal_errors>`
+
+    will occur.
+
+    The ``rtems_task_exit()`` call is equivalent to the following code
+    sequence:
+
+    .. code-block:: c
+
+        pthread_detach(pthread_self());
+        pthread_exit(NULL);
+
+    See also :ref:`rtems_task_delete() <rtems_task_delete>`.
+
+.. raw:: latex
+
+   \clearpage
+
 .. index:: suspending a task
 .. index:: rtems_task_suspend