| <!-- |
| Documentation/_templates/layout.html |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. The |
| ASF licenses this file to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance with the |
| License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| License for the specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| |
| |
| <!DOCTYPE html> |
| <html class="writer-html5" lang="en" > |
| <head> |
| <meta charset="utf-8" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| |
| <title>Task Control Interfaces — NuttX latest documentation</title> |
| |
| |
| |
| <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" /> |
| <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> |
| <link rel="stylesheet" href="../../_static/tabs.css" type="text/css" /> |
| <link rel="stylesheet" href="../../_static/custom.css" type="text/css" /> |
| |
| |
| |
| <link rel="shortcut icon" href="../../_static/favicon.ico"/> |
| |
| |
| |
| |
| |
| |
| |
| |
| <!--[if lt IE 9]> |
| <script src="../../_static/js/html5shiv.min.js"></script> |
| <![endif]--> |
| |
| |
| <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script> |
| <script src="../../_static/jquery.js"></script> |
| <script src="../../_static/underscore.js"></script> |
| <script src="../../_static/doctools.js"></script> |
| |
| <script type="text/javascript" src="../../_static/js/theme.js"></script> |
| |
| |
| <link rel="index" title="Index" href="../../genindex.html" /> |
| <link rel="search" title="Search" href="../../search.html" /> |
| <link rel="next" title="Named Message Queue Interfaces" href="04_message_queue.html" /> |
| <link rel="prev" title="Task Scheduling Interfaces" href="02_task_scheduling.html" /> |
| </head> |
| |
| <body class="wy-body-for-nav"> |
| |
| |
| <div class="wy-grid-for-nav"> |
| |
| <nav data-toggle="wy-nav-shift" class="wy-nav-side"> |
| <div class="wy-side-scroll"> |
| <div class="wy-side-nav-search" > |
| |
| |
| <a href="../../index.html" class="icon icon-home"> NuttX |
| |
| |
| |
| |
| <img src="../../_static/NuttX.png" class="logo" alt="Logo"/> |
| |
| </a> |
| |
| <!-- this version selector is quite ugly, should be probably replaced by something |
| more modern --> |
| |
| <div class="version-selector"> |
| <select onchange="javascript:location.href = this.value;"> |
| |
| <option value="../../../latest" selected="selected">latest</option> |
| |
| <option value="../../../10.0.0" >10.0.0</option> |
| |
| <option value="../../../10.0.1" >10.0.1</option> |
| |
| <option value="../../../10.1.0" >10.1.0</option> |
| |
| <option value="../../../10.2.0" >10.2.0</option> |
| |
| <option value="../../../10.3.0" >10.3.0</option> |
| |
| <option value="../../../11.0.0" >11.0.0</option> |
| |
| <option value="../../../12.0.0" >12.0.0</option> |
| |
| <option value="../../../12.1.0" >12.1.0</option> |
| |
| <option value="../../../12.2.0" >12.2.0</option> |
| |
| <option value="../../../12.2.1" >12.2.1</option> |
| |
| <option value="../../../12.3.0" >12.3.0</option> |
| |
| <option value="../../../12.4.0" >12.4.0</option> |
| |
| <option value="../../../12.5.0" >12.5.0</option> |
| |
| <option value="../../../12.5.1" >12.5.1</option> |
| |
| <option value="../../../12.6.0" >12.6.0</option> |
| |
| <option value="../../../12.7.0" >12.7.0</option> |
| |
| <option value="../../../12.8.0" >12.8.0</option> |
| |
| <option value="../../../12.9.0" >12.9.0</option> |
| |
| <option value="../../../12.10.0" >12.10.0</option> |
| |
| <option value="../../../12.11.0" >12.11.0</option> |
| |
| </select> |
| </div> |
| |
| |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get"> |
| <input type="text" name="q" placeholder="Search docs" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| |
| </div> |
| |
| |
| <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> |
| |
| |
| |
| |
| |
| |
| <p class="caption"><span class="caption-text">Table of Contents</span></p> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../../index.html">Home</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../introduction/index.html">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../quickstart/index.html">Getting Started</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../contributing/index.html">Contributing</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../platforms/index.html">Supported Platforms</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../components/index.html">OS Components</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../applications/index.html">Applications</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="../index.html">API Reference</a><ul class="current"> |
| <li class="toctree-l2 current"><a class="reference internal" href="index.html">Userspace API</a><ul class="current"> |
| <li class="toctree-l3"><a class="reference internal" href="01_task_control.html">Task Control Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="02_task_scheduling.html">Task Scheduling Interfaces</a></li> |
| <li class="toctree-l3 current"><a class="current reference internal" href="#">Task Control Interfaces</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#parent-and-child-tasks">Parent and Child Tasks</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#functions">Functions</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="04_message_queue.html">Named Message Queue Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="05_counting_semaphore.html">Counting Semaphore Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="06_clocks_timers.html">Clocks and Timers</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="07_signals.html">Signal Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="08_pthread.html">Pthread Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="09_env_vars.html">Environment Variables</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="10_filesystem.html">File System Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="11_network.html">Network Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="12_shared_memory.html">Shared Memory Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="13_boardctl.html">Board IOCTL</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="13_logging.html">Logging</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="structures.html">OS Data Structures</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="../os/index.html">Architecture APIs</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../../faq/index.html">FAQ</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../guides/index.html">Guides</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../glossary.html">Glossary</a></li> |
| </ul> |
| |
| |
| |
| </div> |
| |
| </div> |
| </nav> |
| |
| <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> |
| |
| |
| <nav class="wy-nav-top" aria-label="top navigation"> |
| |
| <i data-toggle="wy-nav-top" class="fa fa-bars"></i> |
| <a href="../../index.html">NuttX</a> |
| |
| </nav> |
| |
| |
| <div class="wy-nav-content"> |
| |
| <div class="rst-content"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div role="navigation" aria-label="breadcrumbs navigation"> |
| |
| <ul class="wy-breadcrumbs"> |
| |
| <li><a href="../../index.html" class="icon icon-home"></a> »</li> |
| |
| <li><a href="../index.html">API Reference</a> »</li> |
| |
| <li><a href="index.html">Userspace API</a> »</li> |
| |
| <li>Task Control Interfaces</li> |
| |
| |
| <li class="wy-breadcrumbs-aside"> |
| |
| |
| <a href="../../_sources/reference/user/03_task_control.rst.txt" rel="nofollow"> View page source</a> |
| |
| |
| </li> |
| |
| </ul> |
| |
| |
| <hr/> |
| </div> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <div class="section" id="task-control-interfaces"> |
| <h1>Task Control Interfaces<a class="headerlink" href="#task-control-interfaces" title="Permalink to this headline">¶</a></h1> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>This section name is duplicate with the first, how should it be named?</p> |
| </div> |
| <ul> |
| <li><p><strong>Scheduler locking interfaces</strong>. These <em>non-standard</em> interfaces are |
| used to enable and disable pre-emption and to test is pre-emption is |
| currently enabled.</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p><a class="reference internal" href="#c.sched_lock" title="sched_lock"><code class="xref c c-func docutils literal notranslate"><span class="pre">sched_lock()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sched_unlock" title="sched_unlock"><code class="xref c c-func docutils literal notranslate"><span class="pre">sched_unlock()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sched_lockcount" title="sched_lockcount"><code class="xref c c-func docutils literal notranslate"><span class="pre">sched_lockcount()</span></code></a></p></li> |
| </ul> |
| </div></blockquote> |
| </li> |
| <li><p><strong>Task synchronization interfaces</strong> are used to wait for termination of child tasks.</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p><a class="reference internal" href="#c.waitpid" title="waitpid"><code class="xref c c-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.waitid" title="waitid"><code class="xref c c-func docutils literal notranslate"><span class="pre">waitid()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.wait" title="wait"><code class="xref c c-func docutils literal notranslate"><span class="pre">wait()</span></code></a></p></li> |
| </ul> |
| </div></blockquote> |
| </li> |
| <li><p><strong>Task Exit Hooks</strong> may be used to |
| register callback functions that are executed when a <em>task group</em> |
| terminates. A task group is the functional analog of a process: It is |
| a group that consists of the main task thread and of all of the |
| pthreads created by the main task thread or any of the other pthreads |
| within the task group. Members of a task group share certain |
| resources such as environment variables, file descriptors, <code class="docutils literal notranslate"><span class="pre">FILE</span></code> |
| streams, sockets, pthread keys and open message queues.</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p><a class="reference internal" href="#c.atexit" title="atexit"><code class="xref c c-func docutils literal notranslate"><span class="pre">atexit()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.on_exit" title="on_exit"><code class="xref c c-func docutils literal notranslate"><span class="pre">on_exit()</span></code></a></p></li> |
| </ul> |
| </div></blockquote> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>Behavior of features related to task group’s depend of |
| NuttX configuration settings. See the discussion of “Parent and |
| Child Tasks,” below. See also the<a class="reference external" href="https://cwiki.apache.org/confluence/display/NUTTX/NuttX+Tasking">NuttX |
| Tasking</a>page |
| and the<a class="reference external" href="https://cwiki.apache.org/confluence/display/NUTTX/Tasks+vs.+Threads+FAQ">Tasks vs. Threads |
| FAQ</a>for |
| additional information on tasks and threads in NuttX.</p> |
| </div> |
| <p>A <em>task group</em> terminates when the last thread within the group |
| exits.</p> |
| </li> |
| </ul> |
| <div class="section" id="parent-and-child-tasks"> |
| <h2>Parent and Child Tasks<a class="headerlink" href="#parent-and-child-tasks" title="Permalink to this headline">¶</a></h2> |
| <p>The task synchronization interfaces |
| historically depend upon parent and child relationships between tasks. |
| But default, NuttX does not use any parent/child knowledge. However, |
| there are three important configuration options that can change that.</p> |
| <blockquote> |
| <div><ul> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_HAVE_PARENT</span></code>: If this setting is defined, then it |
| instructs NuttX to remember the task ID of the parent task when each |
| new child task is created. This support enables some additional |
| features (such as <code class="docutils literal notranslate"><span class="pre">SIGCHLD</span></code>) and modifies the behavior of other |
| interfaces. For example, it makes <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> more standards |
| complete by restricting the waited-for tasks to the children of the |
| caller.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_CHILD_STATUS</span></code>: If this option is selected, then |
| the exit status of the child task will be retained after the child |
| task exits. This option should be selected if you require knowledge |
| of a child process’s exit status. Without this setting, <code class="docutils literal notranslate"><span class="pre">wait()</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> or <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> may fail. For example, if you do:</p> |
| <blockquote> |
| <div><ol class="arabic simple"> |
| <li><p>Start child task</p></li> |
| <li><p>Wait for exit status (using <a class="reference internal" href="#c.wait" title="wait"><code class="xref c c-func docutils literal notranslate"><span class="pre">wait()</span></code></a>, <a class="reference internal" href="#c.waitpid" title="waitpid"><code class="xref c c-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a> or |
| <a class="reference internal" href="#c.waitid" title="waitid"><code class="xref c c-func docutils literal notranslate"><span class="pre">waitid()</span></code></a>).</p></li> |
| </ol> |
| </div></blockquote> |
| <p>This may fail because the child task may run to completion before the |
| wait begins. There is a non-standard work-around in this case: The |
| above sequence will work if you disable pre-emption using |
| <a class="reference internal" href="#c.sched_lock" title="sched_lock"><code class="xref c c-func docutils literal notranslate"><span class="pre">sched_lock()</span></code></a> prior to starting the child task, then re-enable |
| pre-emption with <a class="reference internal" href="#c.sched_unlock" title="sched_unlock"><code class="xref c c-func docutils literal notranslate"><span class="pre">sched_unlock()</span></code></a> after the wait completes. This |
| works because the child task is not permitted to run until the wait |
| is in place.</p> |
| <p>The standard solution would be to enable |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_CHILD_STATUS</span></code>. In this case the exit status of the |
| child task is retained after the child exits and the wait will |
| successful obtain the child task’s exit status whether it is called |
| before the child task exits or not.</p> |
| </li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_PREALLOC_CHILDSTATUS</span></code>. To prevent runaway child status |
| allocations and to improve allocation performance, child task exit |
| status structures are pre-allocated when the system boots. This |
| setting determines the number of child status structures that will be |
| pre-allocated.</p> |
| <p>Obviously, if tasks spawn children indefinitely and never have the |
| exit status reaped, then you may have a memory leak! (See <strong>Warning</strong> |
| below)</p> |
| </li> |
| </ul> |
| </div></blockquote> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>If you enable the <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_CHILD_STATUS</span></code> feature, |
| then your application must either (1) take responsibility for reaping |
| the child status with <code class="docutils literal notranslate"><span class="pre">wait()</span></code>, <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> or <code class="docutils literal notranslate"><span class="pre">waitid()</span></code>, or (2) |
| suppress retention of child status. If you do not reap the child status, |
| then you have a memory leak and your system will eventually fail.</p> |
| </div> |
| <p>Retention of child status can be suppressed on the parent using logic |
| like:</p> |
| <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nc">sigaction</span> <span class="n">sa</span><span class="p">;</span> |
| |
| <span class="n">sa</span><span class="p">.</span><span class="n">sa_handler</span> <span class="o">=</span> <span class="n">SIG_IGN</span><span class="p">;</span> |
| <span class="n">sa</span><span class="p">.</span><span class="n">sa_flags</span> <span class="o">=</span> <span class="n">SA_NOCLDWAIT</span><span class="p">;</span> |
| <span class="kt">int</span> <span class="n">ret</span> <span class="o">=</span> <span class="n">sigaction</span><span class="p">(</span><span class="n">SIGCHLD</span><span class="p">,</span> <span class="o">&</span><span class="n">sa</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| </div> |
| <div class="section" id="functions"> |
| <h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2> |
| <dl class="c function"> |
| <dt id="c.sched_lock"> |
| <span class="pre">int</span> <code class="sig-name descname"><span class="pre">sched_lock</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.sched_lock" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Disables context switching by Disabling |
| addition of new tasks to the ready-to-run task list. The task that calls |
| this function will be the only task that is allowed to run until it |
| either calls sched_unlock (the appropriate number of times) or until it |
| blocks itself.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Returns</dt> |
| <dd class="field-odd"><p>OK or ERROR.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> This is a NON-POSIX interface. VxWorks provides |
| the comparable interface:</p> |
| <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">STATUS</span> <span class="nf">taskLock</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.sched_unlock"> |
| <span class="pre">int</span> <code class="sig-name descname"><span class="pre">sched_unlock</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.sched_unlock" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Decrements the preemption lock count. |
| Typically this is paired with sched_lock() and concludes a critical |
| section of code. Preemption will not be unlocked until sched_unlock() |
| has been called as many times as sched_lock(). When the lockCount is |
| decremented to zero, any tasks that were eligible to preempt the current |
| task will execute.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Returns</dt> |
| <dd class="field-odd"><p>OK or ERROR.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> This is a NON-POSIX interface. VxWorks provides |
| the comparable interface:</p> |
| <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">STATUS</span> <span class="nf">taskUnlock</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.sched_lockcount"> |
| <span class="pre">int32_t</span> <code class="sig-name descname"><span class="pre">sched_lockcount</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.sched_lockcount" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Returns the current value of the |
| lockCount. If zero, preemption is enabled; if non-zero, this value |
| indicates the number of times that sched_lock() has been called on this |
| thread of execution.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Returns</dt> |
| <dd class="field-odd"><p>The current value of the lockCount.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> None.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.waitpid"> |
| <span class="pre">ipid_t</span> <code class="sig-name descname"><span class="pre">waitpid</span></code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.pid_t" title="pid_t"><span class="pre">pid_t</span></a> <em><span class="pre">pid</span></em>, <span class="pre">int</span> <span class="pre">*</span><em><span class="pre">stat_loc</span></em>, <span class="pre">int</span> <em><span class="pre">options</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.waitpid" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>The following discussion is a general description of the |
| <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> interface. However, as of this writing, the |
| implementation of <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> is incomplete (but usable). If |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_HAVE_PARENT</span></code> is defined, <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> will be a |
| little more compliant to specifications. Without |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_HAVE_PARENT</span></code>, <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> simply supports waiting |
| for any task to complete execution. With |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_HAVE_PARENT</span></code>, <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> will use <code class="docutils literal notranslate"><span class="pre">SIGCHLD</span></code> and |
| can, therefore, wait for any child of the parent to complete. The |
| implementation is incomplete in either case, however: NuttX does not |
| support any concept of process groups. Nor does NuttX retain the |
| status of exited tasks so if <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> is called after a task has |
| exited, then no status will be available. The options argument is |
| currently ignored.</p> |
| </div> |
| <p>The <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> functions will obtain status information pertaining to |
| one of the caller’s child processes. The <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> function will |
| suspend execution of the calling thread until status information for one |
| of the terminated child processes of the calling process is available, |
| or until delivery of a signal whose action is either to execute a |
| signal-catching function or to terminate the process. If more than one |
| thread is suspended in <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> awaiting termination of the same |
| process, exactly one thread will return the process status at the time |
| of the target process termination. If status information is available |
| prior to the call to <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code>, return will be immediate.</p> |
| <p><strong>NOTE</strong>: Because <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> is not fully POSIX compliant, it must be |
| specifically enabled by setting <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_WAITPID</span></code> in the NuttX |
| configuration file.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters</dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>pid</strong> – The task ID of the thread to wait for</p></li> |
| <li><p><strong>stat_loc</strong> – The location to return the exit status</p></li> |
| <li><p><strong>options</strong> – ignored</p></li> |
| </ul> |
| </dd> |
| </dl> |
| <p>The <code class="docutils literal notranslate"><span class="pre">pid</span></code> argument specifies a set of child processes for which status |
| is requested. The <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> function will only return the status of |
| a child process from this set:</p> |
| <ul class="simple"> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">pid</span></code> is equal to <code class="docutils literal notranslate"><span class="pre">(pid_t)-1</span></code>), status is requested for any |
| child process. In this respect, <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> is then equivalent to |
| <code class="docutils literal notranslate"><span class="pre">wait()</span></code>.</p></li> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">pid</span></code> is greater than 0, it specifies the process ID of a single |
| child process for which status is requested.</p></li> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">pid</span></code> is 0, status is requested for any child process whose |
| process group ID is equal to that of the calling process.</p></li> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">pid</span></code> is less than <code class="docutils literal notranslate"><span class="pre">(pid_t)-1</span></code>), status is requested for any |
| child process whose process group ID is equal to the absolute value |
| of pid.</p></li> |
| </ul> |
| <p>The <code class="docutils literal notranslate"><span class="pre">options</span></code> argument is constructed from the bitwise-inclusive OR of |
| zero or more of the following flags, defined in the <code class="docutils literal notranslate"><span class="pre"><sys/wait.h></span></code> |
| header:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WCONTINUED</span></code>. The <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> function will report the status of |
| any continued child process specified by pid whose status has not |
| been reported since it continued from a job control stop.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WNOHANG</span></code>. The <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> function will not suspend execution of |
| the calling thread if status is not immediately available for one of |
| the child processes specified by <code class="docutils literal notranslate"><span class="pre">pid</span></code>.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WUNTRACED</span></code>. The status of any child processes specified by <code class="docutils literal notranslate"><span class="pre">pid</span></code> |
| that are stopped, and whose status has not yet been reported since |
| they stopped, will also be reported to the requesting process.</p></li> |
| </ul> |
| <p>If the calling process has <code class="docutils literal notranslate"><span class="pre">SA_NOCLDWAIT</span></code> set or has <code class="docutils literal notranslate"><span class="pre">SIGCHLD</span></code> set |
| to <code class="docutils literal notranslate"><span class="pre">SIG_IGN</span></code>, and the process has no unwaited-for children that were |
| transformed into zombie processes, the calling thread will block until |
| all of the children of the process containing the calling thread |
| terminate, and <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> will fail and set <code class="docutils literal notranslate"><span class="pre">errno</span></code> to <code class="docutils literal notranslate"><span class="pre">ECHILD</span></code>.</p> |
| <p>If <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> returns because the status of a child process is |
| available, these functions will return a value equal to the process ID |
| of the child process. In this case, if the value of the argument |
| stat_loc is not a null pointer, information will be stored in the |
| location pointed to by <code class="docutils literal notranslate"><span class="pre">stat_loc</span></code>. The value stored at the location |
| pointed to by <code class="docutils literal notranslate"><span class="pre">stat_loc</span></code> will be 0 if and only if the status returned |
| is from a terminated child process that terminated by one of the |
| following means:</p> |
| <ol class="arabic simple"> |
| <li><p>The process returned 0 from <code class="docutils literal notranslate"><span class="pre">main()</span></code>.</p></li> |
| <li><p>The process called <code class="docutils literal notranslate"><span class="pre">_exit()</span></code> or <code class="docutils literal notranslate"><span class="pre">exit()</span></code> with a status argument |
| of 0.</p></li> |
| <li><p>The process was terminated because the last thread in the process |
| terminated.</p></li> |
| </ol> |
| <p>Regardless of its value, this information may be interpreted using the |
| following macros, which are defined in <code class="docutils literal notranslate"><span class="pre"><sys/wait.h></span></code> and evaluate to |
| integral expressions; the <code class="docutils literal notranslate"><span class="pre">stat_val</span></code> argument is the integer value |
| pointed to by <code class="docutils literal notranslate"><span class="pre">stat_loc</span></code>.</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WIFEXITED(stat_val)</span></code>. Evaluates to a non-zero value if status was |
| returned for a child process that terminated normally.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WEXITSTATUS(stat_val)</span></code>. If the value of <code class="docutils literal notranslate"><span class="pre">WIFEXITED(stat_val)</span></code> is |
| non-zero, this macro evaluates to the low-order 8 bits of the status |
| argument that the child process passed to <code class="docutils literal notranslate"><span class="pre">_exit()</span></code> or <code class="docutils literal notranslate"><span class="pre">exit()</span></code>, |
| or the value the child process returned from <code class="docutils literal notranslate"><span class="pre">main()</span></code>.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WIFSIGNALED(stat_val)</span></code>. Evaluates to a non-zero value if status |
| was returned for a child process that terminated due to the receipt |
| of a signal that was not caught (see >signal.h<).</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WTERMSIG(stat_val)</span></code>. If the value of <code class="docutils literal notranslate"><span class="pre">WIFSIGNALED(stat_val)</span></code> is |
| non-zero, this macro evaluates to the number of the signal that |
| caused the termination of the child process.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WIFSTOPPED(stat_val)</span></code>. Evaluates to a non-zero value if status was |
| returned for a child process that is currently stopped.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WSTOPSIG(stat_val)</span></code>. If the value of <code class="docutils literal notranslate"><span class="pre">WIFSTOPPED(stat_val)</span></code> is |
| non-zero, this macro evaluates to the number of the signal that |
| caused the child process to stop.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WIFCONTINUED(stat_val)</span></code>. Evaluates to a non-zero value if status |
| was returned for a child process that has continued from a job |
| control stop.</p></li> |
| </ul> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Returns</dt> |
| <dd class="field-odd"><p><p>If <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> returns because the status of a child process is |
| available, it will return a value equal to the process ID of the child |
| process for which status is reported.</p> |
| <p>If <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> returns due to the delivery of a signal to the calling |
| process, -1 will be returned and <code class="docutils literal notranslate"><span class="pre">errno</span></code> set to <code class="docutils literal notranslate"><span class="pre">EINTR</span></code>.</p> |
| <p>If <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> was invoked with WNOHANG set in options, it has at |
| least one child process specified by pid for which status is not |
| available, and status is not available for any process specified by pid, |
| 0 is returned.</p> |
| <p>Otherwise, <code class="docutils literal notranslate"><span class="pre">(pid_t)-1errno</span></code> set to indicate the error:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">ECHILD</span></code>. The process specified by <code class="docutils literal notranslate"><span class="pre">pid</span></code> does not exist or is not |
| a child of the calling process, or the process group specified by |
| <code class="docutils literal notranslate"><span class="pre">pid</span></code> does not exist or does not have any member process that is a |
| child of the calling process.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EINTR</span></code>. The function was interrupted by a signal. The value of the |
| location pointed to by <code class="docutils literal notranslate"><span class="pre">stat_loc</span></code> is undefined.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EINVAL</span></code>. The <code class="docutils literal notranslate"><span class="pre">options</span></code> argument is not valid.</p></li> |
| </ul> |
| </p> |
| </dd> |
| </dl> |
| <p><strong>Assumptions/Limitations:</strong></p> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name, but the implementation is incomplete (as detailed above).</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.waitid"> |
| <span class="pre">int</span> <code class="sig-name descname"><span class="pre">waitid</span></code><span class="sig-paren">(</span><span class="pre">idtype_t</span> <em><span class="pre">idtype</span></em>, <span class="pre">id_t</span> <em><span class="pre">id</span></em>, <span class="pre">FAR</span> <a class="reference internal" href="structures.html#c.siginfo_t" title="siginfo_t"><span class="pre">siginfo_t</span></a> <span class="pre">*</span><em><span class="pre">info</span></em>, <span class="pre">int</span> <em><span class="pre">options</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.waitid" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>The following discussion is a general description of the <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> |
| interface. However, as of this writing, the implementation of |
| <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> is incomplete (but usable). If |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_HAVE_PARENT</span></code> is defined, <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> will be a |
| little more compliant to specifications. <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> simply |
| supports waiting a specific child task (<code class="docutils literal notranslate"><span class="pre">P_PID</span></code> or for any child |
| task <code class="docutils literal notranslate"><span class="pre">P_ALL</span></code> to complete execution. <code class="docutils literal notranslate"><span class="pre">SIGCHLD</span></code> is used. The |
| implementation is incomplete in either case, however: NuttX does not |
| support any concept of process groups. Nor does NuttX retain the |
| status of exited tasks so if <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> is called after a task has |
| exited, then no status will be available. The options argument is |
| currently ignored.</p> |
| </div> |
| <p>The <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> function suspends the calling thread until one child of |
| the process containing the calling thread changes state. It records the |
| current state of a child in the structure pointed to by <code class="docutils literal notranslate"><span class="pre">info</span></code>. If a |
| child process changed state prior to the call to <code class="docutils literal notranslate"><span class="pre">waitid()</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> returns immediately. If more than one thread is suspended |
| in <code class="docutils literal notranslate"><span class="pre">wait()</span></code> or <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> waiting termination of the same process, |
| exactly one thread will return the process status at the time of the |
| target process termination</p> |
| <p>The <code class="docutils literal notranslate"><span class="pre">idtype</span></code> and <code class="docutils literal notranslate"><span class="pre">id</span></code> arguments are used to specify which children |
| <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> will wait for.</p> |
| <ul class="simple"> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">idtype</span></code> is P_PID, <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> will wait for the child with a |
| process ID equal to (pid_t)``id``.</p></li> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">idtype</span></code> is P_PGID, <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> will wait for any child with a |
| process group ID equal to (pid_t)``id``.</p></li> |
| <li><p>If <code class="docutils literal notranslate"><span class="pre">idtype</span></code> is P_ALL, <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> will wait for any children and |
| <code class="docutils literal notranslate"><span class="pre">id</span></code> is ignored.</p></li> |
| </ul> |
| <p>The <code class="docutils literal notranslate"><span class="pre">options</span></code> argument is used to specify which state changes |
| <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> will will wait for. It is formed by OR-ing together one or |
| more of the following flags:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WEXITED</span></code>: Wait for processes that have exited.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WSTOPPED</span></code>: Status will be returned for any child that has stopped |
| upon receipt of a signal.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WCONTINUES</span></code>: Status will be returned for any child that was |
| stopped and has been continued.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WNOHANG</span></code>: Return immediately if there are no children to wait for.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">WNOWAIT</span></code>: Keep the process whose status is returned in <code class="docutils literal notranslate"><span class="pre">info</span></code> in |
| a waitable state. This will not affect the state of the process; the |
| process may be waited for again after this call completes.</p></li> |
| </ul> |
| <p>The <code class="docutils literal notranslate"><span class="pre">info</span></code> argument must point to a <code class="docutils literal notranslate"><span class="pre">siginfo_t</span></code> structure. If |
| <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> returns because a child process was found that satisfied |
| the conditions indicated by the arguments <code class="docutils literal notranslate"><span class="pre">idtype</span></code> and options, then |
| the structure pointed to by <code class="docutils literal notranslate"><span class="pre">info</span></code> will be filled in by the system |
| with the status of the process. The <code class="docutils literal notranslate"><span class="pre">si_signo</span></code> member will always be |
| equal to <code class="docutils literal notranslate"><span class="pre">SIGCHLD</span></code>.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Returns</dt> |
| <dd class="field-odd"><p>If <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> returns due to the change of state |
| of one of its children, 0 is returned. Otherwise, -1 is returned and |
| <code class="docutils literal notranslate"><span class="pre">errno</span></code> is set to indicate the error.</p> |
| </dd> |
| </dl> |
| <p>The <code class="docutils literal notranslate"><span class="pre">waitid()</span></code> function will fail if:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">ECHILD</span></code>:</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EINTR</span></code>:</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EINVAL</span></code>: An invalid value was specified for <code class="docutils literal notranslate"><span class="pre">options</span></code>, or |
| <code class="docutils literal notranslate"><span class="pre">idtype</span></code> and <code class="docutils literal notranslate"><span class="pre">id</span></code> specify an invalid set of processes.</p></li> |
| </ul> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name, but the implementation is incomplete (as detailed in the |
| description above).</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.wait"> |
| <a class="reference internal" href="structures.html#c.pid_t" title="pid_t"><span class="pre">pid_t</span></a> <code class="sig-name descname"><span class="pre">wait</span></code><span class="sig-paren">(</span><span class="pre">FAR</span> <span class="pre">int</span> <span class="pre">*</span><em><span class="pre">stat_loc</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.wait" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>The following discussion is a general description of the <a class="reference internal" href="#c.wait" title="wait"><code class="xref c c-func docutils literal notranslate"><span class="pre">wait()</span></code></a> |
| interface. However, as of this writing, the implementation of |
| <a class="reference internal" href="#c.wait" title="wait"><code class="xref c c-func docutils literal notranslate"><span class="pre">wait()</span></code></a> is incomplete (but usable). <a class="reference internal" href="#c.wait" title="wait"><code class="xref c c-func docutils literal notranslate"><span class="pre">wait()</span></code></a> is based |
| on <a class="reference internal" href="#c.waitpid" title="waitpid"><code class="xref c c-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a> (see description for further information).</p> |
| </div> |
| <p>The <code class="docutils literal notranslate"><span class="pre">wait()</span></code> function will suspend execution of the calling thread |
| until status information for one of its terminated child processes is |
| available, or until delivery of a signal whose action is either to |
| execute a signal-catching function or to terminate the process. If more |
| than one thread is suspended in <code class="docutils literal notranslate"><span class="pre">wait()</span></code> awaiting termination of the |
| same process, exactly one thread will return the process status at the |
| time of the target process termination. If status information is |
| available prior to the call to<code class="docutils literal notranslate"><span class="pre">wait()</span></code>, return will be immediate.</p> |
| <p>The <code class="docutils literal notranslate"><span class="pre">waitpid()</span></code> function will behave identically to <code class="docutils literal notranslate"><span class="pre">wait()</span></code>, if its |
| <code class="docutils literal notranslate"><span class="pre">pid</span></code> argument is (pid_t)-1 and the options argument is 0. Otherwise, |
| its behavior will be modified by the values of the <code class="docutils literal notranslate"><span class="pre">pid</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">options</span></code> arguments.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters</dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>stat_loc</strong> – The location to return the exit status</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns</dt> |
| <dd class="field-even"><p>See the values returned by <a class="reference internal" href="#c.waitpid" title="waitpid"><code class="xref c c-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a></p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name, but the implementation is incomplete (as detailed in the |
| description <code class="docutils literal notranslate"><span class="pre">`waitpaid()</span></code> <#waitpid>`__).</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.atexit"> |
| <span class="pre">int</span> <code class="sig-name descname"><span class="pre">atexit</span></code><span class="sig-paren">(</span><span class="pre">void</span> <span class="pre">(</span><span class="pre">*</span><em><span class="pre">func</span></em><span class="pre">)</span><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><span class="sig-paren">)</span><a class="headerlink" href="#c.atexit" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Registers a function to be called at program exit. The |
| <code class="docutils literal notranslate"><span class="pre">atexit()</span></code> function registers the given function to be called at |
| normal process termination, whether via <code class="docutils literal notranslate"><span class="pre">exit()</span></code> or via return from |
| the program’s <code class="docutils literal notranslate"><span class="pre">main()</span></code>.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p><code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_ATEXIT</span></code> must be defined to enable this function.</p> |
| </div> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters</dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>func</strong> – A pointer to the function to be called when the task exits.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns</dt> |
| <dd class="field-even"><p>On success, <code class="docutils literal notranslate"><span class="pre">atexit()</span></code> returns OK (0). On error, |
| ERROR (-1) is returned, and <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__ is set to |
| indicate the cause of the failure.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the ISO C interface of the same |
| name. Limitations in the current implementation:</p> |
| <blockquote> |
| <div><ol class="arabic simple"> |
| <li><p>Only a single <code class="docutils literal notranslate"><span class="pre">atexit</span></code> function can be registered unless |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_ATEXIT_MAX</span></code> defines a larger number.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">atexit()</span></code> functions are not inherited when a new task is created.</p></li> |
| </ol> |
| </div></blockquote> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.on_exit"> |
| <span class="pre">int</span> <code class="sig-name descname"><span class="pre">on_exit</span></code><span class="sig-paren">(</span><span class="pre">CODE</span> <span class="pre">void</span> <span class="pre">(</span><span class="pre">*</span><em><span class="pre">func</span></em><span class="pre">)</span><span class="sig-paren">(</span><span class="pre">int</span>, <span class="pre">FAR</span> <span class="pre">void</span><span class="pre">*</span><span class="sig-paren">)</span>, <span class="pre">FAR</span> <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">arg</span></em>, <span class="sig-paren">)</span><a class="headerlink" href="#c.on_exit" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Registers a function to be called at program exit. The |
| <code class="docutils literal notranslate"><span class="pre">on_exit()</span></code> function registers the given function to be called at |
| normal process termination, whether via <code class="docutils literal notranslate"><span class="pre">exit()</span></code> or via return from |
| the program’s <code class="docutils literal notranslate"><span class="pre">main()</span></code>. The function is passed the status argument |
| given to the last call to <code class="docutils literal notranslate"><span class="pre">exit()</span></code> and the <code class="docutils literal notranslate"><span class="pre">arg</span></code> argument from |
| <code class="docutils literal notranslate"><span class="pre">on_exit()</span></code>.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters</dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>func</strong> – A pointer to the function to be called when the task exits.</p></li> |
| <li><p><strong>arg</strong> – An argument that will be provided to the <code class="docutils literal notranslate"><span class="pre">on_exit()</span></code> |
| function when the task exits.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns</dt> |
| <dd class="field-even"><p>On success, <code class="docutils literal notranslate"><span class="pre">on_exit()</span></code> returns OK (0). On error, |
| ERROR (-1) is returned, and <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__ is set to |
| indicate the cause of the failure.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> This function comes from SunOS 4, but is also |
| present in libc4, libc5 and glibc. It no longer occurs in Solaris (SunOS |
| 5). Avoid this function, and use the standard <code class="docutils literal notranslate"><span class="pre">atexit()</span></code> instead.</p> |
| <blockquote> |
| <div><ol class="arabic simple"> |
| <li><p>Only a single <code class="docutils literal notranslate"><span class="pre">on_exit</span></code> function can be registered unless |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SCHED_ONEXIT_MAX</span></code> defines a larger number.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">on_exit()</span></code> functions are not inherited when a new task is created.</p></li> |
| </ol> |
| </div></blockquote> |
| </dd></dl> |
| |
| </div> |
| </div> |
| |
| |
| </div> |
| |
| </div> |
| <footer> |
| <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> |
| <a href="04_message_queue.html" class="btn btn-neutral float-right" title="Named Message Queue Interfaces" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> |
| <a href="02_task_scheduling.html" class="btn btn-neutral float-left" title="Task Scheduling Interfaces" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| </div> |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p> |
| © Copyright 2020, The Apache Software Foundation. |
| |
| </p> |
| </div> |
| |
| </footer> |
| </div> |
| </div> |
| |
| </section> |
| |
| </div> |
| |
| |
| <script type="text/javascript"> |
| jQuery(function () { |
| SphinxRtdTheme.Navigation.enable(true); |
| }); |
| </script> |
| |
| |
| |
| |
| |
| |
| </body> |
| </html> |
