Google Git
Sign in
apache / nuttx-website / refs/heads/asf-site / . / content / docs / 12.8.0 / applications / nsh / customizing.html
blob: 22fca80097ac9e4476d48e83866632a2d6ac7506 [file] [log] [blame]
<!--
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.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>The NSH Library and NSH Initialization &mdash; NuttX latest documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../_static/css/theme.css" />
<link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../../_static/custom.css" />
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<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="NSH “Built-In” Applications" href="builtin.html" />
<link rel="prev" title="Configuration Settings" href="config.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>
<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" 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 current"><a class="reference internal" href="../index.html">Applications</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../audioutils/index.html">Audio Utility libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../boot/index.html">Bootloader Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../benchmarks/index.html">Benchmark Applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../canutils/index.html">CAN Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../crypto/index.html">Cryptography Library Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../fsutils/index.html">File System Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../games/index.html">Games</a></li>
<li class="toctree-l2"><a class="reference internal" href="../graphics/index.html">Graphics Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../industry/index.html">Industrial Applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../inertial/index.html">Inertial Libraries Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../interpreters/index.html">Interpreters</a></li>
<li class="toctree-l2"><a class="reference internal" href="../logging/index.html">Logging Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../lte/index.html">LTE Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../math/index.html">Math Library Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mlearing/index.html">Machine Learning Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../netutils/index.html">Network Utilities</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">NuttShell (NSH)</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="nsh.html">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="commands.html">Commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="config.html">Configuration Settings</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">The NSH Library and NSH Initialization</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#nsh-initialization-sequence">NSH Initialization sequence</a></li>
<li class="toctree-l4"><a class="reference internal" href="#nsh-initialize"><code class="docutils literal notranslate"><span class="pre">nsh_initialize()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#nsh-commands">NSH Commands</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#adding-new-nsh-commands">Adding New NSH Commands</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="builtin.html">NSH “Built-In” Applications</a></li>
<li class="toctree-l3"><a class="reference internal" href="installation.html">Customizing NSH Initialization</a></li>
<li class="toctree-l3"><a class="reference internal" href="login.html">Shell Login</a></li>
<li class="toctree-l3"><a class="reference internal" href="running_apps.html">Running Applications from NSH</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../sdr/index.html">Software Define Radio Libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../system/index.html">System Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../testing/index.html">Testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tools/index.html">Host Side Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../wireless/index.html">Wireless Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../examples/index.html">Examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../implementation/index.html">Implementation Details</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../reference/index.html">API Reference</a></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>
<li class="toctree-l1"><a class="reference internal" href="../../logos/index.html">NuttX Logos</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">Applications</a></li>
<li class="breadcrumb-item"><a href="index.html">NuttShell (NSH)</a></li>
<li class="breadcrumb-item active">The NSH Library and NSH Initialization</li>
<li class="wy-breadcrumbs-aside">
<a href="../../_sources/applications/nsh/customizing.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">
<p>========================*
Customizing the NuttShell
========================*</p>
<p><strong>Overview.</strong> The NuttShell (NSH) is a simple shell application that may
be used with NuttX. It supports a variety of commands and is (very)
loosely based on the Bash shell and the common utilities used with Bash
shell programming. The paragraphs in this appendix will focus on
customizing NSH: Adding new commands, changing the initialization
sequence, etc.</p>
<section id="the-nsh-library-and-nsh-initialization">
<h1>The NSH Library and NSH Initialization<a class="headerlink" href="#the-nsh-library-and-nsh-initialization" title="Permalink to this heading"></a></h1>
<p><strong>Overview.</strong> NSH is implemented as a library that can be found at
<code class="docutils literal notranslate"><span class="pre">apps/nshlib</span></code>. As a library, it can be custom built into any
application that follows the NSH initialization sequence described
below. As an example, the code at <code class="docutils literal notranslate"><span class="pre">apps/examples/nsh/nsh_main.c</span></code>
illustrates how to start NSH and the logic there was intended to be
incorporated into your own custom code. Although code was generated
simply as an example, in the end most people just use this example code
as their application <code class="docutils literal notranslate"><span class="pre">main()</span></code> function. That initialization performed
by that example is discussed in the following paragraphs.</p>
<section id="nsh-initialization-sequence">
<h2>NSH Initialization sequence<a class="headerlink" href="#nsh-initialization-sequence" title="Permalink to this heading"></a></h2>
<p>The NSH start-up sequence is very simple. As an example, the code at
<code class="docutils literal notranslate"><span class="pre">apps/system/nsh/nsh_main.c</span></code> illustrates how to start NSH. It simple
does the following:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>This function calls <code class="docutils literal notranslate"><span class="pre">nsh_initialize()</span></code> which initializes the NSH
library. <code class="docutils literal notranslate"><span class="pre">nsh_initialize()</span></code> is described in more detail below.</p></li>
<li><p>If the Telnetconsole is enabled, it calls <code class="docutils literal notranslate"><span class="pre">nsh_telnetstart()</span></code> which
resides in the NSH library. <code class="docutils literal notranslate"><span class="pre">nsh_telnetstart()</span></code> will start the
Telnet daemon that will listen for Telnet connections and start
remote NSH sessions.</p></li>
<li><p>If a local console is enabled (probably on a serial port), then
<code class="docutils literal notranslate"><span class="pre">nsh_consolemain()</span></code> is called. <code class="docutils literal notranslate"><span class="pre">nsh_consolemain()</span></code> also resides
in the NSH library. <code class="docutils literal notranslate"><span class="pre">nsh_consolemain()</span></code> does not return so that
finished the entire NSH initialization sequence.</p></li>
</ol>
</div></blockquote>
</section>
<section id="nsh-initialize">
<h2><code class="docutils literal notranslate"><span class="pre">nsh_initialize()</span></code><a class="headerlink" href="#nsh-initialize" title="Permalink to this heading"></a></h2>
<p>The NSH initialization function, <code class="docutils literal notranslate"><span class="pre">nsh_initialize()</span></code>, be found in
<code class="docutils literal notranslate"><span class="pre">apps/nshlib/nsh_init.c</span></code>. It does only four things:</p>
<blockquote>
<div><ol class="arabic">
<li><p><code class="docutils literal notranslate"><span class="pre">nsh_romfsetc()</span></code>: If so configured, it executes NSH system init and
start-up script that can be found at <code class="docutils literal notranslate"><span class="pre">/etc/init.d/rc.sysinit</span></code> and
<code class="docutils literal notranslate"><span class="pre">/etc/init.d/rcS</span></code> in the target file system. The <code class="docutils literal notranslate"><span class="pre">nsh_romfsetc()</span></code>
function can be found in <code class="docutils literal notranslate"><span class="pre">apps/nshlib/nsh_romfsetc.c</span></code>.
This function will (1) register a ROMFS file system, then (2) mount
the ROMFS file system. <code class="docutils literal notranslate"><span class="pre">/etc</span></code> is the default location where a
read-only, ROMFS file system is mounted by <code class="docutils literal notranslate"><span class="pre">nsh_romfsetc()</span></code>.</p>
<p>The ROMFS image is, itself, just built into the firmware. By default,
this <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code> system init script contains the following logic:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># Create a RAMDISK and mount it at XXXRDMOUNTPOINTXXX
mkrd -m XXXMKRDMINORXXX -s XXMKRDSECTORSIZEXXX XXMKRDBLOCKSXXX
mkfatfs /dev/ramXXXMKRDMINORXXX
mount -t vfat /dev/ramXXXMKRDMINORXXX XXXRDMOUNTPOINTXXX
</pre></div>
</div>
<p>Where the <code class="docutils literal notranslate"><span class="pre">XXXX*XXXX</span></code> strings get replaced in the template when the
ROMFS image is created:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">XXXMKRDMINORXXX</span></code> will become the RAM device minor number.
Default: 0</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">XXMKRDSECTORSIZEXXX</span></code> will become the RAM device sector size</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">XXMKRDBLOCKSXXX</span></code> will become the number of sectors in the
device.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">XXXRDMOUNTPOINTXXX</span></code> will become the configured mount point.
Default: <code class="docutils literal notranslate"><span class="pre">/etc</span></code></p></li>
</ul>
<p>By default, the substituted values would yield an <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code> file like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># Create a RAMDISK and mount it at /tmp
mkrd -m 1 -s 512 1024
mkfatfs /dev/ram1
mount -t vfat /dev/ram1 /tmp
</pre></div>
</div>
<p>This script will, then:</p>
<ul class="simple">
<li><p>Create a RAMDISK of size 512*1024 bytes at <code class="docutils literal notranslate"><span class="pre">/dev/ram1</span></code>,</p></li>
<li><p>Format a FAT file system on the RAM disk at <code class="docutils literal notranslate"><span class="pre">/dev/ram1</span></code>, and
then</p></li>
<li><p>Mount the FAT file system at a configured mountpoint, <code class="docutils literal notranslate"><span class="pre">/tmp</span></code>.</p></li>
</ul>
<p>This <code class="docutils literal notranslate"><span class="pre">rc.sysinit.template</span></code> template file can be found at
<code class="docutils literal notranslate"><span class="pre">apps/nshlib/rc.sysinit.template</span></code>. The resulting ROMFS file system can be
found in <code class="docutils literal notranslate"><span class="pre">apps/nshlib/nsh_romfsimg.h</span></code>.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">board_app_initialize()</span></code>: Next any architecture-specific NSH
initialization will be performed (if any). For the STM3240G-EVAL,
this architecture specific initialization can be found at
<code class="docutils literal notranslate"><span class="pre">boards/arm/stm32/stm3240g-eval/src/stm32_appinit.c</span></code>. This it does
things like: (1) Initialize SPI devices, (2) Initialize SDIO, and (3)
mount any SD cards that may be inserted.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">nsh_netinit()</span></code>: The <code class="docutils literal notranslate"><span class="pre">nsh_netinit()</span></code> function can be found in
<code class="docutils literal notranslate"><span class="pre">apps/nshlib/nsh_netinit.c</span></code>.</p></li>
<li><p>The start-up script <code class="docutils literal notranslate"><span class="pre">rcS</span></code> is executed after the system-init script
to startup some application and other system service.</p>
<p>This <code class="docutils literal notranslate"><span class="pre">rcS</span></code> template file can be found at
<code class="docutils literal notranslate"><span class="pre">apps/nshlib/rcS.template</span></code>. The resulting ROMFS file system can be
found in <code class="docutils literal notranslate"><span class="pre">apps/nshlib/nsh_romfsimg.h</span></code>.</p>
</li>
</ol>
</div></blockquote>
</section>
</section>
<section id="nsh-commands">
<h1>NSH Commands<a class="headerlink" href="#nsh-commands" title="Permalink to this heading"></a></h1>
<p><strong>Overview.</strong> NSH supports a variety of commands as part of the NSH
program. All of the NSH commands are listed in the NSH documentation
<a class="reference external" href="#cmdoverview">above</a>. Not all of these commands may be available at
any time, however. Many commands depend upon certain NuttX configuration
options. You can enter the help command at the NSH prompt to see the
commands actual available:</p>
<p>For example, if network support is disabled, then all network-related
commands will be missing from the list of commands presented by
‘<code class="docutils literal notranslate"><span class="pre">nsh&gt;</span> <span class="pre">help</span></code>’. You can see the specific command dependencies in the
table <a class="reference external" href="#cmddependencies">above</a>.</p>
<section id="adding-new-nsh-commands">
<h2>Adding New NSH Commands<a class="headerlink" href="#adding-new-nsh-commands" title="Permalink to this heading"></a></h2>
<p>New commands can be added to the NSH very easily. You simply need to add
two things:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>The implementation of your command, and</p></li>
<li><p>A new entry in the NSH command table</p></li>
</ol>
</div></blockquote>
<p><strong>Implementation of Your Command.</strong> For example, if you want to add a
new a new command called <code class="docutils literal notranslate"><span class="pre">mycmd</span></code> to NSH, you would first implement the
<code class="docutils literal notranslate"><span class="pre">mycmd</span></code> code in a function with this prototype:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">cmd_mycmd</span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">nsh_vtbl_s</span><span class="w"> </span><span class="o">*</span><span class="n">vtbl</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">**</span><span class="n">argv</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">argc</span></code> and <code class="docutils literal notranslate"><span class="pre">argv</span></code> are used to pass command line arguments to the
NSH command. Command line parameters are passed in a very standard way:
<code class="docutils literal notranslate"><span class="pre">argv[0]</span></code> will be the name of the command, and <code class="docutils literal notranslate"><span class="pre">argv[1]</span></code> through
<code class="docutils literal notranslate"><span class="pre">argv[argc-1]</span></code> are the additional arguments provided on the NSH
command line.</p>
<p>The first parameter, <code class="docutils literal notranslate"><span class="pre">vtbl</span></code>, is special. This is a pointer to
session-specific state information. You don’t need to know the contents
of the state information, but you do need to pass this <code class="docutils literal notranslate"><span class="pre">vtbl</span></code> argument
when you interact with the NSH logic. The only use you will need to make
of the <code class="docutils literal notranslate"><span class="pre">vtbl</span></code> argument will be for outputting data to the console. You
don’t use <code class="docutils literal notranslate"><span class="pre">printf()</span></code> within NSH commands. Instead you would use:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span><span class="w"> </span><span class="nf">nsh_output</span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">nsh_vtbl_s</span><span class="w"> </span><span class="o">*</span><span class="n">vtbl</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">fmt</span><span class="p">,</span><span class="w"> </span><span class="p">...);</span>
</pre></div>
</div>
<p>So if you only wanted to output “Hello, World!” on the console, then
your whole command implementation might be:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">cmd_mycmd</span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">nsh_vtbl_s</span><span class="w"> </span><span class="o">*</span><span class="n">vtbl</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">**</span><span class="n">argv</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n">nsh_output</span><span class="p">(</span><span class="n">vtbl</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Hello, World!&quot;</span><span class="p">);</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The prototype for the new command should be placed in
<code class="docutils literal notranslate"><span class="pre">apps/examples/nshlib/nsh.h</span></code>.</p>
<p><strong>Adding You Command to the NSH Command Table</strong>. All of the commands
support by NSH appear in a single table called:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">const</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">cmdmap_s</span><span class="w"> </span><span class="n">g_cmdmap</span><span class="p">[]</span>
</pre></div>
</div>
<p>That table can be found in the file
<code class="docutils literal notranslate"><span class="pre">apps/examples/nshlib/nsh_parse.c</span></code>. The structure <code class="docutils literal notranslate"><span class="pre">cmdmap_s</span></code> is also
defined in <code class="docutils literal notranslate"><span class="pre">apps/nshlib/nsh_parse.c</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">cmdmap_s</span>
<span class="p">{</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">cmd</span><span class="p">;</span><span class="w"> </span><span class="cm">/* Name of the command */</span>
<span class="w"> </span><span class="n">cmd_t</span><span class="w"> </span><span class="n">handler</span><span class="p">;</span><span class="w"> </span><span class="cm">/* Function that handles the command */</span>
<span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">minargs</span><span class="p">;</span><span class="w"> </span><span class="cm">/* Minimum number of arguments (including command) */</span>
<span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="n">maxargs</span><span class="p">;</span><span class="w"> </span><span class="cm">/* Maximum number of arguments (including command) */</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">usage</span><span class="p">;</span><span class="w"> </span><span class="cm">/* Usage instructions for &#39;help&#39; command */</span>
<span class="p">};</span>
</pre></div>
</div>
<p>This structure provides everything that you need to describe your
command: Its name (<code class="docutils literal notranslate"><span class="pre">cmd</span></code>), the function that handles the command
(<code class="docutils literal notranslate"><span class="pre">cmd_mycmd()</span></code>), the minimum and maximum number of arguments needed by
the command, and a string describing the command line arguments. That
last string is what is printed when enter “<code class="docutils literal notranslate"><span class="pre">nsh&gt;</span> <span class="pre">help</span></code>”.</p>
<p>So, for you sample command, you would add the following the to the
<code class="docutils literal notranslate"><span class="pre">g_cmdmap[]</span></code> table:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="w"> </span><span class="s">&quot;mycmd&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">cmd_mycmd</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="w"> </span><span class="p">},</span>
</pre></div>
</div>
<p>This entry is particularly simply because <code class="docutils literal notranslate"><span class="pre">mycmd</span></code> is so simple. Look
at the other commands in <code class="docutils literal notranslate"><span class="pre">g_cmdmap[]</span></code> for more complex examples.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="config.html" class="btn btn-neutral float-left" title="Configuration Settings" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="builtin.html" class="btn btn-neutral float-right" title="NSH “Built-In” Applications" 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>