[svn-r19053] Purpose:

Add --no-dangling-links option to h5ls. 

Description:
Related to "Bug 1830 - Following an dangling external link in h5ls should set non-zero return code."
If --no-dangling-links option is specified and any dangling link is found, return exit code 1 (error).
Merged from hdf5 trunk r19051

Tested:
 jam, amani, heiwa

10 files changed, 214 insertions, 90 deletions

diff --git a/tools/testfiles/help-1.ls b/tools/testfiles/help-1.ls
index 1b5de0c..6a2904e 100644
--- a/tools/testfiles/help-1.ls
+++ b/tools/testfiles/help-1.ls
@@ -3,28 +3,38 @@
 #############################
 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
-   --follow-symlinks  Follow symbolic links (soft links and external links)
-                      to display target object information.
-                      Without this option, h5ls identifies a symbolic link
-                      as a soft link or external link and prints the value
-                      assigned to the symbolic link; it does not provide any
-                      information regarding the target object or determine
-                      whether the link is a dangling link.
-   -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
+   -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
+   --follow-symlinks
+                   Follow symbolic links (soft links and external links)
+                   to display target object information.
+                   Without this option, h5ls identifies a symbolic link
+                   as a soft link or external link and prints the value
+                   assigned to the symbolic link; it does not provide any
+                   information regarding the target object or determine
+                   whether the link is a dangling link.
+   --no-dangling-links
+                   Must be used with --follow-symlinks option;
+                   otherwise, h5ls shows error message and returns an exit
+                   code of 1. 
+                   Check for any symbolic links (soft links or external links)
+                   that do not resolve to an existing object (dataset, group,
+                   or named datatype).
+                   If any dangling link is found, this situation is treated
+                   as an error and h5ls returns an exit code of 1.
+   -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
diff --git a/tools/testfiles/help-2.ls b/tools/testfiles/help-2.ls
index 6f7e75d..92163d1 100644
--- a/tools/testfiles/help-2.ls
+++ b/tools/testfiles/help-2.ls
@@ -3,28 +3,38 @@
 #############################
 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
-   --follow-symlinks  Follow symbolic links (soft links and external links)
-                      to display target object information.
-                      Without this option, h5ls identifies a symbolic link
-                      as a soft link or external link and prints the value
-                      assigned to the symbolic link; it does not provide any
-                      information regarding the target object or determine
-                      whether the link is a dangling link.
-   -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
+   -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
+   --follow-symlinks
+                   Follow symbolic links (soft links and external links)
+                   to display target object information.
+                   Without this option, h5ls identifies a symbolic link
+                   as a soft link or external link and prints the value
+                   assigned to the symbolic link; it does not provide any
+                   information regarding the target object or determine
+                   whether the link is a dangling link.
+   --no-dangling-links
+                   Must be used with --follow-symlinks option;
+                   otherwise, h5ls shows error message and returns an exit
+                   code of 1. 
+                   Check for any symbolic links (soft links or external links)
+                   that do not resolve to an existing object (dataset, group,
+                   or named datatype).
+                   If any dangling link is found, this situation is treated
+                   as an error and h5ls returns an exit code of 1.
+   -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
diff --git a/tools/testfiles/help-3.ls b/tools/testfiles/help-3.ls
index 939c8eb..7199815 100644
--- a/tools/testfiles/help-3.ls
+++ b/tools/testfiles/help-3.ls
@@ -3,28 +3,38 @@
 #############################
 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
-   --follow-symlinks  Follow symbolic links (soft links and external links)
-                      to display target object information.
-                      Without this option, h5ls identifies a symbolic link
-                      as a soft link or external link and prints the value
-                      assigned to the symbolic link; it does not provide any
-                      information regarding the target object or determine
-                      whether the link is a dangling link.
-   -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
+   -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
+   --follow-symlinks
+                   Follow symbolic links (soft links and external links)
+                   to display target object information.
+                   Without this option, h5ls identifies a symbolic link
+                   as a soft link or external link and prints the value
+                   assigned to the symbolic link; it does not provide any
+                   information regarding the target object or determine
+                   whether the link is a dangling link.
+   --no-dangling-links
+                   Must be used with --follow-symlinks option;
+                   otherwise, h5ls shows error message and returns an exit
+                   code of 1. 
+                   Check for any symbolic links (soft links or external links)
+                   that do not resolve to an existing object (dataset, group,
+                   or named datatype).
+                   If any dangling link is found, this situation is treated
+                   as an error and h5ls returns an exit code of 1.
+   -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
diff --git a/tools/testfiles/textlinksrc-2-old.ls b/tools/testfiles/textlinksrc-2-old.ls
index acdc3d2..403a1d2 100644
--- a/tools/testfiles/textlinksrc-2-old.ls
+++ b/tools/testfiles/textlinksrc-2-old.ls
@@ -3,6 +3,6 @@
 #############################
 Opened "textlinksrc.h5" with sec2 driver.
 ext_link5                External Link {textlinktar.h5//empty_group} {Group
-    Location:  3:1832
+    Location:  5:1832
     Links:     1
 }
diff --git a/tools/testfiles/textlinksrc-2.ls b/tools/testfiles/textlinksrc-2.ls
index ea99be8..1e92f59 100644
--- a/tools/testfiles/textlinksrc-2.ls
+++ b/tools/testfiles/textlinksrc-2.ls
@@ -3,6 +3,6 @@
 #############################
 Opened "textlinksrc.h5" with sec2 driver.
 ext_link5                External Link {textlinktar.h5//empty_group} {Group
-    Location:  3:1832
+    Location:  5:1832
     Links:     1
 }
diff --git a/tools/testfiles/textlinksrc-nodangle-1.ls b/tools/testfiles/textlinksrc-nodangle-1.ls
new file mode 100644
index 0000000..8a6144b
--- /dev/null
+++ b/tools/testfiles/textlinksrc-nodangle-1.ls
@@ -0,0 +1,56 @@
+#############################
+ output for 'h5ls -w80 --no-dangling-links textlinksrc.h5'
+#############################
+Error: --no-dangling-links must be used along with --follow-symlinks 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
+   --follow-symlinks
+                   Follow symbolic links (soft links and external links)
+                   to display target object information.
+                   Without this option, h5ls identifies a symbolic link
+                   as a soft link or external link and prints the value
+                   assigned to the symbolic link; it does not provide any
+                   information regarding the target object or determine
+                   whether the link is a dangling link.
+   --no-dangling-links
+                   Must be used with --follow-symlinks option;
+                   otherwise, h5ls shows error message and returns an exit
+                   code of 1. 
+                   Check for any symbolic links (soft links or external links)
+                   that do not resolve to an existing object (dataset, group,
+                   or named datatype).
+                   If any dangling link is found, this situation is treated
+                   as an error and h5ls returns an exit code of 1.
+   -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.
+
+  Deprecated Options
+    The following options have been deprecated in HDF5. While they remain
+    available, they have been superseded as indicated and may be removed
+    from HDF5 in the future. Use the indicated replacement option in all
+    new work; where possible, existing scripts, et cetera, should also be
+    updated to use the replacement option.
+
+   -E or --external   Follow external links.
+                      Replaced by --follow-symlinks.
diff --git a/tools/testfiles/textlinksrc-nodangle-2.ls b/tools/testfiles/textlinksrc-nodangle-2.ls
new file mode 100644
index 0000000..4713849
--- /dev/null
+++ b/tools/testfiles/textlinksrc-nodangle-2.ls
@@ -0,0 +1,8 @@
+#############################
+ output for 'h5ls -w80 --follow-symlinks --no-dangling-links textlinksrc.h5'
+#############################
+ext_link1                External Link {textlinktar.h5//group} {Group}
+ext_link2                External Link {textlinktar.h5//dset} {Dataset {6}}
+ext_link3                External Link {textlinktar.h5//type} {Type}
+ext_link4                External Link {textlinktar.h5//group/elink_t2} {**NOT FOUND**}
+ext_link5                External Link {textlinktar.h5//empty_group} {Group}
diff --git a/tools/testfiles/tgroup-1.ls b/tools/testfiles/tgroup-1.ls
index 8d38e0f..03a70fd 100644
--- a/tools/testfiles/tgroup-1.ls
+++ b/tools/testfiles/tgroup-1.ls
@@ -5,28 +5,38 @@ 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
-   --follow-symlinks  Follow symbolic links (soft links and external links)
-                      to display target object information.
-                      Without this option, h5ls identifies a symbolic link
-                      as a soft link or external link and prints the value
-                      assigned to the symbolic link; it does not provide any
-                      information regarding the target object or determine
-                      whether the link is a dangling link.
-   -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
+   -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
+   --follow-symlinks
+                   Follow symbolic links (soft links and external links)
+                   to display target object information.
+                   Without this option, h5ls identifies a symbolic link
+                   as a soft link or external link and prints the value
+                   assigned to the symbolic link; it does not provide any
+                   information regarding the target object or determine
+                   whether the link is a dangling link.
+   --no-dangling-links
+                   Must be used with --follow-symlinks option;
+                   otherwise, h5ls shows error message and returns an exit
+                   code of 1. 
+                   Check for any symbolic links (soft links or external links)
+                   that do not resolve to an existing object (dataset, group,
+                   or named datatype).
+                   If any dangling link is found, this situation is treated
+                   as an error and h5ls returns an exit code of 1.
+   -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
diff --git a/tools/testfiles/thlinks-nodangle-1.ls b/tools/testfiles/thlinks-nodangle-1.ls
new file mode 100644
index 0000000..37ba6b0
--- /dev/null
+++ b/tools/testfiles/thlinks-nodangle-1.ls
@@ -0,0 +1,7 @@
+#############################
+ output for 'h5ls -w80 --follow-symlinks --no-dangling-links thlink.h5'
+#############################
+dset1                    Dataset {5}
+g1                       Group
+g2                       Group
+g3                       Group, same as /
diff --git a/tools/testfiles/tsoftlinks-nodangle-1.ls b/tools/testfiles/tsoftlinks-nodangle-1.ls
new file mode 100644
index 0000000..6d639b7
--- /dev/null
+++ b/tools/testfiles/tsoftlinks-nodangle-1.ls
@@ -0,0 +1,13 @@
+#############################
+ output for 'h5ls -w80 --follow-symlinks --no-dangling-links tsoftlinks.h5'
+#############################
+dset1                    Dataset {4, 2}
+dset2                    Dataset {4, 2}
+dtype                    Type
+group1                   Group
+group_empty              Group
+soft_dangle              Soft Link {not_yet} {**NOT FOUND**}
+soft_dset1               Soft Link {/dset1} {Dataset {4, 2}}
+soft_dtype               Soft Link {/dtype} {Type}
+soft_empty_grp           Soft Link {/group_empty} {Group}
+soft_group1              Soft Link {/group1} {Group}