NuttShell (NSH)Last Updated: September 5, 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 Get File Via TFTP (get) |
get [-b|-n] [-f <local-path>] -h <ip-address> <remote-path>
Synopsis.
Copy the file at <remote-address> from the host whose IP address is
identified by <ip-address>.
Other options:
-f <local-path> |
The file will be saved relative to the current working directory
unless <local-path> is provided.
|
-b|-n |
Selects either binary ("octect") or test ("netascii") transfer mode. Default: text. |
2.8 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.9 Show Usage Command Usage (help) |
help
Synopsis. Presents summary information about each command to console.
2.10 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.11 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.12 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.13 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.14 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.15 Create a Directory (mkdir) |
Command Syntax:
mkdir <path>
Synopsis.
Create the directory at <path>.
All components of of <path> except the final directory name must exist on a mounted file
system; the final directory must not.
Limited to Mounted File Systems.
Recall that NuttX uses a pseudo filesystem for its root file
system.
The mkdir command can only be used to create directories in volumes set up with the
mount command; it cannot be used to create directories in the pseudo filesystem.
Example:
nsh> mkdir /mnt/fs/tmp nsh> ls -l /mnt/fs /mnt/fs: drw-rw-rw- 0 TESTDIR/ drw-rw-rw- 0 TMP/ nsh>
2.16 Create a FAT Filesystem (mkfatfs) |
Command Syntax:
mkfatfs <path>
Synopsis.
Format a fat file system on the block device specified by <path>.
NSH provides this command to access the mkfatfs() NuttX API.
This block device must reside in the NuttX pseudo filesystem and
must have been created by some call to register_blockdriver() (see include/nuttx/fs.h).
2.17 Create a FIFO (mkfifo) |
Command Syntax:
mkfifo <path>
Synopsis.
Creates a FIFO character device anywhere in the pseudo file system, creating
whatever psuedo directories that may be needed to complete the <path>.
By convention, however, device drivers are place in the standard /dev directory.
After it is created, the FIFO device may be used as any other device driver.
NSH provides this command to access the mkfifo() NuttX API.
Example
nsh> ls -l /dev /dev: crw-rw-rw- 0 console crw-rw-rw- 0 null brw-rw-rw- 0 ram0 nsh> mkfifo /dev/fifo nsh> ls -l /dev ls -l /dev /dev: crw-rw-rw- 0 console crw-rw-rw- 0 fifo crw-rw-rw- 0 null brw-rw-rw- 0 ram0 nsh>
2.18 Create a RAMDISK (mkrd) |
Command Syntax:
mkrd [-m <minor>] [-s <sector-size>] <nsectors>
Synopsis.
Create a ramdisk consisting of <nsectors>, each of size
<sector-size> (or 512 bytes if <sector-size> is not specified.
The ramdisk will be registered as /dev/ram<n> (if <n> is not
specified, mkrd will attempt to register the ramdisk as /dev/ram0.
Example
nsh> ls /dev /dev: console null ttyS0 ttyS1 nsh> mkrd 1024 nsh> ls /dev /dev: console null ram0 ttyS0 ttyS1 nsh>
Once the ramdisk has been created, it may be formatted using
the mkfatfs command and mounted using the mount command.
Example
nsh> mkrd 1024 nsh> mkfatfs /dev/ram0 nsh> mount -t vfat /dev/ram0 /tmp nsh> ls /tmp /tmp: nsh>
2.19 Mount a File System (mount) |
Command Syntax:
mount -t <fstype> <block-device> <dir-path>
Synopsis. The 'm ount' command mounts a file system in the NuttX psuedo filesystem. 'mount' performs a three way associating, binding:
<fstype>' option identifies the type of
file system that has been formatted on the <block-device>.
As of this writing, vfat is the only supported value for <fstype>
<block-device> argument is the full or relative
path to a block driver inode in the pseudo filesystem.
By convention, this is a name under the /dev sub-directory.
This <block-device> must have been previously formatted with the same file system
type as specified by <fstype>
<dir-path>, is the location in the
pseudo filesystem where the mounted volume will appear.
This mount point can only reside in the NuttX pseudo filesystem.
By convention, this mount point is a subdirectory under /mnt.
The mount command will create whatever psuedo directories that may be needed to complete the
full path but the full path must not already exist.
After the the volume has been mounted in the NuttX pseudo filesystem, it may be access in the same way as other objects in thefile system.
Example
nsh> ls -l /dev /dev: crw-rw-rw- 0 console crw-rw-rw- 0 null brw-rw-rw- 0 ram0 nsh> ls /mnt nsh: ls: no such directory: /mnt nsh> mount -t vfat /dev/ram0 /mnt/fs nsh> ls -l /mnt/fs/testdir /mnt/fs/testdir: -rw-rw-rw- 15 TESTFILE.TXT nsh> echo "This is a test" >/mnt/fs/testdir/example.txt nsh> ls -l /mnt/fs/testdir /mnt/fs/testdir: -rw-rw-rw- 15 TESTFILE.TXT -rw-rw-rw- 16 EXAMPLE.TXT nsh> cat /mnt/fs/testdir/example.txt This is a test nsh>
2.20 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.21 Send File Via TFTP (put) |
put [-b|-n] [-f <remote-path>] -h <ip-address> <local-path>
Synopsis.
Copy the file at <local-address> to the host whose IP address is
identified by <ip-address>.
Other options:
-f <remote-path> |
The file will be saved relative with the same name on the host
unless <remote-path> is provided.
|
-b|-n |
Selects either binary ("octect") or test ("netascii") transfer mode. Default: text. |
2.22 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.23 Remove a File (rm) |
rm <file-path>
Synopsis.
Remove the specified <file-path> name from the mounted file system.
Recall that NuttX uses a pseudo filesystem for its root file
system.
The rm command can only be used to remove (unlink) files in volumes set up with the
mount command;
it cannot be used to remove names in the pseudo filesystem.
Example:
nsh> ls /mnt/fs/testdir /mnt/fs/testdir: TESTFILE.TXT EXAMPLE.TXT nsh> rm /mnt/fs/testdir/example.txt nsh> ls /mnt/fs/testdir /mnt/fs/testdir: TESTFILE.TXT nsh>
2.24 Remove a Directory (rmdir) |
rmdir <dir-path>
Synopsis.
Remove the specified <dir-path> directory from the mounted file system.
Recall that NuttX uses a pseudo filesystem for its root file
system.
The rmdir command can only be used to remove directories from volumes set up with the
mount command;
it cannot be used to remove directories from the pseudo filesystem.
Example:
nsh> mkdir /mnt/fs/tmp nsh> ls -l /mnt/fs /mnt/fs: drw-rw-rw- 0 TESTDIR/ drw-rw-rw- 0 TMP/ nsh> rmdir /mnt/fs/tmp nsh> ls -l /mnt/fs /mnt/fs: drw-rw-rw- 0 TESTDIR/ nsh>
2.25 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.26 Execute an NSH Script (sh) |
sh <script-path>
Synopsis.
Execute the sequence of NSH commands in the file referred
to by <script-path>.
2.27 Wait for Seconds (sleep) |
sleep <sec>
Synopsis.
Pause execution (sleep) for <sec> seconds.
2.28 Unmount a File System (umount) |
umount <dir-path>
Synopsis.
Un-mount the file system at mount point <dir-path>.
The umount command can only be used to un-mount volumes previously mounted using
mount command.
Example:
nsh> ls /mnt/fs /mnt/fs: TESTDIR/ nsh> umount /mnt/fs nsh> ls /mnt/fs /mnt/fs: nsh: ls: no such directory: /mnt/fs nsh>
2.29 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.30 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 |
|
get |
CONFIG_NET && CONFIG_NET_UDP &&
CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NET_BUFSIZE >= 5581 |
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_NFILE_DESCRIPTORS > 0 |
mkrd |
!CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT |
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 |
|
put |
CONFIG_NET && CONFIG_NET_UDP &&
CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NET_BUFSIZE >= 5581,2 |
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 |
1 Because of hardware padding, the actual required packet size may be larger
2
Special TFTP server start-up optionss will probably be required to permit
creation of files for the correct operation of the put command.
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. |
Index |
|
helpif-then[-else]-fiifconfigmbmhmwmemmkdirmkfatfsmkfifomkrdmountniceOLDPWDpingpsputpwdPWDrmrmdirsetshsleeptestumountunsetusleep |