summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Young <dyoung@hdfgroup.org>2020-08-31 20:46:22 (GMT)
committerDavid Young <dyoung@hdfgroup.org>2020-08-31 20:46:22 (GMT)
commit5756ac4233dae0d3f9172c5f81e4fe42e5092137 (patch)
treeeafb72e352c6253e062b2972918e3f96a63428e9
parent60787f34e7b97777606157ec10bb7e978096b133 (diff)
downloadhdf5-5756ac4233dae0d3f9172c5f81e4fe42e5092137.zip
hdf5-5756ac4233dae0d3f9172c5f81e4fe42e5092137.tar.gz
hdf5-5756ac4233dae0d3f9172c5f81e4fe42e5092137.tar.bz2
Document H5HG_trap().
-rw-r--r--src/H5HGtrap.c18
1 files changed, 18 insertions, 0 deletions
diff --git a/src/H5HGtrap.c b/src/H5HGtrap.c
index 2f09d48..6b52007 100644
--- a/src/H5HGtrap.c
+++ b/src/H5HGtrap.c
@@ -23,6 +23,24 @@
#include "H5Eprivate.h" /* Error handling */
#include "H5HGpkg.h" /* Global heaps */
+/* H5HG_trap() is an instrumentation point for the global heap.
+ * The H5HG_trap() result modifies the global heap's treatment of
+ * an unexpected condition that ordinarily would cause an
+ * HDassert() statement to abort the program.
+ *
+ * Currently, just one function, H5HG_read(), calls H5HG_trap(), using
+ * the `reason` string "out of bounds".
+ *
+ * Test programs such as test/vfd_swmr_vlstr_{reader,writer}.c provide
+ * their own H5HG_trap() implementation that overrides the one in the library.
+ *
+ * H5HG_trap() returns `true` if the caller should generate an error-stack
+ * entry and return an error code to the caller's caller.
+ *
+ * H5HG_trap() returns `false` if the caller should blithely carry on;
+ * if NDEBUG is not #defined, then the caller will ordinarily abort the
+ * program in a subsequent HDassert() statement.
+ */
bool
H5HG_trap(const char *reason)
{