[svn-r14284] Description:

	Add H5Lvisit_by_name() API routine to library.

	Eliminated all (five!) other group traversal routines and changed them
all to use the new API routine.

	Cleaned up output of h5ls & h5stat:
		- Issue error when requesting recursive traversal of a file
			with the "group info" flag, but no group given
		- Print info about root group in all(?) appropriate situations
		- Don't print "verbose" information about root group until the
			root group is in the list of objects to display
	(mostly because h5ls & h5stat had a different twist on traversing the
groups in a file that the other utilities)

Tested on:
        FreeBSD/32 6.2 (duty) in debug mode
        FreeBSD/64 6.2 (liberty) w/C++ & FORTRAN, in debug mode
        Linux/32 2.6 (kagiso) w/PGI compilers, w/C++ & FORTRAN, w/threadsafe,
                                in debug mode
        Linux/64-amd64 2.6 (smirom) w/default API=1.6.x, w/C++ & FORTRAN,
                                in production mode
        Linux/64-ia64 2.6 (cobalt) w/Intel compilers, w/C++ & FORTRAN,
                                in production mode
        Solaris/32 2.10 (linew) w/deprecated symbols disabled, w/C++ & FORTRAN,
                                w/szip filter, in production mode
        Mac OS X/32 10.4.10 (amazon) in debug mode
        Linux/64-ia64 2.4 (tg-login3) w/parallel, w/FORTRAN, in production mode

24 files changed, 73 insertions, 157 deletions

diff --git a/tools/testfiles/h5copytst.out.ls b/tools/testfiles/h5copytst.out.ls
index c4d1778..785c3f0 100644
--- a/tools/testfiles/h5copytst.out.ls
+++ b/tools/testfiles/h5copytst.out.ls
@@ -2,6 +2,9 @@
 Expected output for 'h5ls ../testfiles/h5copytst.out.h5'
 #############################
 Opened "../testfiles/h5copytst.out.h5" with sec2 driver.
+/                        Group
+    Location:  1:96
+    Links:     1
 /A                       Group
     Location:  1:90344
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_nested.ls b/tools/testfiles/h5mkgrp_nested.ls
index 2b9fb25..472656d 100644
--- a/tools/testfiles/h5mkgrp_nested.ls
+++ b/tools/testfiles/h5mkgrp_nested.ls
@@ -2,6 +2,9 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_nested.h5'
 #############################
 Opened "../testfiles/h5mkgrp_nested.h5" with sec2 driver.
+/                        Group
+    Location:  1:96
+    Links:     1
 /one                     Group
     Location:  1:800
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_nested_latest.ls b/tools/testfiles/h5mkgrp_nested_latest.ls
index f0bab6f..c00292d 100644
--- a/tools/testfiles/h5mkgrp_nested_latest.ls
+++ b/tools/testfiles/h5mkgrp_nested_latest.ls
@@ -2,6 +2,10 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_nested_latest.h5'
 #############################
 Opened "../testfiles/h5mkgrp_nested_latest.h5" with sec2 driver.
+/                        Group
+    Location:  1:48
+    Links:     1
+    Modified:  XXXX-XX-XX XX:XX:XX XXX
 /one                     Group
     Location:  1:195
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_nested_mult.ls b/tools/testfiles/h5mkgrp_nested_mult.ls
index 4fccd83..6a22ffd 100644
--- a/tools/testfiles/h5mkgrp_nested_mult.ls
+++ b/tools/testfiles/h5mkgrp_nested_mult.ls
@@ -2,6 +2,9 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_nested_mult.h5'
 #############################
 Opened "../testfiles/h5mkgrp_nested_mult.h5" with sec2 driver.
+/                        Group
+    Location:  1:96
+    Links:     1
 /one                     Group
     Location:  1:800
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_nested_mult_latest.ls b/tools/testfiles/h5mkgrp_nested_mult_latest.ls
index 7835050..0b19ff9 100644
--- a/tools/testfiles/h5mkgrp_nested_mult_latest.ls
+++ b/tools/testfiles/h5mkgrp_nested_mult_latest.ls
@@ -2,6 +2,10 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_nested_mult_latest.h5'
 #############################
 Opened "../testfiles/h5mkgrp_nested_mult_latest.h5" with sec2 driver.
+/                        Group
+    Location:  1:48
+    Links:     1
+    Modified:  XXXX-XX-XX XX:XX:XX XXX
 /one                     Group
     Location:  1:195
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_several.ls b/tools/testfiles/h5mkgrp_several.ls
index dcbe3eb..bbf5c92 100644
--- a/tools/testfiles/h5mkgrp_several.ls
+++ b/tools/testfiles/h5mkgrp_several.ls
@@ -2,6 +2,9 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_several.h5'
 #############################
 Opened "../testfiles/h5mkgrp_several.h5" with sec2 driver.
+/                        Group
+    Location:  1:96
+    Links:     1
 /one                     Group
     Location:  1:800
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_several_latest.ls b/tools/testfiles/h5mkgrp_several_latest.ls
index c59107e..a3b5224 100644
--- a/tools/testfiles/h5mkgrp_several_latest.ls
+++ b/tools/testfiles/h5mkgrp_several_latest.ls
@@ -2,6 +2,10 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_several_latest.h5'
 #############################
 Opened "../testfiles/h5mkgrp_several_latest.h5" with sec2 driver.
+/                        Group
+    Location:  1:48
+    Links:     1
+    Modified:  XXXX-XX-XX XX:XX:XX XXX
 /one                     Group
     Location:  1:195
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_single.ls b/tools/testfiles/h5mkgrp_single.ls
index 1f7e828..e9932f7 100644
--- a/tools/testfiles/h5mkgrp_single.ls
+++ b/tools/testfiles/h5mkgrp_single.ls
@@ -2,6 +2,9 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_single.h5'
 #############################
 Opened "../testfiles/h5mkgrp_single.h5" with sec2 driver.
+/                        Group
+    Location:  1:96
+    Links:     1
 /single                  Group
     Location:  1:800
     Links:     1
diff --git a/tools/testfiles/h5mkgrp_single_latest.ls b/tools/testfiles/h5mkgrp_single_latest.ls
index 7f5ee72..b6e6ea4 100644
--- a/tools/testfiles/h5mkgrp_single_latest.ls
+++ b/tools/testfiles/h5mkgrp_single_latest.ls
@@ -2,6 +2,10 @@
 Expected output for 'h5ls ../testfiles/h5mkgrp_single_latest.h5'
 #############################
 Opened "../testfiles/h5mkgrp_single_latest.h5" with sec2 driver.
+/                        Group
+    Location:  1:48
+    Links:     1
+    Modified:  XXXX-XX-XX XX:XX:XX XXX
 /latest                  Group
     Location:  1:195
     Links:     1
diff --git a/tools/testfiles/tall-2.ls b/tools/testfiles/tall-2.ls
index 5513214..2e4cd37 100644
--- a/tools/testfiles/tall-2.ls
+++ b/tools/testfiles/tall-2.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tall.h5'
 #############################
+/                        Group
 /g1                      Group
 /g1/g1.1                 Group
 /g1/g1.1/dset1.1.1       Dataset {10, 10}
diff --git a/tools/testfiles/tarray1.ls b/tools/testfiles/tarray1.ls
index 83a51a8..60c002d 100644
--- a/tools/testfiles/tarray1.ls
+++ b/tools/testfiles/tarray1.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tarray1.h5'
 #############################
+/                        Group
 /Dataset1                Dataset {4}
     Data:
         (0) [0,1,2,3], [10,11,12,13], [20,21,22,23], [30,31,32,33]
diff --git a/tools/testfiles/tattr2.ls b/tools/testfiles/tattr2.ls
index 88b24cd..0448868 100644
--- a/tools/testfiles/tattr2.ls
+++ b/tools/testfiles/tattr2.ls
@@ -2,149 +2,6 @@
  output for 'h5ls -w80 -v -S tattr2.h5'
 #############################
 Opened "tattr2.h5" with sec2 driver.
-    Attribute: array     {2}
-        Type:      [3] 32-bit little-endian integer
-        Data:  [1,2,3], [4,5,6]
-    Attribute: array2D   {3, 2}
-        Type:      [3] 32-bit little-endian integer
-        Data:
-            (0,0) [1,2,3], [4,5,6], [7,8,9], [10,11,12], [13,14,15], [16,17,18]
-    Attribute: array3D   {4, 3, 2}
-        Type:      [3] 32-bit little-endian integer
-        Data:
-            (0,0,0) [1,2,3], [4,5,6], [7,8,9], [10,11,12], [13,14,15],
-            (0,2,1) [16,17,18], [19,20,21], [22,23,24], [25,26,27], [28,29,30],
-            (1,2,0) [31,32,33], [34,35,36], [37,38,39], [40,41,42], [43,44,45],
-            (2,1,1) [46,47,48], [49,50,51], [52,53,54], [55,56,57], [58,59,60],
-            (3,1,0) [61,62,63], [64,65,66], [67,68,69], [70,71,72]
-    Attribute: bitfield  {2}
-        Type:      8-bit bitfield
-        Data:  0x01, 0x02
-    Attribute: bitfield2D {3, 2}
-        Type:      8-bit bitfield
-        Data:
-            (0,0) 0x01, 0x02, 0x03, 0x04, 0x05, 0x06
-    Attribute: bitfield3D {4, 3, 2}
-        Type:      8-bit bitfield
-        Data:
-            (0,0,0) 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a,
-            (1,2,0) 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14,
-            (3,1,0) 0x15, 0x16, 0x17, 0x18
-    Attribute: compound  {2}
-        Type:      struct {
-                   "a"                +0    8-bit integer
-                   "b"                +4    IEEE 64-bit little-endian float
-               } 12 bytes
-        Data:  {1, 2}, {3, 4}
-    Attribute: compound2D {3, 2}
-        Type:      struct {
-                   "a"                +0    8-bit integer
-                   "b"                +4    IEEE 64-bit little-endian float
-               } 12 bytes
-        Data:
-            (0,0) {1, 2}, {3, 4}, {5, 6}, {7, 8}, {9, 10}, {11, 12}
-    Attribute: compound3D {4, 3, 2}
-        Type:      struct {
-                   "a"                +0    8-bit integer
-                   "b"                +4    IEEE 64-bit little-endian float
-               } 12 bytes
-        Data:
-            (0,0,0) {1, 2}, {3, 4}, {5, 6}, {7, 8}, {9, 10}, {11, 12}, {13, 
-            (1,0,0)  14}, {15, 16}, {17, 18}, {19, 20}, {21, 22}, {23, 24},
-            (2,0,0) {25, 26}, {27, 28}, {29, 30}, {31, 32}, {33, 34}, {35, 36},
-            (3,0,0) {37, 38}, {39, 40}, {41, 42}, {43, 44}, {45, 46}, {47, 48}
-    Attribute: enum      {2}
-        Type:      enum 32-bit little-endian integer {
-                   RED              = 0
-                   GREEN            = 1
-               }
-        Data:  RED, RED
-    Attribute: enum2D    {3, 2}
-        Type:      enum 32-bit little-endian integer {
-                   RED              = 0
-                   GREEN            = 1
-               }
-        Data:
-            (0,0) RED, RED, RED, RED, RED, RED
-    Attribute: enum3D    {4, 3, 2}
-        Type:      enum 32-bit little-endian integer {
-                   RED              = 0
-                   GREEN            = 1
-               }
-        Data:
-            (0,0,0) RED, RED, RED, RED, RED, RED, RED, RED, RED, RED, RED, RED,
-            (2,0,0) RED, RED, RED, RED, RED, RED, RED, RED, RED, RED, RED, RED
-    Attribute: float     {2}
-        Type:      IEEE 32-bit little-endian float
-        Data:  1, 2
-    Attribute: float2D   {3, 2}
-        Type:      IEEE 32-bit little-endian float
-        Data:
-            (0,0) 1, 2, 3, 4, 5, 6
-    Attribute: float3D   {4, 3, 2}
-        Type:      IEEE 32-bit little-endian float
-        Data:
-            (0,0,0) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17,
-            (2,2,1) 18, 19, 20, 21, 22, 23, 24
-    Attribute: integer   {2}
-        Type:      32-bit little-endian integer
-        Data:  1, 2
-    Attribute: integer2D {3, 2}
-        Type:      32-bit little-endian integer
-        Data:
-            (0,0) 1, 2, 3, 4, 5, 6
-    Attribute: integer3D {4, 3, 2}
-        Type:      32-bit little-endian integer
-        Data:
-            (0,0,0) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17,
-            (2,2,1) 18, 19, 20, 21, 22, 23, 24
-    Attribute: opaque    {2}
-        Type:      1-byte opaque type
-               (tag = "1-byte opaque type")
-        Data:  0x01, 0x02
-    Attribute: opaque2D  {3, 2}
-        Type:      1-byte opaque type
-               (tag = "1-byte opaque type")
-        Data:
-            (0,0) 0x01, 0x02, 0x03, 0x04, 0x05, 0x06
-    Attribute: opaque3D  {4, 3, 2}
-        Type:      1-byte opaque type
-               (tag = "1-byte opaque type")
-        Data:
-            (0,0,0) 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a,
-            (1,2,0) 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14,
-            (3,1,0) 0x15, 0x16, 0x17, 0x18
-    Attribute: string    {2}
-        Type:      2-byte null-terminated ASCII string
-        Data:  "ab", "de"
-    Attribute: string2D  {3, 2}
-        Type:      2-byte null-terminated ASCII string
-        Data:
-            (0,0) "ab", "cd", "ef", "gh", "ij", "kl"
-    Attribute: string3D  {4, 3, 2}
-        Type:      2-byte null-terminated ASCII string
-        Data:
-            (0,0,0) "ab", "cd", "ef", "gh", "ij", "kl", "mn", "pq", "rs", "tu",
-            (1,2,0) "vw", "xz", "AB", "CD", "EF", "GH", "IJ", "KL", "MN", "PQ",
-            (3,1,0) "RS", "TU", "VW", "XZ"
-    Attribute: vlen      {2}
-        Type:      variable length of
-                   32-bit little-endian integer
-        Data:  (1), (2,3)
-    Attribute: vlen2D    {3, 2}
-        Type:      variable length of
-                   32-bit little-endian integer
-        Data:
-            (0,0) (0), (1), (2,3), (4,5), (6,7,8), (9,10,11)
-    Attribute: vlen3D    {4, 3, 2}
-        Type:      variable length of
-                   32-bit little-endian integer
-        Data:
-            (0,0,0) (0), (1), (2), (3), (4), (5), (6,7), (8,9), (10,11),
-            (1,1,1) (12,13), (14,15), (16,17), (18,19,20), (21,22,23),
-            (2,1,0) (24,25,26), (27,28,29), (30,31,32), (33,34,35),
-            (3,0,0) (36,37,38,39), (40,41,42,43), (44,45,46,47), (48,49,50,51),
-            (3,2,0) (52,53,54,55), (56,57,58,59)
 dset                     Dataset {2/2}
     Attribute: array     {2}
         Type:      [3] 32-bit little-endian integer
diff --git a/tools/testfiles/tcomp-1.ls b/tools/testfiles/tcomp-1.ls
index 599fe68..9cfb47d 100644
--- a/tools/testfiles/tcomp-1.ls
+++ b/tools/testfiles/tcomp-1.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tcompound.h5'
 #############################
+/                        Group
 /dset1                   Dataset {5}
     Data:
         (0) {0, 0, 1}, {1, 1, 0.5}, {2, 4, 0.333333333333333}, {3, 9, 0.25},
diff --git a/tools/testfiles/tdset-1.ls b/tools/testfiles/tdset-1.ls
index 6853429..b6e4671 100644
--- a/tools/testfiles/tdset-1.ls
+++ b/tools/testfiles/tdset-1.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tdset.h5'
 #############################
+/                        Group
 /dset1                   Dataset {10, 20}
     Data:
         (0,0) 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18,
diff --git a/tools/testfiles/textlink-1.ls b/tools/testfiles/textlink-1.ls
index f92786b..87be5a7 100644
--- a/tools/testfiles/textlink-1.ls
+++ b/tools/testfiles/textlink-1.ls
@@ -1,5 +1,6 @@
 #############################
  output for 'h5ls -w80 -r textlink.h5'
 #############################
+/                        Group
 /extlink1                -> file: filename    path: objname
 /extlink2                -> file: anotherfile    path: anotherobj
diff --git a/tools/testfiles/tgroup-1.ls b/tools/testfiles/tgroup-1.ls
index 62ebe70..0ca929d 100644
--- a/tools/testfiles/tgroup-1.ls
+++ b/tools/testfiles/tgroup-1.ls
@@ -1,17 +1,29 @@
 #############################
  output for 'h5ls -w80 -r -g tgroup.h5'
 #############################
-/                        Group
-/g1                      Group
-/g1/g1.1                 Group
-/g1/g1.2                 Group
-/g2                      Group
-/g2/g2.1                 Group
-/g2/g2.1/g2.1.1          Group
-/g2/g2.1/g2.1.2          Group
-/g2/g2.1/g2.1.3          Group
-/g3                      Group
-/g3/g3.1                 Group
-/g3/g3.2                 Group
-/g3/g3.3                 Group
-/g3/g3.4                 Group
+Error: 'recursive' option not compatible with 'group info' option!
+
+usage: h5ls [OPTIONS] [OBJECTS...]
+   OPTIONS
+      -h, -?, --help   Print a usage message and exit
+      -a, --address    Print addresses for raw data
+      -d, --data       Print the values of datasets
+      -e, --errors     Show all HDF5 error reporting
+      -f, --full       Print full path names instead of base names
+      -g, --group      Show information about a group, not its contents
+      -l, --label      Label members of compound datasets
+      -r, --recursive  List all groups recursively, avoiding cycles
+      -s, --string     Print 1-byte integer datasets as ASCII
+      -S, --simple     Use a machine-readable output format
+      -wN, --width=N   Set the number of columns of output
+      -v, --verbose    Generate more verbose output
+      -V, --version    Print version number and exit
+      --vfd=DRIVER     Use the specified virtual file driver
+      -x, --hexdump    Show raw data in hexadecimal format
+
+   OBJECTS
+      Each object consists of an HDF5 file name optionally followed by a
+      slash and an object name within the file (if no object is specified
+      within the file then the contents of the root group are displayed).
+      The file name may include a printf(3C) integer format such as
+      "%05d" to open a file family.
diff --git a/tools/testfiles/tgroup-2.ls b/tools/testfiles/tgroup-2.ls
new file mode 100644
index 0000000..0817d93
--- /dev/null
+++ b/tools/testfiles/tgroup-2.ls
@@ -0,0 +1,4 @@
+#############################
+ output for 'h5ls -w80 -g tgroup.h5/g1'
+#############################
+g1                       Group
diff --git a/tools/testfiles/tloop-1.ls b/tools/testfiles/tloop-1.ls
index b9631b7..22cb6c7 100644
--- a/tools/testfiles/tloop-1.ls
+++ b/tools/testfiles/tloop-1.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tloop.h5'
 #############################
+/                        Group
 /g1                      Group
 /g1/g1.1                 Group
 /g1/g1.1/g2.1            Group, same as /g1
diff --git a/tools/testfiles/tnestcomp-1.ls b/tools/testfiles/tnestcomp-1.ls
index eef41ef..9dc193d 100644
--- a/tools/testfiles/tnestcomp-1.ls
+++ b/tools/testfiles/tnestcomp-1.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tnestedcomp.h5'
 #############################
+/                        Group
 /ArrayOfStructures       Dataset {10}
     Data:
         (0) {0, 0, 1, {"A", [-100,100]}}, {1, 1, 0.5, {"B", [-100,100]}},
diff --git a/tools/testfiles/tsaf.ls b/tools/testfiles/tsaf.ls
index 8efc0f2..96d4811 100644
--- a/tools/testfiles/tsaf.ls
+++ b/tools/testfiles/tsaf.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tsaf.h5'
 #############################
+/                        Group
 /.DSL_METADATA           Dataset {5919/Inf}
     Data:
         (0) 47, 32, 67, 79, 78, 84, 65, 73, 78, 69, 82, 10, 47, 46, 97, 116,
diff --git a/tools/testfiles/tslink-1.ls b/tools/testfiles/tslink-1.ls
index 05b9bca..4c16958 100644
--- a/tools/testfiles/tslink-1.ls
+++ b/tools/testfiles/tslink-1.ls
@@ -1,5 +1,6 @@
 #############################
  output for 'h5ls -w80 -r tslink.h5'
 #############################
+/                        Group
 /slink1                  -> somevalue
 /slink2                  -> linkvalue
diff --git a/tools/testfiles/tstr-1.ls b/tools/testfiles/tstr-1.ls
index 1961fd4..8a223cc 100644
--- a/tools/testfiles/tstr-1.ls
+++ b/tools/testfiles/tstr-1.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tstr.h5'
 #############################
+/                        Group
 /comp1                   Dataset {3, 6}
     Data:
         (0,0) {[0,1,4,9,16,25,36,49,64,81,1,4,9,16,25,36,49,64,81,100,4,9,16,
diff --git a/tools/testfiles/tudlink-1.ls b/tools/testfiles/tudlink-1.ls
index e83fce7..b8578ce 100644
--- a/tools/testfiles/tudlink-1.ls
+++ b/tools/testfiles/tudlink-1.ls
@@ -1,5 +1,6 @@
 #############################
  output for 'h5ls -w80 -r tudlink.h5'
 #############################
+/                        Group
 /udlink1                 -> cannot follow UD links
 /udlink2                 -> cannot follow UD links
diff --git a/tools/testfiles/tvldtypes1.ls b/tools/testfiles/tvldtypes1.ls
index cf1688e..4c4c162 100644
--- a/tools/testfiles/tvldtypes1.ls
+++ b/tools/testfiles/tvldtypes1.ls
@@ -1,6 +1,7 @@
 #############################
  output for 'h5ls -w80 -r -d tvldtypes1.h5'
 #############################
+/                        Group
 /Dataset1.0              Dataset {4}
     Data:
         (0) (0), (10,11), (20,21,22), (30,31,32,33)