From 041308f95077ddfb184e9d7c285d943841788fa4 Mon Sep 17 00:00:00 2001 From: raiden00pl Date: Mon, 30 Oct 2023 09:31:00 +0100 Subject: [PATCH] Documentation: review applications/nsh --- Documentation/applications/nsh/builtin.rst | 8 +- Documentation/applications/nsh/commands.rst | 156 +++++++++--------- Documentation/applications/nsh/config.rst | 13 ++ .../applications/nsh/customizing.rst | 14 +- Documentation/applications/nsh/index.rst | 9 +- .../applications/nsh/installation.rst | 6 +- Documentation/applications/nsh/login.rst | 12 +- Documentation/applications/nsh/nsh.rst | 21 +-- 8 files changed, 129 insertions(+), 110 deletions(-) diff --git a/Documentation/applications/nsh/builtin.rst b/Documentation/applications/nsh/builtin.rst index 5b35e24ed8..6c64425b33 100644 --- a/Documentation/applications/nsh/builtin.rst +++ b/Documentation/applications/nsh/builtin.rst @@ -1,6 +1,6 @@ -*************************** +=========================== NSH "Built-In" Applications -*************************** +=========================== **Overview.** In addition to these commands that are a part of NSH, external programs can also be executed as NSH commands. These external @@ -27,7 +27,7 @@ Note that no detailed help information beyond the name of the built-in application is provided. Built-In Applications -~~~~~~~~~~~~~~~~~~~~~ +===================== **Overview.** The underlying logic that supports the NSH built-in applications is called "Built-In Applications". The builtin application @@ -185,7 +185,7 @@ be mentioned. functionality. Synchronous Built-In Applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================= By default, built-in commands started from the NSH command line will run asynchronously with NSH. If you want to force NSH to execute commands diff --git a/Documentation/applications/nsh/commands.rst b/Documentation/applications/nsh/commands.rst index 3a179c1c51..674ab22868 100644 --- a/Documentation/applications/nsh/commands.rst +++ b/Documentation/applications/nsh/commands.rst @@ -5,7 +5,7 @@ Commands .. _cmdtest: ``test`` Evaluate Expression -***************************** +============================= **Command Syntax:** @@ -43,7 +43,7 @@ the conditional command following the ``if`` in the .. _cmdaddroute: ``addroute`` Add a Routing Table Entry -************************************** +====================================== **Command Syntax:** @@ -78,7 +78,7 @@ default gateway. .. _cmdarp: ``arp`` Access the ARP table -**************************** +============================ **Command syntax**:: @@ -111,7 +111,7 @@ default gateway. .. _cmdbase64dec: ``base64dec`` Base64 Decode -*************************** +=========================== **Command Syntax**:: @@ -122,7 +122,7 @@ default gateway. .. _cmdbase64enc: ``base64enc`` Base64 Encode -*************************** +=========================== **Command Syntax**:: @@ -133,7 +133,7 @@ default gateway. .. _cmdbasename: ``basename`` Extract Base File/Directory Name -********************************************* +============================================= **Command Syntax**:: @@ -146,7 +146,7 @@ trailing ````. .. _cmdbreak: ``break`` Terminate a Loop -************************** +========================== **Command Syntax**:: @@ -163,7 +163,7 @@ immediately following the ``done`` token. .. _cmdcat: ``cat`` Concatenate Files -************************* +========================= **Command Syntax**:: @@ -176,7 +176,7 @@ output is redirected). .. _cmdcd: ``cd`` Change Current Working Directory -*************************************** +======================================= **Command Syntax**:: @@ -201,7 +201,7 @@ Also sets the previous working directory environment variable .. _cmdcmp: ``cmp`` Compare Files -********************* +===================== **Command Syntax**:: @@ -214,7 +214,7 @@ indication only if the files differ. .. _cmdcp: ``cp`` Copy Files -***************** +================= **Command Syntax**:: @@ -227,7 +227,7 @@ indication only if the files differ. .. _cmddate: ``date`` Show or set the date and time -************************************** +====================================== **Command Syntax**:: @@ -264,7 +264,7 @@ To change the system clock manually, type ``date -s MMM DD HH:MM:SS YYYY``. .. _cmddd: ``dd`` Copy and Convert Files -***************************** +============================= **Command Syntax**:: @@ -307,7 +307,7 @@ bucket:: .. _cmddelroute: ``delroute`` Delete a Routing Table Entry -***************************************** +========================================= **Command Syntax**:: @@ -331,7 +331,7 @@ which is equivalent to:: .. _cmddf: ``df`` Show Volume Status -************************* +========================= **Command Syntax**:: @@ -358,7 +358,7 @@ readable* format. .. _cmddirname: ``dirname`` Extract Path to a File/Directory -******************************************** +============================================ **Command Syntax**:: @@ -370,7 +370,7 @@ readable* format. .. _cmddmesg: ``dmesg`` Dump Buffered SYSLOG Output -************************************* +===================================== **Command Syntax**:: @@ -388,7 +388,7 @@ that entering ``dmesg`` again will show only newly buffered data. .. _cmdecho: ``echo`` Echo Strings and Variables -*********************************** +=================================== **Command Syntax**:: @@ -403,7 +403,7 @@ The ``-n`` option suppresses the trailing newline character. .. _cmdenv: ``env`` Show Environment Variables -********************************** +================================== **Command Syntax**:: @@ -432,7 +432,7 @@ environment. Example:: .. _cmdexec: ``exec`` Execute User Code -************************** +========================== **Command Syntax**:: @@ -445,7 +445,7 @@ executed in background via ``exec &``. .. _cmdexit: ``exit`` Exit NSH -***************** +================= **Command Syntax**:: @@ -459,7 +459,7 @@ telnet front-end, ``exit`` terminates the telnet session. .. _cmdexport: ``export`` Set an Environment Variable -************************************** +====================================== **Command Syntax**:: @@ -506,7 +506,7 @@ The ``export`` command is not supported by NSH unless both .. _cmdfree: ``free`` Show Memory Manager Status -*********************************** +=================================== **Command Syntax**:: @@ -535,7 +535,7 @@ nfree This is the number of free chunks .. _cmdget: ``get`` Get File Via TFTP -************************* +========================= **Command Syntax**:: @@ -555,7 +555,7 @@ whose IP address is identified by ````. .. _cmdhelp: ``help`` Show Usage Command Usage -********************************* +================================= **Command Syntax**:: @@ -574,7 +574,7 @@ console. .. _cmdhexdump: ``hexdump`` Hexadecimal Dump of File or Device -********************************************** +============================================== **Command Syntax**:: @@ -595,7 +595,7 @@ configuration. .. _cmdifconfig: ``ifconfig`` Manage Network Configuration -***************************************** +========================================= **Command Syntax**:: @@ -637,7 +637,7 @@ supported: .. _cmdifdown: ``ifdown`` Take a network down -****************************** +============================== **Command Syntax**:: @@ -653,7 +653,7 @@ supported: .. _cmdifup: ``ifup`` Bring a network up -*************************** +=========================== **Command Syntax**:: @@ -669,7 +669,7 @@ supported: .. _cmdinsmod: ``insmod`` Install an OS module -******************************* +=============================== **Command Syntax**:: @@ -707,7 +707,7 @@ module . .. _cmdirqinfo: ``irqinfo`` Show Interrupt Status -********************************* +================================= **Command Syntax**:: @@ -727,7 +727,7 @@ attached interrupts. .. _cmdcritmon: ``critmon`` Show Critical Monitor Status -**************************************** +======================================== **Command Syntax**:: @@ -762,7 +762,7 @@ The output of the ``critmon`` command displays the following columns: .. _cmdkill: ``kill`` Send a signal to a task -******************************** +================================ **Command Syntax**:: @@ -806,7 +806,7 @@ The output of the ``critmon`` command displays the following columns: .. _cmdlosetup: ``losetup`` Setup/teardown the Loop Device -****************************************** +========================================== **Command Syntax 1**:: @@ -851,7 +851,7 @@ on the loop-mounted file:: .. _cmdln: ``ln`` Link to a File or Directory -********************************** +================================== **Command Syntax**:: @@ -872,7 +872,7 @@ implementation is simplified for use with NuttX in these ways: .. _cmdls: ``ls`` List Directory Contents -****************************** +============================== **Command Syntax**:: @@ -893,7 +893,7 @@ no other file system object. .. _cmdlsmod: ``lsmod`` Show information about installed OS modules -***************************************************** +===================================================== **Command Syntax**:: @@ -926,7 +926,7 @@ modules. This information includes: .. _cmdmd5: ``md5`` Calculate MD5 -********************* +===================== **Command Syntax**:: @@ -937,7 +937,7 @@ modules. This information includes: .. _cmdmx: ``mb``, ``mh``, ``and`` ``mw`` Access Memory -******************************************** +============================================ **Command Syntax**:: @@ -976,7 +976,7 @@ accesses (mh), or 32-bit access (mw). In each case, .. _cmdps: ``ps`` Show Current Tasks and Threads -************************************* +===================================== **Command Syntax**:: @@ -1002,7 +1002,7 @@ have been mounted with a command like:: .. _cmdmkdir: ``mkdir`` Create a Directory -**************************** +============================ **Command Syntax**:: @@ -1031,7 +1031,7 @@ directories in the *pseudo* file system. .. _cmdmkfatfs: ``mkfatfs`` Create a FAT File System -************************************ +==================================== **Command Syntax** @@ -1062,7 +1062,7 @@ and must have been created by some call to ``register_blockdriver()`` .. _cmdmkfifo: ``mkfifo`` Create a FIFO -************************ +======================== **Command Syntax**:: @@ -1096,7 +1096,7 @@ driver. NSH provides this command to access the .. _cmdmkrd: ``mkrd`` Create a RAMDISK -************************* +========================= **Command Syntax**:: @@ -1141,7 +1141,7 @@ Once the ramdisk has been created, it may be formatted using the .. _cmdmount: ``mount`` Mount a File System -***************************** +============================= **Command Syntax**:: @@ -1215,7 +1215,7 @@ Using ``mount`` to enumerate mounts:: .. _cmdmv: ``mv`` Rename a File -******************** +==================== **Command Syntax**:: @@ -1228,7 +1228,7 @@ system. .. _cmdnfsmount: ``nfsmount`` Mount an NFS file system -************************************* +===================================== **Command Syntax**:: @@ -1241,7 +1241,7 @@ address of the remote server. .. _cmdnslookup: ``nslookup`` Lookup a network address -************************************* +===================================== **Command Syntax**:: @@ -1253,7 +1253,7 @@ address of the remote server. .. _cmdpasswd: ``passwd`` Change a User's Password -*********************************** +=================================== **Command Syntax**:: @@ -1265,7 +1265,7 @@ address of the remote server. .. _cmdpmconfig: ``pmconfig`` Manage Power Management Subsystem -********************************************** +============================================== **Command Syntax**:: @@ -1276,7 +1276,7 @@ address of the remote server. .. _cmdpoweroff: ``poweroff`` Shut the system down -********************************* +================================= **Command Syntax**:: @@ -1293,7 +1293,7 @@ is redundant. .. _cmdput: ``put`` Send File Via TFTP -************************** +========================== **Command Syntax**:: @@ -1314,7 +1314,7 @@ whose IP address is identified by ````. .. _cmdpwd: ``pwd`` Show Current Working Directory -************************************** +====================================== **Command Syntax**:: @@ -1336,7 +1336,7 @@ Same as ``echo $PWD``:: .. _cmdreadlink: ``readlink`` Show target of a link -********************************** +================================== **Command Syntax**:: @@ -1348,7 +1348,7 @@ Same as ``echo $PWD``:: .. _cmdreboot: ``reboot`` Reboot the system -**************************** +============================ **Command Syntax**:: @@ -1365,7 +1365,7 @@ redundant. .. _cmdrm: ``rm`` Remove a File -******************** +==================== **Command Syntax**:: @@ -1394,7 +1394,7 @@ names in the *pseudo* file system. .. _cmdrmdir: ``rmdir`` Remove a Directory -**************************** +============================ **Command Syntax**:: @@ -1424,7 +1424,7 @@ file system. .. _cmdrmmod: ``rmmod`` Remove on OS Module -***************************** +============================= **Command Syntax**:: @@ -1447,7 +1447,7 @@ busy. .. _cmdroute: ``route`` Show routing table -**************************** +============================ **Command Syntax**:: @@ -1462,7 +1462,7 @@ version. .. _cmdrptun: ``rptun`` Start/Stop the OpenAMP RPC Tunnel -******************************************* +=========================================== **Command Syntax**:: @@ -1473,7 +1473,7 @@ version. .. _cmdset: ``set`` Set a Variable -********************** +====================== **Command Syntax**:: @@ -1551,7 +1551,7 @@ script commands and set foobar to foovalue:: .. _cmdsh: ``sh`` Execute an NSH Script -**************************** +============================ **Command Syntax**:: @@ -1563,7 +1563,7 @@ to by ````. .. _cmdshutdown: ``shutdown`` Shut the system down -********************************* +================================= **Command Syntax**:: @@ -1580,7 +1580,7 @@ NOTE: The ``shutdown`` command duplicates the behavior of the .. _cmdsleep: ``sleep`` Wait for Seconds -************************** +========================== **Command Syntax**:: @@ -1591,7 +1591,7 @@ NOTE: The ``shutdown`` command duplicates the behavior of the .. _cmdtelnetd: ``telnetd`` Time Start the Telnet Daemon -**************************************** +======================================== **Command Syntax**:: @@ -1616,7 +1616,7 @@ network is initialized, it will fail. .. _cmdtime: ``time`` Time execution of another command -****************************************** +========================================== **Command Syntax**:: @@ -1672,7 +1672,7 @@ command is run in background with the sleep command:: .. _cmdtruncate: ``truncate`` Set the Size of a File -*********************************** +=================================== **Command Syntax**:: @@ -1691,7 +1691,7 @@ reads as zero bytes. .. _cmdumount: ``umount`` Unmount a File System -******************************** +================================ **Command Syntax**:: @@ -1715,7 +1715,7 @@ mounted using :ref:`mount ` command. .. _cmduname: ``uname`` Print system information -********************************** +================================== **Command Syntax**:: @@ -1739,7 +1739,7 @@ output is the same as -s. .. _cmdunset: ``unset`` Unset an Environment Variable -*************************************** +======================================= **Command Syntax**: @@ -1759,7 +1759,7 @@ and the group-wide environment variables. For example:: .. _cmdurldecode: ``urldecode`` URL Decode -************************ +======================== **Command Syntax**:: @@ -1770,7 +1770,7 @@ and the group-wide environment variables. For example:: .. _cmdurlencode: ``urlencode`` URL Encode -************************ +======================== **Command Syntax**:: @@ -1781,7 +1781,7 @@ and the group-wide environment variables. For example:: .. _cmduseradd: ``useradd`` Add a New User -************************** +========================== **Command Syntax**:: @@ -1792,7 +1792,7 @@ and the group-wide environment variables. For example:: .. _cmduserdel: ``userdel`` Delete a user -************************* +========================= **Command Syntax**:: @@ -1803,7 +1803,7 @@ and the group-wide environment variables. For example:: .. _cmdusleep: ``usleep`` Wait for Microseconds -******************************** +================================ **Command Syntax**:: @@ -1814,7 +1814,7 @@ and the group-wide environment variables. For example:: .. _cmdwget: ``wget`` Get File Via HTTP -************************** +========================== **Command Syntax** @@ -1834,7 +1834,7 @@ directory. .. _cmdxd: ``xd`` Hexadecimal Dump of Memory -********************************* +================================= **Command Syntax**:: @@ -1872,7 +1872,7 @@ common, useful built-in applications are listed below. .. _cmdping: ``ping`` and ``ping6`` Check Network Peer -***************************************** +========================================= **Command Syntax**:: diff --git a/Documentation/applications/nsh/config.rst b/Documentation/applications/nsh/config.rst index 5470f3adaf..b4dfa9cda9 100644 --- a/Documentation/applications/nsh/config.rst +++ b/Documentation/applications/nsh/config.rst @@ -488,3 +488,16 @@ Configuration Description ``CONFIG_NSH_FATSECTSIZE`` This is the sector size use with the FAT FS. Default is 512. ============================== ======================================================= + +Common Problems +=============== + +Problem:: + + The function 'readline' is undefined. + +Usual Cause: + +* The following is missing from your `defconfig` file:: + + CONFIG_SYSTEM_READLINE=y diff --git a/Documentation/applications/nsh/customizing.rst b/Documentation/applications/nsh/customizing.rst index 384b66a15e..2d120373a9 100644 --- a/Documentation/applications/nsh/customizing.rst +++ b/Documentation/applications/nsh/customizing.rst @@ -1,6 +1,6 @@ -************************* +========================* Customizing the NuttShell -************************* +========================* **Overview.** The NuttShell (NSH) is a simple shell application that may be used with NuttX. It supports a variety of commands and is (very) @@ -10,7 +10,7 @@ customizing NSH: Adding new commands, changing the initialization sequence, etc. The NSH Library and NSH Initialization -************************************** +====================================== **Overview.** NSH is implemented as a library that can be found at ``apps/nshlib``. As a library, it can be custom built into any @@ -23,7 +23,7 @@ as their application ``main()`` function. That initialization performed by that example is discussed in the following paragraphs. NSH Initialization sequence -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- The NSH start-up sequence is very simple. As an example, the code at ``apps/system/nsh/nsh_main.c`` illustrates how to start NSH. It simple @@ -43,7 +43,7 @@ does the following: finished the entire NSH initialization sequence. ``nsh_initialize()`` -~~~~~~~~~~~~~~~~~~~~ +-------------------- The NSH initialization function, ``nsh_initialize()``, be found in ``apps/nshlib/nsh_init.c``. It does only four things: @@ -118,7 +118,7 @@ The NSH initialization function, ``nsh_initialize()``, be found in found in ``apps/nshlib/nsh_romfsimg.h``. NSH Commands -************ +============ **Overview.** NSH supports a variety of commands as part of the NSH program. All of the NSH commands are listed in the NSH documentation @@ -133,7 +133,7 @@ commands will be missing from the list of commands presented by table `above <#cmddependencies>`__. Adding New NSH Commands -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- New commands can be added to the NSH very easily. You simply need to add two things: diff --git a/Documentation/applications/nsh/index.rst b/Documentation/applications/nsh/index.rst index a6650d37f2..8f62f5cca4 100644 --- a/Documentation/applications/nsh/index.rst +++ b/Documentation/applications/nsh/index.rst @@ -2,9 +2,14 @@ NuttShell (NSH) =============== -The NuttShell is a very complete shell system to be used in NuttX, similar to bash and other similar options. It supports a rich set of included commands, scripting and the ability to run your own applications as "builtin" (part of the same NuttX binary). NSH is implemented as an application where most of the functionality is part of the library called `nshlib`. +The NuttShell is a very complete shell system to be used in NuttX, similar to +bash and other similar options. It supports a rich set of included commands, +scripting and the ability to run your own applications as "builtin" (part of the +same NuttX binary). NSH is implemented as an application where most of the +functionality is part of the library called `nshlib`. -As such, NSH is completely optional and can be disabled so that NuttX directly starts a given task instead of the main ``nsh`` application. +As such, NSH is completely optional and can be disabled so that NuttX directly +starts a given task instead of the main ``nsh`` application. .. toctree:: :maxdepth: 2 diff --git a/Documentation/applications/nsh/installation.rst b/Documentation/applications/nsh/installation.rst index 29e03a272e..4633460fb8 100644 --- a/Documentation/applications/nsh/installation.rst +++ b/Documentation/applications/nsh/installation.rst @@ -1,6 +1,6 @@ -****************************** +============================== Customizing NSH Initialization -****************************** +============================== **Ways to Customize NSH Initialization**. There are three ways to customize the NSH start-up behavior. Here they are presented in order of @@ -28,7 +28,7 @@ increasing difficulty: deserves its own paragraph NuttShell Start up Scripts -~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- First of all you should look at `NSH Start-Up Script <#startupscript>`__ paragraph. Most everything you need to know can be found there. That diff --git a/Documentation/applications/nsh/login.rst b/Documentation/applications/nsh/login.rst index 9a92d96ff3..e200fe71d5 100644 --- a/Documentation/applications/nsh/login.rst +++ b/Documentation/applications/nsh/login.rst @@ -1,9 +1,9 @@ -*********** +=========== Shell Login -*********** +=========== Enabling Shell Logins -********************* +===================== NuttShell sessions can be protected by requiring that the user supply username and password credentials at the beginning of the session. @@ -39,7 +39,7 @@ will be closed. That number is controlled by:: CONFIG_NSH_LOGIN_FAILCOUNT=3 Verification of Credentials -*************************** +=========================== There are three ways that NSH can be configured to verify user credentials at login time: @@ -89,7 +89,7 @@ credentials at login time: CONFIG_NSH_LOGIN_PASSWD=y Password Files -************** +============== NuttX can also be configured to support a password file, by default at ``/etc/passwd``. This option enables support for a password file:: @@ -150,7 +150,7 @@ Instead, the password file will be consulted to verify the user credentials. Creating a Password File for a ROMFS File System -************************************************ +================================================ What we want to accomplish is a ROMFS file system, mounted at ``/etc`` and containing the password file, ``passwd`` like:: diff --git a/Documentation/applications/nsh/nsh.rst b/Documentation/applications/nsh/nsh.rst index 81b8a02c91..d69aefb47a 100644 --- a/Documentation/applications/nsh/nsh.rst +++ b/Documentation/applications/nsh/nsh.rst @@ -1,9 +1,9 @@ .. include:: /substitutions.rst .. _nsh: -******** +======== Overview -******** +======== **The NSH Library**. The ``apps/nshlib`` sub-directory contains the NuttShell (NSH) library. This library can easily to linked to @@ -12,7 +12,7 @@ produce a NSH application (See as an example application for NuttX. Console/NSH Front End -********************* +===================== **NSH Consoles**. Using settings in the configuration file, NSH may be configured to use (1) the serial stdin/out, (2) a USB serial @@ -83,7 +83,7 @@ Key Binding Editor Action ===================== ================================================ Command Overview -**************** +================ **Simple, Re-directed, and Background Commands**. The NuttShell (NSH) is a simple shell application. NSH supports the following @@ -159,7 +159,7 @@ significant resources, they are disabled by default. also selected. Conditional Command Execution -***************************** +============================= An ``if-then[-else]-fi`` construct is also supported in order to support conditional execution of commands. This works from the @@ -191,7 +191,7 @@ Examples: 1 is not equal 0 Looping -******* +======= **Looping Constructs**. ``while-do-done`` and ``until-do-done`` looping constructs are also supported. These work from the command @@ -233,7 +233,7 @@ the loop will immediately terminate and execution will continue with the next command immediately following the ``done`` token. Built-In Variables -****************** +================== ====== ==================================================== ``$?`` The result of the last simple command execution. |br| @@ -242,7 +242,7 @@ Built-In Variables ====== ==================================================== Current Working Directory -************************* +========================= ``cd`` **and** ``pwd``. All path arguments to commands may be either an absolute path or a path relative to the current working @@ -251,7 +251,7 @@ directory. The current working directory is set using the ``pwd`` command or by using the ``echo $PWD`` command. Environment Variables -********************* +===================== ========== ================================================ ``PATH`` The default path in the file systems to look |br| @@ -260,8 +260,9 @@ Environment Variables ``OLDPWD`` The previous working directory ========== ================================================ + NSH Start-Up Script -******************* +=================== **NSH Start-Up Script**. NSH supports options to provide a start up script for NSH. In general this capability is enabled with