From 7f58a89578b64df2b040d97294cb1cf2a82bebd3 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Fri, 7 May 2021 10:56:07 -0700 Subject: Misc normalization from develop --- .gitattributes | 2 + Makefile.am | 16 +- configure.ac | 5 +- doxygen/Doxyfile.in | 2 +- hl/src/H5LTanalyze.c | 4 +- hl/src/H5LTanalyze.l | 4 +- src/H5Adense.c | 16 +- src/H5Adeprec.c | 12 +- src/H5Amodule.h | 40 +- src/H5Apublic.h | 56 +- src/H5B2.c | 3 - src/H5B2cache.c | 30 +- src/H5B2int.c | 107 ++- src/H5B2internal.c | 12 +- src/H5B2leaf.c | 23 +- src/H5B2stat.c | 2 +- src/H5D.c | 40 +- src/H5Dchunk.c | 6 +- src/H5Ddeprec.c | 10 +- src/H5Dearray.c | 12 +- src/H5Dfarray.c | 12 +- src/H5Dfill.c | 4 +- src/H5Dio.c | 2 +- src/H5Dmodule.h | 38 +- src/H5Dnone.c | 4 +- src/H5Dscatgath.c | 2 +- src/H5Dsingle.c | 4 +- src/H5Dtest.c | 2 +- src/H5Dvirtual.c | 2 +- src/H5Emodule.h | 29 + src/H5Epublic.h | 777 +++++++++++++++++++-- src/H5Fspace.c | 2 +- src/H5Fsuper_cache.c | 14 +- src/H5Groot.c | 4 +- src/H5Gtest.c | 1 - src/H5Gtraverse.c | 4 +- src/H5HFbtree2.c | 18 +- src/H5HFdblock.c | 11 +- src/H5Lmodule.h | 2 + src/H5Mmodule.h | 45 ++ src/H5Mpublic.h | 363 +++++++++- src/H5Oint.c | 6 +- src/H5SM.c | 22 +- src/H5Tmodule.h | 4 - src/H5VLmodule.h | 4 + src/H5public.h | 4 +- src/Makefile.am | 3 - test/dsets.c | 4 +- ...h5repack_layout.h5-dset2_chunk_20x10-errstk.tst | 2 +- 49 files changed, 1458 insertions(+), 333 deletions(-) diff --git a/.gitattributes b/.gitattributes index 2ad5b6e..e01442a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -365,6 +365,7 @@ m4/ax_check_rqrd_class.m4 -text m4/ax_java_check_class.m4 -text m4/ax_java_options.m4 -text m4/ax_jni_include_dir.m4 -text +m4/ax_prog_doxygen.m4 -text m4/ax_prog_jar.m4 -text m4/ax_prog_java.m4 -text m4/ax_prog_java_cc.m4 -text @@ -784,6 +785,7 @@ tools/testfiles/tints4dimsStride2.ddl -text tools/testfiles/tintsattrs.h5 -text svneol=unset#application/x-hdf tools/testfiles/tlarge_objname.h5 -text tools/testfiles/tldouble.h5 -text +tools/testfiles/tldouble_scalar.h5 -text tools/testfiles/tlonglinks.h5 -text tools/testfiles/tloop.h5 -text tools/testfiles/tloop2.h5 -text diff --git a/Makefile.am b/Makefile.am index cc38972..8518114 100644 --- a/Makefile.am +++ b/Makefile.am @@ -35,6 +35,9 @@ include $(top_srcdir)/config/commence.am +# include Doxygen rules (requires autoconf-archive >2016-03-20) +@DX_RULES@ + # Define subdirectories to build. ## Automake understands that `make distclean' should recurse into ## conditional subdirectories even if `make all' does not. @@ -187,15 +190,10 @@ check-all-install: trace: @(cd src && $(MAKE) $(AM_MAKEFLAGS) $@) || exit 1; -# Run doxygen across source files. -# Currently, only invoke doxygen in the src directory. -doxygen: - @echo Invoking doxygen - for d in src; do \ - if test $$d != .; then \ - (cd $$d && $(MAKE) $(AM_MAKEFLAGS) $@) || exit 1; \ - fi; \ - done +# doxygen support +if BUILD_DOXYGEN_CONDITIONAL +doxygen: doxygen-doc +endif # Run tests with different Virtual File Drivers. # Currently, only invoke check-vfd in the test directory. diff --git a/configure.ac b/configure.ac index 7fa32e5..d6dc7b3 100644 --- a/configure.ac +++ b/configure.ac @@ -1126,6 +1126,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then AC_SUBST([DOXYGEN_EXTERNAL_SEARCH]) AC_SUBST([DOXYGEN_SEARCHENGINE_URL]) +# SRCDIR Environment variables used inside doxygen macro for the source location: DOXYGEN_PACKAGE=${PACKAGE_NAME} DOXYGEN_VERSION_STRING=${PACKAGE_VERSION} DOXYGEN_INCLUDE_ALIASES='$(SRCDIR)/doxygen/aliases' @@ -1135,7 +1136,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then DOXYGEN_OPTIMIZE_OUTPUT_FOR_C=YES DOXYGEN_MACRO_EXPANSION=YES DOXYGEN_OUTPUT_DIRECTORY=hdf5lib_docs - DOXYGEN_EXAMPLES_DIRECTORY='$(SRCDIR)/doxygen/examples' + DOXYGEN_EXAMPLES_DIRECTORY='$(SRCDIR)/doxygen/examples $(SRCDIR)/src $(SRCDIR)/examples $(SRCDIR)/test' DOXYGEN_LAYOUT_FILE='$(SRCDIR)/doxygen/hdf5doxy_layout.xml' DOXYGEN_HTML_HEADER='$(SRCDIR)/doxygen/hdf5_header.html' DOXYGEN_HTML_FOOTER='$(SRCDIR)/doxygen/hdf5_footer.html' @@ -1145,7 +1146,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then DOXYGEN_EXTERNAL_SEARCH=NO DOXYGEN_SEARCHENGINE_URL= - DX_INIT_DOXYGEN([HDF5], [../doxygen/Doxyfile], [hdf5lib_docs]) + DX_INIT_DOXYGEN([HDF5], [./doxygen/Doxyfile], [hdf5lib_docs]) else AC_MSG_RESULT([no]) diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index b1cb955..29f3028 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -917,7 +917,7 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = ../src ../examples ../test @DOXYGEN_EXAMPLES_DIRECTORY@ +EXAMPLE_PATH = @DOXYGEN_EXAMPLES_DIRECTORY@ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and diff --git a/hl/src/H5LTanalyze.c b/hl/src/H5LTanalyze.c index 65da9d0..875a37a 100644 --- a/hl/src/H5LTanalyze.c +++ b/hl/src/H5LTanalyze.c @@ -916,7 +916,7 @@ char *yytext; #include "H5LTparse.h" static char *trim_quotes(const char *); -int my_yyinput(char *, int); +static int my_yyinput(char *, int); #undef YY_INPUT #define YY_INPUT(b, r, ms) (r=my_yyinput(b, ms)) #define token(x) (int)x @@ -2554,7 +2554,7 @@ trim_quotes(const char *quoted) return trimmed; } -int my_yyinput(char *buf, int max_size) +static int my_yyinput(char *buf, int max_size) { int ret; diff --git a/hl/src/H5LTanalyze.l b/hl/src/H5LTanalyze.l index fd1cbe5..5006612 100644 --- a/hl/src/H5LTanalyze.l +++ b/hl/src/H5LTanalyze.l @@ -27,7 +27,7 @@ #include "H5LTparse.h" static char *trim_quotes(const char *); -int my_yyinput(char *, int); +static int my_yyinput(char *, int); #undef YY_INPUT #define YY_INPUT(b, r, ms) (r=my_yyinput(b, ms)) #define token(x) (int)x @@ -144,7 +144,7 @@ trim_quotes(const char *quoted) return trimmed; } -int my_yyinput(char *buf, int max_size) +static int my_yyinput(char *buf, int max_size) { int ret; diff --git a/src/H5Adense.c b/src/H5Adense.c index a1c0de6..1575f3c 100644 --- a/src/H5Adense.c +++ b/src/H5Adense.c @@ -15,7 +15,7 @@ * * Created: H5Adense.c * Dec 4 2006 - * Quincey Koziol + * Quincey Koziol * * Purpose: Routines for operating on "dense" attribute storage * for an object. @@ -199,9 +199,6 @@ H5A__dense_create(H5F_t *f, H5O_ainfo_t *ainfo) /* Retrieve the heap's address in the file */ if (H5HF_get_heap_addr(fheap, &ainfo->fheap_addr) < 0) HGOTO_ERROR(H5E_ATTR, H5E_CANTGETSIZE, FAIL, "can't get fractal heap address") -#ifdef QAK - HDfprintf(stderr, "%s: ainfo->fheap_addr = %a\n", FUNC, ainfo->fheap_addr); -#endif /* QAK */ #ifndef NDEBUG { @@ -211,9 +208,6 @@ H5A__dense_create(H5F_t *f, H5O_ainfo_t *ainfo) if (H5HF_get_id_len(fheap, &fheap_id_len) < 0) HGOTO_ERROR(H5E_ATTR, H5E_CANTGETSIZE, FAIL, "can't get fractal heap ID length") HDassert(fheap_id_len == H5O_FHEAP_ID_LEN); -#ifdef QAK - HDfprintf(stderr, "%s: fheap_id_len = %Zu\n", FUNC, fheap_id_len); -#endif /* QAK */ } #endif /* NDEBUG */ @@ -233,9 +227,6 @@ H5A__dense_create(H5F_t *f, H5O_ainfo_t *ainfo) /* Retrieve the v2 B-tree's address in the file */ if (H5B2_get_addr(bt2_name, &ainfo->name_bt2_addr) < 0) HGOTO_ERROR(H5E_ATTR, H5E_CANTGET, FAIL, "can't get v2 B-tree address for name index") -#ifdef QAK - HDfprintf(stderr, "%s: ainfo->name_bt2_addr = %a\n", FUNC, ainfo->name_bt2_addr); -#endif /* QAK */ /* Check if we should create a creation order index v2 B-tree */ if (ainfo->index_corder) { @@ -254,10 +245,7 @@ H5A__dense_create(H5F_t *f, H5O_ainfo_t *ainfo) /* Retrieve the v2 B-tree's address in the file */ if (H5B2_get_addr(bt2_corder, &ainfo->corder_bt2_addr) < 0) HGOTO_ERROR(H5E_ATTR, H5E_CANTGET, FAIL, "can't get v2 B-tree address for creation order index") -#ifdef QAK - HDfprintf(stderr, "%s: ainfo->corder_bt2_addr = %a\n", FUNC, ainfo->corder_bt2_addr); -#endif /* QAK */ - } /* end if */ + } /* end if */ done: /* Release resources */ diff --git a/src/H5Adeprec.c b/src/H5Adeprec.c index ba12d4c..3d4e391 100644 --- a/src/H5Adeprec.c +++ b/src/H5Adeprec.c @@ -15,7 +15,7 @@ * * Created: H5Adeprec.c * November 27 2006 - * Quincey Koziol + * Quincey Koziol * * Purpose: Deprecated functions from the H5A interface. These * functions are here for compatibility purposes and may be @@ -209,7 +209,7 @@ H5Aopen_name(hid_t loc_id, const char *name) /* Register the attribute and get an ID for it */ if ((ret_value = H5VL_register(H5I_ATTR, attr, vol_obj->connector, TRUE)) < 0) - HGOTO_ERROR(H5E_ATTR, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to atomize attribute handle") + HGOTO_ERROR(H5E_ATTR, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register attribute handle") done: /* Clean up on failure */ @@ -277,7 +277,7 @@ H5Aopen_idx(hid_t loc_id, unsigned idx) /* Register the attribute and get an ID for it */ if ((ret_value = H5VL_register(H5I_ATTR, attr, vol_obj->connector, TRUE)) < 0) - HGOTO_ERROR(H5E_ATTR, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to atomize attribute handle") + HGOTO_ERROR(H5E_ATTR, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register attribute handle") done: /* Clean up on failure */ @@ -373,7 +373,7 @@ done: Deprecated in favor of H5Aiterate2 --------------------------------------------------------------------------*/ herr_t -H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data) +H5Aiterate1(hid_t loc_id, unsigned *attr_num /*in,out*/, H5A_operator1_t op, void *op_data) { H5VL_object_t *vol_obj = NULL; /* Object of loc_id */ herr_t ret_value; /* Return value */ @@ -387,12 +387,12 @@ H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data) /* Get the location object */ if (NULL == (vol_obj = H5VL_vol_object(loc_id))) - HGOTO_ERROR(H5E_VOL, H5E_BADTYPE, H5_ITER_ERROR, "invalid location identifier") + HGOTO_ERROR(H5E_ATTR, H5E_BADTYPE, H5_ITER_ERROR, "invalid location identifier") /* Call attribute iteration routine */ if ((ret_value = H5VL_attr_optional(vol_obj, H5VL_NATIVE_ATTR_ITERATE_OLD, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL, loc_id, attr_num, op, op_data)) < 0) - HERROR(H5E_VOL, H5E_BADITER, "error iterating over attributes"); + HERROR(H5E_ATTR, H5E_BADITER, "error iterating over attributes"); done: FUNC_LEAVE_API(ret_value) diff --git a/src/H5Amodule.h b/src/H5Amodule.h index 45172bf..c89c93f 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -30,19 +30,39 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5A H5A - * \brief Attribute Interface * - * \details The Attribute Interface, H5A, provides a mechanism for attaching - * additional information to a dataset, group, or named datatype. + * Use the functions in this module to manage HDF5 attributes. * - * Attributes are accessed by opening the object that they are - * attached to and are not independent objects. Typically an - * attribute is small in size and contains user metadata about the - * object that it is attached to. + * The Attribute Interface, H5A, provides a mechanism for attaching additional + * information to a dataset, group, or named datatype. * - * Attributes look similar to HDF5 datasets in that they have a - * datatype and dataspace. However, they do not support partial - * I/O operations and cannot be compressed or extended. + * Attributes are accessed by opening the object that they are attached to and + * are not independent objects. Typically an attribute is small in size and + * contains user metadata about the object that it is attached to. + * + * Attributes look similar to HDF5 datasets in that they have a datatype and + * dataspace. However, they do not support partial I/O operations and cannot be + * compressed or extended. + * + * + * + * + * + * + * + * + * + * + * + *
CreateRead
+ * \snippet H5A_examples.c create + * + * \snippet H5A_examples.c read + *
UpdateDelete
+ * \snippet H5A_examples.c update + * + * \snippet H5A_examples.c delete + *
* */ diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 28a0e85..6ec9144 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -22,17 +22,40 @@ #include "H5Opublic.h" /* Object Headers */ #include "H5Tpublic.h" /* Datatypes */ -/* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */ +//! +/** + * Information struct for H5Aget_info() / H5Aget_info_by_idx() + */ typedef struct { - hbool_t corder_valid; /* Indicate if creation order is valid */ - H5O_msg_crt_idx_t corder; /* Creation order */ - H5T_cset_t cset; /* Character set of attribute name */ - hsize_t data_size; /* Size of raw data */ + hbool_t corder_valid; /**< Indicate if creation order is valid */ + H5O_msg_crt_idx_t corder; /**< Creation order */ + H5T_cset_t cset; /**< Character set of attribute name */ + hsize_t data_size; /**< Size of raw data */ } H5A_info_t; +//! -/* Typedef for H5Aiterate2() callbacks */ +//! +/** + * Typedef for H5Aiterate2() / H5Aiterate_by_name() callbacks + * \param[in] location_id The identifier for the group, dataset + * or named datatype being iterated over + * \param[in] attr_name The name of the current object attribute + * \param[in] ainfo The attribute’s info struct + * \param[in,out] op_data A pointer to the operator data passed in to + * H5Aiterate2() or H5Aiterate_by_name() + * \returns The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * attribute. + */ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/, const H5A_info_t *ainfo /*in*/, void *op_data /*in,out*/); +//! /********************/ /* Public Variables */ @@ -95,9 +118,28 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char * /* Typedefs */ -/* Typedef for H5Aiterate1() callbacks */ +//! +/** + * \brief Typedef for H5Aiterate1() callbacks + * + * \param[in] location_id The identifier for the group, dataset + * or named datatype being iterated over + * \param[in] attr_name The name of the current object attribute + * \param[in,out] operator_data A pointer to the operator data passed in to + * H5Aiterate1() + * \returns The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * attribute. + */ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_name /*in*/, void *operator_data /*in,out*/); +//! /* Function prototypes */ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id); diff --git a/src/H5B2.c b/src/H5B2.c index 320fe17..5453387 100644 --- a/src/H5B2.c +++ b/src/H5B2.c @@ -1509,9 +1509,6 @@ H5B2_delete(H5F_t *f, haddr_t addr, void *ctx_udata, H5B2_remove_t op, void *op_ HDassert(H5F_addr_defined(addr)); /* Lock the v2 B-tree header into memory */ -#ifdef QAK - HDfprintf(stderr, "%s: addr = %a\n", FUNC, addr); -#endif /* QAK */ if (NULL == (hdr = H5B2__hdr_protect(f, addr, ctx_udata, H5AC__NO_FLAGS_SET))) HGOTO_ERROR(H5E_BTREE, H5E_CANTPROTECT, FAIL, "unable to protect v2 B-tree header") diff --git a/src/H5B2cache.c b/src/H5B2cache.c index 35351d9..f38147b 100644 --- a/src/H5B2cache.c +++ b/src/H5B2cache.c @@ -15,7 +15,7 @@ * * Created: H5B2cache.c * Jan 31 2005 - * Quincey Koziol + * Quincey Koziol * * Purpose: Implement v2 B-tree metadata cache methods. * @@ -159,7 +159,6 @@ const H5AC_class_t H5AC_BT2_LEAF[1] = {{ * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * May 18, 2010 * *------------------------------------------------------------------------- @@ -226,7 +225,6 @@ H5B2__cache_hdr_verify_chksum(const void *_image, size_t len, void H5_ATTR_UNUSE * Failure: NULL * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 1 2005 * *------------------------------------------------------------------------- @@ -255,7 +253,7 @@ H5B2__cache_hdr_deserialize(const void *_image, size_t H5_ATTR_UNUSED len, void HGOTO_ERROR(H5E_BTREE, H5E_CANTALLOC, NULL, "allocation failed for B-tree header") /* Magic number */ - if (HDmemcmp(image, H5B2_HDR_MAGIC, (size_t)H5_SIZEOF_MAGIC)) + if (HDmemcmp(image, H5B2_HDR_MAGIC, (size_t)H5_SIZEOF_MAGIC) != 0) HGOTO_ERROR(H5E_BTREE, H5E_BADVALUE, NULL, "wrong B-tree header signature") image += H5_SIZEOF_MAGIC; @@ -324,7 +322,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * May 20, 2010 * *------------------------------------------------------------------------- @@ -354,7 +351,6 @@ H5B2__cache_hdr_image_len(const void *_thing, size_t *image_len) * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 1 2005 * *------------------------------------------------------------------------- @@ -424,7 +420,6 @@ H5B2__cache_hdr_serialize(const H5F_t *f, void *_image, size_t H5_ATTR_UNUSED le * Return: Non-negative on success/Negative on failure * * Programmer: Neil Fortner - * nfortne2@hdfgroup.org * Apr 24 2012 * *------------------------------------------------------------------------- @@ -515,7 +510,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Mike McGreevy - * mcgreevy@hdfgroup.org * June 18, 2008 * *------------------------------------------------------------------------- @@ -546,7 +540,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * May 18, 2010 * *------------------------------------------------------------------------- @@ -620,7 +613,6 @@ H5B2__cache_int_verify_chksum(const void *_image, size_t H5_ATTR_UNUSED len, voi * Failure: NULL * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 2 2005 * *------------------------------------------------------------------------- @@ -659,7 +651,7 @@ H5B2__cache_int_deserialize(const void *_image, size_t H5_ATTR_UNUSED len, void internal->shadow_epoch = udata->hdr->shadow_epoch; /* Magic number */ - if (HDmemcmp(image, H5B2_INT_MAGIC, (size_t)H5_SIZEOF_MAGIC)) + if (HDmemcmp(image, H5B2_INT_MAGIC, (size_t)H5_SIZEOF_MAGIC) != 0) HGOTO_ERROR(H5E_BTREE, H5E_BADVALUE, NULL, "wrong B-tree internal node signature") image += H5_SIZEOF_MAGIC; @@ -743,7 +735,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * May 20, 2010 * *------------------------------------------------------------------------- @@ -775,7 +766,6 @@ H5B2__cache_int_image_len(const void *_thing, size_t *image_len) * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 3 2005 * *------------------------------------------------------------------------- @@ -861,7 +851,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Neil Fortner - * nfortne2@hdfgroup.org * Apr 25 2012 * *------------------------------------------------------------------------- @@ -872,7 +861,7 @@ H5B2__cache_int_notify(H5AC_notify_action_t action, void *_thing) H5B2_internal_t *internal = (H5B2_internal_t *)_thing; herr_t ret_value = SUCCEED; - FUNC_ENTER_NOAPI_NOINIT + FUNC_ENTER_STATIC /* * Check arguments. @@ -939,7 +928,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Mike McGreevy - * mcgreevy@hdfgroup.org * June 18, 2008 * *------------------------------------------------------------------------- @@ -971,7 +959,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * May 18, 2010 * *------------------------------------------------------------------------- @@ -1044,7 +1031,6 @@ H5B2__cache_leaf_verify_chksum(const void *_image, size_t H5_ATTR_UNUSED len, vo * Failure: NULL * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 2 2005 * *------------------------------------------------------------------------- @@ -1081,7 +1067,7 @@ H5B2__cache_leaf_deserialize(const void *_image, size_t H5_ATTR_UNUSED len, void leaf->shadow_epoch = udata->hdr->shadow_epoch; /* Magic number */ - if (HDmemcmp(image, H5B2_LEAF_MAGIC, (size_t)H5_SIZEOF_MAGIC)) + if (HDmemcmp(image, H5B2_LEAF_MAGIC, (size_t)H5_SIZEOF_MAGIC) != 0) HGOTO_ERROR(H5E_BTREE, H5E_BADVALUE, NULL, "wrong B-tree leaf node signature") image += H5_SIZEOF_MAGIC; @@ -1142,7 +1128,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * May 20, 2010 * *------------------------------------------------------------------------- @@ -1173,7 +1158,6 @@ H5B2__cache_leaf_image_len(const void *_thing, size_t *image_len) * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 2 2005 * *------------------------------------------------------------------------- @@ -1246,7 +1230,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Neil Fortner - * nfortne2@hdfgroup.org * Apr 25 2012 * *------------------------------------------------------------------------- @@ -1257,7 +1240,7 @@ H5B2__cache_leaf_notify(H5AC_notify_action_t action, void *_thing) H5B2_leaf_t *leaf = (H5B2_leaf_t *)_thing; herr_t ret_value = SUCCEED; - FUNC_ENTER_NOAPI_NOINIT + FUNC_ENTER_STATIC /* * Check arguments. @@ -1324,7 +1307,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Mike McGreevy - * mcgreevy@hdfgroup.org * June 18, 2008 * *------------------------------------------------------------------------- diff --git a/src/H5B2int.c b/src/H5B2int.c index 6c014cc..610da6c 100644 --- a/src/H5B2int.c +++ b/src/H5B2int.c @@ -138,15 +138,15 @@ H5B2__split1(H5B2_hdr_t *hdr, uint16_t depth, H5B2_node_ptr_t *curr_node_ptr, unsigned *parent_cache_info_flags_ptr, H5B2_internal_t *internal, unsigned *internal_flags_ptr, unsigned idx) { - const H5AC_class_t *child_class; /* Pointer to child node's class info */ - haddr_t left_addr, right_addr; /* Addresses of left & right child nodes */ - void * left_child = NULL, *right_child = NULL; /* Pointers to child nodes */ - uint16_t * left_nrec, *right_nrec; /* Pointers to child # of records */ - uint8_t * left_native, *right_native; /* Pointers to childs' native records */ - H5B2_node_ptr_t * left_node_ptrs = NULL, - *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ - uint16_t mid_record; /* Index of "middle" record in current node */ - uint16_t old_node_nrec; /* Number of records in internal node split */ + const H5AC_class_t *child_class; /* Pointer to child node's class info */ + haddr_t left_addr = HADDR_UNDEF, right_addr = HADDR_UNDEF; /* Addresses of left & right child nodes */ + void * left_child = NULL, *right_child = NULL; /* Pointers to child nodes */ + uint16_t *left_nrec, *right_nrec; /* Pointers to child # of records */ + uint8_t * left_native, *right_native; /* Pointers to childs' native records */ + H5B2_node_ptr_t *left_node_ptrs = NULL, + *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ + uint16_t mid_record; /* Index of "middle" record in current node */ + uint16_t old_node_nrec; /* Number of records in internal node split */ unsigned left_child_flags = H5AC__NO_FLAGS_SET, right_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ herr_t ret_value = SUCCEED; /* Return value */ @@ -423,13 +423,13 @@ done: herr_t H5B2__redistribute2(H5B2_hdr_t *hdr, uint16_t depth, H5B2_internal_t *internal, unsigned idx) { - const H5AC_class_t *child_class; /* Pointer to child node's class info */ - haddr_t left_addr, right_addr; /* Addresses of left & right child nodes */ - void * left_child = NULL, *right_child = NULL; /* Pointers to child nodes */ - uint16_t * left_nrec, *right_nrec; /* Pointers to child # of records */ - uint8_t * left_native, *right_native; /* Pointers to childs' native records */ - H5B2_node_ptr_t * left_node_ptrs = NULL, - *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ + const H5AC_class_t *child_class; /* Pointer to child node's class info */ + haddr_t left_addr = HADDR_UNDEF, right_addr = HADDR_UNDEF; /* Addresses of left & right child nodes */ + void * left_child = NULL, *right_child = NULL; /* Pointers to child nodes */ + uint16_t *left_nrec, *right_nrec; /* Pointers to child # of records */ + uint8_t * left_native, *right_native; /* Pointers to childs' native records */ + H5B2_node_ptr_t *left_node_ptrs = NULL, + *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ hssize_t left_moved_nrec = 0, right_moved_nrec = 0; /* Number of records moved, for internal redistrib */ unsigned left_child_flags = H5AC__NO_FLAGS_SET, right_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ @@ -696,20 +696,20 @@ H5B2__redistribute3(H5B2_hdr_t *hdr, uint16_t depth, H5B2_internal_t *internal, unsigned idx) { H5B2_node_ptr_t *left_node_ptrs = NULL, - *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ - H5B2_node_ptr_t * middle_node_ptrs = NULL; /* Pointers to childs' node pointer info */ - const H5AC_class_t *child_class; /* Pointer to child node's class info */ - haddr_t left_addr, right_addr; /* Addresses of left & right child nodes */ - haddr_t middle_addr; /* Address of middle child node */ - void * left_child = NULL, *right_child = NULL; /* Pointers to child nodes */ - void * middle_child = NULL; /* Pointers to middle child node */ - uint16_t * left_nrec, *right_nrec; /* Pointers to child # of records */ - uint16_t * middle_nrec; /* Pointers to middle child # of records */ - uint8_t * left_native, *right_native; /* Pointers to childs' native records */ - uint8_t * middle_native; /* Pointers to middle child's native records */ - hssize_t left_moved_nrec = 0, right_moved_nrec = 0; /* Number of records moved, for internal split */ - hssize_t middle_moved_nrec = 0; /* Number of records moved, for internal split */ - unsigned left_child_flags = H5AC__NO_FLAGS_SET, + *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ + H5B2_node_ptr_t * middle_node_ptrs = NULL; /* Pointers to childs' node pointer info */ + const H5AC_class_t *child_class; /* Pointer to child node's class info */ + haddr_t left_addr = HADDR_UNDEF, right_addr = HADDR_UNDEF; /* Addresses of left & right child nodes */ + haddr_t middle_addr = HADDR_UNDEF; /* Address of middle child node */ + void * left_child = NULL, *right_child = NULL; /* Pointers to child nodes */ + void * middle_child = NULL; /* Pointers to middle child node */ + uint16_t *left_nrec, *right_nrec; /* Pointers to child # of records */ + uint16_t *middle_nrec; /* Pointers to middle child # of records */ + uint8_t * left_native, *right_native; /* Pointers to childs' native records */ + uint8_t * middle_native; /* Pointers to middle child's native records */ + hssize_t left_moved_nrec = 0, right_moved_nrec = 0; /* Number of records moved, for internal split */ + hssize_t middle_moved_nrec = 0; /* Number of records moved, for internal split */ + unsigned left_child_flags = H5AC__NO_FLAGS_SET, right_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ unsigned middle_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ herr_t ret_value = SUCCEED; /* Return value */ @@ -1122,16 +1122,16 @@ H5B2__merge2(H5B2_hdr_t *hdr, uint16_t depth, H5B2_node_ptr_t *curr_node_ptr, unsigned *parent_cache_info_flags_ptr, H5B2_internal_t *internal, unsigned *internal_flags_ptr, unsigned idx) { - const H5AC_class_t *child_class; /* Pointer to child node's class info */ - haddr_t left_addr, right_addr; /* Addresses of left & right child nodes */ - void * left_child = NULL, *right_child = NULL; /* Pointers to left & right child nodes */ - uint16_t * left_nrec, *right_nrec; /* Pointers to left & right child # of records */ - uint8_t * left_native, *right_native; /* Pointers to left & right children's native records */ - H5B2_node_ptr_t * left_node_ptrs = NULL, - *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ - unsigned left_child_flags = H5AC__NO_FLAGS_SET, - right_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ - herr_t ret_value = SUCCEED; /* Return value */ + const H5AC_class_t *child_class; /* Pointer to child node's class info */ + haddr_t left_addr = HADDR_UNDEF, right_addr = HADDR_UNDEF; /* Addresses of left & right child nodes */ + void * left_child = NULL, *right_child = NULL; /* Pointers to left & right child nodes */ + uint16_t *left_nrec, *right_nrec; /* Pointers to left & right child # of records */ + uint8_t * left_native, *right_native; /* Pointers to left & right children's native records */ + H5B2_node_ptr_t *left_node_ptrs = NULL, + *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ + unsigned left_child_flags = H5AC__NO_FLAGS_SET, + right_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ + herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_PACKAGE @@ -1297,19 +1297,19 @@ H5B2__merge3(H5B2_hdr_t *hdr, uint16_t depth, H5B2_node_ptr_t *curr_node_ptr, unsigned *parent_cache_info_flags_ptr, H5B2_internal_t *internal, unsigned *internal_flags_ptr, unsigned idx) { - const H5AC_class_t *child_class; /* Pointer to child node's class info */ - haddr_t left_addr, right_addr; /* Addresses of left & right child nodes */ - haddr_t middle_addr; /* Address of middle child node */ - void * left_child = NULL, *right_child = NULL; /* Pointers to left & right child nodes */ - void * middle_child = NULL; /* Pointer to middle child node */ - uint16_t * left_nrec, *right_nrec; /* Pointers to left & right child # of records */ - uint16_t * middle_nrec; /* Pointer to middle child # of records */ - uint8_t * left_native, *right_native; /* Pointers to left & right children's native records */ - uint8_t * middle_native; /* Pointer to middle child's native records */ - H5B2_node_ptr_t * left_node_ptrs = NULL, - *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ - H5B2_node_ptr_t *middle_node_ptrs = NULL; /* Pointer to child's node pointer info */ - hsize_t middle_moved_nrec; /* Number of records moved, for internal split */ + const H5AC_class_t *child_class; /* Pointer to child node's class info */ + haddr_t left_addr = HADDR_UNDEF, right_addr = HADDR_UNDEF; /* Addresses of left & right child nodes */ + haddr_t middle_addr = HADDR_UNDEF; /* Address of middle child node */ + void * left_child = NULL, *right_child = NULL; /* Pointers to left & right child nodes */ + void * middle_child = NULL; /* Pointer to middle child node */ + uint16_t *left_nrec, *right_nrec; /* Pointers to left & right child # of records */ + uint16_t *middle_nrec; /* Pointer to middle child # of records */ + uint8_t * left_native, *right_native; /* Pointers to left & right children's native records */ + uint8_t * middle_native; /* Pointer to middle child's native records */ + H5B2_node_ptr_t *left_node_ptrs = NULL, + *right_node_ptrs = NULL; /* Pointers to childs' node pointer info */ + H5B2_node_ptr_t *middle_node_ptrs = NULL; /* Pointer to child's node pointer info */ + hsize_t middle_moved_nrec; /* Number of records moved, for internal split */ unsigned left_child_flags = H5AC__NO_FLAGS_SET, right_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ unsigned middle_child_flags = H5AC__NO_FLAGS_SET; /* Flags for unprotecting child nodes */ @@ -2005,7 +2005,6 @@ done: * Return: SUCCEED/FAIL * * Programmer: Quincey Koziol - * koziol@lbl.gov * Dec 1 2016 * *------------------------------------------------------------------------- diff --git a/src/H5B2internal.c b/src/H5B2internal.c index 9491c55..c00f555 100644 --- a/src/H5B2internal.c +++ b/src/H5B2internal.c @@ -15,7 +15,7 @@ * * Created: H5B2internal.c * Dec 01 2016 - * Quincey Koziol + * Quincey Koziol * * Purpose: Routines for managing v2 B-tree internal ndoes. * @@ -77,7 +77,6 @@ H5FL_DEFINE(H5B2_internal_t); * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 3 2005 * *------------------------------------------------------------------------- @@ -177,7 +176,6 @@ done: * Return: Pointer to internal node on success/NULL on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Aug 25 2006 * *------------------------------------------------------------------------- @@ -276,7 +274,6 @@ done: * Return: Non-negative on success, negative on failure. * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 9 2005 * *------------------------------------------------------------------------- @@ -353,7 +350,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 2 2005 * *------------------------------------------------------------------------- @@ -523,7 +519,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Dec 24 2015 * *------------------------------------------------------------------------- @@ -801,7 +796,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 3 2005 * *------------------------------------------------------------------------- @@ -1046,7 +1040,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Nov 14 2006 * *------------------------------------------------------------------------- @@ -1341,7 +1334,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 2 2005 * *------------------------------------------------------------------------- @@ -1392,7 +1384,6 @@ done: * Return: Non-negative on success, negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 19 2005 * *------------------------------------------------------------------------- @@ -1433,7 +1424,6 @@ H5B2__assert_internal(hsize_t parent_all_nrec, const H5B2_hdr_t H5_ATTR_NDEBUG_U * Return: Non-negative on success, negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 19 2005 * *------------------------------------------------------------------------- diff --git a/src/H5B2leaf.c b/src/H5B2leaf.c index f60259b..20ace84 100644 --- a/src/H5B2leaf.c +++ b/src/H5B2leaf.c @@ -15,7 +15,7 @@ * * Created: H5B2leaf.c * Dec 01 2016 - * Quincey Koziol + * Quincey Koziol * * Purpose: Routines for managing v2 B-tree leaf ndoes. * @@ -78,7 +78,6 @@ H5FL_DEFINE(H5B2_leaf_t); * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 2 2005 * *------------------------------------------------------------------------- @@ -166,7 +165,6 @@ done: * Return: Pointer to leaf node on success/NULL on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * May 5 2010 * *------------------------------------------------------------------------- @@ -260,7 +258,6 @@ done: * Return: Non-negative on success, negative on failure. * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 9 2005 * *------------------------------------------------------------------------- @@ -332,7 +329,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 3 2005 * *------------------------------------------------------------------------- @@ -447,7 +443,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Dec 23 2015 * *------------------------------------------------------------------------- @@ -604,7 +599,6 @@ done: * Failure: Negative * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 4 2005 * *------------------------------------------------------------------------- @@ -613,11 +607,11 @@ herr_t H5B2__swap_leaf(H5B2_hdr_t *hdr, uint16_t depth, H5B2_internal_t *internal, unsigned *internal_flags_ptr, unsigned idx, void *swap_loc) { - const H5AC_class_t *child_class; /* Pointer to child node's class info */ - haddr_t child_addr; /* Address of child node */ - void * child = NULL; /* Pointer to child node */ - uint8_t * child_native; /* Pointer to child's native records */ - herr_t ret_value = SUCCEED; /* Return value */ + const H5AC_class_t *child_class; /* Pointer to child node's class info */ + haddr_t child_addr = HADDR_UNDEF; /* Address of child node */ + void * child = NULL; /* Pointer to child node */ + uint8_t * child_native; /* Pointer to child's native records */ + herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_PACKAGE @@ -762,7 +756,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 3 2005 * *------------------------------------------------------------------------- @@ -871,7 +864,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Nov 14 2006 * *------------------------------------------------------------------------- @@ -972,7 +964,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 2 2005 * *------------------------------------------------------------------------- @@ -1017,7 +1008,6 @@ done: * Return: Non-negative on success, negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 19 2005 * *------------------------------------------------------------------------- @@ -1039,7 +1029,6 @@ H5B2__assert_leaf(const H5B2_hdr_t H5_ATTR_NDEBUG_UNUSED *hdr, const H5B2_leaf_t * Return: Non-negative on success, negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 19 2005 * *------------------------------------------------------------------------- diff --git a/src/H5B2stat.c b/src/H5B2stat.c index 936e356..4735276 100644 --- a/src/H5B2stat.c +++ b/src/H5B2stat.c @@ -11,7 +11,7 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Quincey Koziol +/* Programmer: Quincey Koziol * Monday, March 6, 2006 * * Purpose: v2 B-tree metadata statistics functions. diff --git a/src/H5D.c b/src/H5D.c index d60465e..eea95b6 100644 --- a/src/H5D.c +++ b/src/H5D.c @@ -138,7 +138,7 @@ H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t /* Create the dataset */ if (NULL == (dset = H5VL_dataset_create(vol_obj, &loc_params, name, lcpl_id, type_id, space_id, dcpl_id, dapl_id, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) - HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to create dataset") + HGOTO_ERROR(H5E_DATASET, H5E_CANTCREATE, H5I_INVALID_HID, "unable to create dataset") /* Get an ID for the dataset */ if ((ret_value = H5VL_register(H5I_DATASET, dset, vol_obj->connector, TRUE)) < 0) @@ -187,9 +187,9 @@ done: hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id) { - void * dset = NULL; /* dset object from VOL connector */ - H5VL_object_t * vol_obj = NULL; /* object of loc_id */ - H5VL_loc_params_t loc_params; + void * dset = NULL; /* dset object from VOL connector */ + H5VL_object_t * vol_obj = NULL; /* Object for loc_id */ + H5VL_loc_params_t loc_params; /* Location parameters for object access */ hid_t ret_value = H5I_INVALID_HID; /* Return value */ FUNC_ENTER_API(H5I_INVALID_HID) @@ -222,7 +222,7 @@ H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dcpl_id, dapl_id, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to create dataset") - /* Get an atom for the dataset */ + /* Get an ID for the dataset */ if ((ret_value = H5VL_register(H5I_DATASET, dset, vol_obj->connector, TRUE)) < 0) HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register dataset") @@ -374,13 +374,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation) +H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation /*out*/) { H5VL_object_t *vol_obj = NULL; /* Dataset structure */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Ds", dset_id, allocation); + H5TRACE2("e", "ix", dset_id, allocation); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(dset_id, H5I_DATASET))) @@ -704,14 +704,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id, hsize_t *size) +H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id, hsize_t *size /*out*/) { H5VL_object_t *vol_obj; /* Dataset for this operation */ hbool_t supported; /* Whether 'get vlen buf size' operation is supported by VOL connector */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "iii*h", dataset_id, type_id, space_id, size); + H5TRACE4("e", "iiix", dataset_id, type_id, space_id, size); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object(dataset_id))) @@ -727,7 +727,7 @@ H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id, hsize_t *s supported = FALSE; if (H5VL_introspect_opt_query(vol_obj, H5VL_SUBCLS_DATASET, H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE, &supported) < 0) - HGOTO_ERROR(H5E_FILE, H5E_CANTGET, H5I_INVALID_HID, "can't check for 'get vlen buf size' operation") + HGOTO_ERROR(H5E_DATASET, H5E_CANTGET, FAIL, "can't check for 'get vlen buf size' operation") if (supported) { /* Make the 'get_vlen_buf_size' callback */ if (H5VL_dataset_optional(vol_obj, H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE, H5P_DATASET_XFER_DEFAULT, @@ -911,13 +911,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dget_chunk_index_type(hid_t dset_id, H5D_chunk_index_t *idx_type) +H5Dget_chunk_index_type(hid_t dset_id, H5D_chunk_index_t *idx_type /*out*/) { H5VL_object_t *vol_obj; /* Dataset for this operation */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Dk", dset_id, idx_type); + H5TRACE2("e", "ix", dset_id, idx_type); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(dset_id, H5I_DATASET))) @@ -950,13 +950,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_nbytes) +H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_nbytes /*out*/) { H5VL_object_t *vol_obj; /* Dataset for this operation */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*h*h", dset_id, offset, chunk_nbytes); + H5TRACE3("e", "i*hx", dset_id, offset, chunk_nbytes); /* Check arguments */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(dset_id, H5I_DATASET))) @@ -1043,15 +1043,15 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_index, hsize_t *offset, unsigned *filter_mask, - haddr_t *addr, hsize_t *size) +H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_index, hsize_t *offset /*out*/, + unsigned *filter_mask /*out*/, haddr_t *addr /*out*/, hsize_t *size /*out*/) { H5VL_object_t *vol_obj = NULL; /* Dataset for this operation */ hsize_t nchunks = 0; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE7("e", "iih*h*Iu*a*h", dset_id, fspace_id, chk_index, offset, filter_mask, addr, size); + H5TRACE7("e", "iihxxxx", dset_id, fspace_id, chk_index, offset, filter_mask, addr, size); /* Check arguments */ if (NULL == offset && NULL == filter_mask && NULL == addr && NULL == size) @@ -1100,14 +1100,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, unsigned *filter_mask, haddr_t *addr, - hsize_t *size) +H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, unsigned *filter_mask /*out*/, + haddr_t *addr /*out*/, hsize_t *size /*out*/) { H5VL_object_t *vol_obj = NULL; /* Dataset for this operation */ herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*h*Iu*a*h", dset_id, offset, filter_mask, addr, size); + H5TRACE5("e", "i*hxxx", dset_id, offset, filter_mask, addr, size); /* Check arguments */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(dset_id, H5I_DATASET))) diff --git a/src/H5Dchunk.c b/src/H5Dchunk.c index 1ca6e9f..e7923fb 100644 --- a/src/H5Dchunk.c +++ b/src/H5Dchunk.c @@ -4978,9 +4978,9 @@ H5D__chunk_collective_fill(const H5D_t *dset, H5D_chunk_coll_info_t *chunk_info, HGOTO_ERROR(H5E_DATASET, H5E_BADVALUE, FAIL, "Resulted in division by zero") num_blocks = (size_t)(chunk_info->num_io / (size_t)mpi_size); /* value should be the same on all procs */ - /* after evenly distributing the blocks between processes, are - there any leftover blocks for each individual process - (round-robin) */ + /* After evenly distributing the blocks between processes, are there any + * leftover blocks for each individual process (round-robin)? + */ leftover_blocks = (size_t)(chunk_info->num_io % (size_t)mpi_size); /* Cast values to types needed by MPI */ diff --git a/src/H5Ddeprec.c b/src/H5Ddeprec.c index 40104be..1c66f26 100644 --- a/src/H5Ddeprec.c +++ b/src/H5Ddeprec.c @@ -15,7 +15,7 @@ * * Created: H5Ddeprec.c * April 5 2007 - * Quincey Koziol + * Quincey Koziol * * Purpose: Deprecated functions from the H5D interface. These * functions are here for compatibility purposes and may be @@ -137,13 +137,13 @@ H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t if (NULL == (vol_obj = H5VL_vol_object(loc_id))) HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, H5I_INVALID_HID, "invalid location identifier") - /* Create the dataset through the VOL */ + /* Create the dataset */ if (NULL == (dset = H5VL_dataset_create(vol_obj, &loc_params, name, H5P_LINK_CREATE_DEFAULT, type_id, space_id, dcpl_id, H5P_DATASET_ACCESS_DEFAULT, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) HGOTO_ERROR(H5E_DATASET, H5E_CANTINIT, H5I_INVALID_HID, "unable to create dataset") - /* Get an atom for the dataset */ + /* Register the new dataset to get an ID for it */ if ((ret_value = H5VL_register(H5I_DATASET, dset, vol_obj->connector, TRUE)) < 0) HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to register dataset") @@ -202,9 +202,9 @@ H5Dopen1(hid_t loc_id, const char *name) H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) HGOTO_ERROR(H5E_DATASET, H5E_CANTOPENOBJ, H5I_INVALID_HID, "unable to open dataset") - /* Get an atom for the dataset */ + /* Get an ID for the dataset */ if ((ret_value = H5VL_register(H5I_DATASET, dset, vol_obj->connector, TRUE)) < 0) - HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "can't register dataset atom") + HGOTO_ERROR(H5E_DATASET, H5E_CANTREGISTER, H5I_INVALID_HID, "can't register dataset ID") done: if (H5I_INVALID_HID == ret_value) diff --git a/src/H5Dearray.c b/src/H5Dearray.c index 64b1e20..db77a4c 100644 --- a/src/H5Dearray.c +++ b/src/H5Dearray.c @@ -418,8 +418,8 @@ H5D__earray_debug(FILE *stream, int indent, int fwidth, hsize_t idx, const void HDassert(elmt); /* Print element */ - HDsprintf(temp_str, "Element #%llu:", (unsigned long long)idx); - HDfprintf(stream, "%*s%-*s %a\n", indent, "", fwidth, temp_str, *(const haddr_t *)elmt); + HDsprintf(temp_str, "Element #%" PRIuHSIZE ":", idx); + HDfprintf(stream, "%*s%-*s %" PRIuHADDR "\n", indent, "", fwidth, temp_str, *(const haddr_t *)elmt); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__earray_debug() */ @@ -574,9 +574,9 @@ H5D__earray_filt_debug(FILE *stream, int indent, int fwidth, hsize_t idx, const HDassert(elmt); /* Print element */ - HDsprintf(temp_str, "Element #%llu:", (unsigned long long)idx); - HDfprintf(stream, "%*s%-*s {%a, %u, %0x}\n", indent, "", fwidth, temp_str, elmt->addr, elmt->nbytes, - elmt->filter_mask); + HDsprintf(temp_str, "Element #%" PRIuHSIZE ":", idx); + HDfprintf(stream, "%*s%-*s {%" PRIuHADDR ", %u, %0x}\n", indent, "", fwidth, temp_str, elmt->addr, + elmt->nbytes, elmt->filter_mask); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__earray_filt_debug() */ @@ -1743,7 +1743,7 @@ H5D__earray_idx_dump(const H5O_storage_chunk_t *storage, FILE *stream) HDassert(storage); HDassert(stream); - HDfprintf(stream, " Address: %a\n", storage->idx_addr); + HDfprintf(stream, " Address: %" PRIuHADDR "\n", storage->idx_addr); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__earray_idx_dump() */ diff --git a/src/H5Dfarray.c b/src/H5Dfarray.c index d9f80a6..8293ec4 100644 --- a/src/H5Dfarray.c +++ b/src/H5Dfarray.c @@ -416,8 +416,8 @@ H5D__farray_debug(FILE *stream, int indent, int fwidth, hsize_t idx, const void HDassert(elmt); /* Print element */ - HDsprintf(temp_str, "Element #%llu:", (unsigned long long)idx); - HDfprintf(stream, "%*s%-*s %a\n", indent, "", fwidth, temp_str, *(const haddr_t *)elmt); + HDsprintf(temp_str, "Element #%" PRIuHSIZE ":", idx); + HDfprintf(stream, "%*s%-*s %" PRIuHADDR "\n", indent, "", fwidth, temp_str, *(const haddr_t *)elmt); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__farray_debug() */ @@ -676,9 +676,9 @@ H5D__farray_filt_debug(FILE *stream, int indent, int fwidth, hsize_t idx, const HDassert(elmt); /* Print element */ - HDsprintf(temp_str, "Element #%llu:", (unsigned long long)idx); - HDfprintf(stream, "%*s%-*s {%a, %u, %0x}\n", indent, "", fwidth, temp_str, elmt->addr, elmt->nbytes, - elmt->filter_mask); + HDsprintf(temp_str, "Element #%" PRIuHSIZE ":", idx); + HDfprintf(stream, "%*s%-*s {%" PRIuHADDR ", %u, %0x}\n", indent, "", fwidth, temp_str, elmt->addr, + elmt->nbytes, elmt->filter_mask); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__farray_filt_debug() */ @@ -1592,7 +1592,7 @@ H5D__farray_idx_dump(const H5O_storage_chunk_t *storage, FILE *stream) HDassert(storage); HDassert(stream); - HDfprintf(stream, " Address: %a\n", storage->idx_addr); + HDfprintf(stream, " Address: %" PRIuHADDR "\n", storage->idx_addr); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__farray_idx_dump() */ diff --git a/src/H5Dfill.c b/src/H5Dfill.c index 9588446..b7ecdc9 100644 --- a/src/H5Dfill.c +++ b/src/H5Dfill.c @@ -15,7 +15,7 @@ * * Created: H5Dfill.c * Jun 19 2007 - * Quincey Koziol + * Quincey Koziol * * Purpose: Fill value operations for datasets * @@ -642,7 +642,7 @@ done: static herr_t H5D__fill_release(H5D_fill_buf_info_t *fb_info) { - FUNC_ENTER_PACKAGE_NOERR + FUNC_ENTER_STATIC_NOERR /* Check args */ HDassert(fb_info); diff --git a/src/H5Dio.c b/src/H5Dio.c index 75727a9..e28da8c 100644 --- a/src/H5Dio.c +++ b/src/H5Dio.c @@ -926,7 +926,7 @@ H5D__typeinfo_init(const H5D_t *dset, hid_t mem_type_id, hbool_t do_write, H5D_t /* Locate the type conversion function and dataspace conversion * functions, and set up the element numbering information. If a data - * type conversion is necessary then register datatype atoms. Data type + * type conversion is necessary then register datatype IDs. Data type * conversion is necessary if the user has set the `need_bkg' to a high * enough value in xfer_parms since turning off datatype conversion also * turns off background preservation. diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index 292b624..595c714 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -29,15 +29,37 @@ #define H5_MY_PKG_ERR H5E_DATASET #define H5_MY_PKG_INIT YES -/** - * \defgroup H5D H5D - * \brief Group Interface - * \details The HDF5 Dataset Interface, H5D, provides a mechanism for managing - * HDF5 datasets, including the transfer of data between memory and - * disk and the description of dataset properties. +/**\defgroup H5D H5D + * + * Use the functions in this module to manage HDF5 datasets, including the + * transfer of data between memory and disk and the description of dataset + * properties. Datasets are used by other HDF5 APIs and referenced either by + * name or by a handle. Such handles can be obtained by either creating or + * opening the dataset. + * + * Typical stages in the HDF5 dataset life cycle are shown below in introductory + * examples. + * + * + * + * + * + * + * + * + * + * + * + *
CreateRead
+ * \snippet H5D_examples.c create + * + * \snippet H5D_examples.c read + *
UpdateDelete
+ * \snippet H5D_examples.c update + * + * \snippet H5D_examples.c delete + *
* - * A Dataset is used by other HDF5 APIs, either by name or by a handle, - * which is obtained by either creating or opening the dataset. */ #endif /* H5Dmodule_H */ diff --git a/src/H5Dnone.c b/src/H5Dnone.c index 507741c..f724949 100644 --- a/src/H5Dnone.c +++ b/src/H5Dnone.c @@ -11,7 +11,7 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Vailin Choi +/* Programmer: Vailin Choi * September 2010 * * Purpose: Implicit (Non Index) chunked I/O functions. @@ -471,7 +471,7 @@ H5D__none_idx_dump(const H5O_storage_chunk_t *storage, FILE *stream) HDassert(storage); HDassert(stream); - HDfprintf(stream, " Address: %a\n", storage->idx_addr); + HDfprintf(stream, " Address: %" PRIuHADDR "\n", storage->idx_addr); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__none_idx_dump() */ diff --git a/src/H5Dscatgath.c b/src/H5Dscatgath.c index e8b70e3..34f35cd 100644 --- a/src/H5Dscatgath.c +++ b/src/H5Dscatgath.c @@ -370,7 +370,7 @@ H5D__gather_mem(const void *_buf, H5S_sel_iter_t *iter, size_t nelmts, void *_tg size_t vec_size; /* Vector length */ size_t ret_value = nelmts; /* Number of elements gathered */ - FUNC_ENTER_STATIC + FUNC_ENTER_PACKAGE /* Check args */ HDassert(buf); diff --git a/src/H5Dsingle.c b/src/H5Dsingle.c index 09f7115..eba569e 100644 --- a/src/H5Dsingle.c +++ b/src/H5Dsingle.c @@ -11,7 +11,7 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Vailin Choi +/* Programmer: Vailin Choi * May 2011; updated 10/2015 * * Purpose: Single Chunk I/O functions. @@ -522,7 +522,7 @@ H5D__single_idx_dump(const H5O_storage_chunk_t *storage, FILE *stream) HDassert(storage); HDassert(stream); - HDfprintf(stream, " Address: %a\n", storage->idx_addr); + HDfprintf(stream, " Address: %" PRIuHADDR "\n", storage->idx_addr); FUNC_LEAVE_NOAPI(SUCCEED) } /* end H5D__single_idx_dump() */ diff --git a/src/H5Dtest.c b/src/H5Dtest.c index 4317124..f37682d 100644 --- a/src/H5Dtest.c +++ b/src/H5Dtest.c @@ -11,7 +11,7 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Quincey Koziol +/* Programmer: Quincey Koziol * Thursday, May 27, 2004 * * Purpose: Dataset testing functions. diff --git a/src/H5Dvirtual.c b/src/H5Dvirtual.c index 235665f..d1c0266 100644 --- a/src/H5Dvirtual.c +++ b/src/H5Dvirtual.c @@ -2310,7 +2310,7 @@ H5D__virtual_is_data_cached(const H5D_shared_t *shared_dset) size_t i, j; /* Local index variables */ hbool_t ret_value = FALSE; /* Return value */ - FUNC_ENTER_PACKAGE_NOERR + FUNC_ENTER_STATIC_NOERR /* Sanity checks */ HDassert(shared_dset); diff --git a/src/H5Emodule.h b/src/H5Emodule.h index 1670c03..43d5d36 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -29,4 +29,33 @@ #define H5_MY_PKG_ERR H5E_ERROR #define H5_MY_PKG_INIT YES +/** + * \defgroup H5E H5E + * \brief Error Handling Interface + * + * \details The Error interface provides error handling in the form of a stack. + * The \Code{FUNC_ENTER} macro clears the error stack whenever an + * interface function is entered. When an error is detected, an entry + * is pushed onto the stack. As the functions unwind, additional + * entries are pushed onto the stack. The API function will return some + * indication that an error occurred and the application can print the + * error stack. + * + * Certain API functions in the \c H5E package, such as H5Eprint1(), do + * not clear the error stack. Otherwise, any function which does not + * have an underscore immediately after the package name will clear the + * error stack. For instance, H5Fopen() clears the error stack while + * \Code{H5F_open} does not. + * + * An error stack has a fixed maximum size. If this size is exceeded + * then the stack will be truncated and only the inner-most functions + * will have entries on the stack. This is expected to be a rare + * condition. + * + * Each thread has its own error stack, but since multi-threading has + * not been added to the library yet, this package maintains a single + * error stack. The error stack is statically allocated to reduce the + * complexity of handling errors within the \c H5E package. + */ + #endif /* H5Emodule_H */ diff --git a/src/H5Epublic.h b/src/H5Epublic.h index 685665a..5d15db9 100644 --- a/src/H5Epublic.h +++ b/src/H5Epublic.h @@ -26,18 +26,29 @@ /* Value for the default error stack */ #define H5E_DEFAULT (hid_t)0 -/* Different kinds of error information */ +/** + * Different kinds of error information + */ typedef enum H5E_type_t { H5E_MAJOR, H5E_MINOR } H5E_type_t; -/* Information about an error; element of error stack */ +/** + * Information about an error; element of error stack + */ typedef struct H5E_error2_t { - hid_t cls_id; /*class ID */ - hid_t maj_num; /*major error ID */ - hid_t min_num; /*minor error number */ - unsigned line; /*line in file where error occurs */ - const char *func_name; /*function in which error occurred */ - const char *file_name; /*file in which error occurred */ - const char *desc; /*optional supplied description */ + hid_t cls_id; + /**< Class ID */ + hid_t maj_num; + /**< Major error ID */ + hid_t min_num; + /**< Minor error number */ + unsigned line; + /**< Line in file where error occurs */ + const char *func_name; + /**< Function in which error occurred */ + const char *file_name; + /**< File in which error occurred */ + const char *desc; + /**< Optional supplied description */ } H5E_error2_t; /* When this header is included from a private header, don't make calls to H5open() */ @@ -61,12 +72,12 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; * trying something that's likely or expected to fail. The code to try can * be nested between calls to H5Eget_auto() and H5Eset_auto(), but it's * easier just to use this macro like: - * H5E_BEGIN_TRY { - * ...stuff here that's likely to fail... + * H5E_BEGIN_TRY { + * ...stuff here that's likely to fail... * } H5E_END_TRY; * * Warning: don't break, return, or longjmp() from the body of the loop or - * the error reporting won't be properly restored! + * the error reporting won't be properly restored! * * These two macros still use the old API functions for backward compatibility * purpose. @@ -124,10 +135,10 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in */ /* And return after pushing error onto stack */ #define H5Epush_ret(func, cls, maj, min, str, ret) \ - { \ + do { \ H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str); \ return (ret); \ - } + } while (0) /* Use the Standard C __FILE__ & __LINE__ macros instead of typing them in * And goto a label after pushing error onto stack. @@ -138,10 +149,12 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; goto label; \ } -/* Error stack traversal direction */ +/** + * Error stack traversal direction + */ typedef enum H5E_direction_t { - H5E_WALK_UPWARD = 0, /*begin deep, end at API function */ - H5E_WALK_DOWNWARD = 1 /*begin at API function, end deep */ + H5E_WALK_UPWARD = 0, /**< begin w/ most specific error, end at API function */ + H5E_WALK_DOWNWARD = 1 /**< begin at API function, end w/ most specific error */ } H5E_direction_t; #ifdef __cplusplus @@ -149,29 +162,478 @@ extern "C" { #endif /* Error stack traversal callback function pointers */ +//! +/** + * \brief Callback function for H5Ewalk2() + * + * \param[in] n Indexed error position in the stack + * \param[in] err_desc Pointer to a data structure describing the error + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data); +//! + +//! +/** + * \brief Callback function for H5Eset_auto2() + * + * \estack_id{estack} + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data); +//! /* Public API functions */ -H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version); -H5_DLL herr_t H5Eunregister_class(hid_t class_id); -H5_DLL herr_t H5Eclose_msg(hid_t err_id); -H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); -H5_DLL hid_t H5Ecreate_stack(void); -H5_DLL hid_t H5Eget_current_stack(void); -H5_DLL herr_t H5Eclose_stack(hid_t stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Registers a client library or application program to the HDF5 error API + * + * \param[in] cls_name Name of the error class + * \param[in] lib_name Name of the client library or application to which the error class belongs + * \param[in] version Version of the client library or application to which the + error class belongs. Can be \c NULL. + * \return Returns a class identifier on success; otherwise returns H5I_INVALID_ID. + * + * \details H5Eregister_class() registers a client library or application + * program to the HDF5 error API so that the client library or + * application program can report errors together with the HDF5 + * library. It receives an identifier for this error class for further + * error operations. The library name and version number will be + * printed out in the error message as a preamble. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Removes an error class + * + * \param[in] class_id Error class identifier. + * \return \herr_t + * + * \details H5Eunregister_class() removes the error class specified by \p + * class_id. All the major and minor errors in this class will also be + * closed. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eunregister_class(hid_t class_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Closes an error message + * + * \param[in] err_id An error message identifier + * \return \herr_t + * + * \details H5Eclose_msg() closes an error message identifier, which can be + * either a major or minor message. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclose_msg(hid_t err_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Adds a major error message to an error class + * + * \param[in] cls An error class identifier + * \param[in] msg_type The type of the error message + * \param[in] msg Major error message + * \return \herr_t + * + * \details H5Ecreate_msg() adds an error message to an error class defined by + * client library or application program. The error message can be + * either major or minor as indicated by the parameter \p msg_type. + * + * Use H5Eclose_msg() to close the message identifier returned by this + * function. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Creates a new, empty error stack + * + * \return \hid_ti{error stack} + * + * \details H5Ecreate_stack() creates a new empty error stack and returns the + * new stack’s identifier. Use H5Eclose_stack() to close the error stack + * identifier returned by this function. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Ecreate_stack(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a copy of the current error stack + * + * \return \hid_ti{error stack} + * + * \details H5Eget_current_stack() copies the current error stack and returns an + * error stack identifier for the new copy. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Eget_current_stack(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Closes an error stack handle + * + * \estack_id{stack_id} + * + * \return \herr_t + * + * \details H5Eclose_stack() closes the error stack handle \p stack_id + * and releases its resources. #H5E_DEFAULT cannot be closed. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclose_stack(hid_t stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves error class name + * + * \param[in] class_id Error class identifier + * \param[out] name Buffer for the error class name + * \param[in] size The maximum number of characters the class name to be returned + * by this function in\p name. + * \return Returns non-negative value as on success; otherwise returns negative value. + * + * \details H5Eget_class_name() retrieves the name of the error class specified + * by the class identifier. If non-NULL pointer is passed in for \p + * name and \p size is greater than zero, the class name of \p size + * long is returned. The length of the error class name is also + * returned. If NULL is passed in as \p name, only the length of class + * name is returned. If zero is returned, it means no name. The user is + * responsible for allocating sufficient buffer space for the name. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size); -H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); -H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, - hid_t maj_id, hid_t min_id, const char *msg, ...); -H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); -H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); -H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data); -H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); -H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); -H5_DLL herr_t H5Eclear2(hid_t err_stack); -H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Replaces the current error stack + * + * \estack_id{err_stack_id} + * + * \return \herr_t + * + * \details H5Eset_current_stack() replaces the content of the current error + * stack with a copy of the content of the error stack specified by + * \p err_stack_id, and it closes the error stack specified by + * \p err_stack_id. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Pushes a new error record onto an error stack + * + * \estack_id{err_stack}. If the identifier is #H5E_DEFAULT, the error record + * will be pushed to the current stack. + * \param[in] file Name of the file in which the error was detected + * \param[in] func Name of the function in which the error was detected + * \param[in] line Line number in the file where the error was detected + * \param[in] cls_id Error class identifier + * \param[in] maj_id Major error identifier + * \param[in] min_id Minor error identifier + * \param[in] msg Error description string + * \return \herr_t + * + * \details H5Epush2() pushes a new error record onto the error stack specified + * by \p err_stack.\n + * The error record contains the error class identifier \p cls_id, the + * major and minor message identifiers \p maj_id and \p min_id, the + * function name \p func where the error was detected, the file name \p + * file and line number \p line in the file where the error was + * detected, and an error description \p msg.\n + * The major and minor errors must be in the same error class.\n + * The function name, filename, and error description strings must be + * statically allocated.\n + * \p msg can be a format control string with additional + * arguments. This design of appending additional arguments is similar + * to the system and C functions printf() and fprintf(). + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, + hid_t maj_id, hid_t min_id, const char *msg, ...); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Deletes specified number of error messages from the error stack + * + * \estack_id{err_stack} + * \param[in] count The number of error messages to be deleted from the top + * of error stack + * \return \herr_t + * + * \details H5Epop() deletes the number of error records specified in \p count + * from the top of the error stack specified by \p err_stack (including + * major, minor messages and description). The number of error messages + * to be deleted is specified by \p count. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Prints the specified error stack in a default manner + * + * \estack_id{err_stack} + * \param[in] stream File pointer, or \c NULL for \c stderr + * \return \herr_t + * + * \details H5Eprint2() prints the error stack specified by \p err_stack on the + * specified stream, \p stream. Even if the error stack is empty, a + * one-line message of the following form will be printed: + * \code{.unparsed} + * HDF5-DIAG: Error detected in HDF5 library version: 1.5.62 thread 0. + * \endcode + * + * A similar line will appear before the error messages of each error + * class stating the library name, library version number, and thread + * identifier. + * + * If \p err_stack is #H5E_DEFAULT, the current error stack will be + * printed. + * + * H5Eprint2() is a convenience function for H5Ewalk2() with a function + * that prints error messages. Users are encouraged to write their own + * more specific error handlers. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Walks the specified error stack, calling the specified function + * + * \estack_id{err_stack} + * \param[in] direction Direction in which the error stack is to be walked + * \param[in] func Function to be called for each error encountered + * \param[in] client_data Data to be passed to \p func + * \return \herr_t + * + * \details H5Ewalk2() walks the error stack specified by err_stack for the + * current thread and calls the function specified in \p func for each + * error along the way. + * + * If the value of \p err_stack is #H5E_DEFAULT, then H5Ewalk2() walks + * the current error stack. + * + * \p direction specifies whether the stack is walked from the inside + * out or the outside in. A value of #H5E_WALK_UPWARD means to begin + * with the most specific error and end at the API; a value of + * #H5E_WALK_DOWNWARD means to start at the API and end at the + * innermost function where the error was first detected. + * + * \p func, a function conforming to the #H5E_walk2_t prototype, will + * be called for each error in the error stack. Its arguments will + * include an index number \c n (beginning at zero regardless of stack + * traversal direction), an error stack entry \c err_desc, and the \c + * client_data pointer passed to H5Eprint(). The #H5E_walk2_t prototype + * is as follows: + * \snippet this H5E_walk2_t_snip + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns the settings for the automatic error stack traversal + * function and its data + * + * \estack_id + * \param[out] func The function currently set to be called upon an error condition + * \param[out] client_data Data currently set to be passed to the error function + * \return \herr_t + * + * \details H5Eget_auto2() returns the settings for the automatic error stack + * traversal function, \p func, and its data, \p client_data, that are + * associated with the error stack specified by \p estack_id. + * + * Either or both of the \p func and \p client_data arguments may be + * \c NULL, in which case the value is not returned. + * + * The library initializes its default error stack traversal functions + * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns + * H5Eprint2() or the user-defined function passed in through + * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the + * user-defined function passed in through H5Eset_auto1(). However, if + * the application passes in a user-defined function through + * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal + * function. If the application passes in a user-defined function + * through H5Eset_auto2(), it should call H5Eget_auto2() to query the + * traversal function. + * + * Mixing the new style and the old style functions will cause a + * failure. For example, if the application sets a user-defined + * old-style traversal function through H5Eset_auto1(), a call to + * H5Eget_auto2() will fail and will indicate that the application has + * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing + * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if + * the traversal functions are the library’s default H5Eprint1() or + * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing + * H5Eset_auto2() and H5Eget_auto1() does not fail. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Turns automatic error printing on or off + * + * \estack_id + * \param[in] func Function to be called upon an error condition + * \param[in] client_data Data passed to the error function + * \return \herr_t + * + * \details H5Eset_auto2() turns on or off automatic printing of errors for the + * error stack specified with \p estack_id. An \p estack_id value of + * #H5E_DEFAULT indicates the current stack. + * + * When automatic printing is turned on, by the use of a non-null \p func + * pointer, any API function which returns an error indication will + * first call \p func, passing it \p client_data as an argument. + * + * \p func, a function compliant with the #H5E_auto2_t prototype, is + * defined in the H5Epublic.h source code file as: + * \snippet this H5E_auto2_t_snip + * + * When the library is first initialized, the auto printing function is + * set to H5Eprint2() (cast appropriately) and \p client_data is the + * standard error stream pointer, \c stderr. + * + * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD + * direction. + * + * Automatic error printing is turned off with a H5Eset_auto2() call + * with a \c NULL \p func pointer. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Clears the specified error stack or the error stack for the current thread + * + * \estack_id{err_stack} + * \return \herr_t + * + * \details H5Eclear2() clears the error stack specified by \p err_stack, or, if + * \p err_stack is set to #H5E_DEFAULT, the error stack for the current + * thread. + * + * \p err_stack is an error stack identifier, such as that returned by + * H5Eget_current_stack(). + * + * The current error stack is also cleared whenever an API function is + * called, with certain exceptions (for instance, H5Eprint1() or + * H5Eprint2()). + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclear2(hid_t err_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Determines the type of error stack + * + * \estack_id{err_stack} + * \param[out] is_stack A flag indicating which error stack \c typedef the + * specified error stack conforms to + * + * \return \herr_t + * + * \details H5Eauto_is_v2() determines whether the error auto reporting function + * for an error stack conforms to the #H5E_auto2_t \c typedef or the + * #H5E_auto1_t \c typedef. + * + * The \p is_stack parameter is set to 1 if the error stack conforms to + * #H5E_auto2_t and 0 if it conforms to #H5E_auto1_t. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves an error message + * + * \param[in] msg_id Error message identifier + * \param[out] type The type of the error message Valid values are #H5E_MAJOR + * and #H5E_MINOR. + * \param[out] msg Error message buffer + * \param[in] size The length of error message to be returned by this function + * \return Returns the size of the error message in bytes on success; otherwise + * returns a negative value. + * + * \details H5Eget_msg() retrieves the error message including its length and + * type. The error message is specified by \p msg_id. The user is + * responsible for passing in sufficient buffer space for the + * message. If \p msg is not NULL and \p size is greater than zero, the + * error message of \p size long is returned. The length of the message + * is also returned. If NULL is passed in as \p msg, only the length + * and type of the message is returned. If the return value is zero, it + * means there is no message. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, size_t size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves the number of error messages in an error stack + * + * \estack_id{error_stack_id} + * \return Returns a non-negative value on success; otherwise returns a negative value. + * + * \details H5Eget_num() retrieves the number of error records in the error + * stack specified by \p error_stack_id (including major, minor + * messages and description). + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. @@ -188,30 +650,259 @@ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); typedef hid_t H5E_major_t; typedef hid_t H5E_minor_t; -/* Information about an error element of error stack. */ +/** + * Information about an error element of error stack. + */ typedef struct H5E_error1_t { - H5E_major_t maj_num; /*major error number */ - H5E_minor_t min_num; /*minor error number */ - const char *func_name; /*function in which error occurred */ - const char *file_name; /*file in which error occurred */ - unsigned line; /*line in file where error occurs */ - const char *desc; /*optional supplied description */ + H5E_major_t maj_num; /**< major error number */ + H5E_minor_t min_num; /**< minor error number */ + const char *func_name; /**< function in which error occurred */ + const char *file_name; /**< file in which error occurred */ + unsigned line; /**< line in file where error occurs */ + const char *desc; /**< optional supplied description */ } H5E_error1_t; /* Error stack traversal callback function pointers */ +//! +/** + * \brief Callback function for H5Ewalk1() + * + * \param[in] n Indexed error position in the stack + * \param[in] err_desc Pointer to a data structure describing the error + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data); +//! + +//! +/** + * \brief Callback function for H5Eset_auto1() + * + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_auto1_t)(void *client_data); +//! /* Function prototypes */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Clears the error stack for the current thread + * + * \return \herr_t + * + * \details H5Eclear1() clears the error stack for the current thread.\n + * The stack is also cleared whenever an API function is called, with + * certain exceptions (for instance, H5Eprint1()). + * + * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated + * in this release. + */ H5_DLL herr_t H5Eclear1(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns the current settings for the automatic error stack traversal + * function and its data + * + * \param[out] func Current setting for the function to be called upon an error + * condition + * \param[out] client_data Current setting for the data passed to the error + * function + * \return \herr_t + * + * \details H5Eget_auto1() returns the current settings for the automatic error + * stack traversal function, \p func, and its data, + * \p client_data. Either or both arguments may be \c NULL, in which case the + * value is not returned. + * + * The library initializes its default error stack traversal functions + * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns + * H5Eprint2() or the user-defined function passed in through + * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the + * user-defined function passed in through H5Eset_auto1(). However, if + * the application passes in a user-defined function through + * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal + * function. If the application passes in a user-defined function + * through H5Eset_auto2(), it should call H5Eget_auto2() to query the + * traversal function. + * + * Mixing the new style and the old style functions will cause a + * failure. For example, if the application sets a user-defined + * old-style traversal function through H5Eset_auto1(), a call to + * H5Eget_auto2() will fail and will indicate that the application has + * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing + * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if + * the traversal functions are the library’s default H5Eprint1() or + * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing + * H5Eset_auto2() and H5Eget_auto1() does not fail. + * + * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Pushes a new error record onto the error stack + * + * \param[in] file Name of the file in which the error was detected + * \param[in] func Name of the function in which the error was detected + * \param[in] line Line number in the file where the error was detected + * \param[in] maj Major error identifier + * \param[in] min Minor error identifier + * \param[in] str Error description string + * \return \herr_t + * + * \details H5Epush1() pushes a new error record onto the error stack for the + * current thread.\n + * The error has major and minor numbers \p maj_num + * and \p min_num, the function \p func where the error was detected, the + * name of the file \p file where the error was detected, the line \p line + * within that file, and an error description string \p str.\n + * The function name, filename, and error description strings must be statically + * allocated. + * + * \since 1.4.0 + * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and + * deprecated in this release. + */ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Prints the current error stack in a default manner + * + * \param[in] stream File pointer, or \c NULL for \c stderr + * \return \herr_t + * + * \details H5Eprint1() prints prints the error stack for the current thread + * on the specified stream, \p stream. Even if the error stack is empty, a + * one-line message of the following form will be printed: + * \code{.unparsed} + * HDF5-DIAG: Error detected in thread 0. + * \endcode + * H5Eprint1() is a convenience function for H5Ewalk1() with a function + * that prints error messages. Users are encouraged to write their own + * more specific error handlers. + * + * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eprint1(FILE *stream); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Turns automatic error printing on or off + * + * \param[in] func Function to be called upon an error condition + * \param[in] client_data Data passed to the error function + * \return \herr_t + * + * \details H5Eset_auto1() turns on or off automatic printing of errors. When + * turned on (non-null \p func pointer), any API function which returns + * an error indication will first call \p func, passing it \p + * client_data as an argument. + * + * \p func, a function conforming to the #H5E_auto1_t prototype, is + * defined in the H5Epublic.h source code file as: + * \snippet this H5E_auto1_t_snip + * + * When the library is first initialized, the auto printing function is + * set to H5Eprint1() (cast appropriately) and \p client_data is the + * standard error stream pointer, \c stderr. + * + * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD + * direction. + * + * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Walks the current error stack, calling the specified function + * + * \param[in] direction Direction in which the error stack is to be walked + * \param[in] func Function to be called for each error encountered + * \param[in] client_data Data to be passed to \p func + * \return \herr_t + * + * \details H5Ewalk1() walks the error stack for the current thread and calls + * the function specified in \p func for each error along the way. + * + * \p direction specifies whether the stack is walked from the inside + * out or the outside in. A value of #H5E_WALK_UPWARD means to begin + * with the most specific error and end at the API; a value of + * #H5E_WALK_DOWNWARD means to start at the API and end at the + * innermost function where the error was first detected. + * + * \p func, a function conforming to the #H5E_walk1_t prototype, will + * be called for each error in the error stack. Its arguments will + * include an index number \c n (beginning at zero regardless of stack + * traversal direction), an error stack entry \c err_desc, and the \c + * client_data pointer passed to H5Eprint(). The #H5E_walk1_t prototype + * is as follows: + * \snippet this H5E_walk1_t_snip + * + * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and + * deprecated in this release. + */ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data); -H5_DLL char * H5Eget_major(H5E_major_t maj); -H5_DLL char * H5Eget_minor(H5E_minor_t min); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a character string describing an error specified by a major + * error number + * + * \param[in] maj Major error number + * \return \herr_t + * + * \details Given a major error number, H5Eget_major() returns a constant + * character string that describes the error. + * + * \attention This function returns a dynamically allocated string (\c char + * array). An application calling this function must free the memory + * associated with the return value to prevent a memory leak. + * + * \deprecated 1.8.0 Function deprecated in this release. + */ +H5_DLL char *H5Eget_major(H5E_major_t maj); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a character string describing an error specified by a minor + * error number + * + * \param[in] min Minor error number + * \return \herr_t + * + * \details Given a minor error number, H5Eget_minor() returns a constant + * character string that describes the error. + * + * \attention In the Release 1.8.x series, H5Eget_minor() returns a string of + * dynamic allocated \c char array. An application calling this + * function from an HDF5 library of Release 1.8.0 or later must free + * the memory associated with the return value to prevent a memory + * leak. This is a change from the 1.6.x release series. + * + * \deprecated 1.8.0 Function deprecated and return type changed in this release. + */ +H5_DLL char *H5Eget_minor(H5E_minor_t min); #endif /* H5_NO_DEPRECATED_SYMBOLS */ #ifdef __cplusplus diff --git a/src/H5Fspace.c b/src/H5Fspace.c index b92fa64..29495f1 100644 --- a/src/H5Fspace.c +++ b/src/H5Fspace.c @@ -15,7 +15,7 @@ * * Created: H5Fspace.c * Dec 30 2013 - * Quincey Koziol + * Quincey Koziol * * Purpose: Space allocation routines for the file. * diff --git a/src/H5Fsuper_cache.c b/src/H5Fsuper_cache.c index 2daa34e..7d1ff86 100644 --- a/src/H5Fsuper_cache.c +++ b/src/H5Fsuper_cache.c @@ -15,7 +15,7 @@ * * Created: H5Fsuper_cache.c * Aug 15 2009 - * Quincey Koziol + * Quincey Koziol * * Purpose: Implement file superblock & driver info metadata cache methods. * @@ -294,7 +294,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 17, 2013 * *------------------------------------------------------------------------- @@ -322,7 +321,6 @@ H5F__cache_superblock_get_initial_load_size(void H5_ATTR_UNUSED *_udata, size_t * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@lbl.gov * November 17, 2016 * *------------------------------------------------------------------------- @@ -410,7 +408,6 @@ H5F__cache_superblock_verify_chksum(const void *_image, size_t len, void *_udata * Failure: NULL * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 18 2013 * *------------------------------------------------------------------------- @@ -603,7 +600,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 19, 2013 * *------------------------------------------------------------------------- @@ -635,7 +631,6 @@ H5F__cache_superblock_image_len(const void *_thing, size_t *image_len) * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 19 2013 * *------------------------------------------------------------------------- @@ -777,7 +772,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 20, 2013 * *------------------------------------------------------------------------- @@ -811,7 +805,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 20, 2013 * *------------------------------------------------------------------------- @@ -838,7 +831,6 @@ H5F__cache_drvrinfo_get_initial_load_size(void H5_ATTR_UNUSED *_udata, size_t *i * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@lbl.gov * November 17, 2016 * *------------------------------------------------------------------------- @@ -881,7 +873,6 @@ done: * Failure: NULL * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 20 2013 * *------------------------------------------------------------------------- @@ -941,7 +932,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 20, 2013 * *------------------------------------------------------------------------- @@ -974,7 +964,6 @@ H5F__cache_drvrinfo_image_len(const void *_thing, size_t *image_len) * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 20 2013 * *------------------------------------------------------------------------- @@ -1036,7 +1025,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * July 20, 2013 * *------------------------------------------------------------------------- diff --git a/src/H5Groot.c b/src/H5Groot.c index 28b94c8..997d187 100644 --- a/src/H5Groot.c +++ b/src/H5Groot.c @@ -15,7 +15,7 @@ * * Created: H5Groot.c * Apr 8 2009 - * Neil Fortner + * Neil Fortner * * Purpose: Functions for operating on the root group. * @@ -126,7 +126,6 @@ H5G_rootof(H5F_t *f) * Return: Non-negative on success/Negative on failure * * Programmer: Robb Matzke - * matzke@llnl.gov * Aug 11 1997 * *------------------------------------------------------------------------- @@ -357,7 +356,6 @@ H5G_root_free(H5G_t *grp) * Failure: Negative * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Mar 5 2007 * *------------------------------------------------------------------------- diff --git a/src/H5Gtest.c b/src/H5Gtest.c index 0d21f22..65a5743 100644 --- a/src/H5Gtest.c +++ b/src/H5Gtest.c @@ -798,7 +798,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Neil Fortner - * nfortne2@hdfgroup.org * April 6 2011 * *------------------------------------------------------------------------- diff --git a/src/H5Gtraverse.c b/src/H5Gtraverse.c index 480d5da..bbd8973 100644 --- a/src/H5Gtraverse.c +++ b/src/H5Gtraverse.c @@ -345,7 +345,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Nov 20 2006 * *------------------------------------------------------------------------- @@ -450,7 +449,6 @@ done: * resolved. * * Programmer: Robb Matzke - * matzke@llnl.gov * Aug 11 1997 * *------------------------------------------------------------------------- @@ -819,7 +817,7 @@ H5G_traverse(const H5G_loc_t *loc, const char *name, unsigned target, H5G_traver /* Retrieve the original # of soft / UD links that are able to be traversed * (So that multiple calls to H5G_traverse don't incorrectly look - * like they've traversed too many. Nested calls, like in H5L_move(), + * like they've traversed too many. Nested calls, like in H5L__move(), * may need their own mechanism to set & reset the # of links to traverse) */ if (H5CX_get_nlinks(&orig_nlinks) < 0) diff --git a/src/H5HFbtree2.c b/src/H5HFbtree2.c index f8ed4fb..353d7d7 100644 --- a/src/H5HFbtree2.c +++ b/src/H5HFbtree2.c @@ -15,7 +15,7 @@ * * Created: H5HFbtree2.c * Aug 7 2006 - * Quincey Koziol + * Quincey Koziol * * Purpose: v2 B-tree callbacks for "huge" object tracker * @@ -434,8 +434,8 @@ H5HF__huge_bt2_indir_debug(FILE *stream, int indent, int fwidth, const void *_nr FUNC_ENTER_STATIC_NOERR - HDfprintf(stream, "%*s%-*s {%a, %Hu, %Hu}\n", indent, "", fwidth, "Record:", nrecord->addr, nrecord->len, - nrecord->id); + HDfprintf(stream, "%*s%-*s {%" PRIuHADDR ", %" PRIuHSIZE ", %" PRIuHSIZE "}\n", indent, "", fwidth, + "Record:", nrecord->addr, nrecord->len, nrecord->id); FUNC_LEAVE_NOAPI(SUCCEED) } /* H5HF__huge_bt2_indir_debug() */ @@ -636,8 +636,9 @@ H5HF__huge_bt2_filt_indir_debug(FILE *stream, int indent, int fwidth, const void FUNC_ENTER_STATIC_NOERR - HDfprintf(stream, "%*s%-*s {%a, %Hu, %x, %Hu, %Hu}\n", indent, "", fwidth, "Record:", nrecord->addr, - nrecord->len, nrecord->filter_mask, nrecord->obj_size, nrecord->id); + HDfprintf(stream, "%*s%-*s {%" PRIuHADDR ", %" PRIuHSIZE ", %x, %" PRIuHSIZE ", %" PRIuHSIZE "}\n", + indent, "", fwidth, "Record:", nrecord->addr, nrecord->len, nrecord->filter_mask, + nrecord->obj_size, nrecord->id); FUNC_LEAVE_NOAPI(SUCCEED) } /* H5HF__huge_bt2_filt_indir_debug() */ @@ -818,7 +819,8 @@ H5HF__huge_bt2_dir_debug(FILE *stream, int indent, int fwidth, const void *_nrec FUNC_ENTER_STATIC_NOERR - HDfprintf(stream, "%*s%-*s {%a, %Hu}\n", indent, "", fwidth, "Record:", nrecord->addr, nrecord->len); + HDfprintf(stream, "%*s%-*s {%" PRIuHADDR ", %" PRIuHSIZE "}\n", indent, "", fwidth, + "Record:", nrecord->addr, nrecord->len); FUNC_LEAVE_NOAPI(SUCCEED) } /* H5HF__huge_bt2_dir_debug() */ @@ -1028,8 +1030,8 @@ H5HF__huge_bt2_filt_dir_debug(FILE *stream, int indent, int fwidth, const void * FUNC_ENTER_STATIC_NOERR - HDfprintf(stream, "%*s%-*s {%a, %Hu, %x, %Hu}\n", indent, "", fwidth, "Record:", nrecord->addr, - nrecord->len, nrecord->filter_mask, nrecord->obj_size); + HDfprintf(stream, "%*s%-*s {%" PRIuHADDR ", %" PRIuHSIZE ", %x, %" PRIuHSIZE "}\n", indent, "", fwidth, + "Record:", nrecord->addr, nrecord->len, nrecord->filter_mask, nrecord->obj_size); FUNC_LEAVE_NOAPI(SUCCEED) } /* H5HF__huge_bt2_filt_dir_debug() */ diff --git a/src/H5HFdblock.c b/src/H5HFdblock.c index 3ad9d67..657306b 100644 --- a/src/H5HFdblock.c +++ b/src/H5HFdblock.c @@ -15,7 +15,7 @@ * * Created: H5HFdblock.c * Apr 10 2006 - * Quincey Koziol + * Quincey Koziol * * Purpose: Direct block routines for fractal heaps. * @@ -77,7 +77,6 @@ H5FL_DEFINE(H5HF_direct_t); * Return: Pointer to new direct block on success, NULL on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 27 2006 * *------------------------------------------------------------------------- @@ -212,7 +211,6 @@ done: * Return: SUCCEED/FAIL * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * May 17 2006 * *------------------------------------------------------------------------- @@ -325,7 +323,6 @@ done: * Return: SUCCEED/FAIL * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Mar 13 2006 * *------------------------------------------------------------------------- @@ -399,7 +396,7 @@ H5HF__man_dblock_new(H5HF_hdr_t *hdr, size_t request, H5HF_free_section_t **ret_ if (min_dblock_size > next_size) { HDfprintf( stderr, - "%s: Skipping direct block sizes not supported, min_dblock_size = %Zu, next_size = %Zu\n", + "%s: Skipping direct block sizes not supported, min_dblock_size = %zu, next_size = %zu\n", FUNC, min_dblock_size, next_size); HGOTO_ERROR(H5E_HEAP, H5E_UNSUPPORTED, FAIL, "skipping direct block sizes not supported yet") } /* end if */ @@ -426,7 +423,6 @@ done: * Return: Pointer to direct block on success, NULL on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Apr 17 2006 * *------------------------------------------------------------------------- @@ -508,7 +504,6 @@ done: * Return: SUCCEED/FAIL * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * May 8 2006 * *------------------------------------------------------------------------- @@ -617,7 +612,6 @@ done: * Return: SUCCEED/FAIL * * Programmer: Quincey Koziol - * koziol@hdfgroup.org * Aug 7 2006 * *------------------------------------------------------------------------- @@ -681,7 +675,6 @@ done: * Return: Non-negative on success/Negative on failure * * Programmer: Quincey Koziol - * koziol@ncsa.uiuc.edu * Feb 27 2006 * *------------------------------------------------------------------------- diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index 54b94a4..16f1f34 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -35,6 +35,8 @@ * * \defgroup TRAV Link Traversal * \ingroup H5L + * \defgroup H5LA Advanced Link Functions + * \ingroup H5L */ #endif /* H5Lmodule_H */ diff --git a/src/H5Mmodule.h b/src/H5Mmodule.h index 8b4f11f..3dae3e2 100644 --- a/src/H5Mmodule.h +++ b/src/H5Mmodule.h @@ -26,4 +26,49 @@ #define H5_MY_PKG_ERR H5E_MAP #define H5_MY_PKG_INIT YES +/** + * \defgroup H5M H5M + * \brief Map Interface + * + * \details \Bold{The interface can only be used with the HDF5 VOL connectors that + * implement map objects.} The native HDF5 library does not support this + * feature. + * + * While the HDF5 data model is a flexible way to store data, some + * applications require a more general way to index information. HDF5 + * effectively uses key-value stores internally for a variety of + * purposes, but it does not expose a generic key-value store to the + * API. The Map APIs provide this capability to the HDF5 applications + * in the form of HDF5 map objects. These Map objects contain + * application-defined key-value stores, to which key-value pairs can + * be added, and from which values can be retrieved by key. + * + * HDF5 VOL connectors with support for map objects: + * - DAOS + * + * \par Example: + * \code + * hid_t file_id, fapl_id, map_id, vls_type_id; + * const char *names[2] = ["Alice", "Bob"]; + * uint64_t IDs[2] = [25385486, 34873275]; + * uint64_t val_out; + * + * + * + * vls_type_id = H5Tcopy(H5T_C_S1); + * H5Tset_size(vls_type_id, H5T_VARIABLE); + * file_id = H5Fcreate("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id); + * map_id = H5Mcreate(file_id, "map", vls_type_id, H5T_NATIVE_UINT64, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + * H5Mput(map_id, vls_type_id, &names[0], H5T_NATIVE_UINT64, &IDs[0], H5P_DEFAULT); + * H5Mput(map_id, vls_type_id, &names[1], H5T_NATIVE_UINT64, &IDs[1], H5P_DEFAULT); + * H5Mget(map_id, vls_type_id, &names[0], H5T_NATIVE_UINT64, &val_out, H5P_DEFAULT); + * if(val_out != IDs[0]) + * ERROR; + * H5Mclose(map_id); + * H5Tclose(vls_type_id); + * H5Fclose(file_id); + * \endcode + * + */ + #endif /* H5Dmodule_H */ diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 004ff05..88db39a 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -61,8 +61,12 @@ typedef enum H5VL_map_specific_t { H5VL_MAP_DELETE /* H5Mdelete */ } H5VL_map_specific_t; -/* Callback for H5Miterate() */ +//! +/** + * Callback for H5Miterate() + */ typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data); +//! /********************/ /* Public Variables */ @@ -81,25 +85,374 @@ extern "C" { */ #ifdef H5_HAVE_MAP_API +/** + * \ingroup H5M + * + * \brief Creates a map object + * + * \fgdta_loc_id + * \param[in] name Map object name + * \type_id{key_type_id} + * \type_id{val_type_id} + * \lcpl_id + * \mcpl_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mcreate() creates a new map object for storing key-value + * pairs. The in-file datatype for keys is defined by \p key_type_id + * and the in-file datatype for values is defined by \p val_type_id. \p + * loc_id specifies the location to create the the map object and \p + * name specifies the name of the link to the map object relative to + * \p loc_id. + * + * \since 1.12.0 + * + */ H5_DLL hid_t H5Mcreate(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, hid_t mcpl_id, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mcreate} + */ +H5_DLL hid_t H5Mcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, + const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, + hid_t mcpl_id, hid_t mapl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief + * + * \details + * + * \since 1.12.0 + * + */ H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id, hid_t mcpl_id, hid_t mapl_id); + +/** + * \ingroup H5M + * + * \brief Opens a map object + * + * \fgdta_loc_id{loc_id} + * \param[in] name Map object name relative to \p loc_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mopen() finds a map object specified by \p name under the location + * specified by \p loc_id. The map object should be close with + * H5Mclose() when the application is not longer interested in + * accessing it. + * + * \since 1.12.0 + * + */ H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mopen} + */ +H5_DLL hid_t H5Mopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, + const char *name, hid_t mapl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief Terminates access to a map object + * + * \map_id + * \returns \herr_t + * + * \details H5Mclose() closes access to a map object specified by \p map_id and + * releases resources used by it. + * + * It is illegal to subsequently use that same map identifier in calls + * to other map functions. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Mclose(hid_t map_id); -H5_DLL hid_t H5Mget_key_type(hid_t map_id); -H5_DLL hid_t H5Mget_val_type(hid_t map_id); -H5_DLL hid_t H5Mget_create_plist(hid_t map_id); -H5_DLL hid_t H5Mget_access_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets key datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_key_type() retrieves key datatype as stored in the file for a + * map object specified by \p map_id and returns identifier for the + * datatype. + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_key_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets value datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_val_type() retrieves value datatype as stored in the file for + * a map object specified by \p map_id and returns identifier for the + * datatype . + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_val_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets creation property list for a map object + * + * \map_id + * \returns \hid_t{map creation property list} + * + * \details H5Mget_create_plist() returns an identifier for a copy of the + * creation property list for a map object specified by \p map_id. + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_create_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets access property list for a map object + * + * \map_id + * \returns \hid_t{map access property list} + * + * \details H5Mget_access_plist() returns an identifier for a copy of the access + * property list for a map object specified by \p map_id. + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_access_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Retrieves the number of key-value pairs in a map object + * + * \map_id + * \param[out] count The number of key-value pairs stored in the map object + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget_count() retrieves the number of key-value pairs stored in a + * map specified by map_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Adds a key-value pair to a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[in] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mput() adds a key-value pair to a map object specified by \p + * map_id, or updates the value for the specified key if one was set + * previously. + * + * \p key_mem_type_id and \p val_mem_type_id specify the datatypes for + * the provided key and value buffers, and if different from those used + * to create the map object, the key and value will be internally + * converted to the datatypes for the map object. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Retrieves a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[out] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget() retrieves from a map object specified by \p map_id, the + * value associated with the provided key \p key. \p key_mem_type_id + * and \p val_mem_type_id specify the datatypes for the provided key + * and value buffers. If if the datatype specified by \p + * key_mem_type_id is different from that used to create the map object + * the key will be internally converted to the datatype for the map + * object for the query, and if the datatype specified by \p + * val_mem_type_id is different from that used to create the map object + * the returned value will be converted to have a datatype as specified + * by \p val_mem_type_id before the function returns. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Mget(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Checks if provided key exists in a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \param[out] exists Pointer to a buffer to return the existence status + * \dxpl_id + * \returns \herr_t + * + * \details H5Mexists() checks if the provided key is stored in the map object + * specified by \p map_id. If \p key_mem_type_id is different from that + * used to create the map object the key will be internally converted + * to the datatype for the map object for the query. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hbool_t *exists, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \map_id + * \param[in,out] idx iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \returns \herr_t + * + * \details H5Miterate() iterates over all key-value pairs stored in the map + * object specified by \p map_id, making the callback specified by \p + * op for each. The \p idx parameter is an in/out parameter that may be + * used to restart a previously interrupted iteration. At the start of + * iteration \p idx should be set to 0, and to restart iteration at the + * same location on a subsequent call to H5Miterate(), \p idx should be + * the same value as returned by the previous call. Iterate callback is + * defined as: + * \snippet this H5M_iterate_t_snip + * The \p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data for + * iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will + * cause H5Miterate() to stop iterating and return this value without + * issuing an error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \loc_id + * \param[in] map_name Map object name relative to the location specified by \p loc_id + * \param[in,out] idx Iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \lapl_id + * \returns \herr_t + * + * \details H5Miterate_by_name() iterates over all key-value pairs stored in the + * map object specified by \p map_id, making the callback specified by + * \p op for each. The \p idx parameter is an in/out parameter that may + * be used to restart a previously interrupted iteration. At the start + * of iteration \p idx should be set to 0, and to restart iteration at + * the same location on a subsequent call to H5Miterate(), \p idx + * should be the same value as returned by the previous call. Iterate + * callback is defined as: + * \snippet this H5M_iterate_t_snip + * The\p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data + * for iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will cause + * H5Miterate() to stop iterating and return this value without issuing an + * error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data, hid_t dxpl_id, hid_t lapl_id); + +/** + * \ingroup H5M + * + * \brief Deletes a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mdelete() deletes a key-value pair from the map object specified + * by \p map_id. \p key_mem_type_id specifies the datatype for the + * provided key buffer key, and if different from that used to create + * the map object, the key will be internally converted to the datatype + * for the map object. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.12.0 + * + */ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. diff --git a/src/H5Oint.c b/src/H5Oint.c index 42a66c4..a88a026 100644 --- a/src/H5Oint.c +++ b/src/H5Oint.c @@ -571,7 +571,7 @@ H5O_open(H5O_loc_t *loc) #ifdef H5O_DEBUG if (H5DEBUG(O)) - HDfprintf(H5DEBUG(O), "> %a\n", loc->addr); + HDfprintf(H5DEBUG(O), "> %" PRIuHADDR "\n", loc->addr); #endif /* Turn off the variable for holding file or increment open-lock counters */ @@ -802,10 +802,10 @@ H5O_close(H5O_loc_t *loc, hbool_t *file_closed /*out*/) #ifdef H5O_DEBUG if (H5DEBUG(O)) { if (FALSE == H5F_ID_EXISTS(loc->file) && 1 == H5F_NREFS(loc->file)) - HDfprintf(H5DEBUG(O), "< %a auto %lu remaining\n", loc->addr, + HDfprintf(H5DEBUG(O), "< %" PRIuHADDR " auto %lu remaining\n", loc->addr, (unsigned long)H5F_NOPEN_OBJS(loc->file)); else - HDfprintf(H5DEBUG(O), "< %a\n", loc->addr); + HDfprintf(H5DEBUG(O), "< %" PRIuHADDR "\n", loc->addr); } #endif diff --git a/src/H5SM.c b/src/H5SM.c index 76a1428..fbf4975 100644 --- a/src/H5SM.c +++ b/src/H5SM.c @@ -2568,19 +2568,19 @@ H5SM_table_debug(H5F_t *f, haddr_t table_addr, FILE *stream, int indent, int fwi ? "List" : (table->indexes[x].index_type == H5SM_BTREE ? "B-Tree" : "Unknown"))); - HDfprintf(stream, "%*s%-*s %a\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %" PRIuHADDR "\n", indent + 3, "", fwidth, "Address of index:", table->indexes[x].index_addr); - HDfprintf(stream, "%*s%-*s %a\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %" PRIuHADDR "\n", indent + 3, "", fwidth, "Address of index's heap:", table->indexes[x].heap_addr); HDfprintf(stream, "%*s%-*s 0x%08x\n", indent + 3, "", fwidth, "Message type flags:", table->indexes[x].mesg_types); - HDfprintf(stream, "%*s%-*s %Zu\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %zu\n", indent + 3, "", fwidth, "Minimum size of messages:", table->indexes[x].min_mesg_size); - HDfprintf(stream, "%*s%-*s %Zu\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %zu\n", indent + 3, "", fwidth, "Number of messages:", table->indexes[x].num_messages); - HDfprintf(stream, "%*s%-*s %Zu\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %zu\n", indent + 3, "", fwidth, "Maximum list size:", table->indexes[x].list_max); - HDfprintf(stream, "%*s%-*s %Zu\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %zu\n", indent + 3, "", fwidth, "Minimum B-tree size:", table->indexes[x].btree_min); } /* end for */ @@ -2668,16 +2668,16 @@ H5SM_list_debug(H5F_t *f, haddr_t list_addr, FILE *stream, int indent, int fwidt HDassert(fh); HDfprintf(stream, "%*s%-*s %s\n", indent + 3, "", fwidth, "Location:", "in heap"); - HDfprintf(stream, "%*s%-*s 0x%Zx\n", indent + 3, "", fwidth, - "Heap ID:", list->messages[x].u.heap_loc.fheap_id); - HDfprintf(stream, "%*s%-*s %u\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s 0x%" PRIx64 "\n", indent + 3, "", fwidth, + "Heap ID:", list->messages[x].u.heap_loc.fheap_id.val); + HDfprintf(stream, "%*s%-*s %" PRIuHSIZE "\n", indent + 3, "", fwidth, "Reference count:", list->messages[x].u.heap_loc.ref_count); } /* end if */ else if (list->messages[x].location == H5SM_IN_OH) { HDfprintf(stream, "%*s%-*s %s\n", indent + 3, "", fwidth, "Location:", "in object header"); - HDfprintf(stream, "%*s%-*s %a\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %" PRIuHADDR "\n", indent + 3, "", fwidth, "Object header address:", list->messages[x].u.mesg_loc.oh_addr); - HDfprintf(stream, "%*s%-*s %u\n", indent + 3, "", fwidth, + HDfprintf(stream, "%*s%-*s %" PRIuHADDR "\n", indent + 3, "", fwidth, "Message creation index:", list->messages[x].u.mesg_loc.oh_addr); HDfprintf(stream, "%*s%-*s %u\n", indent + 3, "", fwidth, "Message type ID:", list->messages[x].msg_type_id); diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index 4f9edde..c489edc 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -44,12 +44,8 @@ * \ingroup H5T * \defgroup ENUM Enumeration Datatypes * \ingroup H5T - * \defgroup GTO General Datatype Operations - * \ingroup H5T * \defgroup OPAQUE Opaque Datatypes * \ingroup H5T - * \defgroup STRING String Datatypes - * \ingroup H5T * \defgroup VLEN Variable-length Sequence Datatypes * \ingroup H5T * diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h index 78c5986..009c0e5 100644 --- a/src/H5VLmodule.h +++ b/src/H5VLmodule.h @@ -32,6 +32,10 @@ * \brief Virtual Object Layer Interface * \todo Describe concisely what the functions in this module are about. * + * \defgroup ASYNC Asynchronous Functions + * \brief Asynchronous Functions + * \todo Describe concisely what the functions in this module are about. + * * \defgroup H5VLDEF Definitions * \ingroup H5VL * \defgroup H5VLDEV VOL Developer diff --git a/src/H5public.h b/src/H5public.h index 751abbe..ada15a7 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -511,7 +511,7 @@ H5_DLL herr_t H5open(void); * If the HDF5 library is initialized and closed more than once, the * \p func callback must be registered within each open/close cycle. * - * \since 1.12.1 + * \since 1.13.0 */ H5_DLL herr_t H5atclose(H5_atclose_func_t func, void *ctx); /** @@ -735,7 +735,7 @@ H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum) * after it has been closed. The value of \p is_terminating is * undefined if this routine fails. * - * \since 1.12.1 + * \since 1.13.0 */ H5_DLL herr_t H5is_library_terminating(hbool_t *is_terminating); /** diff --git a/src/Makefile.am b/src/Makefile.am index 19d358d..65002c1 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -19,9 +19,6 @@ include $(top_srcdir)/config/commence.am include $(top_srcdir)/config/lt_vers.am -# include Doxygen rules (requires autoconf-archive >2016-03-20) -@DX_RULES@ - # How to build H5detect for number format detection. # Use -g to force no optimization since many compilers (e.g., Intel) takes # a long time to compile it with any optimization on. H5detect is used diff --git a/test/dsets.c b/test/dsets.c index 5452e8d..4bd8e01 100644 --- a/test/dsets.c +++ b/test/dsets.c @@ -4599,7 +4599,7 @@ test_nbit_int_size(hid_t file) if ((dset_size = H5Dget_storage_size(dataset)) < DSET_DIM1 * DSET_DIM2 * (precision / 8) || dset_size > DSET_DIM1 * DSET_DIM2 * (precision / 8) + 1 * KB) { H5_FAILED(); - HDfprintf(stdout, " Line %d: wrong dataset size: %Hu\n", __LINE__, dset_size); + HDfprintf(stdout, " Line %d: wrong dataset size: %" PRIuHSIZE "\n", __LINE__, dset_size); goto error; } @@ -4809,7 +4809,7 @@ test_nbit_flt_size(hid_t file) if ((dset_size = H5Dget_storage_size(dataset)) < DSET_DIM1 * DSET_DIM2 * (precision / 8) || dset_size > DSET_DIM1 * DSET_DIM2 * (precision / 8) + 1 * KB) { H5_FAILED(); - HDfprintf(stdout, " Line %d: wrong dataset size: %Hu\n", __LINE__, dset_size); + HDfprintf(stdout, " Line %d: wrong dataset size: %" PRIuHSIZE "\n", __LINE__, dset_size); goto error; } /* end if */ diff --git a/tools/test/h5repack/testfiles/h5repack_layout.h5-dset2_chunk_20x10-errstk.tst b/tools/test/h5repack/testfiles/h5repack_layout.h5-dset2_chunk_20x10-errstk.tst index 9e83ff8..6f586cc 100644 --- a/tools/test/h5repack/testfiles/h5repack_layout.h5-dset2_chunk_20x10-errstk.tst +++ b/tools/test/h5repack/testfiles/h5repack_layout.h5-dset2_chunk_20x10-errstk.tst @@ -1,7 +1,7 @@ HDF5-DIAG: Error detected in HDF5 (version (number)) thread (IDs): #000: (file name) line (number) in H5Dcreate2(): unable to create dataset major: Dataset - minor: Unable to initialize object + minor: Unable to create file #001: (file name) line (number) in H5VL_dataset_create(): dataset create failed major: Virtual Object Layer minor: Unable to create file -- cgit v0.12