+ NuttShell (NSH)+Last Updated: September 3, 2008 + |
+
+ Table of Contents+ |
+
+ 1.0 Overview+ |
+
+ The examples/nsh sub-directory contains the NuttShell (NSH).
+ NSH is a simple shell application for NuttX.
+
+ 1.1 Console/NSH Front End+ |
+
+ Using settings in the configuration file, NSH may be configured to + use either the serial stdin/out or a telnet connection as the console + or BOTH. When NSH is started, you will see the following welcome on + either console: +
+NuttShell (NSH) +nsh> ++
nsh> is the NSH prompt and indicates that you may enter a command
+ from the console.
+
+
+
+ 1.2 Command Overview+ |
+
+ Simple, Re-directed, and Background Commands. + The NuttShell (NSH) is a simple shell application. + NSH supports the following commands forms: +
+| Simple command: | +<cmd> |
+
| Command with re-directed output: | +
+ <cmd> > <file> |
+
| Background command: | +<cmd> & |
+
| Re-directed background command: | +
+ <cmd> > <file> & |
+
Where:
+<cmd> |
+ + is any one of the simple commands listed later. + | +
<file> |
+ + is the full or relative path to any writable object + in the filesystem name space (file or character driver). + Such objects will be referred to simply as files throughout + this document. + | +
+ nice'd Background Commands
+ NSH executes at the mid-priority (128). Backgrounded commands can
+ be made to execute at higher or lower priorities using nice:
+
+ [nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
+
+ Where <niceness> is any value between -20 and 19 where lower
+ (more negative values) correspond to higher priorities.
+ The default niceness is 10.
+
+ 1.3 Conditional Command Execution+ |
+
+ An if-then[-else]-fi construct is also supported in order to
+ support conditional execution of commands. This works from the
+ command line but is primarily intended for use within NSH scripts
+ (see the sh commnd). The syntax is as follows:
+
+if <cmd> +then + [sequence of <cmd>] +else + [sequence of <cmd>] +fi ++ +
+ 1.4 Built-In Variables+ |
+
$? |
+ + The result of the last simple command execution. + On backgrounded commands, this variable holds only the result of spawning the background command. + | +
+ 1.5 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 directory. The current working
+ directory is set using the 'cd' command and can be queried either
+ by using the pwd command or by
+ using the echo $PWD
+ command.
+
+ 1.6 Environment Variables+ |
+
+ Environment Variables: +
+PWD | The current working directory | +
OLDPWD | The previous working directory | +
+ 2.0 Commands+ |
+
+ 2.1 Evaluate Expression (test)+ |
+
Command Syntax:
++[ <expression> ] +test <expression> ++
+ Synopsis.
+ These are two alternative forms of the same command. They support
+ evaluation of a boolean expression which sets $?.
+ This command is used most frequently as the conditional command following the
+ if in the if-then[-else]-fi construct.
+
Expression Syntax:
++ expression = simple-expression | !expression | expression -o expression | expression -a expression +
++ simple-expression = unary-expression | binary-expression +
++ unary-expression = string-unary | file-unary +
++ string-unary = -n string | -z string +
++ file-unary = -b file | -c file | -d file | -e file | -f file | -r file | -s file | -w file +
++ binary-expression = string-binary | numeric-binary +
++ string-binary = string = string | string == string | string != string +
++ numeric-binary = integer -eq integer | integer -ge integer | integer -gt integer | integer -le integer | + integer -lt integer | integer -ne integer +
+
+ 2.2 Concatenate Files (cat)+ |
+
+cat+<path>[<path>[<path>...]] +
+ Synopsis.
+ This command copies and concatentates all of the files at <path>
+ to the console (or to another file if the output is redirected).
+
+ 2.3 Change Current Working Directory (cd)+ |
+
+cd [<dir-path>|-|~|..] ++
+ Synopsis.
+ Changes the current working directory (PWD). Also sets the
+ previous working directory environment variable (OLDPWD).
+
+
Forms:
+cd <dir-path> |
+ sets the current working directory to <dir-path>. |
+
cd - |
+ sets the current working directory to the previous
+ working directory ($OLDPWD).
+ Equivalent to cd $OLDPWD. |
+
cd or cd ~ |
+ set the current working directory to the 'home'
+ directory. The home directory can be configured by setting
+ CONFIG_LIB_HOMEDIR in the configuration file. The default
+ home directory is /. |
+
cd .. |
+ sets the current working directory to the parent directory. | +
+ 2.4 Copy Files (cp)+ |
+
+cp <source-path> <dest-path> ++
+ Synopsis.
+ Copy of the contents of the file at <source-path< to the location
+ in the filesystem indicated by <path-path>.
+
+ 2.5 Echo Strings and Variables (echo)+ |
+
+echo [<string|$name> [<string|$name>...]] ++
+ Synopsis. + Copy the sequence of strings and expanded environment variables to + console output (or to a file if the output is re-directed). +
+ +
+ 2.6 Execute User Code (exec)+ |
+
Command Syntax:
++exec <hex-address> ++
+ Synopsis.
+ Execute the user logic at address <hex-address>. NSH will pause
+ until the execution unless the user logic is executed in background
+ via exec <hex-address> &.
+
+ 2.7 Exit NSH (exit)+ |
+
+exit ++
+ Synopsis.
+ Exit NSH. Only useful for the serial front end if you have started some other tasks (perhaps
+ using the exec command) and you would like to have NSH out of the
+ way. For the telnet front-end, exit terminates the telenet session.
+
+ 2.8 Show Usage Command Usage (help)+ |
+
+help ++
+ Synopsis. + Presents summary information about each command to console. +
+ +
+ 2.9 Show Network Configuration (ifconfig)+ |
+
+ifconfig ++
+ Synopsis. + Show the current configuration of the network, for example: +
++nsh> ifconfig +eth0 HWaddr 00:18:11:80:10:06 + IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0 ++
+ if uIP statistics are enabled (CONFIG_NET_STATISTICS), then
+ this command will also show the detailed state of uIP.
+
+ 2.10 List Directory Contents (ls)+ |
+
+ls [-lRs] <dir-path> ++
+ Synopsis.
+ Show the contents of the directory at <dir-path>. NOTE:
+ <dir-path> must refer to a directory and no other filesystem
+ object.
+
Options:
+-R |
+ Show the constents of specified directory and all of its + sub-directories. | +
-s |
+ Show the size of the files along with the filenames in the + listing | +
-l |
+ Show size and mode information along with the filenames + in the listing. | +
+ 2.11 Access Memory (mb, mh, and mw)+ |
+
Command Syntax:
++mb <hex-address>[=<hex-value>][ <hex-byte-count>] +mh <hex-address>[=<hex-value>][ <hex-byte-count>] +mw <hex-address>[=<hex-value>][ <hex-byte-count>] ++
+ Synopsis. + Access memory using byte size access (mb), 16-bit accesses (mh), + or 32-bit access (mw). In each case, +
+<hex-address>. |
+ Specifies the address to be accessed. The current + value at that address will always be read and displayed. + |
<hex-address>=<hex-value>. |
+ Read the value, then write <hex-value>
+ to the location.
+ |
<hex-byte-count>. |
+ Perform the mb, mh, or mw operation on a total
+ of <hex-byte-count> bytes, increment the <hex-address> appropriately
+ after each access
+ |
Example:
+
+nsh> mh 0 16 + 0 = 0x0c1e + 2 = 0x0100 + 4 = 0x0c1e + 6 = 0x0110 + 8 = 0x0c1e + a = 0x0120 + c = 0x0c1e + e = 0x0130 + 10 = 0x0c1e + 12 = 0x0140 + 14 = 0x0c1e +nsh> ++ +
+ 2.12 Show Memory Manager Status (mem)+ |
+
+mem ++
+ Synopsis. + Show the current state of the memory allocator. For example, +
++nsh> mem + arena: fe2560 + ordblks: 1 + mxordblk: fdc3e0 + uordblks: 6180 + fordblks: fdc3e0 +nsh> ++
Where:
+arena |
+ This is the total size of memory allocated for use by malloc in bytes. | +
ordblks |
+ This is the number of free (not in use) chunks. | +
mxordblk |
+ Size of the largest free (not in use) chunk. | +
uordblks |
+ This is the total size of memory occupied by chunks handed out by malloc. | +
fordblks |
+ This is the total size of memory occupied by free (not in use) chunks. | +
+ 2.13 Show Current Tasks and Threads (ps)+ |
+
+ps ++
+ Synopsis. + Show the currently active threads and tasks. For example, +
++nsh> ps +PID PRI SCHD TYPE NP STATE NAME + 0 0 FIFO TASK READY Idle Task() + 1 128 RR TASK RUNNING init() + 2 128 FIFO TASK WAITSEM nsh_telnetmain() + 3 100 RR PTHREAD WAITSEM <pthread>(21) +nsh> ++ +
+ 2.14 Create a Directory (mkdir)+ |
+
+ 2.15 Create a FAT Filesystem (mkfatfs)+ |
+
+ 2.16 Create a FIFO (mkfifo)+ |
+
+ 2.17 Mount a File System (mount)+ |
+
+ 2.18 Check Network Peer (ping)+ |
+
+ping [-c <count>] [-i <interval>] <ip-address> ++
+ Synopsis. + Test the network communication with a remote peer. Example, +
++nsh> 10.0.0.1 +PING 10.0.0.1 56 bytes of data +56 bytes from 10.0.0.1: icmp_seq=1 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=2 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=3 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=4 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=5 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=6 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=7 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=8 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=9 time=0 ms +56 bytes from 10.0.0.1: icmp_seq=10 time=0 ms +10 packets transmitted, 10 received, 0% packet loss, time 10190 ms +nsh> ++ +
+ 2.19 Show Current Working Directory (pwd)+ |
+
+pwd ++
+ Synopsis. + Show the current working directory. +
++nsh> cd /dev +nsh> pwd +/dev +nsh> ++ + +
+nsh> echo $PWD +/dev +nsh> ++ +
+ 2.20 Remove a File (rm)+ |
+
+ 2.21 Remove a Directory (rmdir)+ |
+
+ 2.22 Set an Environment Variable (set)+ |
+
+set <name> <value> ++
+ Synopsis.
+ Set the environment variable <name> to the string <value>.
+ For example,
+
+nsh> echo $foobar + +nsh> set foobar foovalue +nsh> echo $foobar +foovalue +nsh> ++ +
+ 2.23 Execute an NSH Script (sh)+ |
+
+sh <script-path> ++
+ Synopsis.
+ Execute the sequence of NSH commands in the file referred
+ to by <script-path>.
+
+ 2.24 Wait for Seconds (sleep)+ |
+
+sleep <sec> ++
+ Synopsis.
+ Pause execution (sleep) for <sec> seconds.
+
+ 2.25 Unmount a File System (umount)+ |
+
+ 2.26 Unset an Environment Variable (unset)+ |
+
+unset <name> ++
+ Synopsis.
+ Remove the value associated with the environment variable
+ <name>. Example:
+
+nsh> echo $foobar +foovalue +nsh> unset foobar +nsh> echo $foobar + +nsh> ++ +
+ 2.27 Wait for Microseconds (usleep)+ |
+
+usleep <usec> ++
+ Synopsis.
+ Pause execution (sleep) of <usec> microseconds.
+
+ 3.0 Configuration Settings+ |
+
+ The availability of the above commands depends upon features that + may or may not be enabled in the NuttX configuration file. The + following table indicates the dependency of each command on NuttX + configuration settings. General configuration settings are discussed + in the NuttX Porting Guide. + Configuration settings specific to NSH as discussed at the bottom of this document. +
+ +
+ 3.1 Command Dependencies on Configuration Settings+ |
+
Table. Command Dependencies on Configuration Settings
+| Command | +Depends on Configuration | +
|---|---|
[ |
+ !CONFIG_EXAMPLES_NSH_DISABLESCRIPT |
+
cat |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+
cd |
+ !CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0 |
+
cp |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+
echo |
+ |
exec |
+ |
exit |
+ |
help |
+ |
ifconfig |
+ CONFIG_NET |
+
ls |
+ CONFIG_NFILE_DESCRIPTORS > 0 |
+
mb,mh,mw |
+ |
mem |
+ |
mkdir |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 |
+
mkfatfs |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT |
+
mkfifo |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 |
+
mount |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT |
+
ping |
+ CONFIG_NET && CONFIG_NET_ICMP && CONFIG_NET_ICMP_PING && !CONFIG_DISABLE_CLOCK && !CONFIG_DISABLE_SIGNALS |
+
ps |
+ |
pwd |
+ !CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0 |
+
rm |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 |
+
rmdir |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 |
+
set |
+ !CONFIG_DISABLE_ENVIRON |
+
sh |
+ CONFIG_NFILE_DESCRIPTORS > 0 && |
+
sleep |
+ !CONFIG_DISABLE_SIGNALS |
+
test |
+ !CONFIG_EXAMPLES_NSH_DISABLESCRIPT |
+
umount |
+ !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT |
+
unset |
+ !CONFIG_DISABLE_ENVIRON |
+
usleep |
+ !CONFIG_DISABLE_SIGNALS |
+
+ 3.2 NSH-Specific Configuration Settings+ |
+
+ The behavior of NSH can be modified with the following settings in
+ the configs/<board-name>/defconfig file:
+
| Configuration | +Description | +
|---|---|
CONFIG_EXAMPLES_NSH_FILEIOSIZE |
+ + Size of a static I/O buffer used for file access (ignored if + there is no filesystem). + | +
CONFIG_EXAMPLES_NSH_STRERROR |
+ + strerror(errno) makes more readable output but strerror() is + very large and will not be used unless this setting is y + | +
CONFIG_EXAMPLES_NSH_LINELEN |
+ + The maximum length of one command line and of one output line. + Default: 80 + | +
CONFIG_EXAMPLES_NSH_STACKSIZE |
+ + The stack size to use when spawning new threads or tasks. Such + new threads are generated when a command is executed in background + or as new TELNET connections are established. + | +
CONFIG_EXAMPLES_NSH_NESTDEPTH |
+
+ The maximum number of nested if-then[-else]-fi sequences that
+ are permissable. Default: 3
+ |
+
CONFIG_EXAMPLES_NSH_DISABLESCRIPT |
+
+ This can be set to y to suppress support for scripting. This
+ setting disables the sh, test, and [ commands and the
+ if-then[-else]-fi construct. This would only be set on systems
+ where a minimal footprint is a necessity and scripting is not.
+ |
+
CONFIG_EXAMPLES_NSH_DISABLEBG |
+
+ This can be set to y to suppress support for background
+ commands. This setting disables the nice command prefix and
+ the & command suffix. This would only be set on systems
+ where a minimal footprint is a necessity and background command execution is not.
+ |
+
CONFIG_EXAMPLES_NSH_CONSOLE |
+
+ If CONFIG_EXAMPLES_NSH_CONSOLEis set to y, then a serial
+ console front-end is selected.
+ |
+
CONFIG_EXAMPLES_NSH_TELNET |
+
+ If CONFIG_EXAMPLES_NSH_TELNET is set to y, then a TELENET
+ server front-end is selected. When this option is provided,
+ you may log into NuttX remotely using telnet in order to
+ access NSH.
+ |
+
+ One or both of CONFIG_EXAMPLES_NSH_CONSOLE and CONFIG_EXAMPLES_NSH_TELNET
+ must be defined. If CONFIG_EXAMPLES_NSH_TELNET is selected, then there some
+ other configuration settings that apply:
+
| Configuration | +Description | +CONFIG_EXAMPLES_NSH_IOBUFFER_SIZE |
+ + Determines the size of the I/O buffer to use for sending/ + receiving TELNET commands/reponses + | + +
|---|---|
CONFIG_EXAMPLES_NSH_DHCPC |
+ + Obtain the the IP address via DHCP. + | +
CONFIG_EXAMPLES_NSH_IPADDR |
+
+ If CONFIG_EXAMPLES_NSH_DHCPC is NOT set, then the static IP
+ address must be provided.
+ |
+
CONFIG_EXAMPLES_NSH_DRIPADDR |
+ + Default router IP address + | +
CONFIG_EXAMPLES_NSH_NETMASK |
+ + Network mask + | +
CONFIG_EXAMPLES_NSH_NOMAC |
+ + Set if your ethernet hardware has no built-in MAC address. + If set, a bogus MAC will be assigned. + | +
| Porting Guide | +|
| NuttShell (NSH) | +|
| Change Log |