content/docs/12.4.0/reference/os/app_vs_os.html - nuttx-website - Git at Google

 <!--
  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>Application OS vs. Internal OS Interfaces &mdash; 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="APIs Exported by Architecture-Specific Logic to NuttX" href="arch.html" />
     <link rel="prev" title="Address Environments" href="addrenv.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"><a class="reference internal" href="../../implementation/index.html">Implementation Details</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="../index.html">API Reference</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="../user/index.html">Userspace API</a></li>
 <li class="toctree-l2 current"><a class="reference internal" href="index.html">Architecture APIs</a><ul class="current">
 <li class="toctree-l3"><a class="reference internal" href="addrenv.html">Address Environments</a></li>
 <li class="toctree-l3 current"><a class="current reference internal" href="#">Application OS vs. Internal OS Interfaces</a></li>
 <li class="toctree-l3"><a class="reference internal" href="arch.html">APIs Exported by Architecture-Specific Logic to NuttX</a></li>
 <li class="toctree-l3"><a class="reference internal" href="board.html">APIs Exported by Board-Specific Logic to NuttX</a></li>
 <li class="toctree-l3"><a class="reference internal" href="conventions.html">Naming and Header File Conventions</a></li>
 <li class="toctree-l3"><a class="reference internal" href="iob.html">I/O Buffer Management</a></li>
 <li class="toctree-l3"><a class="reference internal" href="led.html">LED Support</a></li>
 <li class="toctree-l3"><a class="reference internal" href="mutex.html">Mutual Exclusion lock</a></li>
 <li class="toctree-l3"><a class="reference internal" href="nat.html">Network Address Translation (NAT)</a></li>
 <li class="toctree-l3"><a class="reference internal" href="newreno.html">Congestion Control NewReno</a></li>
 <li class="toctree-l3"><a class="reference internal" href="notifier.html">Notifier Chain</a></li>
 <li class="toctree-l3"><a class="reference internal" href="nuttx.html">APIs Exported by NuttX to Architecture-Specific Logic</a></li>
 <li class="toctree-l3"><a class="reference internal" href="paging.html">On-Demand Paging</a></li>
 <li class="toctree-l3"><a class="reference internal" href="shm.html">Shared Memory</a></li>
 <li class="toctree-l3"><a class="reference internal" href="smp.html">Symmetric Multiprocessing (SMP) Application</a></li>
 <li class="toctree-l3"><a class="reference internal" href="time_clock.html">System Time and Clock</a></li>
 <li class="toctree-l3"><a class="reference internal" href="wqueue.html">Work Queues</a></li>
 <li class="toctree-l3"><a class="reference internal" href="netdev.html">Network Devices</a></li>
 </ul>
 </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">Architecture APIs</a></li>
       <li class="breadcrumb-item active">Application OS vs. Internal OS Interfaces</li>
       <li class="wy-breadcrumbs-aside">
             <a href="../../_sources/reference/os/app_vs_os.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="application-os-vs-internal-os-interfaces">
 <h1>Application OS vs. Internal OS Interfaces<a class="headerlink" href="#application-os-vs-internal-os-interfaces" title="Permalink to this heading"></a></h1>
 <p>NuttX provides a standard, portable OS interface for use by
 applications. This standard interface is controlled by the
 specifications proved at <a class="reference external" href="http://opengroup.org">OpenGroup.org</a>.
 These application interfaces, in general, should not be used
 directly by logic executing within the OS. The reason for this is
 that there are certain properties of the standard application
 interfaces that make them unsuitable for use within the OS These
 properties include:</p>
 <ol class="arabic">
 <li><p><strong>Use of the per-thread</strong> <code class="docutils literal notranslate"><span class="pre">errno</span></code> <strong>variable</strong>: Handling of
 return values, particularly, in the case of returned error
 indications. Most legacy POSIX OS interface return information
 via a <em>per-thread</em> <code class="docutils literal notranslate"><span class="pre">errno</span></code>. There must be no alteration of
 the <code class="docutils literal notranslate"><span class="pre">errno</span></code> value that must be stable from the point of view
 of the application. So, as a general rule, internal OS logic
 must never modify the <code class="docutils literal notranslate"><span class="pre">errno</span></code> and particularly not by the
 inappropriate use of application OS interfaces within OS
 itself.</p>
 <p>Within the OS, functions do not return error information via
 the <code class="docutils literal notranslate"><span class="pre">errno</span></code> variable. Instead, the majority of internal OS
 function return error information as an integer value: Returned
 values greater than or equal to zero are success values;
 returned values less than zero indicate failures. Failures are
 reported by returning a negated <code class="docutils literal notranslate"><span class="pre">errno</span></code> value from
 <code class="docutils literal notranslate"><span class="pre">include/errno.h</span></code>,</p>
 </li>
 <li><p><strong>Cancellation Points</strong>: Many of the application OS interfaces
 are <em>cancellation points</em>, i.e., when the task is operating in
 <em>deferred cancellation</em> state, it cannot be deleted or
 cancelled until it calls an application OS interface that is a
 cancellation point.</p>
 <p>The POSIX specification is very specific about this, specific
 both in identifying which application OS interfaces are
 cancellation points and specific in the fact that it is
 prohibited for any OS operation other than those listed in the
 specification to generate cancellation points. If internal OS
 logic were to re-use application OS interfaces directly then it
 could very easily violate this POSIX requirement by incorrectly
 generating cancellation points on inappropriate OS operations
 and could result in very difficult to analyze application
 failures.</p>
 </li>
 <li><p><strong>Use of per-task Resources</strong>: Many resources are only valid in
 the task group context in which a thread operates. Above we
 mentioned one: <code class="docutils literal notranslate"><span class="pre">errno</span></code> is only valid for the thread that is
 currently executing. So, for example, the <code class="docutils literal notranslate"><span class="pre">errno</span></code> at the time
 of a call is a completely different variable than, say, the
 <code class="docutils literal notranslate"><span class="pre">errno</span></code> while running in a work queue task.</p>
 <p>File descriptors are an even better example: An open file on
 file descriptor 5 on task A is <em>not</em> the same open file as
 might be used on file descriptor 5 on task B.</p>
 <p>As a result, internal OS logic may not use application OS
 interfaces that use file descriptors or any other <em>per-task</em>
 resource.</p>
 </li>
 </ol>
 <p>Within NuttX, this is handled by supporting equivalent internal OS
 interfaces that do not break the above rules. These internal
 interfaces are intended for use <em>only</em> within the OS and should
 not be used by application logic. Some examples include:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">nxsem_wait()</span></code>: functionally
 equivalent to the standard application interface
 <code class="docutils literal notranslate"><span class="pre">sem_wait()</span></code>. However, <code class="docutils literal notranslate"><span class="pre">nxsem_wait()</span></code> will not modify the
 errno value and will not cause a cancellation point. (see
 <code class="docutils literal notranslate"><span class="pre">include/nuttx/semaphore.h</span></code> for other internal OS interfaces
 for semaphores).</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">nxsig_waitinfo()</span></code>: functionally
 equivalent to the standard application interface
 <code class="docutils literal notranslate"><span class="pre">sigwaitinfo()</span></code>. However, <code class="docutils literal notranslate"><span class="pre">nxsig_waitinfo()</span></code> will not
 modify the errno value and will not cause a cancellation point
 (see <code class="docutils literal notranslate"><span class="pre">include/nuttx/signal.h</span></code> for other internal OS
 interfaces for signals).</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">nxmq_send()</span></code>: functionally equivalent
 to the standard application interface <code class="docutils literal notranslate"><span class="pre">mq_send()</span></code>. However,
 <code class="docutils literal notranslate"><span class="pre">nxmq_send()</span></code> will not modify the errno value and will not
 cause a cancellation point (see <code class="docutils literal notranslate"><span class="pre">include/nuttx/mqueue.h</span></code> for
 other internal OS interfaces for POSIX message queues).</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">file_read()</span></code>: functionally equivalent
 to the standard application interface <code class="docutils literal notranslate"><span class="pre">read()</span></code>. However,
 <code class="docutils literal notranslate"><span class="pre">file_read()</span></code> will not modify the errno value, will not cause
 a cancellation point, and uses a special internal data
 structure in place of the file descriptor (see
 <code class="docutils literal notranslate"><span class="pre">include/nuttx/fs/fs.h</span></code> for other internal OS interfaces for
 VFS functions).</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">psock_recvfrom()</span></code>: functionally
 equivalent to the standard application interface
 <code class="docutils literal notranslate"><span class="pre">recvfrom()</span></code>. However, <code class="docutils literal notranslate"><span class="pre">psock_recvfrom()</span></code> will not modify
 the errno value, will not cause a cancellation point, and uses
 a special internal data structure in place of the socket
 descriptor (see <code class="docutils literal notranslate"><span class="pre">include/nuttx/net/net.h</span></code> for other internal
 OS interfaces for sockets).</p></li>
 </ul>
 </section>


            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="addrenv.html" class="btn btn-neutral float-left" title="Address Environments" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="arch.html" class="btn btn-neutral float-right" title="APIs Exported by Architecture-Specific Logic to NuttX" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>

   <hr/>

   <div role="contentinfo">
     <p>&#169; Copyright 2023, The Apache Software Foundation.</p>
   </div>


 </footer>
         </div>
       </div>
     </section>
   </div>
   <script>
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
       });
   </script>

 </body>
 </html>
	<!--
	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>Application OS vs. Internal OS 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="APIs Exported by Architecture-Specific Logic to NuttX" href="arch.html" />
	<link rel="prev" title="Address Environments" href="addrenv.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"><a class="reference internal" href="../../implementation/index.html">Implementation Details</a></li>
	<li class="toctree-l1 current"><a class="reference internal" href="../index.html">API Reference</a><ul class="current">
	<li class="toctree-l2"><a class="reference internal" href="../user/index.html">Userspace API</a></li>
	<li class="toctree-l2 current"><a class="reference internal" href="index.html">Architecture APIs</a><ul class="current">
	<li class="toctree-l3"><a class="reference internal" href="addrenv.html">Address Environments</a></li>
	<li class="toctree-l3 current"><a class="current reference internal" href="#">Application OS vs. Internal OS Interfaces</a></li>
	<li class="toctree-l3"><a class="reference internal" href="arch.html">APIs Exported by Architecture-Specific Logic to NuttX</a></li>
	<li class="toctree-l3"><a class="reference internal" href="board.html">APIs Exported by Board-Specific Logic to NuttX</a></li>
	<li class="toctree-l3"><a class="reference internal" href="conventions.html">Naming and Header File Conventions</a></li>
	<li class="toctree-l3"><a class="reference internal" href="iob.html">I/O Buffer Management</a></li>
	<li class="toctree-l3"><a class="reference internal" href="led.html">LED Support</a></li>
	<li class="toctree-l3"><a class="reference internal" href="mutex.html">Mutual Exclusion lock</a></li>
	<li class="toctree-l3"><a class="reference internal" href="nat.html">Network Address Translation (NAT)</a></li>
	<li class="toctree-l3"><a class="reference internal" href="newreno.html">Congestion Control NewReno</a></li>
	<li class="toctree-l3"><a class="reference internal" href="notifier.html">Notifier Chain</a></li>
	<li class="toctree-l3"><a class="reference internal" href="nuttx.html">APIs Exported by NuttX to Architecture-Specific Logic</a></li>
	<li class="toctree-l3"><a class="reference internal" href="paging.html">On-Demand Paging</a></li>
	<li class="toctree-l3"><a class="reference internal" href="shm.html">Shared Memory</a></li>
	<li class="toctree-l3"><a class="reference internal" href="smp.html">Symmetric Multiprocessing (SMP) Application</a></li>
	<li class="toctree-l3"><a class="reference internal" href="time_clock.html">System Time and Clock</a></li>
	<li class="toctree-l3"><a class="reference internal" href="wqueue.html">Work Queues</a></li>
	<li class="toctree-l3"><a class="reference internal" href="netdev.html">Network Devices</a></li>
	</ul>
	</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">Architecture APIs</a></li>
	<li class="breadcrumb-item active">Application OS vs. Internal OS Interfaces</li>
	<li class="wy-breadcrumbs-aside">
	<a href="../../_sources/reference/os/app_vs_os.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="application-os-vs-internal-os-interfaces">
	<h1>Application OS vs. Internal OS Interfaces<a class="headerlink" href="#application-os-vs-internal-os-interfaces" title="Permalink to this heading"></a></h1>
	<p>NuttX provides a standard, portable OS interface for use by
	applications. This standard interface is controlled by the
	specifications proved at <a class="reference external" href="http://opengroup.org">OpenGroup.org</a>.
	These application interfaces, in general, should not be used
	directly by logic executing within the OS. The reason for this is
	that there are certain properties of the standard application
	interfaces that make them unsuitable for use within the OS These
	properties include:</p>
	<ol class="arabic">
	<li><p><strong>Use of the per-thread</strong> <code class="docutils literal notranslate"><span class="pre">errno</span></code> <strong>variable</strong>: Handling of
	return values, particularly, in the case of returned error
	indications. Most legacy POSIX OS interface return information
	via a <em>per-thread</em> <code class="docutils literal notranslate"><span class="pre">errno</span></code>. There must be no alteration of
	the <code class="docutils literal notranslate"><span class="pre">errno</span></code> value that must be stable from the point of view
	of the application. So, as a general rule, internal OS logic
	must never modify the <code class="docutils literal notranslate"><span class="pre">errno</span></code> and particularly not by the
	inappropriate use of application OS interfaces within OS
	itself.</p>
	<p>Within the OS, functions do not return error information via
	the <code class="docutils literal notranslate"><span class="pre">errno</span></code> variable. Instead, the majority of internal OS
	function return error information as an integer value: Returned
	values greater than or equal to zero are success values;
	returned values less than zero indicate failures. Failures are
	reported by returning a negated <code class="docutils literal notranslate"><span class="pre">errno</span></code> value from
	<code class="docutils literal notranslate"><span class="pre">include/errno.h</span></code>,</p>
	</li>
	<li><p><strong>Cancellation Points</strong>: Many of the application OS interfaces
	are <em>cancellation points</em>, i.e., when the task is operating in
	<em>deferred cancellation</em> state, it cannot be deleted or
	cancelled until it calls an application OS interface that is a
	cancellation point.</p>
	<p>The POSIX specification is very specific about this, specific
	both in identifying which application OS interfaces are
	cancellation points and specific in the fact that it is
	prohibited for any OS operation other than those listed in the
	specification to generate cancellation points. If internal OS
	logic were to re-use application OS interfaces directly then it
	could very easily violate this POSIX requirement by incorrectly
	generating cancellation points on inappropriate OS operations
	and could result in very difficult to analyze application
	failures.</p>
	</li>
	<li><p><strong>Use of per-task Resources</strong>: Many resources are only valid in
	the task group context in which a thread operates. Above we
	mentioned one: <code class="docutils literal notranslate"><span class="pre">errno</span></code> is only valid for the thread that is
	currently executing. So, for example, the <code class="docutils literal notranslate"><span class="pre">errno</span></code> at the time
	of a call is a completely different variable than, say, the
	<code class="docutils literal notranslate"><span class="pre">errno</span></code> while running in a work queue task.</p>
	<p>File descriptors are an even better example: An open file on
	file descriptor 5 on task A is <em>not</em> the same open file as
	might be used on file descriptor 5 on task B.</p>
	<p>As a result, internal OS logic may not use application OS
	interfaces that use file descriptors or any other <em>per-task</em>
	resource.</p>
	</li>
	</ol>
	<p>Within NuttX, this is handled by supporting equivalent internal OS
	interfaces that do not break the above rules. These internal
	interfaces are intended for use <em>only</em> within the OS and should
	not be used by application logic. Some examples include:</p>
	<ul class="simple">
	<li><p><code class="docutils literal notranslate"><span class="pre">nxsem_wait()</span></code>: functionally
	equivalent to the standard application interface
	<code class="docutils literal notranslate"><span class="pre">sem_wait()</span></code>. However, <code class="docutils literal notranslate"><span class="pre">nxsem_wait()</span></code> will not modify the
	errno value and will not cause a cancellation point. (see
	<code class="docutils literal notranslate"><span class="pre">include/nuttx/semaphore.h</span></code> for other internal OS interfaces
	for semaphores).</p></li>
	<li><p><code class="docutils literal notranslate"><span class="pre">nxsig_waitinfo()</span></code>: functionally
	equivalent to the standard application interface
	<code class="docutils literal notranslate"><span class="pre">sigwaitinfo()</span></code>. However, <code class="docutils literal notranslate"><span class="pre">nxsig_waitinfo()</span></code> will not
	modify the errno value and will not cause a cancellation point
	(see <code class="docutils literal notranslate"><span class="pre">include/nuttx/signal.h</span></code> for other internal OS
	interfaces for signals).</p></li>
	<li><p><code class="docutils literal notranslate"><span class="pre">nxmq_send()</span></code>: functionally equivalent
	to the standard application interface <code class="docutils literal notranslate"><span class="pre">mq_send()</span></code>. However,
	<code class="docutils literal notranslate"><span class="pre">nxmq_send()</span></code> will not modify the errno value and will not
	cause a cancellation point (see <code class="docutils literal notranslate"><span class="pre">include/nuttx/mqueue.h</span></code> for
	other internal OS interfaces for POSIX message queues).</p></li>
	<li><p><code class="docutils literal notranslate"><span class="pre">file_read()</span></code>: functionally equivalent
	to the standard application interface <code class="docutils literal notranslate"><span class="pre">read()</span></code>. However,
	<code class="docutils literal notranslate"><span class="pre">file_read()</span></code> will not modify the errno value, will not cause
	a cancellation point, and uses a special internal data
	structure in place of the file descriptor (see
	<code class="docutils literal notranslate"><span class="pre">include/nuttx/fs/fs.h</span></code> for other internal OS interfaces for
	VFS functions).</p></li>
	<li><p><code class="docutils literal notranslate"><span class="pre">psock_recvfrom()</span></code>: functionally
	equivalent to the standard application interface
	<code class="docutils literal notranslate"><span class="pre">recvfrom()</span></code>. However, <code class="docutils literal notranslate"><span class="pre">psock_recvfrom()</span></code> will not modify
	the errno value, will not cause a cancellation point, and uses
	a special internal data structure in place of the socket
	descriptor (see <code class="docutils literal notranslate"><span class="pre">include/nuttx/net/net.h</span></code> for other internal
	OS interfaces for sockets).</p></li>
	</ul>
	</section>


	</div>
	</div>
	<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
	<a href="addrenv.html" class="btn btn-neutral float-left" title="Address Environments" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
	<a href="arch.html" class="btn btn-neutral float-right" title="APIs Exported by Architecture-Specific Logic to NuttX" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
	</div>

	<hr/>

	<div role="contentinfo">
	<p>© Copyright 2023, The Apache Software Foundation.</p>
	</div>



	</footer>
	</div>
	</div>
	</section>
	</div>
	<script>
	jQuery(function () {
	SphinxRtdTheme.Navigation.enable(true);
	});
	</script>

	</body>
	</html>