2008-02-28 Joel Sherrill <joel.sherrill@oarcorp.com>

	* shell/file.t, shell/network.t: Document more commands and provide
	more examples.

2 files changed, 271 insertions, 28 deletions

diff --git a/doc/shell/file.t b/doc/shell/file.t
index f4673c8bce..2016569383 100644
--- a/doc/shell/file.t
+++ b/doc/shell/file.t
@@ -237,10 +237,42 @@ NONE
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{cp}:
+The following is an example of how to use @code{cp} to
+copy a file to a new name in the current directory:
 
 @example
-EXAMPLE_TBD
+SHLL [/] # cat joel
+cat: joel: No such file or directory
+SHLL [/] # cp etc/passwd joel
+SHLL [/] # cat joel
+root:*:0:0:root::/:/bin/sh
+rtems:*:1:1:RTEMS Application::/:/bin/sh
+tty:!:2:2:tty owner::/:/bin/false
+SHLL [/] # ls
+drwxr-xr-x   1   root   root         536 Jan 01 00:00 dev/
+drwxr-xr-x   1   root   root        1072 Jan 01 00:00 etc/
+-rw-r--r--   1   root   root         102 Jan 01 00:00 joel 
+3 files 1710 bytes occupied
+@end example
+
+The following is an example of how to use @code{cp} to
+copy one or more files to a destination directory and
+use the same @code{basename} in the destination directory:
+
+@example
+SHLL [/] # mkdir tmp
+SHLL [/] # ls tmp         
+0 files 0 bytes occupied
+SHLL [/] # cp /etc/passwd tmp
+SHLL [/] # ls /tmp
+-rw-r--r--   1   root   root         102 Jan 01 00:01 passwd 
+1 files 102 bytes occupied
+SHLL [/] # cp /etc/passwd /etc/group /tmp
+SHLL [/] # ls /tmp
+-rw-r--r--   1   root   root         102 Jan 01 00:01 passwd 
+-rw-r--r--   1   root   root          42 Jan 01 00:01 group 
+2 files 144 bytes occupied
+SHLL [/] # 
 @end example
 
 @subheading CONFIGURATION:
@@ -280,8 +312,8 @@ extern rtems_shell_cmd_t rtems_shell_CP_Command;
 
 @subheading ORIGIN:
 
-The implementation and documentation for this command are from
-NetBSD 4.0.
+The implementation and portions of the documentation for this
+command are from NetBSD 4.0.
 
 @c
 @c
@@ -708,10 +740,20 @@ NONE
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{chroot}:
+The following is an example of how to use @code{chroot}
+and the impact it has on the environment for subsequent
+command invocations:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ cat passwd
+cat: passwd: No such file or directory
+SHLL [/] $ chroot etc
+SHLL [/] $ cat passwd
+root:*:0:0:root::/:/bin/sh
+rtems:*:1:1:RTEMS Application::/:/bin/sh
+tty:!:2:2:tty owner::/:/bin/false
+SHLL [/] $ cat /etc/passwd
+cat: /etc/passwd: No such file or directory
 @end example
 
 @subheading CONFIGURATION:
@@ -1149,7 +1191,7 @@ unmount path
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command unmounts the device at the specified @code{path}.
 
 @subheading EXIT STATUS:
 
@@ -1157,7 +1199,7 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-TBD
+TBD - Surely there must be some warnings to go here.
 
 @subheading EXAMPLES:
 
@@ -1304,7 +1346,16 @@ NONE
 The following is an example of how to use @code{dir}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ dir
+drwxr-xr-x   1   root   root         536 Jan 01 00:00 dev/
+drwxr-xr-x   1   root   root        1072 Jan 01 00:00 etc/
+2 files 1608 bytes occupied
+SHLL [/] $ dir etc
+-rw-r--r--   1   root   root         102 Jan 01 00:00 passwd 
+-rw-r--r--   1   root   root          42 Jan 01 00:00 group 
+-rw-r--r--   1   root   root          30 Jan 01 00:00 issue 
+-rw-r--r--   1   root   root          28 Jan 01 00:00 issue.net 
+4 files 202 bytes occupied
 @end example
 
 @subheading CONFIGURATION:
@@ -1375,7 +1426,18 @@ NONE
 The following is an example of how to use @code{cd}:
 
 @example
-EXAMPLE_TBD
+SHLL [/] $ cd etc
+SHLL [/etc] $ cd /
+SHLL [/] $ cd /etc
+SHLL [/etc] $ pwd
+/etc
+SHLL [/etc] $ cd /
+SHLL [/] $ pwd
+/
+SHLL [/] $ cd etc
+SHLL [/etc] $ cd ..
+SHLL [/] $ pwd
+/
 @end example
 
 @subheading CONFIGURATION:
diff --git a/doc/shell/network.t b/doc/shell/network.t
index fab482d895..0324e2700e 100644
--- a/doc/shell/network.t
+++ b/doc/shell/network.t
@@ -37,12 +37,41 @@ command as well as providing an example usage.
 @subheading SYNOPSYS:
 
 @example
-netstats [-Aimfpcutv]
+netstats [-Aimfpcut]
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command is used to display various types of network statistics.  The
+information displayed can be specified using command line arguments in
+various combinations.  The arguments are interpreted as follows:
+
+@table @b
+@item -A
+print All statistics
+
+@item -i
+print Inet Routes
+
+@item -m
+print MBUF Statistics
+
+@item -f
+print IF Statistics
+
+@item -p
+print IP Statistics
+
+@item -c
+print ICMP Statistics
+
+@item -u
+print UDP Statistics
+
+@item -t
+print TCP Statistics
+
+@end table
 
 @subheading EXIT STATUS:
 
@@ -56,9 +85,108 @@ NONE
 
 The following is an example of how to use @code{netstats}:
 
-@example
-EXAMPLE_TBD
-@end example
+The following is an example of using the @code{netstats}
+command to print the IP routing table:
+
+@smallexample
+[/] $ netstats -i
+Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
+default         192.168.1.14       UGS         0        0      0 eth1
+192.168.1.0     255.255.255.0      U           0        0      1 eth1
+192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1219 eth1
+192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0      840   1202 eth1
+192.168.1.151   00:1C:23:B2:0F:BB  UHL         1       23   1219 eth1
+@end smallexample
+
+The following is an example of using the @code{netstats}
+command to print the MBUF statistics:
+
+@smallexample
+[/] $ netstats -m
+************ MBUF STATISTICS ************
+mbufs:2048    clusters: 128    free:  63
+drops:   0       waits:   0  drains:   0
+      free:1967          data:79          header:2           socket:0       
+       pcb:0           rtable:0           htable:0           atable:0       
+    soname:0           soopts:0           ftable:0           rights:0       
+    ifaddr:0          control:0          oobdata:0       
+@end smallexample
+
+The following is an example of using the @code{netstats}
+command to print the print the interface statistics:
+
+@smallexample
+[/] $ netstats -f
+************ INTERFACE STATISTICS ************
+***** eth1 *****
+Ethernet Address: 00:04:9F:00:5B:21
+Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0   
+Flags: Up Broadcast Running Active Multicast
+Send queue limit:50   length:1    Dropped:0       
+      Rx Interrupts:889            Not First:0               Not Last:0       
+              Giant:0              Non-octet:0       
+            Bad CRC:0                Overrun:0              Collision:0       
+      Tx Interrupts:867             Deferred:0         Late Collision:0       
+   Retransmit Limit:0               Underrun:0             Misaligned:0       
+@end smallexample
+
+The following is an example of using the @code{netstats}
+command to print the print IP statistics:
+
+@smallexample
+[/] $ netstats -p
+************ IP Statistics ************
+             total packets received         894
+  packets rcvd for unreachable dest          13
+ datagrams delivered to upper level         881
+    total ip packets generated here         871
+
+@end smallexample
+
+The following is an example of using the @code{netstats}
+command to print the ICMP statistics:
+
+@smallexample
+[/] $ netstats -c
+************ ICMP Statistics ************
+                        Type 0 sent         843
+                number of responses         843
+                    Type 8 received         843
+
+@end smallexample
+
+The following is an example of using the @code{netstats}
+command to print the UDP statistics:
+
+@smallexample
+[/] $ netstats -u
+************ UDP Statistics ************
+
+@end smallexample
+
+The following is an example of using the @code{netstats}
+command to print the TCP statistics:
+
+@smallexample
+[/] $ netstats -t
+************ TCP Statistics ************
+               connections accepted           1
+            connections established           1
+     segs where we tried to get rtt          34
+                 times we succeeded          35
+                  delayed acks sent           2
+                 total packets sent          37
+                  data packets sent          35
+                    data bytes sent        2618
+              ack-only packets sent           2
+             total packets received          47
+       packets received in sequence          12
+         bytes received in sequence         307
+                   rcvd ack packets          35
+           bytes acked by rcvd acks        2590
+      times hdr predict ok for acks          27
+ times hdr predict ok for data pkts          10
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -107,11 +235,16 @@ extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command;
 
 @example
 ifconfig
+ifconfig interface
+ifconfig interface [up|down]
+ifconfig interface [netmask|pointtopoint|broadcast] IP
+
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command may be used to display information about the
+network interfaces in the system or configure them.
 
 @subheading EXIT STATUS:
 
@@ -119,15 +252,26 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+Just like its counterpart on GNU/Linux and BSD systems, this command
+is complicated.  More example usages would be a welcome submission.
 
 @subheading EXAMPLES:
 
 The following is an example of how to use @code{ifconfig}:
 
-@example
-EXAMPLE_TBD
-@end example
+@smallexample
+ ************ INTERFACE STATISTICS ************
+***** eth1 *****
+Ethernet Address: 00:04:9F:00:5B:21
+Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0   
+Flags: Up Broadcast Running Active Multicast
+Send queue limit:50   length:1    Dropped:0       
+      Rx Interrupts:5391           Not First:0               Not Last:0       
+              Giant:0              Non-octet:0       
+            Bad CRC:0                Overrun:0              Collision:0       
+      Tx Interrupts:5256            Deferred:0         Late Collision:0       
+   Retransmit Limit:0               Underrun:0             Misaligned:0      
+@end smallexample
 
 @subheading CONFIGURATION:
 
@@ -175,12 +319,24 @@ extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command;
 @subheading SYNOPSYS:
 
 @example
-route [subcommand]
+route [subcommand] [args]
 @end example
 
 @subheading DESCRIPTION:
 
-This command XXX
+This command is used to display and manipulate the routing table.
+When invoked with no arguments, the current routing information is
+displayed.  When invoked with the subcommands @code{add} or @code{del},
+then additional arguments must be provided to describe the route.
+
+Command templates include the following:
+
+@smallexample
+route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK]
+route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK]
+@end smallexample
+
+When not provided the netmask defaults to @code{255.255.255.0}
 
 @subheading EXIT STATUS:
 
@@ -188,15 +344,40 @@ This command returns 0 on success and non-zero if an error is encountered.
 
 @subheading NOTES:
 
-NONE
+Just like its counterpart on GNU/Linux and BSD systems, this command
+is complicated.  More example usages would be a welcome submission.
 
 @subheading EXAMPLES:
 
-The following is an example of how to use @code{route}:
-
-@example
-EXAMPLE_TBD
-@end example
+The following is an example of how to use @code{route} to display,
+add, and delete a new route:
+
+@smallexample
+[/] $ route
+Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
+default         192.168.1.14       UGS         0        0      0 eth1
+192.168.1.0     255.255.255.0      U           0        0      1 eth1
+192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1444 eth1
+192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    10844   1202 eth1
+192.168.1.151   00:1C:23:B2:0F:BB  UHL         2       37   1399 eth1
+[/] $  route add -net 192.168.3.0 gw 192.168.1.14
+[/] $ route
+Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
+default         192.168.1.14       UGS         0        0      0 eth1
+192.168.1.0     255.255.255.0      U           0        0      1 eth1
+192.168.1.14    00:A0:C8:1C:EE:28  UHL         2        0   1498 eth1
+192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    14937   1202 eth1
+192.168.1.151   00:1C:23:B2:0F:BB  UHL         2       96   1399 eth1
+192.168.3.0     192.168.1.14       UGS         0        0      0 eth1
+[/] $ route del -net 192.168.3.0 gw 192.168.1.14
+[/] $ route
+Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
+default         192.168.1.14       UGS         0        0      0 eth1
+192.168.1.0     255.255.255.0      U           0        0      1 eth1
+192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1498 eth1
+192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    15945   1202 eth1
+192.168.1.151   00:1C:23:B2:0F:BB  UHL         2      117   1399 eth1
+@end smallexample
 
 @subheading CONFIGURATION: