| <!-- |
| 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="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title>Counting Semaphore Interfaces — NuttX latest documentation</title> |
| <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> |
| <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" /> |
| <link rel="stylesheet" href="../../_static/copybutton.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 src="../../_static/jquery.js"></script> |
| <script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script> |
| <script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script> |
| <script src="../../_static/doctools.js"></script> |
| <script src="../../_static/sphinx_highlight.js"></script> |
| <script src="../../_static/clipboard.min.js"></script> |
| <script src="../../_static/copybutton.js"></script> |
| <script 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="Clocks and Timers" href="06_clocks_timers.html" /> |
| <link rel="prev" title="Named Message Queue Interfaces" href="04_message_queue.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 |
| |
| |
| |
| </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> |
| |
| </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" aria-label="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="Navigation menu"> |
| <p class="caption" role="heading"><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"><a class="reference internal" href="03_task_control.html">Task Control Interfaces</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="04_message_queue.html">Named Message Queue Interfaces</a></li> |
| <li class="toctree-l3 current"><a class="current reference internal" href="#">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="Mobile navigation menu" > |
| <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="Page navigation"> |
| <ul class="wy-breadcrumbs"> |
| <li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li> |
| <li class="breadcrumb-item"><a href="../index.html">API Reference</a></li> |
| <li class="breadcrumb-item"><a href="index.html">Userspace API</a></li> |
| <li class="breadcrumb-item active">Counting Semaphore Interfaces</li> |
| <li class="wy-breadcrumbs-aside"> |
| <a href="../../_sources/reference/user/05_counting_semaphore.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"> |
| |
| <section id="counting-semaphore-interfaces"> |
| <h1>Counting Semaphore Interfaces<a class="headerlink" href="#counting-semaphore-interfaces" title="Permalink to this heading"></a></h1> |
| <p><strong>Semaphores</strong>. Semaphores are the basis for synchronization and mutual |
| exclusion in NuttX. NuttX supports POSIX semaphores.</p> |
| <p>Semaphores are the preferred mechanism for gaining exclusive access to a |
| resource. sched_lock() and sched_unlock() can also be used for this |
| purpose. However, sched_lock() and sched_unlock() have other undesirable |
| side-effects in the operation of the system: sched_lock() also prevents |
| higher-priority tasks from running that do not depend upon the |
| semaphore-managed resource and, as a result, can adversely affect system |
| response times.</p> |
| <p>Priority Inversion. Proper use of semaphores avoids the issues of |
| <code class="docutils literal notranslate"><span class="pre">sched_lock()</span></code>. However, consider the following example:</p> |
| <blockquote> |
| <div><ol class="arabic simple"> |
| <li><p>Some low-priority task, <em>Task C</em>, acquires a semaphore in order to |
| get exclusive access to a protected resource.</p></li> |
| <li><p><em>Task C</em> is suspended to allow some high-priority task,</p></li> |
| <li><p><em>Task A</em> attempts to acquire the semaphore held by <em>Task C</em> and gets |
| blocked until <em>Task C</em> relinquishes the semaphore.</p></li> |
| <li><p><em>Task C</em> is allowed to execute again, but gets suspended by some |
| medium-priority <em>Task B</em>.</p></li> |
| </ol> |
| </div></blockquote> |
| <p>At this point, the high-priority <em>Task A</em> cannot execute until <em>Task B</em> |
| (and possibly other medium-priority tasks) completes and until <em>Task C</em> |
| relinquishes the semaphore. In effect, the high-priority task, <em>Task A</em> |
| behaves as though it were lower in priority than the low-priority task, |
| <em>Task C</em>! This phenomenon is called <em>priority inversion</em>.</p> |
| <p>Some operating systems avoid priority inversion by <em>automatically</em> |
| increasing the priority of the low-priority <em>Task C</em> (the operable |
| buzz-word for this behavior is <em>priority inheritance</em>). NuttX supports |
| this behavior, but only if <code class="docutils literal notranslate"><span class="pre">CONFIG_PRIORITY_INHERITANCE</span></code> is defined in |
| your OS configuration file. If <code class="docutils literal notranslate"><span class="pre">CONFIG_PRIORITY_INHERITANCE</span></code> is not |
| defined, then it is left to the designer to provide implementations that |
| will not suffer from priority inversion. The designer may, as examples:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>Implement all tasks that need the semaphore-managed resources at the |
| same priority level,</p></li> |
| <li><p>Boost the priority of the low-priority task before the semaphore is |
| acquired, or</p></li> |
| <li><p>Use sched_lock() in the low-priority task.</p></li> |
| </ul> |
| </div></blockquote> |
| <p>Priority Inheritance. As mentioned, NuttX does support <em>priority |
| inheritance</em> provided that <code class="docutils literal notranslate"><span class="pre">CONFIG_PRIORITY_INHERITANCE</span></code> is defined in |
| your OS configuration file. However, the implementation and |
| configuration of the priority inheritance feature is sufficiently |
| complex that more needs to be said. How can a feature that can be |
| described by a single, simple sentence require such a complex |
| implementation:</p> |
| <blockquote> |
| <div><ul> |
| <li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_SEM_PREALLOCHOLDERS</span></code>. First of all, in NuttX priority |
| inheritance is implement on POSIX counting semaphores. The reason for |
| this is that these semaphores are the most primitive waiting |
| mechanism in NuttX; Most other waiting facilities are based on |
| semaphores. So if priority inheritance is implemented for POSIX |
| counting semaphores, then most NuttX waiting mechanisms will have |
| this capability.</p> |
| <p>Complexity arises because counting semaphores can have numerous |
| holders of semaphore counts. Therefore, in order to implement |
| priority inheritance across all holders, then internal data |
| structures must be allocated to manage the various holders associated |
| with a semaphore. The setting <code class="docutils literal notranslate"><span class="pre">CONFIG_SEM_PREALLOCHOLDERS</span></code> defines |
| the maximum number of different threads (minus one per semaphore |
| instance) that can take counts on a semaphore with priority |
| inheritance support. This setting defines the size of a single pool |
| of pre-allocated structures. It may be set to zero if priority |
| inheritance is disabled OR if you are only using semaphores as |
| mutexes (only one holder) OR if no more than two threads participate |
| using a counting semaphore.</p> |
| <p>The cost associated with setting <code class="docutils literal notranslate"><span class="pre">CONFIG_SEM_PREALLOCHOLDERS</span></code> is |
| slightly increased code size and around 6-12 bytes times the value of |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_SEM_PREALLOCHOLDERS</span></code>.</p> |
| </li> |
| <li><p><strong>Increased Susceptibility to Bad Thread Behavior</strong>. These various |
| structures tie the semaphore implementation more tightly to the |
| behavior of the implementation. For examples, if a thread executes |
| while holding counts on a semaphore, or if a thread exits without |
| call <code class="docutils literal notranslate"><span class="pre">sem_destroy()</span></code> then. Or what if the thread with the boosted |
| priority re-prioritizes itself? The NuttX implement of priority |
| inheritance attempts to handle all of these types of corner cases, |
| but it is very likely that some are missed. The worst case result is |
| that memory could by stranded within the priority inheritance logic.</p></li> |
| </ul> |
| </div></blockquote> |
| <p>Locking versus Signaling Semaphores. Semaphores (and mutexes) may be |
| used for many different purposes. One typical use is for mutual |
| exclusion and locking of resources: In this usage, the thread that needs |
| exclusive access to a resources takes the semaphore to get access to the |
| resource. The same thread subsequently releases the semaphore count when |
| it no longer needs exclusive access. Priority inheritance is intended |
| just for this usage case.</p> |
| <p>In a different usage case, a semaphore may to be used to signal an |
| event: One thread A waits on a semaphore for an event to occur. When the |
| event occurs, another thread B will post the semaphore waking the |
| waiting thread A. This is a completely different usage model; notice |
| that in the mutual exclusion case, the same thread takes and posts the |
| semaphore. In the signaling case, one thread takes the semaphore and a |
| different thread posts the semaphore. Priority inheritance should |
| <em>never</em> be used in this signaling case. Subtle, strange behaviors may |
| result.</p> |
| <p>Semaphore does not support priority inheritance by default. If you need to |
| use a semaphore as a mutex you need to change its default behavior.</p> |
| <p>In user space, it is recommended to use pthread_mutex instead of |
| semaphore for resource protection</p> |
| <p>When priority inheritance is enabled with |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_PRIORITY_INHERITANCE</span></code>, the default <em>protocol</em> for the |
| semaphore will be to use priority inheritance. For signaling semaphores, |
| priority inheritance must be explicitly disabled by calling |
| <code class="docutils literal notranslate"><span class="pre">`sem_setprotocol</span></code> <#semsetprotocol>`__ with <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_NONE</span></code>. For |
| the case of pthread mutexes, |
| <code class="docutils literal notranslate"><span class="pre">`pthread_mutexattr_setprotocol</span></code> <#pthreadmutexattrsetprotocol>`__ |
| with <code class="docutils literal notranslate"><span class="pre">PTHREAD_PRIO_NONE</span></code>.</p> |
| <p>This is discussed in much more detail on this <a class="reference external" href="https://cwiki.apache.org/confluence/display/NUTTX/Signaling+Semaphores+and+Priority+Inheritance">Wiki |
| page</a>.</p> |
| <p><strong>POSIX semaphore interfaces:</strong></p> |
| <ul class="simple"> |
| <li><p><a class="reference internal" href="#c.sem_init" title="sem_init"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_init()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_destroy" title="sem_destroy"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_destroy()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_open" title="sem_open"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_open()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_close" title="sem_close"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_close()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_unlink" title="sem_unlink"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_unlink()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_wait" title="sem_wait"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_wait()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_timedwait" title="sem_timedwait"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_timedwait()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_trywait" title="sem_trywait"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_trywait()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_post" title="sem_post"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_post()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_getvalue" title="sem_getvalue"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_getvalue()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_getprotocol" title="sem_getprotocol"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_getprotocol()</span></code></a></p></li> |
| <li><p><a class="reference internal" href="#c.sem_setprotocol" title="sem_setprotocol"><code class="xref c c-func docutils literal notranslate"><span class="pre">sem_setprotocol()</span></code></a></p></li> |
| </ul> |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_init"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_init</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">pshared</span></span>, <span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_init" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>Initializes the UN-NAMED semaphore sem. |
| Following a successful call to sem_init(), the semaphore may be used in |
| subsequent calls to sem_wait(), sem_post(), and sem_trywait(). The |
| semaphore remains usable until it is destroyed.</p> |
| <p>Only <code class="docutils literal notranslate"><span class="pre">sem</span></code> itself may be used for performing synchronization. The |
| result of referring to copies of <code class="docutils literal notranslate"><span class="pre">sem</span></code> in calls to <code class="docutils literal notranslate"><span class="pre">sem_wait()</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">sem_trywait()</span></code>, <code class="docutils literal notranslate"><span class="pre">sem_post()</span></code>, and <code class="docutils literal notranslate"><span class="pre">sem_destroy()</span></code>, is not |
| defined.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – Semaphore to be initialized</p></li> |
| <li><p><strong>pshared</strong> – Process sharing (not used)</p></li> |
| <li><p><strong>value</strong> – Semaphore initialization value</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>), or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) if unsuccessful.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name. Differences from the full POSIX implementation include:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>pshared is not used.</p></li> |
| </ul> |
| </div></blockquote> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_destroy"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_destroy</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_destroy" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>Used to destroy the un-named semaphore |
| indicated by <code class="docutils literal notranslate"><span class="pre">sem</span></code>. Only a semaphore that was created using |
| <code class="docutils literal notranslate"><span class="pre">sem_init()</span></code> may be destroyed using <code class="docutils literal notranslate"><span class="pre">sem_destroy()</span></code>. The effect of |
| calling <code class="docutils literal notranslate"><span class="pre">sem_destroy()</span></code> with a named semaphore is undefined. The |
| effect of subsequent use of the semaphore <code class="docutils literal notranslate"><span class="pre">sem</span></code> is undefined until |
| <code class="docutils literal notranslate"><span class="pre">sem</span></code> is re-initialized by another call to <code class="docutils literal notranslate"><span class="pre">sem_init()</span></code>.</p> |
| <p>The effect of destroying a semaphore upon which other tasks are |
| currently blocked is undefined.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – Semaphore to be destroyed.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>), or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) if unsuccessful.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_open"> |
| <a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">sem_open</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">oflag</span></span>, <span class="p"><span class="pre">...</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_open" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>Establishes a connection between named |
| semaphores and a task. Following a call to sem_open() with the semaphore |
| name, the task may reference the semaphore associated with name using |
| the address returned by this call. The semaphore may be used in |
| subsequent calls to sem_wait(), sem_trywait(), and sem_post(). The |
| semaphore remains usable until the semaphore is closed by a successful |
| call to sem_close().</p> |
| <p>If a task makes multiple calls to sem_open() with the same name, then |
| the same semaphore address is returned (provided there have been no |
| calls to sem_unlink()).</p> |
| <p><strong>Input Parameters:</strong></p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>name</strong> – Semaphore name</p></li> |
| <li><p><strong>oflag</strong> – <p>Semaphore creation options. This may one of the following |
| bit settings:</p> |
| <ul> |
| <li><p><code class="docutils literal notranslate"><span class="pre">oflag</span></code> = 0: Connect to the semaphore only if it already exists.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">oflag</span></code> = O_CREAT: Connect to the semaphore if it exists, |
| otherwise create the semaphore.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">oflag</span></code> = O_CREAT with O_EXCL (O_CREAT|O_EXCL): Create a new |
| semaphore unless one of this name already exists.</p></li> |
| </ul> |
| </p></li> |
| <li><p><strong>...</strong> – <p><strong>Optional parameters</strong>. NOTE: When the O_CREAT flag is specified, |
| POSIX requires that a third and fourth parameter be supplied:</p> |
| <ul> |
| <li><p><code class="docutils literal notranslate"><span class="pre">mode</span></code>. The mode parameter is of type mode_t. This parameter is |
| required but not used in the present implementation.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">value</span></code>. The value parameter is type unsigned int. The semaphore |
| is created with an initial value of <code class="docutils literal notranslate"><span class="pre">value</span></code>. Valid initial |
| values for semaphores must be less than or equal to |
| <code class="docutils literal notranslate"><span class="pre">SEM_VALUE_MAX</span></code> (defined in <code class="docutils literal notranslate"><span class="pre">include/limits.h</span></code>).</p></li> |
| </ul> |
| </p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>A pointer to sem_t or <code class="docutils literal notranslate"><span class="pre">SEM_FAILED</span></code> if unsuccessful.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name. Differences from the full POSIX implementation include:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>Treatment of links/connections is highly simplified. It is just a |
| counting semaphore.</p></li> |
| </ul> |
| </div></blockquote> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_close"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_close</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_close" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>This function is called to indicate that the calling |
| task is finished with the specified named semaphore, sem. The |
| sem_close() deallocates any system resources allocated by the system for |
| this named semaphore.</p> |
| <p>If the semaphore has not been removed with a call to sem_unlink(), then |
| sem_close() has no effect on the named semaphore. However, when the |
| named semaphore has been fully unlinked, the semaphore will vanish when |
| the last task closes it.</p> |
| <p>Care must be taken to avoid risking the deletion of a semaphore that |
| another calling task has already locked.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – Semaphore descriptor</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>), or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) if unsuccessful.</p> |
| </dd> |
| </dl> |
| <p><strong>Assumptions/Limitations:</strong></p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>Care must be taken to avoid deletion of a semaphore that another task |
| has already locked.</p></li> |
| <li><p>sem_close() must not be called with an un-named semaphore.</p></li> |
| </ul> |
| </div></blockquote> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_unlink"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_unlink</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_unlink" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>This function will remove the semaphore named by the |
| input name parameter. If one or more tasks have the semaphore named by |
| name open when sem_unlink() is called, destruction of the semaphore will |
| be postponed until all references have been destroyed by calls to |
| sem_close().</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>name</strong> – Semaphore name</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>), or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) if unsuccessful.</p> |
| </dd> |
| </dl> |
| <p><strong>Assumptions/Limitations:</strong></p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>Care must be taken to avoid deletion of a semaphore that another task |
| has already locked.</p></li> |
| <li><p>sem_unlink() must not be called with an un-named semaphore.</p></li> |
| </ul> |
| </div></blockquote> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name. Differences from the full POSIX implementation include:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>Treatment of links/connections is highly simplified. It is just a |
| counting semaphore.</p></li> |
| <li><p>Calls to sem_open() to re-create or re-connect to the semaphore may |
| refer to the same semaphore; POSIX specifies that a new semaphore |
| with the same name should be created after sem_unlink() is called.</p></li> |
| </ul> |
| </div></blockquote> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_wait"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_wait</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_wait" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>This function attempts to lock the semaphore referenced |
| by sem. If the semaphore as already locked by another task, the calling |
| task will not return until it either successfully acquires the lock or |
| the call is interrupted by a signal.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – Semaphore descriptor.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>), or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) is unsuccessful</p> |
| </dd> |
| </dl> |
| <p>If <code class="docutils literal notranslate"><span class="pre">sem_wait</span></code> returns -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) then the cause of the failure |
| will be indicated by the thread-specific <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__. |
| The following lists the possible values for |
| <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EINVAL</span></code>: Indicates that the <code class="docutils literal notranslate"><span class="pre">sem</span></code> input parameter is not valid.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EINTR</span></code>: Indicates that the wait was interrupt by a signal received |
| by this task. In this case, the semaphore has not be acquired.</p></li> |
| </ul> |
| </div></blockquote> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_timedwait"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_timedwait</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="structures.html#c.timespec" title="timespec"><span class="n"><span class="pre">timespec</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">abstime</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_timedwait" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>This function will lock the semaphore referenced by sem |
| as in the <code class="docutils literal notranslate"><span class="pre">sem_wait()</span></code> function. However, if the semaphore cannot be |
| locked without waiting for another process or thread to unlock the |
| semaphore by performing a <code class="docutils literal notranslate"><span class="pre">sem_post()</span></code> function, this wait will be |
| terminated when the specified timeout expires.</p> |
| <p>The timeout will expire when the absolute time specified by <code class="docutils literal notranslate"><span class="pre">abstime</span></code> |
| passes, as measured by the clock on which timeouts are based (that is, |
| when the value of that clock equals or exceeds abstime), or if the |
| absolute time specified by abstime has already been passed at the time |
| of the call. This function attempts to lock the semaphore referenced by |
| <code class="docutils literal notranslate"><span class="pre">sem</span></code>. If the semaphore is already locked by another task, the calling |
| task will not return until it either successfully acquires the lock or |
| the call is interrupted by a signal.</p> |
| <p><strong>Input Parameters:</strong></p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – Semaphore descriptor.</p></li> |
| <li><p><strong>abstime</strong> – The absolute time to wait until a timeout is declared.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>), or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) is unsuccessful</p> |
| </dd> |
| </dl> |
| <p>If <code class="docutils literal notranslate"><span class="pre">sem_timedwait</span></code> returns -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) then the cause of the |
| failure will be indicated by the thread-specific |
| <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__. The following lists the possible values |
| for <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__:</p> |
| <p><code class="docutils literal notranslate"><span class="pre">EINVAL</span></code>: Indicates that the <code class="docutils literal notranslate"><span class="pre">sem</span></code> input parameter is not valid or |
| the thread would have blocked, and the abstime parameter specified a |
| nanoseconds field value less than zero or greater than or equal to 1000 |
| million.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">ETIMEDOUT</span></code>: The semaphore could not be locked before the specified |
| timeout expired.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">EDEADLK</span></code>: A deadlock condition was detected.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">EINTR</span></code>: Indicates that the wait was interrupt by a signal received by |
| this task. In this case, the semaphore has not be acquired.</p> |
| <p><strong>POSIX Compatibility:</strong> Derived from IEEE Std 1003.1d-1999.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_trywait"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_trywait</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_trywait" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>This function locks the specified semaphore only if the |
| semaphore is currently not locked. In any event, the call returns |
| without blocking.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – The semaphore descriptor</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>) or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) if unsuccessful</p> |
| </dd> |
| </dl> |
| <p>If <code class="docutils literal notranslate"><span class="pre">sem_trywait</span></code> returns -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) then the cause of the failure |
| will be indicated by the thread-specific <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__. |
| The following lists the possible values for |
| <code class="docutils literal notranslate"><span class="pre">`errno</span></code> <#ErrnoAccess>`__:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EINVAL</span></code>: Indicates that the <code class="docutils literal notranslate"><span class="pre">sem</span></code> input parameter is not valid.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">EAGAIN</span></code>: Indicates that the semaphore was not acquired.</p></li> |
| </ul> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_post"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_post</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_post" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>When a task has finished with a semaphore, it will call |
| sem_post(). This function unlocks the semaphore referenced by <code class="docutils literal notranslate"><span class="pre">sem</span></code> by |
| performing the semaphore unlock operation.</p> |
| <p>If the semaphore value resulting from this operation is positive, then |
| no tasks were blocked waiting for the semaphore to become unlocked; The |
| semaphore value is simply incremented.</p> |
| <p>If the value of the semaphore resulting from this operation is zero, |
| then on of the tasks blocked waiting for the semaphore will be allowed |
| to return successfully from its call to <code class="docutils literal notranslate"><span class="pre">sem_wait()</span></code>.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p><code class="docutils literal notranslate"><span class="pre">sem_post()</span></code> may be called from an interrupt handler.</p> |
| </div> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – Semaphore descriptor</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>) or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) if unsuccessful.</p> |
| </dd> |
| </dl> |
| <p><strong>Assumptions/Limitations:</strong>. When called from an interrupt handler, it |
| will appear as though the interrupt task is the one that is performing |
| the unlock.</p> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_getvalue"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_getvalue</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.sem_t" title="sem_t"><span class="n"><span class="pre">sem_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sem</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sval</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_getvalue" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>This function updates the location referenced by sval |
| argument to have the value of the semaphore referenced by sem without |
| effecting the state of the semaphore. The updated value represents the |
| actual semaphore value that occurred at some unspecified time during the |
| call, but may not reflect the actual value of the semaphore when it is |
| returned to the calling task.</p> |
| <p>If sem is locked, the value return by sem_getvalue() will either be zero |
| or a negative number whose absolute value represents the number of tasks |
| waiting for the semaphore.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>sem</strong> – Semaphore descriptor</p></li> |
| <li><p><strong>sval</strong> – Buffer by which the value is returned</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>0 (<code class="docutils literal notranslate"><span class="pre">OK</span></code>) or -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) if unsuccessful.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Comparable to the POSIX interface of the same |
| name.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_getprotocol"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_getprotocol</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">pthread_mutexattr_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr</span></span>, <span class="pre">FAR</span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">protocol</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_getprotocol" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>Return the value of the semaphore protocol attribute.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>attr</strong> – A pointer to the semaphore to be queried</p></li> |
| <li><p><strong>protocol</strong> – The user provided location in which to store the |
| protocol value. May be one of <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_NONE</span></code>, or |
| <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_INHERIT</span></code>, <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_PROTECT</span></code>.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>If successful, the <code class="docutils literal notranslate"><span class="pre">sem_getprotocol()</span></code> function will return zero |
| (<code class="docutils literal notranslate"><span class="pre">OK</span></code>). Otherwise, an -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) will be returned and the |
| <code class="docutils literal notranslate"><span class="pre">errno</span></code> value will be set to indicate the nature of the error.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Non-standard NuttX interface. Should not be |
| used in portable code. Analogous to |
| <code class="docutils literal notranslate"><span class="pre">pthread_muxtexattr_getprotocol()</span></code>.</p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt class="sig sig-object c" id="c.sem_setprotocol"> |
| <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">sem_setprotocol</span></span></span><span class="sig-paren">(</span><span class="pre">FAR</span><span class="w"> </span><span class="n"><span class="pre">pthread_mutexattr_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">protocol</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.sem_setprotocol" title="Permalink to this definition"></a><br /></dt> |
| <dd><p>Set semaphore protocol attribute. See the paragraph |
| <a class="reference external" href="#lockingvssignaling">Locking versus Signaling Semaphores</a> for some |
| important information about the use of this interface.</p> |
| <dl class="field-list simple"> |
| <dt class="field-odd">Parameters<span class="colon">:</span></dt> |
| <dd class="field-odd"><ul class="simple"> |
| <li><p><strong>attr</strong> – A pointer to the semaphore to be modified</p></li> |
| <li><p><strong>protocol</strong> – The new protocol to use. One of <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_NONE</span></code>, or |
| <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_INHERIT</span></code>, <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_PROTECT</span></code>. <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_INHERIT</span></code> is |
| supported only if <code class="docutils literal notranslate"><span class="pre">CONFIG_PRIORITY_INHERITANCE</span></code> is defined; |
| <code class="docutils literal notranslate"><span class="pre">SEM_PRIO_PROTECT</span></code> is not currently supported in any configuration.</p></li> |
| </ul> |
| </dd> |
| <dt class="field-even">Returns<span class="colon">:</span></dt> |
| <dd class="field-even"><p>If successful, the <code class="docutils literal notranslate"><span class="pre">sem_setprotocol()</span></code> function will return zero |
| (<code class="docutils literal notranslate"><span class="pre">OK</span></code>). Otherwise, an -1 (<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>) will be returned and the |
| <code class="docutils literal notranslate"><span class="pre">errno</span></code> value will be set to indicate the nature of the error.</p> |
| </dd> |
| </dl> |
| <p><strong>POSIX Compatibility:</strong> Non-standard NuttX interface. Should not be |
| used in portable code. Analogous to |
| <code class="docutils literal notranslate"><span class="pre">pthread_muxtexattr_setprotocol()</span></code>.</p> |
| </dd></dl> |
| |
| </section> |
| |
| |
| </div> |
| </div> |
| <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> |
| <a href="04_message_queue.html" class="btn btn-neutral float-left" title="Named Message Queue Interfaces" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| <a href="06_clocks_timers.html" class="btn btn-neutral float-right" title="Clocks and Timers" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> |
| </div> |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p>© Copyright 2020, The Apache Software Foundation.</p> |
| </div> |
| |
| |
| |
| </footer> |
| </div> |
| </div> |
| </section> |
| </div> |
| <script> |
| jQuery(function () { |
| SphinxRtdTheme.Navigation.enable(true); |
| }); |
| </script> |
| |
| </body> |
| </html> |
