Adds h5delete tool (#187)

* Adds h5delete tool

* Fixed MANIFEST

* Added RELEASE.txt note

* Fix typo in RELEASE.txt

MANIFEST

@@ -1695,6 +1695,7 @@
 ./tools/src/misc/Makefile.am
 ./tools/src/misc/h5clear.c
 ./tools/src/misc/h5debug.c
+./tools/src/misc/h5delete.c
 ./tools/src/misc/h5mkgrp.c
 ./tools/src/misc/h5repart.c
 ./tools/test/misc/Makefile.am

release_docs/RELEASE.txt

@@ -576,6 +576,20 @@ New Features
 
     Tools:
     ------
+    - Added h5delete tool
+
+        Deleting HDF5 storage when using the VOL can be tricky when the VOL
+        does not create files. The h5delete tool is a simple wrapper around
+        the H5Fdelete() API call that uses the VOL specified in the
+        HDF5_VOL_CONNECTOR environment variable to delete a "file". If
+        the call to H5Fdelete() fails, the tool will attempt to use
+        the POSIX remove(3) call to remove the file.
+
+        Note that the HDF5 library does currently have support for
+        H5Fdelete() in the native VOL connector.
+
+        (DER - 2020/12/16)
+
     - h5repack added options to control how external links are handled.
 
         Currently h5repack preserves external links and cannot copy and merge

tools/src/misc/CMakeLists.txt

@@ -38,11 +38,20 @@ if (NOT ONLY_SHARED_LIBS)
   set_target_properties (h5clear PROPERTIES FOLDER tools)
   set_global_variable (HDF5_UTILS_TO_EXPORT "${HDF5_UTILS_TO_EXPORT};h5clear")
 
+  add_executable (h5delete ${HDF5_TOOLS_SRC_MISC_SOURCE_DIR}/h5delete.c)
+  target_include_directories (h5delete PRIVATE "${HDF5_TOOLS_DIR}/lib;${HDF5_SRC_DIR};${HDF5_SRC_BINARY_DIR};$<$<BOOL:${HDF5_ENABLE_PARALLEL}>:${MPI_C_INCLUDE_DIRS}>")
+  target_compile_options(h5delete PRIVATE "${HDF5_CMAKE_C_FLAGS}")
+  TARGET_C_PROPERTIES (h5delete STATIC)
+  target_link_libraries (h5delete PRIVATE ${HDF5_TOOLS_LIB_TARGET} ${HDF5_LIB_TARGET})
+  set_target_properties (h5delete PROPERTIES FOLDER tools)
+  set_global_variable (HDF5_UTILS_TO_EXPORT "${HDF5_UTILS_TO_EXPORT};h5delete")
+
   set (H5_DEP_EXECUTABLES
       h5debug
       h5repart
       h5mkgrp
-     h5clear
+      h5clear
+      h5delete
   )
 endif ()
 if (BUILD_SHARED_LIBS)
@@ -78,11 +87,20 @@ if (BUILD_SHARED_LIBS)
   set_target_properties (h5clear-shared PROPERTIES FOLDER tools)
   set_global_variable (HDF5_UTILS_TO_EXPORT "${HDF5_UTILS_TO_EXPORT};h5clear-shared")
 
+  add_executable (h5delete-shared ${HDF5_TOOLS_SRC_MISC_SOURCE_DIR}/h5delete.c)
+  target_include_directories (h5delete-shared PRIVATE "${HDF5_TOOLS_DIR}/lib;${HDF5_SRC_DIR};${HDF5_SRC_BINARY_DIR};$<$<BOOL:${HDF5_ENABLE_PARALLEL}>:${MPI_C_INCLUDE_DIRS}>")
+  target_compile_options(h5delete-shared PRIVATE "${HDF5_CMAKE_C_FLAGS}")
+  TARGET_C_PROPERTIES (h5delete-shared SHARED)
+  target_link_libraries (h5delete-shared PRIVATE ${HDF5_TOOLS_LIBSH_TARGET} ${HDF5_LIBSH_TARGET})
+  set_target_properties (h5delete-shared PROPERTIES FOLDER tools)
+  set_global_variable (HDF5_UTILS_TO_EXPORT "${HDF5_UTILS_TO_EXPORT};h5delete-shared")
+
   set (H5_DEP_EXECUTABLES ${H5_DEP_EXECUTABLES}
       h5debug-shared
       h5repart-shared
       h5mkgrp-shared
       h5clear-shared
+      h5delete-shared
   )
 endif ()
 
@@ -95,11 +113,13 @@ if (HDF5_ENABLE_FORMATTERS)
     clang_format (HDF5_H5REPART_SRC_FORMAT h5repart)
     clang_format (HDF5_H5MKGRP_SRC_FORMAT h5mkgrp)
     clang_format (HDF5_H5CLEAR_SRC_FORMAT h5clear)
+    clang_format (HDF5_H5DELETE_SRC_FORMAT h5delete)
   else ()
     clang_format (HDF5_H5DEBUG_SRC_FORMAT h5debug-shared)
     clang_format (HDF5_H5REPART_SRC_FORMAT h5repart-shared)
     clang_format (HDF5_H5MKGRP_SRC_FORMAT h5mkgrp-shared)
     clang_format (HDF5_H5CLEAR_SRC_FORMAT h5clear-shared)
+    clang_format (HDF5_H5DELETE_SRC_FORMAT h5delete-shared)
   endif ()
 endif ()
 

tools/src/misc/Makefile.am

@@ -22,13 +22,14 @@ include $(top_srcdir)/config/commence.am
 AM_CPPFLAGS+=-I$(top_srcdir)/src -I$(top_srcdir)/tools/lib
 
 # These are our main targets, the tools
-bin_PROGRAMS=h5debug h5repart h5mkgrp h5clear
+bin_PROGRAMS=h5debug h5repart h5mkgrp h5clear h5delete
 
 # Add h5debug, h5repart, and h5mkgrp specific linker flags here
 h5debug_LDFLAGS = $(LT_STATIC_EXEC) $(AM_LDFLAGS)
 h5repart_LDFLAGS = $(LT_STATIC_EXEC) $(AM_LDFLAGS)
 h5mkgrp_LDFLAGS = $(LT_STATIC_EXEC) $(AM_LDFLAGS)
 h5clear_LDFLAGS = $(LT_STATIC_EXEC) $(AM_LDFLAGS)
+h5delete_LDFLAGS = $(LT_STATIC_EXEC) $(AM_LDFLAGS)
 
 # All programs rely on hdf5 library and h5tools library
 LDADD=$(LIBH5TOOLS) $(LIBHDF5)

tools/src/misc/h5delete.c

@@ -0,0 +1,71 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the COPYING file, which can be found at the root of the source code       *
+ * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases.  *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/* h5delete tool
+ *
+ * Deletes storage via H5Fdelete() using the VOL connector specified in the
+ * environment variable.
+ */
+
+#include "H5private.h"
+#include "H5Eprivate.h"
+#include "H5Pprivate.h"
+
+static void usage(void);
+
+static void
+usage(void)
+{
+    HDfprintf(stderr, "Usage: h5delete [-f] <filename>\n");
+}
+
+int
+main(int argc, const char *argv[])
+{
+    hbool_t     quiet = FALSE;
+    const char  *name = NULL;
+    int         ret = 0;
+
+    switch (argc) {
+        case 3:
+            if (HDstrcmp(argv[1], "-f")) {
+                usage();
+                return EXIT_FAILURE;
+            }
+            quiet = TRUE;
+            name = argv[2];
+            break;
+        case 2:
+            name = argv[1];
+            break;
+        default:
+            usage();
+            return EXIT_FAILURE;
+    }
+
+    H5E_BEGIN_TRY {
+        /* Only uses the environment variable at this time */
+        ret = (int)H5Fdelete(name, H5P_DEFAULT);
+    } H5E_END_TRY;
+
+    /* The native VOL connector does not implement the H5Fdelete() call
+     * at this time, so try to remove the file via the POSIX remove(3)
+     * call on failures.
+     */
+    if (ret < 0)
+        ret  = HDremove(name);
+
+    if (ret < 0 && !quiet)
+            HDfprintf(stderr, "Unable to delete storage at: %s\n", name);
+
+    return ret < 0 ? EXIT_FAILURE : EXIT_SUCCESS;
+}