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. |