diff options
Diffstat (limited to 'src')
175 files changed, 16922 insertions, 6181 deletions
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 597f620..a7e3f57 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -380,6 +380,8 @@ IDE_GENERATED_PROPERTIES ("H5HP" "${H5HP_HDRS}" "${H5HP_SOURCES}" ) set (H5I_SOURCES ${HDF5_SRC_DIR}/H5I.c + ${HDF5_SRC_DIR}/H5Idbg.c + ${HDF5_SRC_DIR}/H5Iint.c ${HDF5_SRC_DIR}/H5Itest.c ) set (H5I_HDRS @@ -714,6 +716,7 @@ set (H5Z_HDRS IDE_GENERATED_PROPERTIES ("H5Z" "${H5Z_HDRS}" "${H5Z_SOURCES}" ) set (H5_MODULE_HEADERS + ${HDF5_SRC_DIR}/H5module.h ${HDF5_SRC_DIR}/H5Amodule.h ${HDF5_SRC_DIR}/H5ACmodule.h ${HDF5_SRC_DIR}/H5Bmodule.h @@ -743,6 +746,7 @@ set (H5_MODULE_HEADERS ${HDF5_SRC_DIR}/H5PBmodule.h ${HDF5_SRC_DIR}/H5PLmodule.h ${HDF5_SRC_DIR}/H5Rmodule.h + ${HDF5_SRC_DIR}/H5RSmodule.h ${HDF5_SRC_DIR}/H5Smodule.h ${HDF5_SRC_DIR}/H5SLmodule.h ${HDF5_SRC_DIR}/H5SMmodule.h @@ -1356,3 +1360,41 @@ if (NOT WIN32) COMPONENT libraries ) endif () + +#----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +if (DOXYGEN_FOUND) + set (DOXYGEN_PACKAGE ${HDF5_PACKAGE}) + set (DOXYGEN_VERSION_STRING ${HDF5_VERSION_STRING}) + set (DOXYGEN_INCLUDE_ALIASES ${HDF5_DOXYGEN_DIR}/aliases) + set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png) + set (DOXYGEN_PROJECT_BRIEF "C-API Reference") + set (DOXYGEN_INPUT_DIRECTORY ${HDF5_SRC_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}/shared) + set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) + set (DOXYGEN_MACRO_EXPANSION YES) + set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs) + + # Replace variables inside @@ with the current values + configure_file(${HDF5_DOXYGEN_DIR}/Doxyfile.in Doxyfile @ONLY) + + doxygen_add_docs(hdf5lib_doc +# ${common_SRCS} ${shared_gen_SRCS} ${H5_PUBLIC_HEADERS} ${H5_PRIVATE_HEADERS} ${H5_GENERATED_HEADERS} ${HDF5_DOXYGEN_DIR}/dox + ${DOXYGEN_INPUT_DIRECTORY} + ALL + WORKING_DIRECTORY ${HDF5_SRC_DIR} + COMMENT "Generating HDF5 library Source Documentation" + ) + install( + DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs/html + DESTINATION ${HDF5_INSTALL_DATA_DIR} + COMPONENT Documents + ) + + if(NOT TARGET doxygen) + add_custom_target(doxygen) + endif() + + add_dependencies(doxygen hdf5lib_doc) + +endif () @@ -14,6 +14,7 @@ /****************/ /* Module Setup */ /****************/ +#include "H5module.h" /* This source code file is part of the H5 module */ /***********/ /* Headers */ @@ -55,6 +56,9 @@ static int H5__mpi_delete_cb(MPI_Comm comm, int keyval, void *attr_val, int *fla /* Package Variables */ /*********************/ +/* Package initialization variable */ +hbool_t H5_PKG_INIT_VAR = FALSE; + /*****************************/ /* Library Private Variables */ /*****************************/ @@ -85,6 +89,33 @@ H5_debug_t H5_debug_g; /* debugging info */ /*******************/ /*-------------------------------------------------------------------------- +NAME + H5__init_package -- Initialize interface-specific information +USAGE + herr_t H5__init_package() +RETURNS + Non-negative on success/Negative on failure +DESCRIPTION + Initializes any interface-specific data or routines. +--------------------------------------------------------------------------*/ +herr_t +H5__init_package(void) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI_NOINIT + + /* Run the library initialization routine, if it hasn't already ran */ + if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) { + if (H5_init_library() < 0) + HGOTO_ERROR(H5E_LIB, H5E_CANTINIT, FAIL, "unable to initialize library") + } /* end if */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5__init_package() */ + +/*-------------------------------------------------------------------------- * NAME * H5_init_library -- Initialize library-global information * USAGE @@ -103,6 +134,11 @@ H5_init_library(void) { herr_t ret_value = SUCCEED; + /* Set the 'library initialized' flag as early as possible, to avoid + * possible re-entrancy. + */ + H5_INIT_GLOBAL = TRUE; + FUNC_ENTER_NOAPI(FAIL) #ifdef H5_HAVE_PARALLEL @@ -336,6 +372,7 @@ H5_term_library(void) */ if (pending == 0) { pending += DOWN(AC); + /* Shut down the "pluggable" interfaces, before the plugin framework */ pending += DOWN(Z); pending += DOWN(FD); pending += DOWN(VL); @@ -367,7 +404,7 @@ H5_term_library(void) HDfprintf(stderr, " %s\n", loop); #ifndef NDEBUG HDabort(); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end if */ } /* end if */ @@ -560,12 +597,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5get_free_list_sizes(size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size) +H5get_free_list_sizes(size_t *reg_size /*out*/, size_t *arr_size /*out*/, size_t *blk_size /*out*/, + size_t *fac_size /*out*/) { herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "*z*z*z*z", reg_size, arr_size, blk_size, fac_size); + H5TRACE4("e", "xxxx", reg_size, arr_size, blk_size, fac_size); /* Call the free list function to actually get the sizes */ if (H5FL_get_free_list_sizes(reg_size, arr_size, blk_size, fac_size) < 0) @@ -600,12 +638,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5get_alloc_stats(H5_alloc_stats_t *stats) +H5get_alloc_stats(H5_alloc_stats_t *stats /*out*/) { herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE1("e", "*x", stats); + H5TRACE1("e", "x", stats); /* Call the internal allocation stat routine to get the values */ if (H5MM_get_alloc_stats(stats) < 0) @@ -763,12 +801,12 @@ H5__mpi_delete_cb(MPI_Comm H5_ATTR_UNUSED comm, int H5_ATTR_UNUSED keyval, void *------------------------------------------------------------------------- */ herr_t -H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *relnum) +H5get_libversion(unsigned *majnum /*out*/, unsigned *minnum /*out*/, unsigned *relnum /*out*/) { herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE3("e", "*Iu*Iu*Iu", majnum, minnum, relnum); + H5TRACE3("e", "xxx", majnum, minnum, relnum); /* Set the version information */ if (majnum) @@ -1079,7 +1117,7 @@ H5is_library_threadsafe(hbool_t *is_ts) /* At this time, it is impossible for this to fail. */ #ifdef H5_HAVE_THREADSAFE *is_ts = TRUE; -#else /* H5_HAVE_THREADSAFE */ +#else /* H5_HAVE_THREADSAFE */ *is_ts = FALSE; #endif /* H5_HAVE_THREADSAFE */ @@ -40,13 +40,6 @@ /* Local Typedefs */ /******************/ -/* Object header iterator callbacks */ -/* Data structure for callback for locating the index by name */ -typedef struct H5A_iter_cb1 { - const char *name; - int idx; -} H5A_iter_cb1; - /********************/ /* Package Typedefs */ /********************/ @@ -59,9 +52,6 @@ typedef struct H5A_iter_cb1 { /* Package Variables */ /*********************/ -/* Package initialization variable */ -hbool_t H5_PKG_INIT_VAR = FALSE; - /*****************************/ /* Library Private Variables */ /*****************************/ @@ -70,160 +60,6 @@ hbool_t H5_PKG_INIT_VAR = FALSE; /* Local Variables */ /*******************/ -/* Declare the free lists of H5A_t */ -H5FL_DEFINE(H5A_t); - -/* Declare the free lists for H5A_shared_t's */ -H5FL_DEFINE(H5A_shared_t); - -/* Declare a free list to manage blocks of type conversion data */ -H5FL_BLK_DEFINE(attr_buf); - -/* Attribute ID class */ -static const H5I_class_t H5I_ATTR_CLS[1] = {{ - H5I_ATTR, /* ID class value */ - 0, /* Class flags */ - 0, /* # of reserved IDs for class */ - (H5I_free_t)H5A__close_cb /* Callback routine for closing objects of this class */ -}}; - -/* Flag indicating "top" of interface has been initialized */ -static hbool_t H5A_top_package_initialize_s = FALSE; - -/*------------------------------------------------------------------------- - * Function: H5A_init - * - * Purpose: Initialize the interface from some other layer. - * - * Return: Success: non-negative - * - * Failure: negative - *------------------------------------------------------------------------- - */ -herr_t -H5A_init(void) -{ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_NOAPI(FAIL) - /* FUNC_ENTER() does all the work */ - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5A_init() */ - -/*-------------------------------------------------------------------------- -NAME - H5A__init_package -- Initialize interface-specific information -USAGE - herr_t H5A__init_package() - -RETURNS - Non-negative on success/Negative on failure -DESCRIPTION - Initializes any interface-specific data or routines. - ---------------------------------------------------------------------------*/ -herr_t -H5A__init_package(void) -{ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_PACKAGE - - /* - * Create attribute ID type. - */ - if (H5I_register_type(H5I_ATTR_CLS) < 0) - HGOTO_ERROR(H5E_ATTR, H5E_CANTINIT, FAIL, "unable to initialize interface") - - /* Mark "top" of interface as initialized, too */ - H5A_top_package_initialize_s = TRUE; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5A__init_package() */ - -/*-------------------------------------------------------------------------- - NAME - H5A_top_term_package - PURPOSE - Terminate various H5A objects - USAGE - void H5A_top_term_package() - RETURNS - DESCRIPTION - Release IDs for the atom group, deferring full interface shutdown - until later (in H5A_term_package). - GLOBAL VARIABLES - COMMENTS, BUGS, ASSUMPTIONS - Can't report errors... - EXAMPLES - REVISION LOG ---------------------------------------------------------------------------*/ -int -H5A_top_term_package(void) -{ - int n = 0; - - FUNC_ENTER_NOAPI_NOINIT_NOERR - - if (H5A_top_package_initialize_s) { - if (H5I_nmembers(H5I_ATTR) > 0) { - (void)H5I_clear_type(H5I_ATTR, FALSE, FALSE); - n++; /*H5I*/ - } /* end if */ - - /* Mark closed */ - if (0 == n) - H5A_top_package_initialize_s = FALSE; - } /* end if */ - - FUNC_LEAVE_NOAPI(n) -} /* H5A_top_term_package() */ - -/*-------------------------------------------------------------------------- - NAME - H5A_term_package - PURPOSE - Terminate various H5A objects - USAGE - void H5A_term_package() - RETURNS - DESCRIPTION - Release any other resources allocated. - GLOBAL VARIABLES - COMMENTS, BUGS, ASSUMPTIONS - Can't report errors... - - Finishes shutting down the interface, after H5A_top_term_package() - is called - EXAMPLES - REVISION LOG ---------------------------------------------------------------------------*/ -int -H5A_term_package(void) -{ - int n = 0; - - FUNC_ENTER_NOAPI_NOINIT_NOERR - - if (H5_PKG_INIT_VAR) { - /* Sanity checks */ - HDassert(0 == H5I_nmembers(H5I_ATTR)); - HDassert(FALSE == H5A_top_package_initialize_s); - - /* Destroy the attribute object id group */ - n += (H5I_dec_type_ref(H5I_ATTR) > 0); - - /* Mark closed */ - if (0 == n) - H5_PKG_INIT_VAR = FALSE; - } /* end if */ - - FUNC_LEAVE_NOAPI(n) -} /* H5A_term_package() */ - /*-------------------------------------------------------------------------- * Function: H5Acreate2 * @@ -685,13 +521,13 @@ done: This function reads a complete attribute from disk. --------------------------------------------------------------------------*/ herr_t -H5Aread(hid_t attr_id, hid_t dtype_id, void *buf) +H5Aread(hid_t attr_id, hid_t dtype_id, void *buf /*out*/) { H5VL_object_t *vol_obj; /* Attribute object for ID */ herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ii*x", attr_id, dtype_id, buf); + H5TRACE3("e", "iix", attr_id, dtype_id, buf); /* Check arguments */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(attr_id, H5I_ATTR))) @@ -849,14 +685,14 @@ done: properly terminate the string. --------------------------------------------------------------------------*/ ssize_t -H5Aget_name(hid_t attr_id, size_t buf_size, char *buf) +H5Aget_name(hid_t attr_id, size_t buf_size, char *buf /*out*/) { H5VL_object_t * vol_obj = NULL; /* Attribute object for ID */ H5VL_loc_params_t loc_params; ssize_t ret_value = -1; FUNC_ENTER_API((-1)) - H5TRACE3("Zs", "iz*s", attr_id, buf_size, buf); + H5TRACE3("Zs", "izx", attr_id, buf_size, buf); /* check arguments */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(attr_id, H5I_ATTR))) @@ -995,14 +831,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Aget_info(hid_t attr_id, H5A_info_t *ainfo) +H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/) { H5VL_object_t * vol_obj; H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", attr_id, ainfo); + H5TRACE2("e", "ix", attr_id, ainfo); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(attr_id, H5I_ATTR))) @@ -1036,7 +872,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, H5A_info_t *ainfo, +H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, H5A_info_t *ainfo /*out*/, hid_t lapl_id) { H5VL_object_t * vol_obj; @@ -1044,7 +880,7 @@ H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, H herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*s*s*xi", loc_id, obj_name, attr_name, ainfo, lapl_id); + H5TRACE5("e", "i*s*sxi", loc_id, obj_name, attr_name, ainfo, lapl_id); /* Check args */ if (H5I_ATTR == H5I_get_type(loc_id)) @@ -1094,14 +930,14 @@ done: */ herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, - H5A_info_t *ainfo, hid_t lapl_id) + H5A_info_t *ainfo /*out*/, hid_t lapl_id) { H5VL_object_t * vol_obj; H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "i*sIiIoh*xi", loc_id, obj_name, idx_type, order, n, ainfo, lapl_id); + H5TRACE7("e", "i*sIiIohxi", loc_id, obj_name, idx_type, order, n, ainfo, lapl_id); /* Check args */ if (H5I_ATTR == H5I_get_type(loc_id)) @@ -1300,7 +1136,7 @@ done: attribute. --------------------------------------------------------------------------*/ herr_t -H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, +H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx /*in,out */, H5A_operator2_t op, void *op_data) { H5VL_object_t * vol_obj = NULL; /* object of loc_id */ @@ -1308,7 +1144,7 @@ H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *i herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "iIiIo*hx*x", loc_id, idx_type, order, idx, op, op_data); + H5TRACE6("e", "iIiIo*hAO*x", loc_id, idx_type, order, idx, op, op_data); /* check arguments */ if (H5I_ATTR == H5I_get_type(loc_id)) @@ -1379,14 +1215,14 @@ done: --------------------------------------------------------------------------*/ herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t *idx, H5A_operator2_t op, void *op_data, hid_t lapl_id) + hsize_t *idx /*in,out */, H5A_operator2_t op, void *op_data, hid_t lapl_id) { H5VL_object_t * vol_obj = NULL; /* Object location */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIo*hx*xi", loc_id, obj_name, idx_type, order, idx, op, op_data, lapl_id); + H5TRACE8("e", "i*sIiIo*hAO*xi", loc_id, obj_name, idx_type, order, idx, op, op_data, lapl_id); /* Check arguments */ if (H5I_ATTR == H5I_get_type(loc_id)) @@ -374,7 +374,7 @@ H5AC_create(const H5F_t *f, H5AC_cache_config_t *config_ptr, H5AC_cache_image_co H5C_create(H5AC__DEFAULT_MAX_CACHE_SIZE, H5AC__DEFAULT_MIN_CLEAN_SIZE, (H5AC_NTYPES - 1), H5AC_class_s, H5AC__check_if_write_permitted, TRUE, NULL, NULL); #ifdef H5_HAVE_PARALLEL - } /* end else */ + } /* end else */ #endif /* H5_HAVE_PARALLEL */ if (NULL == f->shared->cache) @@ -432,7 +432,7 @@ done: aux_ptr = H5FL_FREE(H5AC_aux_t, aux_ptr); } /* end if */ } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ FUNC_LEAVE_NOAPI(ret_value) } /* H5AC_create() */ @@ -466,7 +466,7 @@ H5AC_dest(H5F_t *f) hbool_t curr_logging; /* TRUE if currently logging */ #ifdef H5_HAVE_PARALLEL H5AC_aux_t *aux_ptr = NULL; -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_NOAPI(FAIL) @@ -585,7 +585,7 @@ H5AC_dest(H5F_t *f) aux_ptr->magic = 0; aux_ptr = H5FL_FREE(H5AC_aux_t, aux_ptr); - } /* end if */ + } /* end if */ #endif /* H5_HAVE_PARALLEL */ done: @@ -1104,7 +1104,7 @@ H5AC_move_entry(H5F_t *f, const H5AC_class_t *type, haddr_t old_addr, haddr_t ne { #ifdef H5_HAVE_PARALLEL H5AC_aux_t *aux_ptr; -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_NOAPI(FAIL) @@ -1414,7 +1414,7 @@ H5AC_protect(H5F_t *f, const H5AC_class_t *type, haddr_t addr, void *udata, unsi #ifdef H5_HAVE_PARALLEL HDassert(0 == (flags & (unsigned)(~(H5C__READ_ONLY_FLAG | H5C__FLUSH_LAST_FLAG | H5C__FLUSH_COLLECTIVELY_FLAG)))); -#else /* H5_HAVE_PARALLEL */ +#else /* H5_HAVE_PARALLEL */ HDassert(0 == (flags & (unsigned)(~(H5C__READ_ONLY_FLAG | H5C__FLUSH_LAST_FLAG)))); #endif /* H5_HAVE_PARALLEL */ @@ -1631,7 +1631,7 @@ H5AC_unprotect(H5F_t *f, const H5AC_class_t *type, haddr_t addr, void *thing, un hbool_t deleted; #ifdef H5_HAVE_PARALLEL H5AC_aux_t *aux_ptr = NULL; -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_NOAPI(FAIL) @@ -1674,7 +1674,7 @@ H5AC_unprotect(H5F_t *f, const H5AC_class_t *type, haddr_t addr, void *thing, un if (deleted && aux_ptr->mpi_rank == 0) if (H5AC__log_deleted_entry((H5AC_info_t *)thing) < 0) HGOTO_ERROR(H5E_CACHE, H5E_CANTUNPROTECT, FAIL, "H5AC__log_deleted_entry() failed") - } /* end if */ + } /* end if */ #endif /* H5_HAVE_PARALLEL */ if (H5C_unprotect(f, addr, thing, flags) < 0) @@ -2163,7 +2163,7 @@ H5AC__check_if_write_permitted(const H5F_t write_permitted = aux_ptr->write_permitted; else write_permitted = FALSE; - } /* end if */ + } /* end if */ #endif /* H5_HAVE_PARALLEL */ *write_permitted_ptr = write_permitted; diff --git a/src/H5ACmpio.c b/src/H5ACmpio.c index a806b35..3826a9c 100644 --- a/src/H5ACmpio.c +++ b/src/H5ACmpio.c @@ -137,8 +137,7 @@ H5FL_DEFINE_STATIC(H5AC_slist_entry_t); *------------------------------------------------------------------------- */ herr_t -H5AC__set_sync_point_done_callback(H5C_t *cache_ptr, - void (*sync_point_done)(unsigned num_writes, haddr_t *written_entries_tbl)) +H5AC__set_sync_point_done_callback(H5C_t *cache_ptr, H5AC_sync_point_done_cb_t sync_point_done) { H5AC_aux_t *aux_ptr; @@ -170,7 +169,7 @@ H5AC__set_sync_point_done_callback(H5C_t *cache_ptr, *------------------------------------------------------------------------- */ herr_t -H5AC__set_write_done_callback(H5C_t *cache_ptr, void (*write_done)(void)) +H5AC__set_write_done_callback(H5C_t *cache_ptr, H5AC_write_done_cb_t write_done) { H5AC_aux_t *aux_ptr; @@ -760,7 +759,7 @@ H5AC__log_dirtied_entry(const H5AC_info_t *entry_ptr) #if H5AC_DEBUG_DIRTY_BYTES_CREATION aux_ptr->unprotect_dirty_bytes += entry_ptr->size; aux_ptr->unprotect_dirty_bytes_updates += 1; -#endif /* H5AC_DEBUG_DIRTY_BYTES_CREATION */ +#endif /* H5AC_DEBUG_DIRTY_BYTES_CREATION */ } /* end if */ /* the entry is dirty. If it exists on the cleaned entries list, @@ -776,7 +775,7 @@ H5AC__log_dirtied_entry(const H5AC_info_t *entry_ptr) aux_ptr->unprotect_dirty_bytes += entry_ptr->size; aux_ptr->unprotect_dirty_bytes_updates += 1; #endif /* H5AC_DEBUG_DIRTY_BYTES_CREATION */ - } /* end else */ + } /* end else */ done: FUNC_LEAVE_NOAPI(ret_value) @@ -1090,7 +1089,7 @@ H5AC__log_moved_entry(const H5F_t *f, haddr_t old_addr, haddr_t new_addr) #if H5AC_DEBUG_DIRTY_BYTES_CREATION aux_ptr->move_dirty_bytes += entry_size; aux_ptr->move_dirty_bytes_updates += 1; -#endif /* H5AC_DEBUG_DIRTY_BYTES_CREATION */ +#endif /* H5AC_DEBUG_DIRTY_BYTES_CREATION */ } /* end else */ /* insert / reinsert the entry in the dirty slist */ @@ -1104,7 +1103,7 @@ H5AC__log_moved_entry(const H5F_t *f, haddr_t old_addr, haddr_t new_addr) aux_ptr->move_dirty_bytes += entry_size; aux_ptr->move_dirty_bytes_updates += 1; #endif /* H5AC_DEBUG_DIRTY_BYTES_CREATION */ - } /* end else-if */ + } /* end else-if */ done: FUNC_LEAVE_NOAPI(ret_value) diff --git a/src/H5ACpkg.h b/src/H5ACpkg.h index 5ec364a..0548193 100644 --- a/src/H5ACpkg.h +++ b/src/H5ACpkg.h @@ -401,7 +401,12 @@ typedef struct H5AC_aux_t { unsigned p0_image_len; } H5AC_aux_t; /* struct H5AC_aux_t */ -#endif /* H5_HAVE_PARALLEL */ + +/* Typedefs for debugging function pointers */ +typedef void (*H5AC_sync_point_done_cb_t)(unsigned num_writes, haddr_t *written_entries_tbl); +typedef void (*H5AC_write_done_cb_t)(void); + +#endif /* H5_HAVE_PARALLEL */ /******************************/ /* Package Private Prototypes */ @@ -417,10 +422,8 @@ H5_DLL herr_t H5AC__log_inserted_entry(const H5AC_info_t *entry_ptr); H5_DLL herr_t H5AC__log_moved_entry(const H5F_t *f, haddr_t old_addr, haddr_t new_addr); H5_DLL herr_t H5AC__flush_entries(H5F_t *f); H5_DLL herr_t H5AC__run_sync_point(H5F_t *f, int sync_point_op); -H5_DLL herr_t H5AC__set_sync_point_done_callback(H5C_t *cache_ptr, - void (*sync_point_done)(unsigned num_writes, - haddr_t *written_entries_tbl)); -H5_DLL herr_t H5AC__set_write_done_callback(H5C_t *cache_ptr, void (*write_done)(void)); +H5_DLL herr_t H5AC__set_sync_point_done_callback(H5C_t *cache_ptr, H5AC_sync_point_done_cb_t sync_point_done); +H5_DLL herr_t H5AC__set_write_done_callback(H5C_t *cache_ptr, H5AC_write_done_cb_t write_done); #endif /* H5_HAVE_PARALLEL */ #endif /* _H5ACpkg_H */ diff --git a/src/H5ACproxy_entry.c b/src/H5ACproxy_entry.c index 76e885f..4426189 100644 --- a/src/H5ACproxy_entry.c +++ b/src/H5ACproxy_entry.c @@ -521,7 +521,7 @@ H5AC__proxy_entry_notify(H5AC_notify_action_t action, void *_thing) case H5AC_NOTIFY_ACTION_AFTER_LOAD: #ifdef NDEBUG HGOTO_ERROR(H5E_CACHE, H5E_BADVALUE, FAIL, "invalid notify action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Invalid action?!?"); #endif /* NDEBUG */ break; @@ -529,7 +529,7 @@ H5AC__proxy_entry_notify(H5AC_notify_action_t action, void *_thing) case H5AC_NOTIFY_ACTION_AFTER_FLUSH: #ifdef NDEBUG HGOTO_ERROR(H5E_CACHE, H5E_BADVALUE, FAIL, "invalid notify action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Invalid action?!?"); #endif /* NDEBUG */ break; @@ -605,10 +605,10 @@ H5AC__proxy_entry_notify(H5AC_notify_action_t action, void *_thing) default: #ifdef NDEBUG HGOTO_ERROR(H5E_CACHE, H5E_BADVALUE, FAIL, "unknown notify action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ done: FUNC_LEAVE_NOAPI(ret_value) diff --git a/src/H5Adense.c b/src/H5Adense.c index 3d99202..1efe45d 100644 --- a/src/H5Adense.c +++ b/src/H5Adense.c @@ -1100,7 +1100,7 @@ H5A__dense_iterate_bt2_cb(const void *_record, void *_bt2_udata) HDassert("unknown attribute op type" && 0); #ifdef NDEBUG HGOTO_ERROR(H5E_ATTR, H5E_UNSUPPORTED, FAIL, "unsupported attribute op type") -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ /* Release the space allocated for the attribute */ diff --git a/src/H5Adeprec.c b/src/H5Adeprec.c index 3589296..cd3dd25 100644 --- a/src/H5Adeprec.c +++ b/src/H5Adeprec.c @@ -373,13 +373,13 @@ 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 */ FUNC_ENTER_API(H5_ITER_ERROR) - H5TRACE4("e", "i*Iux*x", loc_id, attr_num, op, op_data); + H5TRACE4("e", "i*IuAo*x", loc_id, attr_num, op, op_data); /* check arguments */ if (H5I_ATTR == H5I_get_type(loc_id)) diff --git a/src/H5Aint.c b/src/H5Aint.c index b7e7be6..5a78a67 100644 --- a/src/H5Aint.c +++ b/src/H5Aint.c @@ -83,6 +83,7 @@ typedef struct { /* Local Prototypes */ /********************/ +static herr_t H5A__close_cb(H5VL_object_t *attr_vol_obj); static herr_t H5A__compact_build_table_cb(H5O_t *oh, H5O_mesg_t *mesg /*in,out*/, unsigned sequence, unsigned *oh_flags_ptr, void *_udata /*in,out*/); static herr_t H5A__dense_build_table_cb(const H5A_t *attr, void *_udata); @@ -98,6 +99,9 @@ static herr_t H5A__iterate_common(hid_t loc_id, H5_index_t idx_type, H5_iter_ord /* Package Variables */ /*********************/ +/* Package initialization variable */ +hbool_t H5_PKG_INIT_VAR = FALSE; + /* Format version bounds for attribute */ const unsigned H5O_attr_ver_bounds[] = { H5O_ATTR_VERSION_1, /* H5F_LIBVER_EARLIEST */ @@ -115,8 +119,162 @@ const unsigned H5O_attr_ver_bounds[] = { /* Local Variables */ /*******************/ +/* Declare the free lists of H5A_t */ +H5FL_DEFINE(H5A_t); + +/* Declare the free lists for H5A_shared_t's */ +H5FL_DEFINE(H5A_shared_t); + +/* Declare a free list to manage blocks of type conversion data */ +H5FL_BLK_DEFINE(attr_buf); + typedef H5A_t *H5A_t_ptr; -H5FL_SEQ_DEFINE(H5A_t_ptr); +H5FL_SEQ_DEFINE_STATIC(H5A_t_ptr); + +/* Attribute ID class */ +static const H5I_class_t H5I_ATTR_CLS[1] = {{ + H5I_ATTR, /* ID class value */ + 0, /* Class flags */ + 0, /* # of reserved IDs for class */ + (H5I_free_t)H5A__close_cb /* Callback routine for closing objects of this class */ +}}; + +/* Flag indicating "top" of interface has been initialized */ +static hbool_t H5A_top_package_initialize_s = FALSE; + +/*------------------------------------------------------------------------- + * Function: H5A_init + * + * Purpose: Initialize the interface from some other layer. + * + * Return: Success: non-negative + * + * Failure: negative + *------------------------------------------------------------------------- + */ +herr_t +H5A_init(void) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + /* FUNC_ENTER() does all the work */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5A_init() */ + +/*-------------------------------------------------------------------------- +NAME + H5A__init_package -- Initialize interface-specific information +USAGE + herr_t H5A__init_package() + +RETURNS + Non-negative on success/Negative on failure +DESCRIPTION + Initializes any interface-specific data or routines. + +--------------------------------------------------------------------------*/ +herr_t +H5A__init_package(void) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_PACKAGE + + /* + * Create attribute ID type. + */ + if (H5I_register_type(H5I_ATTR_CLS) < 0) + HGOTO_ERROR(H5E_ATTR, H5E_CANTINIT, FAIL, "unable to initialize interface") + + /* Mark "top" of interface as initialized, too */ + H5A_top_package_initialize_s = TRUE; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5A__init_package() */ + +/*-------------------------------------------------------------------------- + NAME + H5A_top_term_package + PURPOSE + Terminate various H5A objects + USAGE + void H5A_top_term_package() + RETURNS + DESCRIPTION + Release IDs for the atom group, deferring full interface shutdown + until later (in H5A_term_package). + GLOBAL VARIABLES + COMMENTS, BUGS, ASSUMPTIONS + Can't report errors... + EXAMPLES + REVISION LOG +--------------------------------------------------------------------------*/ +int +H5A_top_term_package(void) +{ + int n = 0; + + FUNC_ENTER_NOAPI_NOINIT_NOERR + + if (H5A_top_package_initialize_s) { + if (H5I_nmembers(H5I_ATTR) > 0) { + (void)H5I_clear_type(H5I_ATTR, FALSE, FALSE); + n++; /*H5I*/ + } /* end if */ + + /* Mark closed */ + if (0 == n) + H5A_top_package_initialize_s = FALSE; + } /* end if */ + + FUNC_LEAVE_NOAPI(n) +} /* H5A_top_term_package() */ + +/*-------------------------------------------------------------------------- + NAME + H5A_term_package + PURPOSE + Terminate various H5A objects + USAGE + void H5A_term_package() + RETURNS + DESCRIPTION + Release any other resources allocated. + GLOBAL VARIABLES + COMMENTS, BUGS, ASSUMPTIONS + Can't report errors... + + Finishes shutting down the interface, after H5A_top_term_package() + is called + EXAMPLES + REVISION LOG +--------------------------------------------------------------------------*/ +int +H5A_term_package(void) +{ + int n = 0; + + FUNC_ENTER_NOAPI_NOINIT_NOERR + + if (H5_PKG_INIT_VAR) { + /* Sanity checks */ + HDassert(0 == H5I_nmembers(H5I_ATTR)); + HDassert(FALSE == H5A_top_package_initialize_s); + + /* Destroy the attribute object id group */ + n += (H5I_dec_type_ref(H5I_ATTR) > 0); + + /* Mark closed */ + if (0 == n) + H5_PKG_INIT_VAR = FALSE; + } /* end if */ + + FUNC_LEAVE_NOAPI(n) +} /* H5A_term_package() */ /*------------------------------------------------------------------------- * Function: H5A__create @@ -356,12 +514,12 @@ done: * *------------------------------------------------------------------------- */ -herr_t +static herr_t H5A__open_common(const H5G_loc_t *loc, H5A_t *attr) { herr_t ret_value = SUCCEED; /* Return value */ - FUNC_ENTER_PACKAGE + FUNC_ENTER_STATIC /* check args */ HDassert(loc); @@ -1134,12 +1292,12 @@ H5A__shared_free(H5A_t *attr) * *------------------------------------------------------------------------- */ -herr_t +static herr_t H5A__close_cb(H5VL_object_t *attr_vol_obj) { herr_t ret_value = SUCCEED; /* Return value */ - FUNC_ENTER_PACKAGE + FUNC_ENTER_STATIC /* Sanity check */ HDassert(attr_vol_obj); @@ -1813,7 +1971,7 @@ H5A__attr_iterate_table(const H5A_attr_table_t *atable, hsize_t skip, hsize_t *l HDassert("unknown attribute op type" && 0); #ifdef NDEBUG HGOTO_ERROR(H5E_ATTR, H5E_UNSUPPORTED, FAIL, "unsupported attribute op type") -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ /* Increment the number of entries passed through */ diff --git a/src/H5Amodule.h b/src/H5Amodule.h index 707fc54..09e6c4a 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -29,4 +29,21 @@ #define H5_MY_PKG_ERR H5E_ATTR #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. + * + * 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. + * + */ + #endif /* _H5Amodule_H */ diff --git a/src/H5Apkg.h b/src/H5Apkg.h index 49d86b1..5a64a1b 100644 --- a/src/H5Apkg.h +++ b/src/H5Apkg.h @@ -185,14 +185,12 @@ H5_DLL H5A_t *H5A__open(const H5G_loc_t *loc, const char *attr_name); H5_DLL H5A_t *H5A__open_by_name(const H5G_loc_t *loc, const char *obj_name, const char *attr_name); H5_DLL H5A_t *H5A__open_by_idx(const H5G_loc_t *loc, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n); -H5_DLL herr_t H5A__open_common(const H5G_loc_t *loc, H5A_t *attr); H5_DLL H5A_t *H5A__copy(H5A_t *new_attr, const H5A_t *old_attr); H5_DLL hid_t H5A__get_type(H5A_t *attr); H5_DLL herr_t H5A__get_info(const H5A_t *attr, H5A_info_t *ainfo); H5_DLL hid_t H5A__get_create_plist(H5A_t *attr); H5_DLL herr_t H5A__shared_free(H5A_t *attr); H5_DLL herr_t H5A__close(H5A_t *attr); -H5_DLL herr_t H5A__close_cb(H5VL_object_t *attr_vol_obj); H5_DLL htri_t H5A__get_ainfo(H5F_t *f, H5O_t *oh, H5O_ainfo_t *ainfo); H5_DLL herr_t H5A__set_version(const H5F_t *f, H5A_t *attr); H5_DLL herr_t H5A__rename_by_name(H5G_loc_t loc, const char *obj_name, const char *old_attr_name, diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 89a3b04..c3442b8 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -45,18 +45,285 @@ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_nam extern "C" { #endif +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] attr_name Name of attribute + * \param[in] type_id Attribute datatype identifier + * \space_id + * \acpl_id + * \aapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Acreate2() creates an attribute, \p attr_name, which is attached + * to the object specified by the identifier \p loc_id. + * + * The attribute name, \p attr_name, must be unique for the object. + * + * The attribute is created with the specified datatype and dataspace, + * \p type_id and \p space_id, which are created with the H5T and + * H5S interfaces, respectively. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the + * datatype. String datatypes are derived from #H5T_C_S1 (or + * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in + * size. See H5Tset_size() and Creating variable-length string + * datatypes. + * + * The access property list is currently unused, but will be used in + * the future. This property list should currently be #H5P_DEFAULT. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() resource leaks will develop. + * + * \note The \p acpl and \p aapl parameters are currently not used; specify + * #H5P_DEFAULT. + * \note If \p loc_id is a file identifier, the attribute will be attached + * that file’s root group. + * + * \since 1.8.0 + * + * \see H5Aclose() + * + */ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] obj_name Name, relative to \p loc_id, of object that + * attribute is to be attached to + * \param[in] attr_name Attribute name + * \param[in] type_id Attribute datatype identifier + * \space_id + * \acpl_id + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Acreate_by_name() creates an attribute, \p attr_name, which is + * attached to the object specified by \p loc_id and \p obj_name. + * + * \p loc_id is a location identifier; \p obj_name is the object + * name relative to \p loc_id. If \p loc_id fully specifies the + * object to which the attribute is to be attached, \p obj_name + * should be '.' (a dot). + * + * The attribute name, \p attr_name, must be unique for the object. + * + * The attribute is created with the specified datatype and + * dataspace, \p type_id and \p space_id, which are created with + * the H5T and H5S interfaces respectively. + * + * The attribute creation and access property lists are currently + * unused, but will be used in the future for optional attribute + * creation and access properties. These property lists should + * currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * The attribute identifier returned by this function must be + * released with H5close() or resource leaks will develop. + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute for an object specified by object identifier and + * attribute name + * + * \fgdt_loc_id{obj_id} + * \param[in] attr_name Name of attribute to open + * \aapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen() opens an existing attribute, \p attr_name, that is + * attached to object specified by an object identifier, \p obj_id. + * + * The attribute access property list, \p aapl_id, is currently unused + * and should be #H5P_DEFAULT. + * + * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called + * before the attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + * \see H5Aclose(), H5Acreate() + */ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); -H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, - hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens the nth attribute attached to an object + * + * \loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to location + * \param[in] idx_type Type of index + * \param[in] order Index traversal order + * \param[in] n Attribute’s position in index + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen_by_idx() opens an existing attribute that is attached + * to an object specified by location and name, \p loc_id and + * \p obj_name, respectively. If \p loc_id fully specifies the + * object to which the attribute is attached, \p obj_name, should + * be '.' (a dot). + * + * The attribute is identified by an index type, an index traversal + * order, and a position in the index, \p idx_type, \p order and + * \p n, respectively. These parameters and their valid values are + * discussed in the description of H5Aiterate2(). + * + * The attribute access property list, \p aapl_id, is currently + * unused and should currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * This function, H5Aopen(), or H5Aopen_by_name() must be called + * before an attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, hid_t lapl_id); -H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute for an object by object name and attribute name + * + * \fgdt_loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to \p loc_id + * \param[in] attr_name Name of attribute to open + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen_by_name() opens an existing attribute, \p attr_name, + * that is attached to an object specified by location and name, + * \p loc_id and \p obj_name, respectively. + * + * \p loc_id specifies a location from which the target object can + * be located and \p obj_name is an object name relative to + * \p loc_id. If \p loc_id fully specifies the object to which the + * attribute is attached, \p obj_name should be '.' (a dot). + * + * The attribute access property list, \p aapl_id, is currently + * unused and should currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * This function, H5Aopen(), or H5Aopen_by_idx() must be called + * before an attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, + hid_t lapl_id); +/*-------------------------------------------------------------------------- */ +/** + * \ingroup H5A + * + * \brief Reads the value of an attribute + * + * \attr_id + * \mem_type_id{type_id} + * \param[out] buf Buffer for data to be read + * + * \return \herr_t + * + * \details H5Aread() reads an attribute, specified with \p attr_id. The + * attribute's in-memory datatype is specified with \p type_id. The + * entire attribute is read into \p buf from the file. + * + * Datatype conversion takes place at the time of a read or write and + * is automatic. + * + * \version 1.8.8 Fortran updated to Fortran2003. + * \version 1.4.2 The \p dims parameter was added to the Fortran API in this + * release. + * \since 1.0.0 + * + * \see H5Awrite() + * +*/ H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); -H5_DLL herr_t H5Aclose(hid_t attr_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Writes data to an attribute + * + * \attr_id + * \mem_type_id{type_id} + * \param[out] buf Data to be written + * + * \return \herr_t + * + * \details H5Awrite() writes an attribute, specified with \p attr_id. The + * attribute's in-memory datatype is specified with \p type_id. + * The entire attribute is written from \p buf to the file. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the datatype. + * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for + * Fortran codes), which defaults to 1 character in size. + * See H5Tset_size() and Creating variable-length string datatypes. + * + * Datatype conversion takes place at the time of a read or write and + * is automatic. + * + * \version 1.8.8 Fortran updated to Fortran2003. + * \version 1.4.2 Fortran \p dims parameter added in this release + * \since 1.0.0 + * \see H5Aread() + * + */ +H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); H5_DLL hid_t H5Aget_space(hid_t attr_id); H5_DLL hid_t H5Aget_type(hid_t attr_id); H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); @@ -84,6 +351,27 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id hsize_t n, hid_t lapl_id); H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Closes the specified attribute + * + * \attr_id + * + * \return \herr_t + * + * \details H5Aclose() terminates access to the attribute specified by + * \p attr_id by releasing the identifier. + * + * \attention Further use of a released attribute identifier is illegal; a + * function using such an identifier will generate an error. + * + * \since 1.0.0 + * + * \see H5Acreate(), H5Aopen() + */ +H5_DLL herr_t H5Aclose(hid_t attr_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -100,6 +388,51 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam void *operator_data /*in,out*/); /* Function prototypes */ +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] name Name of attribute to locate and open + * \param[in] type_id Identifier of attribute datatype + * \space_id + * \acpl_id + * + * \return \hid_tv{attribute} + * + * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT. + * + * \deprecated Deprecated in favor of H5Acreate2() + * + * \details H5Acreate1() creates an attribute, \p name, which is attached + * to the object specified by the identifier \p loc_id. + * + * The attribute name, \p name, must be unique for the object. + * + * The attribute is created with the specified datatype and dataspace, + * \p type_id and \p space_id, which are created with the H5T and + * H5S interfaces, respectively. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the + * datatype. String datatypes are derived from #H5T_C_S1 (or + * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in + * size. See H5Tset_size() and Creating variable-length string + * datatypes. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() resource leaks will develop. + * + * \since 1.8.0 + * + * \version 1.8.0 The function H5Acreate() was renamed to H5Acreate1() and + * deprecated in this release. + * + * \see H5Aclose() + * + */ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id); H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name); H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); @@ -1313,9 +1313,9 @@ H5B2_modify(H5B2_t *bt2, void *udata, H5B2_modify_t op, void *op_data) */ #ifdef OLD_WAY HGOTO_ERROR(H5E_BTREE, H5E_NOTFOUND, FAIL, "key not found in leaf node") -#else /* OLD_WAY */ +#else /* OLD_WAY */ HGOTO_DONE(FAIL) -#endif /* OLD_WAY */ +#endif /* OLD_WAY */ } /* end if */ else { /* Make callback for current record */ diff --git a/src/H5B2cache.c b/src/H5B2cache.c index ce91085..106542e 100644 --- a/src/H5B2cache.c +++ b/src/H5B2cache.c @@ -486,9 +486,9 @@ H5B2__cache_hdr_notify(H5AC_notify_action_t action, void *_thing) default: #ifdef NDEBUG HGOTO_ERROR(H5E_BTREE, H5E_BADVALUE, FAIL, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ } /* end if */ else @@ -904,9 +904,9 @@ H5B2__cache_int_notify(H5AC_notify_action_t action, void *_thing) default: #ifdef NDEBUG HGOTO_ERROR(H5E_BTREE, H5E_BADVALUE, FAIL, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ } /* end if */ else @@ -1283,9 +1283,9 @@ H5B2__cache_leaf_notify(H5AC_notify_action_t action, void *_thing) default: #ifdef NDEBUG HGOTO_ERROR(H5E_BTREE, H5E_BADVALUE, FAIL, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ } /* end if */ else @@ -576,7 +576,7 @@ void H5C_def_auto_resize_rpt_fcn(H5C_t *cache_ptr, #ifndef NDEBUG int32_t version, -#else /* NDEBUG */ +#else /* NDEBUG */ int32_t H5_ATTR_UNUSED version, #endif /* NDEBUG */ double hit_rate, enum H5C_resize_status status, size_t old_max_cache_size, @@ -806,7 +806,7 @@ H5C_prep_for_file_close(H5F_t *f) */ if (H5C__serialize_cache(f) < 0) HGOTO_ERROR(H5E_CACHE, H5E_CANTSERIALIZE, FAIL, "serialization of the cache failed") - } /* end if */ + } /* end if */ #endif /* H5_HAVE_PARALLEL */ done: @@ -1310,7 +1310,7 @@ H5C_insert_entry(H5F_t *f, const H5C_class_t *type, haddr_t addr, void *thing, u hbool_t flush_last; #ifdef H5_HAVE_PARALLEL hbool_t coll_access = FALSE; /* whether access to the cache entry is done collectively */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ hbool_t set_flush_marker; hbool_t write_permitted = TRUE; size_t empty_space; @@ -2092,7 +2092,7 @@ H5C_resize_entry(void *thing, size_t new_size) H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr->coll_list_len), (cache_ptr->coll_list_size), (entry_ptr->size), (new_size)) } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ /* update statistics just before changing the entry size */ H5C__UPDATE_STATS_FOR_ENTRY_SIZE_CHANGE(cache_ptr, entry_ptr, new_size); @@ -2228,7 +2228,7 @@ H5C_protect(H5F_t *f, const H5C_class_t *type, haddr_t addr, void *udata, unsign hbool_t flush_last; #ifdef H5_HAVE_PARALLEL hbool_t coll_access = FALSE; /* whether access to the cache entry is done collectively */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ hbool_t write_permitted; hbool_t was_loaded = FALSE; /* Whether the entry was loaded as a result of the protect */ size_t empty_space; @@ -2348,7 +2348,7 @@ H5C_protect(H5F_t *f, const H5C_class_t *type, haddr_t addr, void *udata, unsign H5C__MOVE_TO_TOP_IN_COLL_LIST(cache_ptr, entry_ptr, NULL) } /* end else-if */ } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ #if H5C_DO_TAGGING_SANITY_CHECKS { @@ -3359,7 +3359,7 @@ H5C_unprotect(H5F_t *f, haddr_t addr, void *thing, unsigned flags) if (!dirtied) clear_entry = TRUE; } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ if (!entry_ptr->is_protected) @@ -3538,7 +3538,7 @@ H5C_unprotect(H5F_t *f, haddr_t addr, void *thing, unsigned flags) HGOTO_ERROR(H5E_CACHE, H5E_CANTUNPROTECT, FAIL, "Can't clear entry") } /* end else if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ } H5C__UPDATE_STATS_FOR_UNPROTECT(cache_ptr) @@ -3899,7 +3899,7 @@ H5C_create_flush_dependency(void *parent_thing, void *child_thing) for (u = 0; u < child_entry->flush_dep_nparents; u++) HDassert(child_entry->flush_dep_parent[u] != parent_entry); - } /* end block */ + } /* end block */ #endif /* NDEBUG */ /* More sanity checks */ @@ -4138,13 +4138,13 @@ done: * *------------------------------------------------------------------------- */ -#if H5C_COLLECT_CACHE_STATS -static herr_t -H5C__pin_entry_from_client(H5C_t *cache_ptr, H5C_cache_entry_t *entry_ptr) -#else static herr_t -H5C__pin_entry_from_client(H5C_t H5_ATTR_UNUSED *cache_ptr, H5C_cache_entry_t *entry_ptr) +H5C__pin_entry_from_client(H5C_t +#if !H5C_COLLECT_CACHE_STATS + H5_ATTR_UNUSED #endif + * cache_ptr, + H5C_cache_entry_t *entry_ptr) { herr_t ret_value = SUCCEED; /* Return value */ @@ -5823,7 +5823,7 @@ H5C__flush_invalidate_ring(H5F_t *f, H5C_ring_t ring, unsigned flags) HDassert(cache_ptr->slist_size == (size_t)((ssize_t)initial_slist_size + cache_ptr->slist_size_increase)); } /* end if */ -#endif /* H5C_DO_SANITY_CHECKS */ +#endif /* H5C_DO_SANITY_CHECKS */ /* Since we are doing a destroy, we must make a pass through * the hash table and try to flush - destroy all entries that @@ -6321,7 +6321,7 @@ H5C__flush_ring(H5F_t *f, H5C_ring_t ring, unsigned flags) HDassert(cache_ptr->slist_ring_len[ring] == 0); HDassert(cache_ptr->slist_ring_size[ring] == 0); - } /* end if */ + } /* end if */ #endif /* H5C_DO_SANITY_CHECKS */ done: @@ -6763,7 +6763,7 @@ H5C__flush_single_entry(H5F_t *f, H5C_cache_entry_t *entry_ptr, unsigned flags) H5C__REMOVE_FROM_COLL_LIST(cache_ptr, entry_ptr, FAIL) } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ H5C__UPDATE_RP_FOR_EVICTION(cache_ptr, entry_ptr, FAIL) @@ -7130,7 +7130,7 @@ H5C__load_entry(H5F_t *f, int mpi_rank = 0; /* MPI process rank */ MPI_Comm comm = MPI_COMM_NULL; /* File MPI Communicator */ int mpi_code; /* MPI error code */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ void *ret_value = NULL; /* Return value */ FUNC_ENTER_STATIC @@ -7176,7 +7176,7 @@ H5C__load_entry(H5F_t *f, HGOTO_ERROR(H5E_FILE, H5E_CANTGET, NULL, "Can't get MPI rank") if ((comm = H5F_mpi_get_comm(f)) == MPI_COMM_NULL) HGOTO_ERROR(H5E_FILE, H5E_CANTGET, NULL, "get_comm request failed") - } /* end if */ + } /* end if */ #endif /* H5_HAVE_PARALLEL */ /* Get the on-disk entry image */ @@ -7206,7 +7206,7 @@ H5C__load_entry(H5F_t *f, image = (uint8_t *)new_image; #if H5C_DO_MEMORY_SANITY_CHECKS H5MM_memcpy(image + len, H5C_IMAGE_SANITY_VALUE, H5C_IMAGE_EXTRA_SPACE); -#endif /* H5C_DO_MEMORY_SANITY_CHECKS */ +#endif /* H5C_DO_MEMORY_SANITY_CHECKS */ } /* end if */ #ifdef H5_HAVE_PARALLEL @@ -7227,7 +7227,7 @@ H5C__load_entry(H5F_t *f, if (MPI_SUCCESS != (mpi_code = MPI_Bcast(image, buf_size, MPI_BYTE, 0, comm))) HMPI_GOTO_ERROR(NULL, "MPI_Bcast failed", mpi_code) } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ /* If the entry could be read speculatively and the length is still * changing, check for updating the actual size @@ -7275,9 +7275,9 @@ H5C__load_entry(H5F_t *f, (mpi_code = MPI_Bcast(image + len, buf_size, MPI_BYTE, 0, comm))) HMPI_GOTO_ERROR(NULL, "MPI_Bcast failed", mpi_code) } /* end if */ -#endif /* H5_HAVE_PARALLEL */ - } /* end if */ - } /* end if (actual_len != len) */ +#endif /* H5_HAVE_PARALLEL */ + } /* end if */ + } /* end if (actual_len != len) */ else { /* The length has stabilized */ len_changed = FALSE; @@ -7306,8 +7306,7 @@ H5C__load_entry(H5F_t *f, /* Check for too many tries */ if (tries == 0) - HGOTO_ERROR(H5E_CACHE, H5E_READERROR, NULL, - "incorrect metadatda checksum after all read attempts") + HGOTO_ERROR(H5E_CACHE, H5E_READERROR, NULL, "incorrect metadata checksum after all read attempts") /* Calculate and track the # of retries */ retries = max_tries - tries; @@ -8534,7 +8533,7 @@ H5C__serialize_cache(H5F_t *f) scan_ptr = scan_ptr->il_next; } /* end while */ } /* end block */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ /* set cache_ptr->serialization_in_progress to TRUE, and back * to FALSE at the end of the function. Must maintain this flag @@ -8600,7 +8599,7 @@ H5C__serialize_cache(H5F_t *f) scan_ptr = scan_ptr->il_next; } /* end while */ } /* end block */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ done: cache_ptr->serialization_in_progress = FALSE; @@ -8777,7 +8776,7 @@ H5C__serialize_ring(H5F_t *f, H5C_ring_t ring) #ifndef NDEBUG /* Increment serialization counter (to detect multiple serializations) */ entry_ptr->serialization_count++; -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end if */ } /* end if */ @@ -8846,7 +8845,7 @@ H5C__serialize_ring(H5F_t *f, H5C_ring_t ring) #ifndef NDEBUG /* Increment serialization counter (to detect multiple serializations) */ entry_ptr->serialization_count++; -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end if */ } /* end if */ else { @@ -8911,7 +8910,7 @@ H5C__serialize_single_entry(H5F_t *f, H5C_t *cache_ptr, H5C_cache_entry_t *entry H5MM_memcpy(((uint8_t *)entry_ptr->image_ptr) + image_size, H5C_IMAGE_SANITY_VALUE, H5C_IMAGE_EXTRA_SPACE); #endif /* H5C_DO_MEMORY_SANITY_CHECKS */ - } /* end if */ + } /* end if */ /* Generate image for entry */ if (H5C__generate_image(f, cache_ptr, entry_ptr) < 0) @@ -9218,7 +9217,7 @@ H5C_remove_entry(void *_entry) if (entry->coll_access) { entry->coll_access = FALSE; H5C__REMOVE_FROM_COLL_LIST(cache, entry, FAIL) - } /* end if */ + } /* end if */ #endif /* H5_HAVE_PARALLEL */ H5C__UPDATE_RP_FOR_EVICTION(cache, entry, FAIL) @@ -213,7 +213,7 @@ typedef struct H5CX_t { MPI_Datatype ftype; /* MPI datatype for file, when using collective I/O */ hbool_t mpi_file_flushing; /* Whether an MPI-opened file is being flushed */ hbool_t rank0_bcast; /* Whether a dataset meets read-with-rank0-and-bcast requirements */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ /* Cached DXPL properties */ size_t max_temp_buf; /* Maximum temporary buffer size */ @@ -241,8 +241,8 @@ typedef struct H5CX_t { hbool_t mpio_chunk_opt_num_valid; /* Whether collective chunk threshold is valid */ unsigned mpio_chunk_opt_ratio; /* Collective chunk ratio (H5D_XFER_MPIO_CHUNK_OPT_RATIO_NAME) */ hbool_t mpio_chunk_opt_ratio_valid; /* Whether collective chunk ratio is valid */ -#endif /* H5_HAVE_PARALLEL */ - H5Z_EDC_t err_detect; /* Error detection info (H5D_XFER_EDC_NAME) */ +#endif /* H5_HAVE_PARALLEL */ + H5Z_EDC_t err_detect; /* Error detection info (H5D_XFER_EDC_NAME) */ hbool_t err_detect_valid; /* Whether error detection info is valid */ H5Z_cb_t filter_cb; /* Filter callback function (H5D_XFER_FILTER_CB_NAME) */ hbool_t filter_cb_valid; /* Whether filter callback function is valid */ @@ -298,8 +298,8 @@ typedef struct H5CX_t { (H5D_XFER_COLL_CHUNK_MULTI_RATIO_IND_NAME) */ hbool_t mpio_coll_rank0_bcast_set; /* Whether instrumented "collective chunk multi ratio ind" value is set */ -#endif /* H5_HAVE_INSTRUMENTED_LIBRARY */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_INSTRUMENTED_LIBRARY */ +#endif /* H5_HAVE_PARALLEL */ /* Cached LCPL properties */ H5T_cset_t encoding; /* Link name character encoding */ @@ -373,7 +373,7 @@ typedef struct H5CX_dxpl_cache_t { mpio_chunk_opt_mode; /* Collective chunk option (H5D_XFER_MPIO_CHUNK_OPT_HARD_NAME) */ unsigned mpio_chunk_opt_num; /* Collective chunk thrreshold (H5D_XFER_MPIO_CHUNK_OPT_NUM_NAME) */ unsigned mpio_chunk_opt_ratio; /* Collective chunk ratio (H5D_XFER_MPIO_CHUNK_OPT_RATIO_NAME) */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ H5Z_EDC_t err_detect; /* Error detection info (H5D_XFER_EDC_NAME) */ H5Z_cb_t filter_cb; /* Filter callback function (H5D_XFER_FILTER_CB_NAME) */ H5Z_data_xform_t * data_transform; /* Data transform info (H5D_XFER_XFORM_NAME) */ @@ -437,7 +437,7 @@ hbool_t H5_PKG_INIT_VAR = FALSE; #ifndef H5_HAVE_THREADSAFE static H5CX_node_t *H5CX_head_g = NULL; /* Pointer to head of context stack */ -#endif /* H5_HAVE_THREADSAFE */ +#endif /* H5_HAVE_THREADSAFE */ /* Define a "default" dataset transfer property list cache structure to use for default DXPLs */ static H5CX_dxpl_cache_t H5CX_def_dxpl_cache; @@ -932,9 +932,11 @@ H5CX_retrieve_state(H5CX_state_t **api_state) /* Keep a reference to the current VOL wrapping context */ (*api_state)->vol_wrap_ctx = (*head)->ctx.vol_wrap_ctx; - if (NULL != (*api_state)->vol_wrap_ctx) + if (NULL != (*api_state)->vol_wrap_ctx) { + HDassert((*head)->ctx.vol_wrap_ctx_valid); if (H5VL_inc_vol_wrapper((*api_state)->vol_wrap_ctx) < 0) HGOTO_ERROR(H5E_CONTEXT, H5E_CANTINC, FAIL, "can't increment refcount on VOL wrapping context") + } /* end if */ /* Keep a copy of the VOL connector property, if there is one */ if ((*head)->ctx.vol_connector_prop_valid && (*head)->ctx.vol_connector_prop.connector_id > 0) { @@ -1023,6 +1025,8 @@ H5CX_restore_state(const H5CX_state_t *api_state) /* Restore the VOL wrapper context */ (*head)->ctx.vol_wrap_ctx = api_state->vol_wrap_ctx; + if (NULL != (*head)->ctx.vol_wrap_ctx) + (*head)->ctx.vol_wrap_ctx_valid = TRUE; /* Restore the VOL connector info */ if (api_state->vol_connector_prop.connector_id) { @@ -1377,8 +1381,8 @@ H5CX_set_apl(hid_t *acspl_id, const H5P_libclass_t *libclass, if (H5P_USER_TRUE == md_coll_read) is_collective = TRUE; } /* end if */ -#endif /* H5_HAVE_PARALLEL */ - } /* end else */ +#endif /* H5_HAVE_PARALLEL */ + } /* end else */ #ifdef H5_HAVE_PARALLEL /* Check for collective operation */ @@ -1404,7 +1408,7 @@ H5CX_set_apl(hid_t *acspl_id, const H5P_libclass_t *libclass, MPI_Barrier(mpi_comm); } /* end if */ } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ done: FUNC_LEAVE_NOAPI(ret_value) @@ -1465,7 +1469,7 @@ H5CX_set_loc(hid_t done: FUNC_LEAVE_NOAPI(ret_value) -#else /* H5_HAVE_PARALLEL */ +#else /* H5_HAVE_PARALLEL */ FUNC_ENTER_NOAPI_NOINIT_NOERR FUNC_LEAVE_NOAPI(SUCCEED) diff --git a/src/H5Cdbg.c b/src/H5Cdbg.c index a8917ea..3cd6e6c 100644 --- a/src/H5Cdbg.c +++ b/src/H5Cdbg.c @@ -434,7 +434,7 @@ H5C_stats(H5C_t *cache_ptr, const char *cache_name, double average_entries_skipped_per_calls_to_msic = 0.0f; double average_dirty_pf_entries_skipped_per_call_to_msic = 0.0f; double average_entries_scanned_per_calls_to_msic = 0.0f; -#endif /* H5C_COLLECT_CACHE_STATS */ +#endif /* H5C_COLLECT_CACHE_STATS */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_NOAPI(FAIL) @@ -489,7 +489,7 @@ H5C_stats(H5C_t *cache_ptr, const char *cache_name, if (aggregate_max_pins < cache_ptr->max_pins[i]) aggregate_max_pins = cache_ptr->max_pins[i]; #endif /* H5C_COLLECT_CACHE_ENTRY_STATS */ - } /* end for */ + } /* end for */ if ((total_hits > 0) || (total_misses > 0)) hit_rate = (double)100.0f * ((double)(total_hits)) / ((double)(total_hits + total_misses)); @@ -738,7 +738,7 @@ H5C_stats__reset(H5C_t *cache_ptr) #else /* NDEBUG */ #if H5C_COLLECT_CACHE_STATS H5C_stats__reset(H5C_t *cache_ptr) -#else /* H5C_COLLECT_CACHE_STATS */ +#else /* H5C_COLLECT_CACHE_STATS */ H5C_stats__reset(H5C_t H5_ATTR_UNUSED *cache_ptr) #endif /* H5C_COLLECT_CACHE_STATS */ #endif /* NDEBUG */ diff --git a/src/H5Cimage.c b/src/H5Cimage.c index b3f6c12..3135969 100644 --- a/src/H5Cimage.c +++ b/src/H5Cimage.c @@ -361,7 +361,7 @@ H5C__construct_cache_image_buffer(H5F_t *f, H5C_t *cache_ptr) fake_cache_ptr->image_entries = (H5C_image_entry_t *)H5MM_xfree(fake_cache_ptr->image_entries); fake_cache_ptr = (H5C_t *)H5MM_xfree(fake_cache_ptr); - } /* end block */ + } /* end block */ #endif /* NDEBUG */ done: @@ -908,7 +908,7 @@ done: herr_t #if H5C_COLLECT_CACHE_STATS H5C_image_stats(H5C_t *cache_ptr, hbool_t print_header) -#else /* H5C_COLLECT_CACHE_STATS */ +#else /* H5C_COLLECT_CACHE_STATS */ H5C_image_stats(H5C_t *cache_ptr, hbool_t H5_ATTR_UNUSED print_header) #endif /* H5C_COLLECT_CACHE_STATS */ { @@ -918,7 +918,7 @@ H5C_image_stats(H5C_t *cache_ptr, hbool_t H5_ATTR_UNUSED print_header) int64_t total_misses = 0; double hit_rate; double prefetch_use_rate; -#endif /* H5C_COLLECT_CACHE_STATS */ +#endif /* H5C_COLLECT_CACHE_STATS */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_NOAPI(FAIL) @@ -1024,7 +1024,7 @@ H5C__read_cache_image(H5F_t *f, H5C_t *cache_ptr) HMPI_GOTO_ERROR(FAIL, "can't receive cache image MPI_Bcast", mpi_result) } /* end else-if */ } /* end block */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ done: FUNC_LEAVE_NOAPI(ret_value) @@ -1607,7 +1607,7 @@ H5C_set_cache_image_config(const H5F_t *f, H5C_t *cache_ptr, H5C_cache_image_ctl HDassert(!(cache_ptr->image_ctl.generate_image)); } /* end else */ #ifdef H5_HAVE_PARALLEL - } /* end else */ + } /* end else */ #endif /* H5_HAVE_PARALLEL */ done: @@ -2088,7 +2088,7 @@ H5C__destroy_pf_entry_child_flush_deps(H5C_t *cache_ptr, H5C_cache_entry_t *pf_e u++; } /* end while */ HDassert(found); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end if */ } /* end if */ @@ -3172,7 +3172,7 @@ H5C__reconstruct_cache_contents(H5F_t *f, H5C_t *cache_ptr) * we add code to store and restore adaptive resize status. */ HDassert(lru_rank_holes <= H5C__MAX_EPOCH_MARKERS); - } /* end block */ + } /* end block */ #endif /* NDEBUG */ /* Check to see if the cache is oversize, and evict entries as @@ -3480,7 +3480,7 @@ H5C__write_cache_image(H5F_t *f, const H5C_t *cache_ptr) #ifdef H5_HAVE_PARALLEL } /* end if */ } /* end block */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ done: FUNC_LEAVE_NOAPI(ret_value) diff --git a/src/H5Clog.c b/src/H5Clog.c index d48b7b1..3e7d6da 100644 --- a/src/H5Clog.c +++ b/src/H5Clog.c @@ -269,8 +269,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5C_get_logging_status(const H5C_t *cache, /*OUT*/ hbool_t *is_enabled, - /*OUT*/ hbool_t *is_currently_logging) +H5C_get_logging_status(const H5C_t *cache, hbool_t *is_enabled, hbool_t *is_currently_logging) { FUNC_ENTER_NOAPI_NOERR diff --git a/src/H5Ctag.c b/src/H5Ctag.c index a3eb173..47df69f 100644 --- a/src/H5Ctag.c +++ b/src/H5Ctag.c @@ -883,7 +883,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5C_get_tag(const void *thing, haddr_t *tag /*OUT*/) +H5C_get_tag(const void *thing, haddr_t *tag) { const H5C_cache_entry_t *entry = (const H5C_cache_entry_t *)thing; /* Pointer to cache entry */ @@ -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) @@ -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))) @@ -661,7 +661,7 @@ H5Diterate(void *buf, hid_t type_id, hid_t space_id, H5D_operator_t op, void *op herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "*xiix*x", buf, type_id, space_id, op, operator_data); + H5TRACE5("e", "*xiiDO*x", buf, type_id, space_id, op, operator_data); /* Check args */ if (NULL == op) @@ -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))) @@ -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))) @@ -997,13 +997,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks) +H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks /*out*/) { H5VL_object_t *vol_obj = NULL; /* Dataset for this operation */ herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ii*h", dset_id, fspace_id, nchunks); + H5TRACE3("e", "iix", dset_id, fspace_id, nchunks); /* 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 60bf57e..081206e 100644 --- a/src/H5Dchunk.c +++ b/src/H5Dchunk.c @@ -2429,7 +2429,7 @@ H5D__chunk_cacheable(const H5D_io_info_t *io_info, haddr_t caddr, hbool_t write_ #ifdef H5_HAVE_PARALLEL } /* end else */ #endif /* H5_HAVE_PARALLEL */ - } /* end else */ + } /* end else */ done: FUNC_LEAVE_NOAPI(ret_value) @@ -4427,7 +4427,7 @@ H5D__chunk_allocate(const H5D_io_info_t *io_info, hbool_t full_overwrite, hsize_ /* Check for the chunk expanding too much to encode in a 32-bit value */ if (orig_chunk_size > ((size_t)0xffffffff)) HGOTO_ERROR(H5E_DATASET, H5E_BADRANGE, FAIL, "chunk too large for 32-bit length") -#endif /* H5_SIZEOF_SIZE_T > 4 */ +#endif /* H5_SIZEOF_SIZE_T > 4 */ } /* end if */ } /* end if */ @@ -4629,7 +4629,7 @@ H5D__chunk_allocate(const H5D_io_info_t *io_info, hbool_t full_overwrite, hsize_ #ifdef H5_HAVE_PARALLEL } /* end else */ #endif /* H5_HAVE_PARALLEL */ - } /* end if */ + } /* end if */ /* Insert the chunk record into the index */ if (need_insert && ops->insert) diff --git a/src/H5Defl.c b/src/H5Defl.c index 1ab677a..77ea056 100644 --- a/src/H5Defl.c +++ b/src/H5Defl.c @@ -272,8 +272,8 @@ H5D__efl_read(const H5O_efl_t *efl, const H5D_t *dset, haddr_t addr, size_t size tempto_read = MIN((size_t)(efl->slot[u].size - skip), (hsize_t)size); H5_CHECK_OVERFLOW(tempto_read, hsize_t, size_t); to_read = (size_t)tempto_read; -#else /* NDEBUG */ - to_read = MIN((size_t)(efl->slot[u].size - skip), (hsize_t)size); +#else /* NDEBUG */ + to_read = MIN((size_t)(efl->slot[u].size - skip), (hsize_t)size); #endif /* NDEBUG */ if ((n = HDread(fd, buf, to_read)) < 0) HGOTO_ERROR(H5E_EFL, H5E_READERROR, FAIL, "read error in external raw data file") @@ -364,7 +364,7 @@ H5D__efl_write(const H5O_efl_t *efl, const H5D_t *dset, haddr_t addr, size_t siz tempto_write = MIN(efl->slot[u].size - skip, (hsize_t)size); H5_CHECK_OVERFLOW(tempto_write, hsize_t, size_t); to_write = (size_t)tempto_write; -#else /* NDEBUG */ +#else /* NDEBUG */ to_write = MIN((size_t)(efl->slot[u].size - skip), size); #endif /* NDEBUG */ if ((size_t)HDwrite(fd, buf, to_write) != to_write) diff --git a/src/H5Dint.c b/src/H5Dint.c index 7a2b93b..813a7c7 100644 --- a/src/H5Dint.c +++ b/src/H5Dint.c @@ -344,11 +344,6 @@ H5D__close_cb(H5VL_object_t *dset_vol_obj) HGOTO_ERROR(H5E_DATASET, H5E_CLOSEERROR, FAIL, "unable to close dataset"); done: - /* XXX: (MSC) Weird thing for datasets and filters: - * Always decrement the ref count on the VOL for datasets, since - * the ID is removed even if the close fails. - */ - /* Free the VOL object */ if (H5VL_free_object(dset_vol_obj) < 0) HGOTO_ERROR(H5E_DATASET, H5E_CANTDEC, FAIL, "unable to free VOL object"); @@ -2006,7 +2001,7 @@ H5D_close(H5D_t *dataset) HDassert("not implemented yet" && 0); #ifdef NDEBUG HGOTO_ERROR(H5E_IO, H5E_UNSUPPORTED, FAIL, "unsupported storage layout") -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ /*lint !e788 All appropriate cases are covered */ /* Destroy any cached layout information for the dataset */ @@ -2170,7 +2165,7 @@ H5D_mult_refresh_close(hid_t dset_id) HDassert("not implemented yet" && 0); #ifdef NDEBUG HGOTO_ERROR(H5E_IO, H5E_UNSUPPORTED, FAIL, "unsupported storage layout") -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ /*lint !e788 All appropriate cases are covered */ /* Destroy any cached layout information for the dataset */ @@ -2380,7 +2375,7 @@ H5D__alloc_storage(const H5D_io_info_t *io_info, H5D_time_alloc_t time_alloc, hb HDassert("not implemented yet" && 0); #ifdef NDEBUG HGOTO_ERROR(H5E_IO, H5E_UNSUPPORTED, FAIL, "unsupported storage layout") -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ /*lint !e788 All appropriate cases are covered */ /* Check if we need to initialize the space */ @@ -2502,7 +2497,7 @@ H5D__init_storage(const H5D_io_info_t *io_info, hbool_t full_overwrite, hsize_t HDassert("not implemented yet" && 0); #ifdef NDEBUG HGOTO_ERROR(H5E_IO, H5E_UNSUPPORTED, FAIL, "unsupported storage layout") -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ /*lint !e788 All appropriate cases are covered */ done: diff --git a/src/H5Dmpio.c b/src/H5Dmpio.c index df7c829..71e5f0a 100644 --- a/src/H5Dmpio.c +++ b/src/H5Dmpio.c @@ -207,6 +207,9 @@ typedef struct H5D_filtered_collective_io_info_t { } async_info; } H5D_filtered_collective_io_info_t; +/* Function pointer typedef for sort function */ +typedef int (*H5D_mpio_sort_func_cb_t)(const void *, const void *); + /********************/ /* Local Prototypes */ /********************/ @@ -424,7 +427,7 @@ H5D__mpio_opt_possible(const H5D_io_info_t *io_info, const H5S_t *file_space, co #ifdef H5_HAVE_INSTRUMENTED_LIBRARY H5CX_test_set_mpio_coll_rank0_bcast(TRUE); #endif /* H5_HAVE_INSTRUMENTED_LIBRARY */ - } /* end if */ + } /* end if */ /* Set the return value, based on the global cause */ ret_value = global_cause[0] > 0 ? FALSE : TRUE; @@ -527,7 +530,7 @@ done: static herr_t H5D__mpio_array_gatherv(void *local_array, size_t local_array_num_entries, size_t array_entry_size, void **_gathered_array, size_t *_gathered_array_num_entries, hbool_t allgather, - int root, MPI_Comm comm, int (*sort_func)(const void *, const void *)) + int root, MPI_Comm comm, H5D_mpio_sort_func_cb_t sort_func) { size_t gathered_array_num_entries = 0; /* The size of the newly-constructed array */ void * gathered_array = NULL; /* The newly-constructed array returned to the caller */ @@ -843,7 +846,7 @@ H5D__chunk_collective_io(H5D_io_info_t *io_info, const H5D_type_info_t *type_inf else temp_not_link_io = TRUE; #endif /* H5_HAVE_INSTRUMENTED_LIBRARY */ - } /* end else */ + } /* end else */ #ifdef H5_HAVE_INSTRUMENTED_LIBRARY { diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 6a85a95..4e40d27 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -131,7 +131,6 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t s hid_t dcpl_id, hid_t dapl_id); H5_DLL hid_t H5Dcreate_anon(hid_t file_id, hid_t type_id, hid_t space_id, hid_t plist_id, hid_t dapl_id); H5_DLL hid_t H5Dopen2(hid_t file_id, const char *name, hid_t dapl_id); -H5_DLL herr_t H5Dclose(hid_t dset_id); H5_DLL hid_t H5Dget_space(hid_t dset_id); H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); H5_DLL hid_t H5Dget_type(hid_t dset_id); @@ -163,9 +162,10 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, h void *dst_buf); H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf_size, void *dst_buf, H5D_gather_func_t op, void *op_data); -H5_DLL herr_t H5Ddebug(hid_t dset_id); +H5_DLL herr_t H5Dclose(hid_t dset_id); /* Internal API routines */ +H5_DLL herr_t H5Ddebug(hid_t dset_id); H5_DLL herr_t H5Dformat_convert(hid_t dset_id); H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); diff --git a/src/H5Dscatgath.c b/src/H5Dscatgath.c index 1a272d8..ee3fce8 100644 --- a/src/H5Dscatgath.c +++ b/src/H5Dscatgath.c @@ -916,7 +916,7 @@ H5D__compound_opt_write(size_t nelmts, const H5D_type_info_t *type_info) *------------------------------------------------------------------------- */ herr_t -H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_id, void *dst_buf) +H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_id, void *dst_buf /*out*/) { H5T_t * type; /* Datatype */ H5S_t * dst_space; /* Dataspace */ @@ -930,7 +930,7 @@ H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "x*xii*x", op, op_data, type_id, dst_space_id, dst_buf); + H5TRACE5("e", "DS*xiix", op, op_data, type_id, dst_space_id, dst_buf); /* Check args */ if (op == NULL) @@ -1012,7 +1012,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf_size, void *dst_buf, +H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf_size, void *dst_buf /*out*/, H5D_gather_func_t op, void *op_data) { H5T_t * type; /* Datatype */ @@ -1026,7 +1026,7 @@ H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "i*xiz*xx*x", src_space_id, src_buf, type_id, dst_buf_size, dst_buf, op, op_data); + H5TRACE7("e", "i*xizxDg*x", src_space_id, src_buf, type_id, dst_buf_size, dst_buf, op, op_data); /* Check args */ if (NULL == (src_space = (H5S_t *)H5I_object_verify(src_space_id, H5I_DATASPACE))) diff --git a/src/H5Dvirtual.c b/src/H5Dvirtual.c index 2588d1c..f61522f 100644 --- a/src/H5Dvirtual.c +++ b/src/H5Dvirtual.c @@ -2821,8 +2821,8 @@ H5D__virtual_read(H5D_io_info_t *io_info, const H5D_type_info_t *type_info, hsiz HDassert((tot_nelmts + (hsize_t)select_nelmts) >= nelmts); } /* end block */ #endif /* NDEBUG */ - } /* end if */ - } /* end if */ + } /* end if */ + } /* end if */ done: /* Cleanup I/O operation */ @@ -306,14 +306,14 @@ H5E__set_default_auto(H5E_t *stk) #ifndef H5_NO_DEPRECATED_SYMBOLS #ifdef H5_USE_16_API_DEFAULT stk->auto_op.vers = 1; -#else /* H5_USE_16_API */ +#else /* H5_USE_16_API */ stk->auto_op.vers = 2; #endif /* H5_USE_16_API_DEFAULT */ stk->auto_op.func1 = stk->auto_op.func1_default = (H5E_auto1_t)H5Eprint1; stk->auto_op.func2 = stk->auto_op.func2_default = (H5E_auto2_t)H5Eprint2; stk->auto_op.is_default = TRUE; -#else /* H5_NO_DEPRECATED_SYMBOLS */ +#else /* H5_NO_DEPRECATED_SYMBOLS */ stk->auto_op.func2 = (H5E_auto2_t)H5Eprint2; #endif /* H5_NO_DEPRECATED_SYMBOLS */ @@ -575,13 +575,13 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Eget_class_name(hid_t class_id, char *name, size_t size) +H5Eget_class_name(hid_t class_id, char *name /*out*/, size_t size) { H5E_cls_t *cls; /* Pointer to error class */ ssize_t ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE3("Zs", "i*sz", class_id, name, size); + H5TRACE3("Zs", "ixz", class_id, name, size); /* Get the error class */ if (NULL == (cls = (H5E_cls_t *)H5I_object_verify(class_id, H5I_ERROR_CLASS))) @@ -836,13 +836,13 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg_str, size_t size) +H5Eget_msg(hid_t msg_id, H5E_type_t *type /*out*/, char *msg_str /*out*/, size_t size) { H5E_msg_t *msg; /* Pointer to error message */ ssize_t ret_value = -1; /* Return value */ FUNC_ENTER_API_NOCLEAR((-1)) - H5TRACE4("Zs", "i*Et*sz", msg_id, type, msg_str, size); + H5TRACE4("Zs", "ixxz", msg_id, type, msg_str, size); /* Get the message object */ if (NULL == (msg = (H5E_msg_t *)H5I_object_verify(msg_id, H5I_ERROR_MSG))) @@ -1318,6 +1318,7 @@ done: * *------------------------------------------------------------------------- */ +H5_ATTR_FORMAT(printf, 8, 9) 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 *fmt, ...) @@ -1524,14 +1525,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data) +H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func /*out*/, void **client_data /*out*/) { H5E_t * estack; /* Error stack to operate on */ H5E_auto_op_t op; /* Error stack function */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*x**x", estack_id, func, client_data); + H5TRACE3("e", "ixx", estack_id, func, client_data); if (estack_id == H5E_DEFAULT) { if (NULL == (estack = H5E__get_my_stack())) /*lint !e506 !e774 Make lint 'constant value Boolean' in @@ -1589,7 +1590,7 @@ H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data) /* Don't clear the error stack! :-) */ FUNC_ENTER_API_NOCLEAR(FAIL) - H5TRACE3("e", "ix*x", estack_id, func, client_data); + H5TRACE3("e", "iEA*x", estack_id, func, client_data); if (estack_id == H5E_DEFAULT) { if (NULL == (estack = H5E__get_my_stack())) /*lint !e506 !e774 Make lint 'constant value Boolean' in diff --git a/src/H5EAcache.c b/src/H5EAcache.c index 6316ded..a41c25c 100644 --- a/src/H5EAcache.c +++ b/src/H5EAcache.c @@ -555,9 +555,9 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ } /* end if */ else @@ -939,10 +939,10 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ CATCH @@ -1346,10 +1346,10 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ CATCH @@ -1750,10 +1750,10 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ CATCH @@ -2125,10 +2125,10 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ CATCH diff --git a/src/H5EAtest.c b/src/H5EAtest.c index 0a85729..bbd436e 100644 --- a/src/H5EAtest.c +++ b/src/H5EAtest.c @@ -262,7 +262,7 @@ BEGIN_FUNC(STATIC, NOERR, herr_t, SUCCEED, -, /* Local variables */ #ifndef NDEBUG H5EA__test_ctx_t *ctx = (H5EA__test_ctx_t *)_ctx; /* Callback context to destroy */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ uint64_t * elmt = (uint64_t *)_elmt; /* Convenience pointer to native elements */ const uint8_t *raw = (const uint8_t *)_raw; /* Convenience pointer to raw elements */ diff --git a/src/H5ESpublic.h b/src/H5ESpublic.h index 63f2379..dad929e 100644 --- a/src/H5ESpublic.h +++ b/src/H5ESpublic.h @@ -10,6 +10,10 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the H5ES (event set) module. + */ + #ifndef _H5ESpublic_H #define _H5ESpublic_H diff --git a/src/H5Edeprec.c b/src/H5Edeprec.c index d3eef5d..0f887ec 100644 --- a/src/H5Edeprec.c +++ b/src/H5Edeprec.c @@ -334,14 +334,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Eget_auto1(H5E_auto1_t *func, void **client_data) +H5Eget_auto1(H5E_auto1_t *func /*out*/, void **client_data /*out*/) { H5E_t * estack; /* Error stack to operate on */ H5E_auto_op_t auto_op; /* Error stack operator */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "*x**x", func, client_data); + H5TRACE2("e", "xx", func, client_data); /* Retrieve default error stack */ if (NULL == (estack = H5E__get_my_stack())) /*lint !e506 !e774 Make lint 'constant value Boolean' in @@ -395,7 +395,7 @@ H5Eset_auto1(H5E_auto1_t func, void *client_data) /* Don't clear the error stack! :-) */ FUNC_ENTER_API_NOCLEAR(FAIL) - H5TRACE2("e", "x*x", func, client_data); + H5TRACE2("e", "Ea*x", func, client_data); if (NULL == (estack = H5E__get_my_stack())) /*lint !e506 !e774 Make lint 'constant value Boolean' in non-threaded case */ diff --git a/src/H5Eint.c b/src/H5Eint.c index c743ddb..2580fa4 100644 --- a/src/H5Eint.c +++ b/src/H5Eint.c @@ -440,10 +440,10 @@ H5E__print(const H5E_t *estack, FILE *stream, hbool_t bk_compatible) walk_op.u.func1 = H5E__walk1_cb; if (H5E__walk(estack, H5E_WALK_DOWNWARD, &walk_op, (void *)&eprint) < 0) HGOTO_ERROR(H5E_ERROR, H5E_CANTLIST, FAIL, "can't walk error stack") -#else /* H5_NO_DEPRECATED_SYMBOLS */ +#else /* H5_NO_DEPRECATED_SYMBOLS */ HDassert(0 && "version 1 error stack print without deprecated symbols!"); #endif /* H5_NO_DEPRECATED_SYMBOLS */ - } /* end if */ + } /* end if */ else { walk_op.vers = 2; walk_op.u.func2 = H5E__walk2_cb; @@ -539,10 +539,10 @@ H5E__walk(const H5E_t *estack, H5E_direction_t direction, const H5E_walk_op_t *o if (ret_value < 0) HERROR(H5E_ERROR, H5E_CANTLIST, "can't walk error stack"); } /* end if */ -#else /* H5_NO_DEPRECATED_SYMBOLS */ +#else /* H5_NO_DEPRECATED_SYMBOLS */ HDassert(0 && "version 1 error stack walk without deprecated symbols!"); -#endif /* H5_NO_DEPRECATED_SYMBOLS */ - } /* end if */ +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + } /* end if */ else { HDassert(op->vers == 2); if (op->u.func2) { @@ -939,7 +939,7 @@ H5E_dump_api_stack(hbool_t is_api) #ifdef H5_NO_DEPRECATED_SYMBOLS if (estack->auto_op.func2) (void)((estack->auto_op.func2)(H5E_DEFAULT, estack->auto_data)); -#else /* H5_NO_DEPRECATED_SYMBOLS */ +#else /* H5_NO_DEPRECATED_SYMBOLS */ if (estack->auto_op.vers == 1) { if (estack->auto_op.func1) (void)((estack->auto_op.func1)(estack->auto_data)); @@ -949,7 +949,7 @@ H5E_dump_api_stack(hbool_t is_api) (void)((estack->auto_op.func2)(H5E_DEFAULT, estack->auto_data)); } /* end else */ #endif /* H5_NO_DEPRECATED_SYMBOLS */ - } /* end if */ + } /* end if */ done: FUNC_LEAVE_NOAPI(ret_value) diff --git a/src/H5Epkg.h b/src/H5Epkg.h index a1db885..fe5e127 100644 --- a/src/H5Epkg.h +++ b/src/H5Epkg.h @@ -73,7 +73,7 @@ typedef struct { H5E_auto1_t func1_default; /* The saved library's default function - old style. */ H5E_auto2_t func2_default; /* The saved library's default function - new style. */ } H5E_auto_op_t; -#else /* H5_NO_DEPRECATED_SYMBOLS */ +#else /* H5_NO_DEPRECATED_SYMBOLS */ typedef struct { H5E_auto2_t func2; /* Only the new style callback function is available. */ } H5E_auto_op_t; @@ -85,7 +85,7 @@ typedef struct { union { #ifndef H5_NO_DEPRECATED_SYMBOLS H5E_walk1_t func1; /* Old-style callback, NO error stack param. */ -#endif /* H5_NO_DEPRECATED_SYMBOLS */ +#endif /* H5_NO_DEPRECATED_SYMBOLS */ H5E_walk2_t func2; /* New-style callback, with error stack param. */ } u; } H5E_walk_op_t; diff --git a/src/H5Eprivate.h b/src/H5Eprivate.h index 8f89201..f3d3b6f 100644 --- a/src/H5Eprivate.h +++ b/src/H5Eprivate.h @@ -114,12 +114,18 @@ typedef struct H5E_t H5E_t; #define HSYS_DONE_ERROR(majorcode, minorcode, retcode, str) \ { \ int myerrno = errno; \ + /* Other projects may rely on the description format to get the errno and any changes should be \ + * considered as an API change \ + */ \ HDONE_ERROR(majorcode, minorcode, retcode, "%s, errno = %d, error message = '%s'", str, myerrno, \ HDstrerror(myerrno)); \ } #define HSYS_GOTO_ERROR(majorcode, minorcode, retcode, str) \ { \ int myerrno = errno; \ + /* Other projects may rely on the description format to get the errno and any changes should be \ + * considered as an API change \ + */ \ HGOTO_ERROR(majorcode, minorcode, retcode, "%s, errno = %d, error message = '%s'", str, myerrno, \ HDstrerror(myerrno)); \ } @@ -21,20 +21,13 @@ /* Headers */ /***********/ #include "H5private.h" /* Generic Functions */ -#include "H5Aprivate.h" /* Attributes */ #include "H5ACprivate.h" /* Metadata cache */ #include "H5CXprivate.h" /* API Contexts */ -#include "H5Dprivate.h" /* Datasets */ #include "H5Eprivate.h" /* Error handling */ #include "H5Fpkg.h" /* File access */ -#include "H5FDprivate.h" /* File drivers */ #include "H5FLprivate.h" /* Free lists */ -#include "H5Gprivate.h" /* Groups */ #include "H5Iprivate.h" /* IDs */ -#include "H5MFprivate.h" /* File memory management */ -#include "H5MMprivate.h" /* Memory management */ #include "H5Pprivate.h" /* Property lists */ -#include "H5Tprivate.h" /* Datatypes */ #include "H5VLprivate.h" /* Virtual Object Layer */ #include "H5VLnative_private.h" /* Native VOL connector */ @@ -312,12 +305,12 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *oid_list) +H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *oid_list /*out*/) { ssize_t ret_value = 0; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE4("Zs", "iIuz*i", file_id, types, max_objs, oid_list); + H5TRACE4("Zs", "iIuzx", file_id, types, max_objs, oid_list); /* Check arguments */ if (0 == (types & H5F_OBJ_ALL)) @@ -391,13 +384,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_vfd_handle(hid_t file_id, hid_t fapl_id, void **file_handle) +H5Fget_vfd_handle(hid_t file_id, hid_t fapl_id, void **file_handle /*out*/) { H5VL_object_t *vol_obj; /* File info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ii**x", file_id, fapl_id, file_handle); + H5TRACE3("e", "iix", file_id, fapl_id, file_handle); /* Check args */ if (!file_handle) @@ -479,7 +472,7 @@ done: hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id) { - H5F_t * new_file = NULL; /* File struct for new file */ + void * new_file = NULL; /* File struct for new file */ H5P_genplist_t * plist; /* Property list pointer */ H5VL_connector_prop_t connector_prop; /* Property for VOL connector ID & info */ H5VL_object_t * vol_obj = NULL; /* VOL object for file */ @@ -534,8 +527,8 @@ H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id) flags |= H5F_ACC_RDWR | H5F_ACC_CREAT; /* Create a new file or truncate an existing file through the VOL */ - if (NULL == (new_file = (H5F_t *)H5VL_file_create(&connector_prop, filename, flags, fcpl_id, fapl_id, - H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) + if (NULL == (new_file = H5VL_file_create(&connector_prop, filename, flags, fcpl_id, fapl_id, + H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) HGOTO_ERROR(H5E_FILE, H5E_CANTOPENFILE, H5I_INVALID_HID, "unable to create file") /* Get an atom for the file */ @@ -579,7 +572,7 @@ done: hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id) { - H5F_t * new_file = NULL; /* File struct for new file */ + void * new_file = NULL; /* File struct for new file */ H5P_genplist_t * plist; /* Property list pointer */ H5VL_connector_prop_t connector_prop; /* Property for VOL connector ID & info */ H5VL_object_t * vol_obj = NULL; /* VOL object for file */ @@ -622,8 +615,8 @@ H5Fopen(const char *filename, unsigned flags, hid_t fapl_id) HGOTO_ERROR(H5E_FILE, H5E_CANTSET, H5I_INVALID_HID, "can't set VOL connector info in API context") /* Open the file through the VOL layer */ - if (NULL == (new_file = (H5F_t *)H5VL_file_open(&connector_prop, filename, flags, fapl_id, - H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) + if (NULL == (new_file = H5VL_file_open(&connector_prop, filename, flags, fapl_id, + H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) HGOTO_ERROR(H5E_FILE, H5E_CANTOPENFILE, H5I_INVALID_HID, "unable to open file") /* Get an ID for the file */ @@ -674,7 +667,7 @@ H5Fflush(hid_t object_id, H5F_scope_t scope) H5I_DATASET != obj_type && H5I_ATTR != obj_type) HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file or file object") - /* get the file object */ + /* Get the file object */ if (NULL == (vol_obj = H5VL_vol_object(object_id))) HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid object identifier") @@ -704,7 +697,7 @@ done: herr_t H5Fclose(hid_t file_id) { - herr_t ret_value = SUCCEED; + herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) H5TRACE1("e", "i", file_id); @@ -715,7 +708,7 @@ H5Fclose(hid_t file_id) /* Close the file */ if (H5I_dec_app_ref(file_id) < 0) - HGOTO_ERROR(H5E_FILE, H5E_CANTCLOSEFILE, FAIL, "closing file ID failed") + HGOTO_ERROR(H5E_FILE, H5E_CANTCLOSEFILE, FAIL, "decrementing file ID failed") done: FUNC_LEAVE_API(ret_value) @@ -833,7 +826,6 @@ H5Freopen(hid_t file_id) HGOTO_ERROR(H5E_FILE, H5E_CANTINIT, H5I_INVALID_HID, "unable to make file 'post open' callback") done: - /* XXX (VOL MERGE): If registration fails, file will not be closed */ FUNC_LEAVE_API(ret_value) } /* end H5Freopen() */ @@ -848,12 +840,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_intent(hid_t file_id, unsigned *intent_flags) +H5Fget_intent(hid_t file_id, unsigned *intent_flags /*out*/) { herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Iu", file_id, intent_flags); + H5TRACE2("e", "ix", file_id, intent_flags); /* If no intent flags were passed in, exit quietly */ if (intent_flags) { @@ -884,12 +876,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_fileno(hid_t file_id, unsigned long *fnumber) +H5Fget_fileno(hid_t file_id, unsigned long *fnumber /*out*/) { herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Ul", file_id, fnumber); + H5TRACE2("e", "ix", file_id, fnumber); /* If no fnumber pointer was passed in, exit quietly */ if (fnumber) { @@ -952,13 +944,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_filesize(hid_t file_id, hsize_t *size) +H5Fget_filesize(hid_t file_id, hsize_t *size /*out*/) { H5VL_object_t *vol_obj; /* File info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*h", file_id, size); + H5TRACE2("e", "ix", file_id, size); /* Check args */ if (!size) @@ -1013,13 +1005,13 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len) +H5Fget_file_image(hid_t file_id, void *buf /*out*/, size_t buf_len) { H5VL_object_t *vol_obj; /* File object for file ID */ ssize_t ret_value; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE3("Zs", "i*xz", file_id, buf_ptr, buf_len); + H5TRACE3("Zs", "ixz", file_id, buf, buf_len); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) @@ -1027,7 +1019,7 @@ H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len) /* Get the file image */ if (H5VL_file_optional(vol_obj, H5VL_NATIVE_FILE_GET_FILE_IMAGE, H5P_DATASET_XFER_DEFAULT, - H5_REQUEST_NULL, buf_ptr, &ret_value, buf_len) < 0) + H5_REQUEST_NULL, buf, &ret_value, buf_len) < 0) HGOTO_ERROR(H5E_FILE, H5E_CANTGET, (-1), "unable to get file image") done: @@ -1049,17 +1041,17 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr) +H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config /*out*/) { H5VL_object_t *vol_obj = NULL; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", file_id, config_ptr); + H5TRACE2("e", "ix", file_id, config); /* Check args */ - if ((NULL == config_ptr) || (config_ptr->version != H5AC__CURR_CACHE_CONFIG_VERSION)) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "Bad config_ptr") + if ((NULL == config) || (config->version != H5AC__CURR_CACHE_CONFIG_VERSION)) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "Bad config ptr") /* Get the file object */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object(file_id))) @@ -1067,7 +1059,7 @@ H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr) /* Get the metadata cache configuration */ if (H5VL_file_optional(vol_obj, H5VL_NATIVE_FILE_GET_MDC_CONF, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL, - config_ptr) < 0) + config) < 0) HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "unable to get metadata cache configuration") done: @@ -1092,7 +1084,7 @@ H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", file_id, config_ptr); + H5TRACE2("e", "i*Cc", file_id, config_ptr); /* Get the file object */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object(file_id))) @@ -1120,23 +1112,23 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr) +H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate /*out*/) { H5VL_object_t *vol_obj; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*d", file_id, hit_rate_ptr); + H5TRACE2("e", "ix", file_id, hit_rate); /* Check args */ - if (NULL == hit_rate_ptr) + if (NULL == hit_rate) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL hit rate pointer") if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a file ID") /* Get the current hit rate */ if (H5VL_file_optional(vol_obj, H5VL_NATIVE_FILE_GET_MDC_HR, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL, - hit_rate_ptr) < 0) + hit_rate) < 0) HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "unable to get MDC hit rate") done: @@ -1157,14 +1149,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr, size_t *cur_size_ptr, - int *cur_num_entries_ptr) +H5Fget_mdc_size(hid_t file_id, size_t *max_size /*out*/, size_t *min_clean_size /*out*/, + size_t *cur_size /*out*/, int *cur_num_entries /*out*/) { H5VL_object_t *vol_obj; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*z*z*z*Is", file_id, max_size_ptr, min_clean_size_ptr, cur_size_ptr, cur_num_entries_ptr); + H5TRACE5("e", "ixxxx", file_id, max_size, min_clean_size, cur_size, cur_num_entries); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) @@ -1172,7 +1164,7 @@ H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr, /* Get the size data */ if (H5VL_file_optional(vol_obj, H5VL_NATIVE_FILE_GET_MDC_SIZE, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL, - max_size_ptr, min_clean_size_ptr, cur_size_ptr, cur_num_entries_ptr) < 0) + max_size, min_clean_size, cur_size, cur_num_entries) < 0) HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "unable to get MDC size") done: @@ -1279,14 +1271,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_info2(hid_t obj_id, H5F_info2_t *finfo) +H5Fget_info2(hid_t obj_id, H5F_info2_t *finfo /*out*/) { H5VL_object_t *vol_obj = NULL; H5I_type_t type; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", obj_id, finfo); + H5TRACE2("e", "ix", obj_id, finfo); /* Check args */ if (!finfo) @@ -1322,13 +1314,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info) +H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info /*out*/) { H5VL_object_t *vol_obj = NULL; /* File object for file ID */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", file_id, info); + H5TRACE2("e", "ix", file_id, info); /* Check args */ if (!info) @@ -1553,13 +1545,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled, hbool_t *is_currently_logging) +H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled /*out*/, hbool_t *is_currently_logging /*out*/) { H5VL_object_t *vol_obj; /* File info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*b*b", file_id, is_enabled, is_currently_logging); + H5TRACE3("e", "ixx", file_id, is_enabled, is_currently_logging); /* Sanity check */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) @@ -1690,14 +1682,15 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], unsigned hits[2], unsigned misses[2], - unsigned evictions[2], unsigned bypasses[2]) +H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2] /*out*/, unsigned hits[2] /*out*/, + unsigned misses[2] /*out*/, unsigned evictions[2] /*out*/, + unsigned bypasses[2] /*out*/) { H5VL_object_t *vol_obj; /* File object */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "i*Iu*Iu*Iu*Iu*Iu", file_id, accesses, hits, misses, evictions, bypasses); + H5TRACE6("e", "ixxxxx", file_id, accesses, hits, misses, evictions, bypasses); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) @@ -1728,13 +1721,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_len) +H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr /*out*/, hsize_t *image_len /*out*/) { H5VL_object_t *vol_obj; /* File info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*a*h", file_id, image_addr, image_len); + H5TRACE3("e", "ixx", file_id, image_addr, image_len); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) @@ -1761,13 +1754,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_eoa(hid_t file_id, haddr_t *eoa) +H5Fget_eoa(hid_t file_id, haddr_t *eoa /*out*/) { H5VL_object_t *vol_obj; /* File info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*a", file_id, eoa); + H5TRACE2("e", "ix", file_id, eoa); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) @@ -1827,13 +1820,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize) +H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize /*out*/) { H5VL_object_t *vol_obj = NULL; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*b", file_id, minimize); + H5TRACE2("e", "ix", file_id, minimize); if (NULL == minimize) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "out pointer 'minimize' cannot be NULL") diff --git a/src/H5FAcache.c b/src/H5FAcache.c index 3772399..b9c2f93 100644 --- a/src/H5FAcache.c +++ b/src/H5FAcache.c @@ -478,9 +478,9 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ } /* end if */ else @@ -862,9 +862,9 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ } /* end if */ @@ -1205,10 +1205,10 @@ BEGIN_FUNC(STATIC, ERR, herr_t, SUCCEED, FAIL, default: #ifdef NDEBUG H5E_THROW(H5E_BADVALUE, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ CATCH diff --git a/src/H5FAtest.c b/src/H5FAtest.c index 4da7d6f..350530a 100644 --- a/src/H5FAtest.c +++ b/src/H5FAtest.c @@ -241,7 +241,7 @@ BEGIN_FUNC(STATIC, NOERR, herr_t, SUCCEED, -, /* Local variables */ #ifndef NDEBUG H5FA__test_ctx_t *ctx = (H5FA__test_ctx_t *)_ctx; /* Callback context to destroy */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ uint64_t * elmt = (uint64_t *)_elmt; /* Convenience pointer to native elements */ const uint8_t *raw = (const uint8_t *)_raw; /* Convenience pointer to raw elements */ @@ -218,7 +218,7 @@ H5FDregister(const H5FD_class_t *cls) hid_t ret_value = H5I_INVALID_HID; FUNC_ENTER_API(H5I_INVALID_HID) - H5TRACE1("i", "*x", cls); + H5TRACE1("i", "*FC", cls); /* Check arguments */ if (!cls) @@ -644,7 +644,7 @@ H5FDopen(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr) H5FD_t *ret_value = NULL; FUNC_ENTER_API(NULL) - H5TRACE4("*x", "*sIuia", name, flags, fapl_id, maxaddr); + H5TRACE4("*#", "*sIuia", name, flags, fapl_id, maxaddr); /* Check arguments */ if (H5P_DEFAULT == fapl_id) @@ -780,7 +780,7 @@ H5FDclose(H5FD_t *file) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE1("e", "*x", file); + H5TRACE1("e", "*#", file); /* Check arguments */ if (!file) @@ -858,7 +858,7 @@ H5FDcmp(const H5FD_t *f1, const H5FD_t *f2) int ret_value = -1; FUNC_ENTER_API(-1) /* return value is arbitrary */ - H5TRACE2("Is", "*x*x", f1, f2); + H5TRACE2("Is", "*#*#", f1, f2); /* Call private function */ ret_value = H5FD_cmp(f1, f2); @@ -928,7 +928,7 @@ H5FDquery(const H5FD_t *file, unsigned long *flags /*out*/) int ret_value = 0; FUNC_ENTER_API((-1)) - H5TRACE2("Is", "*xx", file, flags); + H5TRACE2("Is", "*#x", file, flags); /* Check arguments */ if (!file) @@ -1021,7 +1021,7 @@ H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size) haddr_t ret_value = HADDR_UNDEF; FUNC_ENTER_API(HADDR_UNDEF) - H5TRACE4("a", "*xMtih", file, type, dxpl_id, size); + H5TRACE4("a", "*#Mtih", file, type, dxpl_id, size); /* Check arguments */ if (!file) @@ -1071,7 +1071,7 @@ H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t siz herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "*xMtiah", file, type, dxpl_id, addr, size); + H5TRACE5("e", "*#Mtiah", file, type, dxpl_id, addr, size); /* Check arguments */ if (!file) @@ -1114,7 +1114,7 @@ H5FDget_eoa(H5FD_t *file, H5FD_mem_t type) haddr_t ret_value; FUNC_ENTER_API(HADDR_UNDEF) - H5TRACE2("a", "*xMt", file, type); + H5TRACE2("a", "*#Mt", file, type); /* Check arguments */ if (!file) @@ -1162,7 +1162,7 @@ H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t addr) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "*xMta", file, type, addr); + H5TRACE3("e", "*#Mta", file, type, addr); /* Check arguments */ if (!file) @@ -1210,7 +1210,7 @@ H5FDget_eof(H5FD_t *file, H5FD_mem_t type) haddr_t ret_value; FUNC_ENTER_API(HADDR_UNDEF) - H5TRACE2("a", "*xMt", file, type); + H5TRACE2("a", "*#Mt", file, type); /* Check arguments */ if (!file) @@ -1361,7 +1361,7 @@ H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "*xMtiazx", file, type, dxpl_id, addr, size, buf); + H5TRACE6("e", "*#Mtiazx", file, type, dxpl_id, addr, size, buf); /* Check arguments */ if (!file) @@ -1407,7 +1407,7 @@ H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t siz herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "*xMtiaz*x", file, type, dxpl_id, addr, size, buf); + H5TRACE6("e", "*#Mtiaz*x", file, type, dxpl_id, addr, size, buf); /* Check arguments */ if (!file) @@ -1451,7 +1451,7 @@ H5FDflush(H5FD_t *file, hid_t dxpl_id, hbool_t closing) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "*xib", file, dxpl_id, closing); + H5TRACE3("e", "*#ib", file, dxpl_id, closing); /* Check arguments */ if (!file) @@ -1518,7 +1518,7 @@ H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "*xib", file, dxpl_id, closing); + H5TRACE3("e", "*#ib", file, dxpl_id, closing); /* Check arguments */ if (!file) @@ -1584,7 +1584,7 @@ H5FDlock(H5FD_t *file, hbool_t rw) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "*xb", file, rw); + H5TRACE2("e", "*#b", file, rw); /* Check arguments */ if (!file) @@ -1643,7 +1643,7 @@ H5FDunlock(H5FD_t *file) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE1("e", "*x", file); + H5TRACE1("e", "*#", file); /* Check arguments */ if (!file) @@ -1724,12 +1724,12 @@ H5FD_get_fileno(const H5FD_t *file, unsigned long *filenum) *-------------------------------------------------------------------------- */ herr_t -H5FDget_vfd_handle(H5FD_t *file, hid_t fapl_id, void **file_handle) +H5FDget_vfd_handle(H5FD_t *file, hid_t fapl_id, void **file_handle /*out*/) { herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE3("e", "*xi**x", file, fapl_id, file_handle); + H5TRACE3("e", "*#ix", file, fapl_id, file_handle); /* Check arguments */ if (!file) diff --git a/src/H5FDcore.c b/src/H5FDcore.c index 419a0d9..a9e49d3 100644 --- a/src/H5FDcore.c +++ b/src/H5FDcore.c @@ -88,7 +88,7 @@ typedef struct H5FD_core_t { DWORD dwVolumeSerialNumber; HANDLE hFile; /* Native windows file handle */ -#endif /* H5_HAVE_WIN32_API */ +#endif /* H5_HAVE_WIN32_API */ hbool_t dirty; /* changes not saved? */ H5FD_file_image_callbacks_t fi_callbacks; /* file image callbacks */ H5SL_t * dirty_list; /* dirty parts of the file */ @@ -281,13 +281,13 @@ H5FD__core_add_dirty_region(H5FD_core_t *file, haddr_t start, haddr_t end) else { /* Store the new item endpoint if it's bigger */ item->end = (item->end < end) ? end : item->end; - } /* end else */ - } /* end if */ + } + } else { /* Update the size of the before region */ if (b_item->end < end) b_item->end = end; - } /* end else */ + } done: FUNC_LEAVE_NOAPI(ret_value) @@ -557,14 +557,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_core_write_tracking(hid_t plist_id, hbool_t *is_enabled, size_t *page_size) +H5Pget_core_write_tracking(hid_t plist_id, hbool_t *is_enabled /*out*/, size_t *page_size /*out*/) { H5P_genplist_t * plist; /* Property list pointer */ const H5FD_core_fapl_t *fa; /* Core VFD info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*b*z", plist_id, is_enabled, page_size); + H5TRACE3("e", "ixx", plist_id, is_enabled, page_size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -831,11 +831,11 @@ H5FD__core_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr file->nFileIndexHigh = fileinfo.nFileIndexHigh; file->nFileIndexLow = fileinfo.nFileIndexLow; file->dwVolumeSerialNumber = fileinfo.dwVolumeSerialNumber; -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ file->device = sb.st_dev; file->inode = sb.st_ino; #endif /* H5_HAVE_WIN32_API */ - } /* end if */ + } /* end if */ /* If an existing file is opened, load the whole file into memory. */ if (!(H5F_ACC_CREAT & flags)) { @@ -1071,7 +1071,7 @@ H5FD__core_cmp(const H5FD_t *_f1, const H5FD_t *_f2) HGOTO_DONE(-1) if (f1->device > f2->device) HGOTO_DONE(1) -#else /* H5_DEV_T_IS_SCALAR */ +#else /* H5_DEV_T_IS_SCALAR */ /* If dev_t isn't a scalar value on this system, just use memcmp to * determine if the values are the same or not. The actual return value * shouldn't really matter... @@ -1088,7 +1088,7 @@ H5FD__core_cmp(const H5FD_t *_f1, const H5FD_t *_f2) HGOTO_DONE(1) #endif /*H5_HAVE_WIN32_API*/ - } /* end if */ + } /* end if */ else { if (NULL == f1->name && NULL == f2->name) { if (f1 < f2) @@ -1335,7 +1335,7 @@ H5FD__core_read(H5FD_t *_file, H5FD_mem_t H5_ATTR_UNUSED type, hid_t H5_ATTR_UNU temp_nbytes = file->eof - addr; H5_CHECK_OVERFLOW(temp_nbytes, hsize_t, size_t); nbytes = MIN(size, (size_t)temp_nbytes); -#else /* NDEBUG */ +#else /* NDEBUG */ nbytes = MIN(size, (size_t)(file->eof - addr)); #endif /* NDEBUG */ @@ -1607,7 +1607,7 @@ H5FD__core_truncate(H5FD_t *_file, hid_t H5_ATTR_UNUSED dxpl_id, hbool_t closing bError = SetEndOfFile(file->hFile); if (0 == bError) HGOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ if (-1 == HDftruncate(file->fd, (HDoff_t)new_eof)) HSYS_GOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") #endif /* H5_HAVE_WIN32_API */ diff --git a/src/H5FDdirect.c b/src/H5FDdirect.c index ac7720f..eb2590f 100644 --- a/src/H5FDdirect.c +++ b/src/H5FDdirect.c @@ -383,15 +383,14 @@ done: static void * H5FD__direct_fapl_get(H5FD_t *_file) { - H5FD_direct_t *file = (H5FD_direct_t *)_file; - void * ret_value; /* Return value */ + H5FD_direct_t *file = (H5FD_direct_t *)_file; + void * ret_value = NULL; /* Return value */ - FUNC_ENTER_STATIC + FUNC_ENTER_STATIC_NOERR /* Set return value */ ret_value = H5FD__direct_fapl_copy(&(file->fa)); -done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5FD__direct_fapl_get() */ @@ -444,10 +443,10 @@ H5FD__direct_fapl_copy(const void *_old_fa) static H5FD_t * H5FD__direct_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr) { - int o_flags; - int fd = (-1); - H5FD_direct_t * file = NULL; - H5FD_direct_fapl_t *fa; + int o_flags; + int fd = (-1); + H5FD_direct_t * file = NULL; + const H5FD_direct_fapl_t *fa; #ifdef H5_HAVE_WIN32_API HFILE filehandle; struct _BY_HANDLE_FILE_INFORMATION fileinfo; @@ -496,7 +495,7 @@ H5FD__direct_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxad /* Get the driver specific information */ if (NULL == (plist = H5P_object_verify(fapl_id, H5P_FILE_ACCESS))) HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, NULL, "not a file access property list") - if (NULL == (fa = (H5FD_direct_fapl_t *)H5P_peek_driver_info(plist))) + if (NULL == (fa = (const H5FD_direct_fapl_t *)H5P_peek_driver_info(plist))) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, NULL, "bad VFL driver info") file->fd = fd; @@ -546,7 +545,8 @@ H5FD__direct_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxad } else { file->fa.must_align = FALSE; - HDftruncate(file->fd, (HDoff_t)0); + if (-1 == HDftruncate(file->fd, (HDoff_t)0)) + HSYS_GOTO_ERROR(H5E_IO, H5E_SEEKERROR, NULL, "unable to truncate file") } } else { @@ -660,7 +660,7 @@ H5FD__direct_cmp(const H5FD_t *_f1, const H5FD_t *_f2) HGOTO_DONE(-1) if (f1->device > f2->device) HGOTO_DONE(1) -#else /* H5_DEV_T_IS_SCALAR */ +#else /* H5_DEV_T_IS_SCALAR */ /* If dev_t isn't a scalar value on this system, just use memcmp to * determine if the values are the same or not. The actual return value * shouldn't really matter... @@ -793,7 +793,7 @@ H5FD__direct_get_eof(const H5FD_t *_file, H5FD_mem_t H5_ATTR_UNUSED type) { const H5FD_direct_t *file = (const H5FD_direct_t *)_file; - FUNC_ENTER_STATIC + FUNC_ENTER_STATIC_NOERR FUNC_LEAVE_NOAPI(file->eof) } @@ -1276,7 +1276,7 @@ H5FD__direct_truncate(H5FD_t *_file, hid_t H5_ATTR_UNUSED dxpl_id, hbool_t H5_AT (void)SetFilePointer((HANDLE)filehandle, li.LowPart, &li.HighPart, FILE_BEGIN); if (SetEndOfFile((HANDLE)filehandle) == 0) HGOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ if (-1 == HDftruncate(file->fd, (HDoff_t)file->eoa)) HSYS_GOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") #endif /* H5_HAVE_WIN32_API */ diff --git a/src/H5FDdirect.h b/src/H5FDdirect.h index 2d88a69..ea2b3f2 100644 --- a/src/H5FDdirect.h +++ b/src/H5FDdirect.h @@ -23,7 +23,7 @@ #ifdef H5_HAVE_DIRECT #define H5FD_DIRECT (H5FD_direct_init()) #else -#define H5FD_DIRECT (-1) +#define H5FD_DIRECT (H5I_INVALID_HID) #endif /* H5_HAVE_DIRECT */ #ifdef H5_HAVE_DIRECT diff --git a/src/H5FDhdfs.c b/src/H5FDhdfs.c index 569b889..43ad9a1 100644 --- a/src/H5FDhdfs.c +++ b/src/H5FDhdfs.c @@ -20,6 +20,9 @@ * File System (HDFS). */ +/* This source code file is part of the H5FD driver module */ +#include "H5FDdrvr_module.h" + #include "H5private.h" /* Generic Functions */ #include "H5Eprivate.h" /* Error handling */ #include "H5FDprivate.h" /* File drivers */ @@ -30,9 +33,6 @@ #ifdef H5_HAVE_LIBHDFS -/* This source code file is part of the H5FD driver module */ -#include "H5FDdrvr_module.h" - /* HDFS routines */ #include "hdfs.h" @@ -231,8 +231,7 @@ typedef struct { * * Programmer: Jacob Smith * - *************************************************************************** - */ + ***************************************************************************/ typedef struct H5FD_hdfs_t { H5FD_t pub; H5FD_hdfs_fapl_t fa; @@ -357,12 +356,12 @@ done: hid_t H5FD_hdfs_init(void) { - hid_t ret_value = H5I_INVALID_HID; /* Return value */ + hid_t ret_value = H5I_INVALID_HID; #if HDFS_STATS unsigned int bin_i; #endif - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI(H5I_INVALID_HID) #if HDFS_DEBUG HDfprintf(stdout, "called %s.\n", FUNC); @@ -379,7 +378,7 @@ H5FD_hdfs_init(void) HDFS_STATS_POW(bin_i, &value) hdfs_stats_boundaries[bin_i] = value; - } /* end for */ + } #endif ret_value = H5FD_HDFS_g; @@ -593,7 +592,7 @@ done: * Function: H5Pset_fapl_hdfs * * Purpose: Modify the file access property list to use the H5FD_HDFS - * driver defined in this source file. All driver specfic + * driver defined in this source file. All driver specific * properties are passed in as a pointer to a suitably * initialized instance of H5FD_hdfs_fapl_t * @@ -611,7 +610,7 @@ H5Pset_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa) herr_t ret_value = FAIL; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, fa); + H5TRACE2("e", "i*#", fapl_id, fa); HDassert(fa != NULL); @@ -647,33 +646,34 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out) +H5Pget_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa_dst /*out*/) { - const H5FD_hdfs_fapl_t *fa = NULL; + const H5FD_hdfs_fapl_t *fa_src = NULL; H5P_genplist_t * plist = NULL; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, fa_out); + H5TRACE2("e", "ix", fapl_id, fa_dst); #if HDFS_DEBUG HDfprintf(stdout, "called %s.\n", FUNC); #endif - if (fa_out == NULL) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "fa_out is NULL") + if (fa_dst == NULL) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "fa_dst ptr is NULL") plist = H5P_object_verify(fapl_id, H5P_FILE_ACCESS); if (plist == NULL) HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file access list") + if (H5FD_HDFS != H5P_peek_driver(plist)) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "incorrect VFL driver") - fa = (const H5FD_hdfs_fapl_t *)H5P_peek_driver_info(plist); - if (fa == NULL) + fa_src = (const H5FD_hdfs_fapl_t *)H5P_peek_driver_info(plist); + if (fa_src == NULL) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "bad VFL driver info") /* Copy the hdfs fapl data out */ - HDmemcpy(fa_out, fa, sizeof(H5FD_hdfs_fapl_t)); + H5MM_memcpy(fs_dst, fa_src, sizeof(H5FD_hdfs_fapl_t)); done: FUNC_LEAVE_API(ret_value) @@ -708,7 +708,7 @@ H5FD__hdfs_fapl_get(H5FD_t *_file) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, NULL, "memory allocation failed") /* Copy the fields of the structure */ - HDmemcpy(fa, &(file->fa), sizeof(H5FD_hdfs_fapl_t)); + H5MM_memcpy(fa, &(file->fa), sizeof(H5FD_hdfs_fapl_t)); ret_value = fa; @@ -746,7 +746,7 @@ H5FD__hdfs_fapl_copy(const void *_old_fa) if (new_fa == NULL) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, NULL, "memory allocation failed") - HDmemcpy(new_fa, old_fa, sizeof(H5FD_hdfs_fapl_t)); + H5MM_memcpy(new_fa, old_fa, sizeof(H5FD_hdfs_fapl_t)); ret_value = new_fa; done: @@ -813,7 +813,7 @@ hdfs__reset_stats(H5FD_hdfs_t *file) FUNC_ENTER_STATIC #if HDFS_DEBUG - HDprintf("hdfs__reset_stats() called\n"); + HDfprintf(stdout, "called %s.\n", FUNC); #endif if (file == NULL) @@ -903,7 +903,7 @@ H5FD__hdfs_open(const char *path, unsigned flags, hid_t fapl_id, haddr_t maxaddr if (file == NULL) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, NULL, "unable to allocate file struct") file->hdfs_handle = handle; - HDmemcpy(&(file->fa), &fa, sizeof(H5FD_hdfs_fapl_t)); + H5MM_memcpy(&(file->fa), &fa, sizeof(H5FD_hdfs_fapl_t)); #if HDFS_STATS if (FAIL == hdfs__reset_stats(file)) @@ -1203,8 +1203,8 @@ done: static herr_t H5FD__hdfs_close(H5FD_t *_file) { - herr_t ret_value = SUCCEED; H5FD_hdfs_t *file = (H5FD_hdfs_t *)_file; + herr_t ret_value = SUCCEED; FUNC_ENTER_STATIC @@ -1245,8 +1245,8 @@ done: * field-by-field. * * Return: - * + Equivalent: 0 - * + Not Equivalent: -1 + * Equivalent: 0 + * Not Equivalent: -1 * * Programmer: Gerd Herber * May 2018 @@ -1470,8 +1470,8 @@ H5FD__hdfs_get_eof(const H5FD_t *_file, H5FD_mem_t H5_ATTR_UNUSED type) static herr_t H5FD__hdfs_get_handle(H5FD_t *_file, hid_t H5_ATTR_UNUSED fapl, void **file_handle) { - herr_t ret_value = SUCCEED; H5FD_hdfs_t *file = (H5FD_hdfs_t *)_file; + herr_t ret_value = SUCCEED; FUNC_ENTER_STATIC @@ -1514,9 +1514,9 @@ static herr_t H5FD__hdfs_read(H5FD_t *_file, H5FD_mem_t H5_ATTR_UNUSED type, hid_t H5_ATTR_UNUSED dxpl_id, haddr_t addr, size_t size, void *buf) { - herr_t ret_value = SUCCEED; H5FD_hdfs_t *file = (H5FD_hdfs_t *)_file; size_t filesize = 0; + herr_t ret_value = SUCCEED; #if HDFS_STATS /* working variables for storing stats */ hdfs_statsbin *bin = NULL; @@ -1655,7 +1655,7 @@ done: * No effect on Read-Only S3 file. * * Suggestion: remove lock/unlock from class - * > would result in error at H5FD_[un]lock() (H5FD.c) + * would result in error at H5FD_[un]lock() (H5FD.c) * * Return: * diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h index 05506d4..abe7682 100644 --- a/src/H5FDhdfs.h +++ b/src/H5FDhdfs.h @@ -16,7 +16,7 @@ * Programmer: Jacob Smith * 2018-04-23 * - * Purpose: The public header file for the hdfs driver. + * Purpose: The public header file for the hdfs driver. */ #ifndef H5FDhdfs_H @@ -25,7 +25,7 @@ #ifdef H5_HAVE_LIBHDFS #define H5FD_HDFS (H5FD_hdfs_init()) #else /* H5_HAVE_LIBHDFS */ -#define H5FD_HDFS (-1) +#define H5FD_HDFS (H5I_INVALID_HID) #endif /* H5_HAVE_LIBHDFS */ #ifdef H5_HAVE_LIBHDFS diff --git a/src/H5FDlog.c b/src/H5FDlog.c index fc2cb12..99b0b8d 100644 --- a/src/H5FDlog.c +++ b/src/H5FDlog.c @@ -570,7 +570,7 @@ H5FD__log_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr) file->nFileIndexHigh = fileinfo.nFileIndexHigh; file->nFileIndexLow = fileinfo.nFileIndexLow; file->dwVolumeSerialNumber = fileinfo.dwVolumeSerialNumber; -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ file->device = sb.st_dev; file->inode = sb.st_ino; #endif /* H5_HAVE_WIN32_API */ @@ -861,7 +861,7 @@ H5FD__log_cmp(const H5FD_t *_f1, const H5FD_t *_f2) HGOTO_DONE(-1) if (f1->device > f2->device) HGOTO_DONE(1) -#else /* H5_DEV_T_IS_SCALAR */ +#else /* H5_DEV_T_IS_SCALAR */ /* If dev_t isn't a scalar value on this system, just use memcmp to * determine if the values are the same or not. The actual return value * shouldn't really matter... @@ -1182,7 +1182,7 @@ H5FD__log_read(H5FD_t *_file, H5FD_mem_t type, hid_t H5_ATTR_UNUSED dxpl_id, had #ifndef H5_HAVE_PREADWRITE H5_timer_t seek_timer; /* Timer for seek operation */ H5_timevals_t seek_times; /* Elapsed time for seek operation */ -#endif /* H5_HAVE_PREADWRITE */ +#endif /* H5_HAVE_PREADWRITE */ HDoff_t offset = (HDoff_t)addr; herr_t ret_value = SUCCEED; /* Return value */ @@ -1250,7 +1250,7 @@ H5FD__log_read(H5FD_t *_file, H5FD_mem_t type, hid_t H5_ATTR_UNUSED dxpl_id, had HDfprintf(file->logfp, "\n"); } /* end if */ } /* end if */ -#endif /* H5_HAVE_PREADWRITE */ +#endif /* H5_HAVE_PREADWRITE */ /* Start timer for read operation */ if (file->fa.flags & H5FD_LOG_TIME_READ) { @@ -1280,7 +1280,7 @@ H5FD__log_read(H5FD_t *_file, H5FD_mem_t type, hid_t H5_ATTR_UNUSED dxpl_id, had if (bytes_read > 0) offset += bytes_read; #else - bytes_read = HDread(file->fd, buf, bytes_in); + bytes_read = HDread(file->fd, buf, bytes_in); #endif /* H5_HAVE_PREADWRITE */ } while (-1 == bytes_read && EINTR == errno); @@ -1396,7 +1396,7 @@ H5FD__log_write(H5FD_t *_file, H5FD_mem_t type, hid_t H5_ATTR_UNUSED dxpl_id, ha #ifndef H5_HAVE_PREADWRITE H5_timer_t seek_timer; /* Timer for seek operation */ H5_timevals_t seek_times; /* Elapsed time for seek operation */ -#endif /* H5_HAVE_PREADWRITE */ +#endif /* H5_HAVE_PREADWRITE */ HDoff_t offset = (HDoff_t)addr; herr_t ret_value = SUCCEED; /* Return value */ @@ -1472,7 +1472,7 @@ H5FD__log_write(H5FD_t *_file, H5FD_mem_t type, hid_t H5_ATTR_UNUSED dxpl_id, ha HDfprintf(file->logfp, "\n"); } /* end if */ } /* end if */ -#endif /* H5_HAVE_PREADWRITE */ +#endif /* H5_HAVE_PREADWRITE */ /* Start timer for write operation */ if (file->fa.flags & H5FD_LOG_TIME_WRITE) { @@ -1648,7 +1648,7 @@ H5FD__log_truncate(H5FD_t *_file, hid_t H5_ATTR_UNUSED dxpl_id, hbool_t H5_ATTR_ if (0 == SetEndOfFile(file->hFile)) HGOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") } -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ /* Truncate/extend the file */ if (-1 == HDftruncate(file->fd, (HDoff_t)file->eoa)) HSYS_GOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") diff --git a/src/H5FDmirror.c b/src/H5FDmirror.c index 3895b42..9448adb 100644 --- a/src/H5FDmirror.c +++ b/src/H5FDmirror.c @@ -126,7 +126,7 @@ typedef struct H5FD_mirror_t { } while (0) #else #define LOG_XMIT_BYTES(label, buf, len) /* no-op */ -#endif /* MIRROR_DEBUG_XMIT_BYTE */ +#endif /* MIRROR_DEBUG_XMIT_BYTE */ #if MIRROR_DEBUG_OP_CALLS #define LOG_OP_CALL(name) \ @@ -136,7 +136,7 @@ typedef struct H5FD_mirror_t { } while (0) #else #define LOG_OP_CALL(name) /* no-op */ -#endif /* MIRROR_DEBUG_OP_CALLS */ +#endif /* MIRROR_DEBUG_OP_CALLS */ /* Prototypes */ static herr_t H5FD__mirror_term(void); @@ -242,7 +242,7 @@ H5FD_mirror_init(void) { hid_t ret_value = H5I_INVALID_HID; - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI(H5I_INVALID_HID) LOG_OP_CALL(FUNC); @@ -298,7 +298,7 @@ H5FD__mirror_xmit_decode_uint16(uint16_t *out, const unsigned char *_buf) HDassert(_buf && out); - HDmemcpy(&n, _buf, sizeof(n)); + H5MM_memcpy(&n, _buf, sizeof(n)); *out = (uint16_t)HDntohs(n); return 2; /* number of bytes eaten */ @@ -326,7 +326,7 @@ H5FD__mirror_xmit_decode_uint32(uint32_t *out, const unsigned char *_buf) HDassert(_buf && out); - HDmemcpy(&n, _buf, sizeof(n)); + H5MM_memcpy(&n, _buf, sizeof(n)); *out = (uint32_t)HDntohl(n); return 4; /* number of bytes eaten */ @@ -385,7 +385,7 @@ H5FD__mirror_xmit_decode_uint64(uint64_t *out, const unsigned char *_buf) HDassert(_buf && out); - HDmemcpy(&n, _buf, sizeof(n)); + H5MM_memcpy(&n, _buf, sizeof(n)); if (TRUE == is_host_little_endian()) *out = BSWAP_64(n); else @@ -412,7 +412,7 @@ H5FD__mirror_xmit_decode_uint8(uint8_t *out, const unsigned char *_buf) HDassert(_buf && out); - HDmemcpy(out, _buf, sizeof(uint8_t)); + H5MM_memcpy(out, _buf, sizeof(uint8_t)); return 1; /* number of bytes eaten */ } /* end H5FD__mirror_xmit_decode_uint8() */ @@ -439,7 +439,7 @@ H5FD__mirror_xmit_encode_uint16(unsigned char *_dest, uint16_t v) HDassert(_dest); n = (uint16_t)HDhtons(v); - HDmemcpy(_dest, &n, sizeof(n)); + H5MM_memcpy(_dest, &n, sizeof(n)); return 2; } /* end H5FD__mirror_xmit_encode_uint16() */ @@ -466,7 +466,7 @@ H5FD__mirror_xmit_encode_uint32(unsigned char *_dest, uint32_t v) HDassert(_dest); n = (uint32_t)HDhtonl(v); - HDmemcpy(_dest, &n, sizeof(n)); + H5MM_memcpy(_dest, &n, sizeof(n)); return 4; } /* end H5FD__mirror_xmit_encode_uint32() */ @@ -494,7 +494,7 @@ H5FD__mirror_xmit_encode_uint64(unsigned char *_dest, uint64_t v) if (TRUE == is_host_little_endian()) n = BSWAP_64(v); - HDmemcpy(_dest, &n, sizeof(n)); + H5MM_memcpy(_dest, &n, sizeof(n)); return 8; } /* H5FD__mirror_xmit_encode_uint64() */ @@ -519,7 +519,7 @@ H5FD__mirror_xmit_encode_uint8(unsigned char *dest, uint8_t v) HDassert(dest); - HDmemcpy(dest, &v, sizeof(v)); + H5MM_memcpy(dest, &v, sizeof(v)); return 1; } /* end H5FD__mirror_xmit_encode_uint8() */ @@ -1188,7 +1188,7 @@ H5FD__mirror_fapl_get(H5FD_t *_file) if (NULL == fa) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, NULL, "calloc failed"); - HDmemcpy(fa, &(file->fa), sizeof(H5FD_mirror_fapl_t)); + H5MM_memcpy(fa, &(file->fa), sizeof(H5FD_mirror_fapl_t)); ret_value = fa; @@ -1224,7 +1224,7 @@ H5FD__mirror_fapl_copy(const void *_old_fa) if (new_fa == NULL) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, NULL, "memory allocation failed"); - HDmemcpy(new_fa, old_fa, sizeof(H5FD_mirror_fapl_t)); + H5MM_memcpy(new_fa, old_fa, sizeof(H5FD_mirror_fapl_t)); ret_value = new_fa; done: @@ -1266,25 +1266,25 @@ H5FD__mirror_fapl_free(void *_fa) * Function: H5Pget_fapl_mirror * * Purpose: Get the configuration information for this fapl. - * Data is memcopied into the fa_out pointer. + * Data is memcopied into the fa_dst pointer. * * Return: SUCCEED/FAIL * ------------------------------------------------------------------------- */ herr_t -H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out) +H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_dst /*out*/) { - const H5FD_mirror_fapl_t *fa = NULL; + const H5FD_mirror_fapl_t *fa_src = NULL; H5P_genplist_t * plist = NULL; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, fa_out); + H5TRACE2("e", "ix", fapl_id, fa_dst); LOG_OP_CALL(FUNC); - if (NULL == fa_out) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "fa_out is NULL"); + if (NULL == fa_dst) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "fa_dst is NULL"); plist = H5P_object_verify(fapl_id, H5P_FILE_ACCESS); if (NULL == plist) @@ -1292,13 +1292,13 @@ H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out) if (H5P_peek_driver(plist) != H5FD_MIRROR) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "incorrect VFL driver"); - fa = (const H5FD_mirror_fapl_t *)H5P_peek_driver_info(plist); - if (NULL == fa) + fa_src = (const H5FD_mirror_fapl_t *)H5P_peek_driver_info(plist); + if (NULL == fa_src) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "bad VFL driver info"); - HDassert(fa->magic == H5FD_MIRROR_FAPL_MAGIC); /* sanity check */ + HDassert(fa_src->magic == H5FD_MIRROR_FAPL_MAGIC); /* sanity check */ - HDmemcpy(fa_out, fa, sizeof(H5FD_mirror_fapl_t)); + H5MM_memcpy(fa_dst, fa_src, sizeof(H5FD_mirror_fapl_t)); done: FUNC_LEAVE_API(ret_value); @@ -1320,7 +1320,7 @@ H5Pset_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa) herr_t ret_value = FAIL; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, fa); + H5TRACE2("e", "i*#", fapl_id, fa); LOG_OP_CALL(FUNC); diff --git a/src/H5FDmpio.c b/src/H5FDmpio.c index 6042776..a4e0baf 100644 --- a/src/H5FDmpio.c +++ b/src/H5FDmpio.c @@ -200,7 +200,7 @@ H5FD_mpio_init(void) { #ifdef H5FDmpio_DEBUG static int H5FD_mpio_Debug_inited = 0; -#endif /* H5FDmpio_DEBUG */ +#endif /* H5FDmpio_DEBUG */ const char *s; /* String for environment variables */ hid_t ret_value = H5I_INVALID_HID; /* Return value */ @@ -229,7 +229,7 @@ H5FD_mpio_init(void) } /* end while */ } /* end if */ H5FD_mpio_Debug_inited++; - } /* end if */ + } /* end if */ #endif /* H5FDmpio_DEBUG */ /* Set return value */ @@ -1746,33 +1746,4 @@ H5FD__mpio_communicator(const H5FD_t *_file) FUNC_LEAVE_NOAPI(file->comm) } /* end H5FD__mpio_communicator() */ -/*------------------------------------------------------------------------- - * Function: H5FD__mpio_get_info - * - * Purpose: Returns the file info of MPIO file driver. - * - * Returns: Non-negative if succeed or negative if fails. - * - * Programmer: John Mainzer - * April 4, 2017 - * - *------------------------------------------------------------------------- - */ -static herr_t -H5FD__mpio_get_info(H5FD_t *_file, void **mpi_info) -{ - H5FD_mpio_t *file = (H5FD_mpio_t *)_file; - herr_t ret_value = SUCCEED; - - FUNC_ENTER_STATIC - - if (!mpi_info) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "mpi info not valid") - - *mpi_info = &(file->info); - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* H5FD__mpio_get_info() */ - #endif /* H5_HAVE_PARALLEL */ diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h index c9280c7..0773d9e 100644 --- a/src/H5FDmpio.h +++ b/src/H5FDmpio.h @@ -25,7 +25,7 @@ #ifdef H5_HAVE_PARALLEL #define H5FD_MPIO (H5FD_mpio_init()) #else -#define H5FD_MPIO (-1) +#define H5FD_MPIO (H5I_INVALID_HID) #endif /* H5_HAVE_PARALLEL */ #ifdef H5_HAVE_PARALLEL diff --git a/src/H5FDros3.c b/src/H5FDros3.c index fa41b6f..83e4315 100644 --- a/src/H5FDros3.c +++ b/src/H5FDros3.c @@ -320,7 +320,7 @@ H5FD_ros3_init(void) unsigned int bin_i; #endif - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI(H5I_INVALID_HID) #if ROS3_DEBUG HDfprintf(stdout, "H5FD_ros3_init() called.\n"); @@ -340,7 +340,6 @@ H5FD_ros3_init(void) } #endif - /* Set return value */ ret_value = H5FD_ROS3_g; done: @@ -395,7 +394,7 @@ H5Pset_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa) herr_t ret_value = FAIL; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, fa); + H5TRACE2("e", "i*#", fapl_id, fa); HDassert(fa != NULL); @@ -473,21 +472,21 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out) +H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_dst /*out*/) { - const H5FD_ros3_fapl_t *fa = NULL; + const H5FD_ros3_fapl_t *fa_src = NULL; H5P_genplist_t * plist = NULL; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, fa_out); + H5TRACE2("e", "ix", fapl_id, fa_dst); #if ROS3_DEBUG HDfprintf(stdout, "H5Pget_fapl_ros3() called.\n"); #endif - if (fa_out == NULL) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "fa_out is NULL") + if (fa_dst == NULL) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "fa_dst is NULL") plist = H5P_object_verify(fapl_id, H5P_FILE_ACCESS); if (plist == NULL) @@ -496,12 +495,12 @@ H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out) if (H5FD_ROS3 != H5P_peek_driver(plist)) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "incorrect VFL driver") - fa = (const H5FD_ros3_fapl_t *)H5P_peek_driver_info(plist); - if (fa == NULL) + fa_src = (const H5FD_ros3_fapl_t *)H5P_peek_driver_info(plist); + if (fa_src == NULL) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "bad VFL driver info") /* Copy the ros3 fapl data out */ - HDmemcpy(fa_out, fa, sizeof(H5FD_ros3_fapl_t)); + H5MM_memcpy(fa_dst, fa_src, sizeof(H5FD_ros3_fapl_t)); done: FUNC_LEAVE_API(ret_value) @@ -536,7 +535,7 @@ H5FD__ros3_fapl_get(H5FD_t *_file) HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, NULL, "memory allocation failed") /* Copy the fields of the structure */ - HDmemcpy(fa, &(file->fa), sizeof(H5FD_ros3_fapl_t)); + H5MM_memcpy(fa, &(file->fa), sizeof(H5FD_ros3_fapl_t)); /* Set return value */ ret_value = fa; @@ -576,7 +575,7 @@ H5FD__ros3_fapl_copy(const void *_old_fa) if (new_fa == NULL) HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, NULL, "memory allocation failed"); - HDmemcpy(new_fa, old_fa, sizeof(H5FD_ros3_fapl_t)); + H5MM_memcpy(new_fa, old_fa, sizeof(H5FD_ros3_fapl_t)); ret_value = new_fa; done: @@ -769,7 +768,7 @@ H5FD__ros3_open(const char *url, unsigned flags, hid_t fapl_id, haddr_t maxaddr) HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, NULL, "unable to allocate file struct") file->s3r_handle = handle; - HDmemcpy(&(file->fa), &fa, sizeof(H5FD_ros3_fapl_t)); + H5MM_memcpy(&(file->fa), &fa, sizeof(H5FD_ros3_fapl_t)); #if ROS3_STATS if (FAIL == ros3_reset_stats(file)) diff --git a/src/H5FDs3comms.c b/src/H5FDs3comms.c index 2ac27d0..ac58f67 100644 --- a/src/H5FDs3comms.c +++ b/src/H5FDs3comms.c @@ -144,7 +144,7 @@ curlwritecallback(char *ptr, size_t size, size_t nmemb, void *userdata) return written; if (size > 0) { - HDmemcpy(&(sds->data[sds->size]), ptr, product); + H5MM_memcpy(&(sds->data[sds->size]), ptr, product); sds->size += product; written = product; } @@ -263,12 +263,12 @@ H5FD_s3comms_hrb_node_set(hrb_node_t **L, const char *name, const char *value) namecpy = (char *)H5MM_malloc(sizeof(char) * (namelen + 1)); if (namecpy == NULL) HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, FAIL, "cannot make space for name copy."); - HDmemcpy(namecpy, name, (namelen + 1)); + H5MM_memcpy(namecpy, name, (namelen + 1)); valuecpy = (char *)H5MM_malloc(sizeof(char) * (valuelen + 1)); if (valuecpy == NULL) HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, FAIL, "cannot make space for value copy."); - HDmemcpy(valuecpy, value, (valuelen + 1)); + H5MM_memcpy(valuecpy, value, (valuelen + 1)); nvcat = (char *)H5MM_malloc(sizeof(char) * catwrite); if (nvcat == NULL) @@ -701,14 +701,14 @@ H5FD_s3comms_hrb_init_request(const char *_verb, const char *_resource, const ch res = (char *)H5MM_malloc(sizeof(char) * (reslen + 1)); if (res == NULL) HGOTO_ERROR(H5E_ARGS, H5E_CANTALLOC, NULL, "no space for resource string"); - HDmemcpy(res, _resource, (reslen + 1)); + H5MM_memcpy(res, _resource, (reslen + 1)); } else { res = (char *)H5MM_malloc(sizeof(char) * (reslen + 2)); if (res == NULL) HGOTO_ERROR(H5E_ARGS, H5E_CANTALLOC, NULL, "no space for resource string"); *res = '/'; - HDmemcpy((&res[1]), _resource, (reslen + 1)); + H5MM_memcpy((&res[1]), _resource, (reslen + 1)); HDassert((reslen + 1) == HDstrlen(res)); } /* end if (else resource string not starting with '/') */ @@ -910,7 +910,7 @@ H5FD_s3comms_s3r_getsize(s3r_t *handle) handle->httpverb = (char *)H5MM_malloc(sizeof(char) * 16); if (handle->httpverb == NULL) HGOTO_ERROR(H5E_ARGS, H5E_CANTALLOC, FAIL, "unable to allocate space for S3 request HTTP verb"); - HDmemcpy(handle->httpverb, "HEAD", 5); + H5MM_memcpy(handle->httpverb, "HEAD", 5); headerresponse = (char *)H5MM_malloc(sizeof(char) * CURL_MAX_HTTP_HEADER); if (headerresponse == NULL) @@ -1078,19 +1078,19 @@ H5FD_s3comms_s3r_open(const char *url, const char *region, const char *id, const handle->region = (char *)H5MM_malloc(sizeof(char) * tmplen); if (handle->region == NULL) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, NULL, "could not malloc space for handle region copy."); - HDmemcpy(handle->region, region, tmplen); + H5MM_memcpy(handle->region, region, tmplen); tmplen = HDstrlen(id) + 1; handle->secret_id = (char *)H5MM_malloc(sizeof(char) * tmplen); if (handle->secret_id == NULL) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, NULL, "could not malloc space for handle ID copy."); - HDmemcpy(handle->secret_id, id, tmplen); + H5MM_memcpy(handle->secret_id, id, tmplen); tmplen = SHA256_DIGEST_LENGTH; handle->signing_key = (unsigned char *)H5MM_malloc(sizeof(unsigned char) * tmplen); if (handle->signing_key == NULL) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, NULL, "could not malloc space for handle key copy."); - HDmemcpy(handle->signing_key, signing_key, tmplen); + H5MM_memcpy(handle->signing_key, signing_key, tmplen); } /* if authentication information provided */ /************************ @@ -1138,7 +1138,7 @@ H5FD_s3comms_s3r_open(const char *url, const char *region, const char *id, const *********************/ HDassert(handle->httpverb != NULL); - HDmemcpy(handle->httpverb, "GET", 4); + H5MM_memcpy(handle->httpverb, "GET", 4); ret_value = handle; @@ -1951,7 +1951,7 @@ H5FD__s3comms_load_aws_creds_from_file(FILE *file, const char *profile_name, cha for (buffer_i = 0; buffer_i < 128; buffer_i++) buffer[buffer_i] = 0; - line_buffer = fgets(line_buffer, 128, file); + line_buffer = HDfgets(line_buffer, 128, file); if (line_buffer == NULL) /* reached end of file */ goto done; } while (HDstrncmp(line_buffer, profile_line, HDstrlen(profile_line))); @@ -1963,7 +1963,7 @@ H5FD__s3comms_load_aws_creds_from_file(FILE *file, const char *profile_name, cha buffer[buffer_i] = 0; /* collect a line from file */ - line_buffer = fgets(line_buffer, 128, file); + line_buffer = HDfgets(line_buffer, 128, file); if (line_buffer == NULL) goto done; /* end of file */ @@ -2062,9 +2062,9 @@ H5FD_s3comms_load_aws_profile(const char *profile_name, char *key_id_out, char * #endif #ifdef H5_HAVE_WIN32_API - ret = HDsnprintf(awspath, 117, "%s/.aws/", getenv("USERPROFILE")); + ret = HDsnprintf(awspath, 117, "%s/.aws/", HDgetenv("USERPROFILE")); #else - ret = HDsnprintf(awspath, 117, "%s/.aws/", getenv("HOME")); + ret = HDsnprintf(awspath, 117, "%s/.aws/", HDgetenv("HOME")); #endif if (ret < 0 || (size_t)ret >= 117) HGOTO_ERROR(H5E_ARGS, H5E_CANTCOPY, FAIL, "unable to format home-aws path") @@ -2150,7 +2150,7 @@ H5FD_s3comms_nlowercase(char *dest, const char *s, size_t len) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "destination cannot be null."); if (len > 0) { - HDmemcpy(dest, s, len); + H5MM_memcpy(dest, s, len); do { len--; dest[len] = (char)HDtolower((int)dest[len]); @@ -2686,14 +2686,14 @@ H5FD_s3comms_tostringtosign(char *dest, const char *req, const char *now, const if (ret <= 0 || ret >= 127) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "problem adding day and region to string") - HDmemcpy((dest + d), "AWS4-HMAC-SHA256\n", 17); + H5MM_memcpy((dest + d), "AWS4-HMAC-SHA256\n", 17); d = 17; - HDmemcpy((dest + d), now, HDstrlen(now)); + H5MM_memcpy((dest + d), now, HDstrlen(now)); d += HDstrlen(now); dest[d++] = '\n'; - HDmemcpy((dest + d), tmp, HDstrlen(tmp)); + H5MM_memcpy((dest + d), tmp, HDstrlen(tmp)); d += HDstrlen(tmp); dest[d++] = '\n'; @@ -2777,7 +2777,7 @@ H5FD_s3comms_trim(char *dest, char *s, size_t s_len, size_t *n_written) s_len++; /* write output into dest */ - HDmemcpy(dest, s, s_len); + H5MM_memcpy(dest, s, s_len); } } diff --git a/src/H5FDsec2.c b/src/H5FDsec2.c index 7789d39..02323c6 100644 --- a/src/H5FDsec2.c +++ b/src/H5FDsec2.c @@ -377,7 +377,7 @@ H5FD__sec2_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr file->nFileIndexHigh = fileinfo.nFileIndexHigh; file->nFileIndexLow = fileinfo.nFileIndexLow; file->dwVolumeSerialNumber = fileinfo.dwVolumeSerialNumber; -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ file->device = sb.st_dev; file->inode = sb.st_ino; #endif /* H5_HAVE_WIN32_API */ @@ -507,7 +507,7 @@ H5FD__sec2_cmp(const H5FD_t *_f1, const H5FD_t *_f2) HGOTO_DONE(-1) if (f1->device > f2->device) HGOTO_DONE(1) -#else /* H5_DEV_T_IS_SCALAR */ +#else /* H5_DEV_T_IS_SCALAR */ /* If dev_t isn't a scalar value on this system, just use memcmp to * determine if the values are the same or not. The actual return value * shouldn't really matter... @@ -742,7 +742,7 @@ H5FD__sec2_read(H5FD_t *_file, H5FD_mem_t H5_ATTR_UNUSED type, hid_t H5_ATTR_UNU if (bytes_read > 0) offset += bytes_read; #else - bytes_read = HDread(file->fd, buf, bytes_in); + bytes_read = HDread(file->fd, buf, bytes_in); #endif /* H5_HAVE_PREADWRITE */ } while (-1 == bytes_read && EINTR == errno); @@ -945,7 +945,7 @@ H5FD__sec2_truncate(H5FD_t *_file, hid_t H5_ATTR_UNUSED dxpl_id, hbool_t H5_ATTR bError = SetEndOfFile(file->hFile); if (0 == bError) HGOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ if (-1 == HDftruncate(file->fd, (HDoff_t)file->eoa)) HSYS_GOTO_ERROR(H5E_IO, H5E_SEEKERROR, FAIL, "unable to extend file properly") #endif /* H5_HAVE_WIN32_API */ diff --git a/src/H5FDspace.c b/src/H5FDspace.c index 38a96fb..98210a4 100644 --- a/src/H5FDspace.c +++ b/src/H5FDspace.c @@ -333,7 +333,7 @@ H5FD__free_real(H5FD_t *file, H5FD_mem_t type, haddr_t addr, hsize_t size) HDfprintf(stderr, "%s: LEAKED MEMORY!!! type = %u, addr = %a, size = %Hu\n", FUNC, (unsigned)type, addr, size); #endif /* H5FD_ALLOC_DEBUG */ - } /* end else */ + } /* end else */ done: FUNC_LEAVE_NOAPI(ret_value) diff --git a/src/H5FDsplitter.c b/src/H5FDsplitter.c index 5ba1a27..09bb4f3 100644 --- a/src/H5FDsplitter.c +++ b/src/H5FDsplitter.c @@ -94,7 +94,7 @@ typedef struct H5FD_splitter_t { } while (0) #else #define H5FD_SPLITTER_LOG_CALL(name) /* no-op */ -#endif /* H5FD_SPLITTER_DEBUG_OP_CALLS */ +#endif /* H5FD_SPLITTER_DEBUG_OP_CALLS */ /* Private functions */ @@ -210,7 +210,7 @@ H5FD_splitter_init(void) { hid_t ret_value = H5I_INVALID_HID; - FUNC_ENTER_NOAPI(FAIL) + FUNC_ENTER_NOAPI(H5I_INVALID_HID) H5FD_SPLITTER_LOG_CALL(FUNC); @@ -297,7 +297,7 @@ H5Pset_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *vfd_config) herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Dr", fapl_id, vfd_config); + H5TRACE2("e", "i*#", fapl_id, vfd_config); H5FD_SPLITTER_LOG_CALL(FUNC); @@ -369,39 +369,39 @@ done: * Function: H5Pget_fapl_splitter * * Purpose: Returns information about the splitter file access property - * list through the structure config_out. + * list through the structure config. * - * Will fail if config_out is received without pre-set valid + * Will fail if config is received without pre-set valid * magic and version information. * * Return: SUCCEED/FAIL *------------------------------------------------------------------------- */ herr_t -H5Pget_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config_out) +H5Pget_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config /*out*/) { const H5FD_splitter_fapl_t *fapl_ptr = NULL; H5P_genplist_t * plist_ptr = NULL; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Dr", fapl_id, config_out); + H5TRACE2("e", "ix", fapl_id, config); H5FD_SPLITTER_LOG_CALL(FUNC); /* Check arguments */ if (TRUE != H5P_isa_class(fapl_id, H5P_FILE_ACCESS)) HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a file access property list") - if (config_out == NULL) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "config_out pointer is null") - if (H5FD_SPLITTER_MAGIC != config_out->magic) + if (config == NULL) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "config pointer is null") + if (H5FD_SPLITTER_MAGIC != config->magic) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "info-out pointer invalid (magic number mismatch)") - if (H5FD_CURR_SPLITTER_VFD_CONFIG_VERSION != config_out->version) + if (H5FD_CURR_SPLITTER_VFD_CONFIG_VERSION != config->version) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "info-out pointer invalid (version unsafe)") /* Pre-set out FAPL IDs with intent to replace these values */ - config_out->rw_fapl_id = H5I_INVALID_HID; - config_out->wo_fapl_id = H5I_INVALID_HID; + config->rw_fapl_id = H5I_INVALID_HID; + config->wo_fapl_id = H5I_INVALID_HID; /* Check and get the splitter fapl */ if (NULL == (plist_ptr = H5P_object_verify(fapl_id, H5P_FILE_ACCESS))) @@ -411,14 +411,14 @@ H5Pget_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config_out) if (NULL == (fapl_ptr = (const H5FD_splitter_fapl_t *)H5P_peek_driver_info(plist_ptr))) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "unable to get specific-driver info") - HDstrncpy(config_out->wo_path, fapl_ptr->wo_path, H5FD_SPLITTER_PATH_MAX); - HDstrncpy(config_out->log_file_path, fapl_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX); - config_out->ignore_wo_errs = fapl_ptr->ignore_wo_errs; + HDstrncpy(config->wo_path, fapl_ptr->wo_path, H5FD_SPLITTER_PATH_MAX); + HDstrncpy(config->log_file_path, fapl_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX); + config->ignore_wo_errs = fapl_ptr->ignore_wo_errs; /* Copy R/W and W/O FAPLs */ - if (H5FD__copy_plist(fapl_ptr->rw_fapl_id, &(config_out->rw_fapl_id)) < 0) + if (H5FD__copy_plist(fapl_ptr->rw_fapl_id, &(config->rw_fapl_id)) < 0) HGOTO_ERROR(H5E_VFL, H5E_BADVALUE, FAIL, "can't copy R/W FAPL"); - if (H5FD__copy_plist(fapl_ptr->wo_fapl_id, &(config_out->wo_fapl_id)) < 0) + if (H5FD__copy_plist(fapl_ptr->wo_fapl_id, &(config->wo_fapl_id)) < 0) HGOTO_ERROR(H5E_VFL, H5E_BADVALUE, FAIL, "can't copy W/O FAPL"); done: @@ -585,7 +585,7 @@ H5FD__splitter_fapl_copy(const void *_old_fa) if (NULL == new_fa_ptr) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, NULL, "unable to allocate log file FAPL") - HDmemcpy(new_fa_ptr, old_fa_ptr, sizeof(H5FD_splitter_fapl_t)); + H5MM_memcpy(new_fa_ptr, old_fa_ptr, sizeof(H5FD_splitter_fapl_t)); HDstrncpy(new_fa_ptr->wo_path, old_fa_ptr->wo_path, H5FD_SPLITTER_PATH_MAX); HDstrncpy(new_fa_ptr->log_file_path, old_fa_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX); @@ -1300,14 +1300,14 @@ H5FD__splitter_log_error(const H5FD_splitter_t *file, const char *atfunc, const char * s; size = HDstrlen(atfunc) + HDstrlen(msg) + 3; /* ':', ' ', '\n' */ - s = (char *)HDmalloc(sizeof(char) * (size + 1)); + s = (char *)H5MM_malloc(sizeof(char) * (size + 1)); if (NULL == s) ret_value = FAIL; else if (size < (size_t)HDsnprintf(s, size + 1, "%s: %s\n", atfunc, msg)) ret_value = FAIL; else if (size != HDfwrite(s, 1, size, file->logfp)) ret_value = FAIL; - HDfree(s); + H5MM_free(s); } FUNC_LEAVE_NOAPI(ret_value) diff --git a/src/H5FDstdio.c b/src/H5FDstdio.c index 4650c39..c66765a 100644 --- a/src/H5FDstdio.c +++ b/src/H5FDstdio.c @@ -115,7 +115,7 @@ typedef struct H5FD_stdio_t { DWORD nFileIndexHigh; DWORD dwVolumeSerialNumber; - HANDLE hFile; /* Native windows file handle */ + HANDLE hFile; /* Native windows file handle */ #endif /* H5_HAVE_WIN32_API */ } H5FD_stdio_t; @@ -338,7 +338,7 @@ H5FD_stdio_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr static const char *func = "H5FD_stdio_open"; /* Function Name for error reporting */ #ifdef H5_HAVE_WIN32_API struct _BY_HANDLE_FILE_INFORMATION fileinfo; -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ struct stat sb; #endif /* H5_HAVE_WIN32_API */ @@ -431,7 +431,7 @@ H5FD_stdio_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr /* Get the file descriptor (needed for truncate and some Windows information) */ #ifdef H5_HAVE_WIN32_API file->fd = _fileno(file->fp); -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ file->fd = fileno(file->fp); #endif /* H5_HAVE_WIN32_API */ if (file->fd < 0) { @@ -458,7 +458,7 @@ H5FD_stdio_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr file->nFileIndexHigh = fileinfo.nFileIndexHigh; file->nFileIndexLow = fileinfo.nFileIndexLow; file->dwVolumeSerialNumber = fileinfo.dwVolumeSerialNumber; -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ if (fstat(file->fd, &sb) < 0) { free(file); fclose(f); @@ -549,7 +549,7 @@ H5FD_stdio_cmp(const H5FD_t *_f1, const H5FD_t *_f2) return -1; if (f1->device > f2->device) return 1; -#else /* H5_DEV_T_IS_SCALAR */ +#else /* H5_DEV_T_IS_SCALAR */ /* If dev_t isn't a scalar value on this system, just use memcmp to * determine if the values are the same or not. The actual return value * shouldn't really matter... @@ -1075,7 +1075,7 @@ H5FD_stdio_truncate(H5FD_t *_file, hid_t /*UNUSED*/ dxpl_id, hbool_t /*UNUSED*/ if (0 == bError) H5Epush_ret(func, H5E_ERR_CLS, H5E_IO, H5E_SEEKERROR, "unable to truncate/extend file properly", -1) -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ /* Reset seek offset to beginning of file, so that file isn't re-extended later */ rewind(file->fp); @@ -362,7 +362,7 @@ H5FS_delete(H5F_t *f, haddr_t fs_addr) #ifdef H5FS_DEBUG HDfprintf(stderr, "%s: Done expunging free space section info from cache\n", FUNC); -#endif /* H5FS_DEBUG */ +#endif /* H5FS_DEBUG */ } /* end if */ else { #ifdef H5FS_DEBUG @@ -513,7 +513,7 @@ H5FS_close(H5F_t *f, H5FS_t *fspace) */ #ifdef H5FS_DEBUG HDfprintf(stderr, "%s: Section info can't 'go away', header will own it\n", FUNC); -#endif /* H5FS_DEBUG */ +#endif /* H5FS_DEBUG */ } /* end if */ else { #ifdef H5FS_DEBUG diff --git a/src/H5FScache.c b/src/H5FScache.c index bf91e22..fc61edd 100644 --- a/src/H5FScache.c +++ b/src/H5FScache.c @@ -820,10 +820,10 @@ H5FS__cache_hdr_notify(H5AC_notify_action_t action, void *_thing) default: #ifdef NDEBUG HGOTO_ERROR(H5E_FSPACE, H5E_BADVALUE, FAIL, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ done: FUNC_LEAVE_NOAPI(ret_value) @@ -1004,8 +1004,7 @@ H5FS__cache_sinfo_deserialize(const void *_image, size_t H5_ATTR_NDEBUG_UNUSED l /* Check for any serialized sections */ if (fspace->serial_sect_count > 0) { hsize_t old_tot_sect_count; /* Total section count from header */ - hsize_t H5_ATTR_NDEBUG_UNUSED - old_serial_sect_count; /* Total serializable section count from header */ + hsize_t H5_ATTR_NDEBUG_UNUSED old_serial_sect_count; /* Total serializable section count from header */ hsize_t H5_ATTR_NDEBUG_UNUSED old_ghost_sect_count; /* Total ghost section count from header */ hsize_t H5_ATTR_NDEBUG_UNUSED old_tot_space; /* Total space managed from header */ unsigned sect_cnt_size; /* The size of the section size counts */ @@ -1358,9 +1357,9 @@ H5FS__cache_sinfo_notify(H5AC_notify_action_t action, void *_thing) default: #ifdef NDEBUG HGOTO_ERROR(H5E_FSPACE, H5E_BADVALUE, FAIL, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end switch */ } /* end if */ diff --git a/src/H5Fdeprec.c b/src/H5Fdeprec.c index bc0e6c5..f3cdb1f 100644 --- a/src/H5Fdeprec.c +++ b/src/H5Fdeprec.c @@ -87,7 +87,7 @@ *------------------------------------------------------------------------- */ herr_t -H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo) +H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo /*out*/) { H5VL_object_t *vol_obj = NULL; H5I_type_t type; @@ -95,7 +95,7 @@ H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", obj_id, finfo); + H5TRACE2("e", "ix", obj_id, finfo); /* Check args */ if (!finfo) diff --git a/src/H5Fint.c b/src/H5Fint.c index b3d1be5..7b89b85 100644 --- a/src/H5Fint.c +++ b/src/H5Fint.c @@ -2624,7 +2624,7 @@ H5F__build_actual_name(const H5F_t *f, const H5P_genplist_t *fapl, const char *n #ifdef H5_HAVE_SYMLINK /* This has to be declared here to avoid unfreed resources on errors */ char *realname = NULL; /* Fully resolved path name of file */ -#endif /* H5_HAVE_SYMLINK */ +#endif /* H5_HAVE_SYMLINK */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_STATIC diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index 953b4da..d57926f 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -29,4 +29,17 @@ #define H5_MY_PKG_ERR H5E_FILE #define H5_MY_PKG_INIT YES +/** + * \defgroup H5F H5F + * \brief File Interface + * \todo Describe concisely what the functions in this module are about. + * + * \defgroup MDC Metadata Cache + * \ingroup H5F + * \defgroup PH5F Parallel + * \ingroup H5F + * \defgroup SWMR Single Writer Multiple Readers + * \ingroup H5F + */ + #endif /* _H5Fmodule_H */ diff --git a/src/H5Fmpi.c b/src/H5Fmpi.c index d930c1f..4c4d649 100644 --- a/src/H5Fmpi.c +++ b/src/H5Fmpi.c @@ -336,13 +336,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag) +H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag /*out*/) { H5VL_object_t *vol_obj = NULL; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL); - H5TRACE2("e", "i*b", file_id, flag); + H5TRACE2("e", "ix", file_id, flag); /* Get the file object */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(file_id, H5I_FILE))) diff --git a/src/H5Fprivate.h b/src/H5Fprivate.h index ba6d67f..f4268e5 100644 --- a/src/H5Fprivate.h +++ b/src/H5Fprivate.h @@ -31,7 +31,7 @@ typedef struct H5F_t H5F_t; #include "H5MMprivate.h" /* Memory management */ #ifdef H5_HAVE_PARALLEL #include "H5Pprivate.h" /* Property lists */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ #include "H5VMprivate.h" /* Vectors and arrays */ #include "H5VLprivate.h" /* Virtual Object Layer */ @@ -618,7 +618,7 @@ typedef struct H5F_t H5F_t; #ifdef H5_HAVE_PARALLEL #define H5F_ACS_MPI_PARAMS_COMM_NAME "mpi_params_comm" /* the MPI communicator */ #define H5F_ACS_MPI_PARAMS_INFO_NAME "mpi_params_info" /* the MPI info struct */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ /* ======================== File Mount properties ====================*/ #define H5F_MNT_SYM_LOCAL_NAME "local" /* Whether absolute symlinks local to file. */ @@ -648,8 +648,7 @@ typedef struct H5F_t H5F_t; /* B-tree internal 'K' values */ #define HDF5_BTREE_SNODE_IK_DEF 16 -#define HDF5_BTREE_CHUNK_IK_DEF \ - 32 /* Note! this value is assumed \ +#define HDF5_BTREE_CHUNK_IK_DEF 32 /* Note! this value is assumed \ to be 32 for version 0 \ of the superblock and \ if it is changed, the code \ diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index b84cff6..7981372 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -47,24 +47,20 @@ * We're assuming that these constants are used rather early in the hdf5 * session. */ -#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /*absence of rdwr => rd-only */ -#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /*open for read and write */ -#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /*overwrite existing files */ -#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /*fail if file already exists*/ +#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< absence of rdwr => rd-only */ +#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< open for read and write */ +#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< overwrite existing files */ +#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< fail if file already exists*/ /* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */ -#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /*create non-existing files */ +#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< create non-existing files */ #define H5F_ACC_SWMR_WRITE \ - (H5CHECK 0x0020u) /*indicate that this file is \ - * open for writing in a \ - * single-writer/multi-reader (SWMR) \ - * scenario. Note that the \ - * process(es) opening the file \ - * for reading must open the file \ - * with RDONLY access, and use \ - * the special "SWMR_READ" access \ - * flag. */ + (H5CHECK 0x0020u) /**< indicate that this file is open for writing in a \ + single-writer/multi-reader (SWMR) scenario. \ + Note that the process(es) opening the file for reading must \ + open the file with RDONLY access, and use the special "SWMR_READ" \ + access flag. */ #define H5F_ACC_SWMR_READ \ - (H5CHECK 0x0040u) /*indicate that this file is \ + (H5CHECK 0x0040u) /**< indicate that this file is \ * open for reading in a \ * single-writer/multi-reader (SWMR) \ * scenario. Note that the \ @@ -73,19 +69,23 @@ * open the file with the RDONLY \ * flag. */ -/* Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the - * parent file. */ -#define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu) /*ignore setting on lapl */ +/** + * Default property list identifier + * + * \internal Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the parent file. + * \internal ignore setting on lapl + */ +#define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu) /* Flags for H5Fget_obj_count() & H5Fget_obj_ids() calls */ -#define H5F_OBJ_FILE (0x0001u) /* File objects */ -#define H5F_OBJ_DATASET (0x0002u) /* Dataset objects */ -#define H5F_OBJ_GROUP (0x0004u) /* Group objects */ -#define H5F_OBJ_DATATYPE (0x0008u) /* Named datatype objects */ -#define H5F_OBJ_ATTR (0x0010u) /* Attribute objects */ +#define H5F_OBJ_FILE (0x0001u) /**< File objects */ +#define H5F_OBJ_DATASET (0x0002u) /**< Dataset objects */ +#define H5F_OBJ_GROUP (0x0004u) /**< Group objects */ +#define H5F_OBJ_DATATYPE (0x0008u) /**< Named datatype objects */ +#define H5F_OBJ_ATTR (0x0010u) /**< Attribute objects */ #define H5F_OBJ_ALL (H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR) -#define H5F_OBJ_LOCAL (0x0020u) /* Restrict search to objects opened through current file ID */ -/* (as opposed to objects opened through any file ID accessing this file) */ +#define H5F_OBJ_LOCAL (0x0020u) /**< Restrict search to objects opened through current file ID + (as opposed to objects opened through any file ID accessing this file) */ #define H5F_FAMILY_DEFAULT (hsize_t)0 @@ -99,128 +99,148 @@ #define H5F_MPIO_DEBUG_KEY "H5F_mpio_debug_key" #endif /* H5_HAVE_PARALLEL */ -/* The difference between a single file and a set of mounted files */ +/** + * The difference between a single file and a set of mounted files + */ typedef enum H5F_scope_t { - H5F_SCOPE_LOCAL = 0, /*specified file handle only */ - H5F_SCOPE_GLOBAL = 1 /*entire virtual file */ + H5F_SCOPE_LOCAL = 0, /**< specified file handle only */ + H5F_SCOPE_GLOBAL = 1 /**< entire virtual file */ } H5F_scope_t; -/* Unlimited file size for H5Pset_external() */ +/** + * Unlimited file size for H5Pset_external() + */ #define H5F_UNLIMITED ((hsize_t)(-1L)) -/* How does file close behave? - * H5F_CLOSE_DEFAULT - Use the degree pre-defined by underlining VFL - * H5F_CLOSE_WEAK - file closes only after all opened objects are closed - * H5F_CLOSE_SEMI - if no opened objects, file is close; otherwise, file - close fails - * H5F_CLOSE_STRONG - if there are opened objects, close them first, then - close file +/** + * How does file close behave? */ typedef enum H5F_close_degree_t { - H5F_CLOSE_DEFAULT = 0, - H5F_CLOSE_WEAK = 1, - H5F_CLOSE_SEMI = 2, - H5F_CLOSE_STRONG = 3 + H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlining VFL */ + H5F_CLOSE_WEAK = 1, /**< File closes only after all opened objects are closed */ + H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is close; otherwise, file close fails */ + H5F_CLOSE_STRONG = 3 /**< If there are opened objects, close them first, then close file */ } H5F_close_degree_t; -/* Current "global" information about file */ +/** + * Current "global" information about file + */ +//! [H5F_info2_t_snip] typedef struct H5F_info2_t { struct { - unsigned version; /* Superblock version # */ - hsize_t super_size; /* Superblock size */ - hsize_t super_ext_size; /* Superblock extension size */ + unsigned version; /**< Superblock version # */ + hsize_t super_size; /**< Superblock size */ + hsize_t super_ext_size; /**< Superblock extension size */ } super; struct { - unsigned version; /* Version # of file free space management */ - hsize_t meta_size; /* Free space manager metadata size */ - hsize_t tot_space; /* Amount of free space in the file */ + unsigned version; /**< Version # of file free space management */ + hsize_t meta_size; /**< Free space manager metadata size */ + hsize_t tot_space; /**< Amount of free space in the file */ } free; struct { - unsigned version; /* Version # of shared object header info */ - hsize_t hdr_size; /* Shared object header message header size */ - H5_ih_info_t msgs_info; /* Shared object header message index & heap size */ + unsigned version; /**< Version # of shared object header info */ + hsize_t hdr_size; /**< Shared object header message header size */ + H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; } H5F_info2_t; +//! [H5F_info2_t_snip] -/* - * Types of allocation requests. The values larger than H5FD_MEM_DEFAULT +/** + * Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT * should not change other than adding new types to the end. These numbers * might appear in files. * - * Note: please change the log VFD flavors array if you change this - * enumeration. + * \internal Please change the log VFD flavors array if you change this + * enumeration. */ typedef enum H5F_mem_t { - H5FD_MEM_NOLIST = -1, /* Data should not appear in the free list. + H5FD_MEM_NOLIST = -1, /**< Data should not appear in the free list. * Must be negative. */ - H5FD_MEM_DEFAULT = 0, /* Value not yet set. Can also be the + H5FD_MEM_DEFAULT = 0, /**< Value not yet set. Can also be the * datatype set in a larger allocation * that will be suballocated by the library. * Must be zero. */ - H5FD_MEM_SUPER = 1, /* Superblock data */ - H5FD_MEM_BTREE = 2, /* B-tree data */ - H5FD_MEM_DRAW = 3, /* Raw data (content of datasets, etc.) */ - H5FD_MEM_GHEAP = 4, /* Global heap data */ - H5FD_MEM_LHEAP = 5, /* Local heap data */ - H5FD_MEM_OHDR = 6, /* Object header data */ - - H5FD_MEM_NTYPES /* Sentinel value - must be last */ + H5FD_MEM_SUPER = 1, /**< Superblock data */ + H5FD_MEM_BTREE = 2, /**< B-tree data */ + H5FD_MEM_DRAW = 3, /**< Raw data (content of datasets, etc.) */ + H5FD_MEM_GHEAP = 4, /**< Global heap data */ + H5FD_MEM_LHEAP = 5, /**< Local heap data */ + H5FD_MEM_OHDR = 6, /**< Object header data */ + + H5FD_MEM_NTYPES /**< Sentinel value - must be last */ } H5F_mem_t; -/* Free space section information */ +/** + * Free space section information + */ +//! [H5F_sect_info_t_snip] typedef struct H5F_sect_info_t { - haddr_t addr; /* Address of free space section */ - hsize_t size; /* Size of free space section */ + haddr_t addr; /**< Address of free space section */ + hsize_t size; /**< Size of free space section */ } H5F_sect_info_t; +//! [H5F_sect_info_t_snip] -/* Library's format versions */ +/** + * Library's format versions + */ typedef enum H5F_libver_t { H5F_LIBVER_ERROR = -1, - H5F_LIBVER_EARLIEST = 0, /* Use the earliest possible format for storing objects */ - H5F_LIBVER_V18 = 1, /* Use the latest v18 format for storing objects */ - H5F_LIBVER_V110 = 2, /* Use the latest v110 format for storing objects */ - H5F_LIBVER_V112 = 3, /* Use the latest v112 format for storing objects */ - H5F_LIBVER_V114 = 4, /* Use the latest v114 format for storing objects */ + H5F_LIBVER_EARLIEST = 0, /**< Use the earliest possible format for storing objects */ + H5F_LIBVER_V18 = 1, /**< Use the latest v18 format for storing objects */ + H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */ + H5F_LIBVER_V112 = 3, /**< Use the latest v112 format for storing objects */ + H5F_LIBVER_V114 = 4, /**< Use the latest v114 format for storing objects */ H5F_LIBVER_NBOUNDS } H5F_libver_t; #define H5F_LIBVER_LATEST H5F_LIBVER_V114 -/* File space handling strategy */ +/** + * File space handling strategy + */ typedef enum H5F_fspace_strategy_t { - H5F_FSPACE_STRATEGY_FSM_AGGR = - 0, /* Mechanisms: free-space managers, aggregators, and virtual file drivers */ - /* This is the library default when not set */ + H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /**< Mechanisms: free-space managers, aggregators, and virtual file + drivers This is the library default when not set */ H5F_FSPACE_STRATEGY_PAGE = - 1, /* Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */ - H5F_FSPACE_STRATEGY_AGGR = 2, /* Mechanisms: aggregators and virtual file drivers */ - H5F_FSPACE_STRATEGY_NONE = 3, /* Mechanisms: virtual file drivers */ - H5F_FSPACE_STRATEGY_NTYPES /* must be last */ + 1, /**< Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */ + H5F_FSPACE_STRATEGY_AGGR = 2, /**< Mechanisms: aggregators and virtual file drivers */ + H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */ + H5F_FSPACE_STRATEGY_NTYPES /**< Sentinel */ } H5F_fspace_strategy_t; -/* Deprecated: File space handling strategy for release 1.10.0 */ -/* They are mapped to H5F_fspace_strategy_t as defined above from release 1.10.1 onwards */ +/** + * File space handling strategy for release 1.10.0 + * + * \deprecated 1.10.1 + */ typedef enum H5F_file_space_type_t { - H5F_FILE_SPACE_DEFAULT = 0, /* Default (or current) free space strategy setting */ - H5F_FILE_SPACE_ALL_PERSIST = 1, /* Persistent free space managers, aggregators, virtual file driver */ - H5F_FILE_SPACE_ALL = 2, /* Non-persistent free space managers, aggregators, virtual file driver */ - /* This is the library default */ - H5F_FILE_SPACE_AGGR_VFD = 3, /* Aggregators, Virtual file driver */ - H5F_FILE_SPACE_VFD = 4, /* Virtual file driver */ - H5F_FILE_SPACE_NTYPES /* must be last */ + H5F_FILE_SPACE_DEFAULT = 0, /**< Default (or current) free space strategy setting */ + H5F_FILE_SPACE_ALL_PERSIST = 1, /**< Persistent free space managers, aggregators, virtual file driver */ + H5F_FILE_SPACE_ALL = 2, /**< Non-persistent free space managers, aggregators, virtual file driver + This is the library default */ + H5F_FILE_SPACE_AGGR_VFD = 3, /**< Aggregators, Virtual file driver */ + H5F_FILE_SPACE_VFD = 4, /**< Virtual file driver */ + H5F_FILE_SPACE_NTYPES /**< Sentinel */ } H5F_file_space_type_t; -/* Data structure to report the collection of read retries for metadata items with checksum */ -/* Used by public routine H5Fget_metadata_read_retry_info() */ +//! [H5F_retry_info_t_snip] #define H5F_NUM_METADATA_READ_RETRY_TYPES 21 + +/** + * Data structure to report the collection of read retries for metadata items with checksum as + * used by H5Fget_metadata_read_retry_info() + */ typedef struct H5F_retry_info_t { unsigned nbins; uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES]; } H5F_retry_info_t; +//! [H5F_retry_info_t_snip] -/* Callback for H5Pset_object_flush_cb() in a file access property list */ +/** + * Callback for H5Pset_object_flush_cb() in a file access property list + */ typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata); /*********************/ @@ -230,56 +250,1912 @@ typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata); extern "C" { #endif -H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id); -H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t create_plist, hid_t access_plist); -H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t access_plist); -H5_DLL hid_t H5Freopen(hid_t file_id); -H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); -H5_DLL herr_t H5Fclose(hid_t file_id); -H5_DLL herr_t H5Fdelete(const char *filename, hid_t fapl_id); -H5_DLL hid_t H5Fget_create_plist(hid_t file_id); -H5_DLL hid_t H5Fget_access_plist(hid_t file_id); -H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned *intent); -H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno); -H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types); -H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list); -H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle); -H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist); -H5_DLL herr_t H5Funmount(hid_t loc, const char *name); +/** + * \ingroup H5F + * + * \brief Checks if a file can be opened with a given file access property + * list + * + * \param[in] container_name Name of a file + * \fapl_id + * + * \return \htri_t + * + * \details H5Fis_accessible() checks if the file specified by \p + * container_name can be opened with the file access property list + * \p fapl_id. + * + * \note The H5Fis_accessible() function enables files to be checked with a + * given file access property list, unlike H5Fis_hdf5(), which only uses + * the default file driver when opening a file. + * + * \since 1.12.0 + * + */ +H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id); +/** + * \example H5Fcreate.c + * After creating an HDF5 file with H5Fcreate(), we close it with + * H5Fclose(). + */ +/** + * \ingroup H5F + * + * \brief Creates an HDF5 file + * + * \param[in] filename Name of the file to create + * \param[in] flags File access flags. Allowable values are: + * - #H5F_ACC_TRUNC: Truncate file, if it already exists, + * erasing all data previously stored in the file + * - #H5F_ACC_EXCL: Fail if file already exists + * \fcpl_id + * \fapl_id + * \return \hid_t{file} + * + * \details H5Fcreate() is the primary function for creating HDF5 files; it + * creates a new HDF5 file with the specified name and property lists. + * + * The \p filename parameter specifies the name of the new file. + * + * The \p flags parameter specifies whether an existing file is to be + * overwritten. It should be set to either #H5F_ACC_TRUNC to overwrite + * an existing file or #H5F_ACC_EXCL, instructing the function to fail + * if the file already exists. + * + * New files are always created in read-write mode, so the read-write + * and read-only flags, #H5F_ACC_RDWR and #H5F_ACC_RDONLY, + * respectively, are not relevant in this function. Further note that + * a specification of #H5F_ACC_RDONLY will be ignored; the file will + * be created in read-write mode, regardless. + * + * More complex behaviors of file creation and access are controlled + * through the file creation and file access property lists, + * \p fcpl_id and \p fapl_id, respectively. The value of #H5P_DEFAULT + * for any property list value indicates that the library should use + * the default values for that appropriate property list. + * + * The return value is a file identifier for the newly-created file; + * this file identifier should be closed by calling H5Fclose() when + * it is no longer needed. + * + * \include H5Fcreate.c + * + * \note #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use + * exactly one. + * + * \note An additional flag, #H5F_ACC_DEBUG, prints debug information. This + * flag can be combined with one of the above values using the bit-wise + * OR operator (\c |), but it is used only by HDF5 library developers; + * \Emph{it is neither tested nor supported for use in applications}. + * + * \attention \Bold{Special case — File creation in the case of an already-open file:} + * If a file being created is already opened, by either a previous + * H5Fopen() or H5Fcreate() call, the HDF5 library may or may not + * detect that the open file and the new file are the same physical + * file. (See H5Fopen() regarding the limitations in detecting the + * re-opening of an already-open file.)\n + * If the library detects that the file is already opened, + * H5Fcreate() will return a failure, regardless of the use of + * #H5F_ACC_TRUNC.\n + * If the library does not detect that the file is already opened + * and #H5F_ACC_TRUNC is not used, H5Fcreate() will return a failure + * because the file already exists. Note that this is correct + * behavior.\n + * But if the library does not detect that the file is already + * opened and #H5F_ACC_TRUNC is used, H5Fcreate() will truncate the + * existing file and return a valid file identifier. Such a + * truncation of a currently-opened file will almost certainly + * result in errors. While unlikely, the HDF5 library may not be + * able to detect, and thus report, such errors.\n + * Applications should avoid calling H5Fcreate() with an already + * opened file. + * + * \since 1.0.0 + * + * \see H5Fopen(), H5Fclose() + * + */ +H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Opens an existing HDF5 file + * + * \param[in] filename Name of the file to be opened + * \param[in] flags File access flags. Allowable values are: + * - #H5F_ACC_RDWR: Allows read and write access to file + * - #H5F_ACC_RDONLY: Allows read-only access to file + * - #H5F_ACC_RDWR \c | #H5F_ACC_SWMR_WRITE: Indicates that + * the file is open for writing in a + * single-writer/multi-writer (SWMR) scenario. + * - #H5F_ACC_RDONLY \c | #H5F_ACC_SWMR_READ: Indicates + * that the file is open for reading in a + * single-writer/multi-reader (SWMR) scenario. + * - An additional flag, #H5F_ACC_DEBUG, prints debug + * information. This flag can be combined with one of the + * above values using the bit-wise OR operator (\c |), but + * it is used only by HDF5 library developers; + * \Emph{it is neither tested nor supported} for use in + * applications. + * \fapl_id + * \return \hid_t{file} + * + * \details H5Fopen() is the primary function for accessing existing HDF5 files. + * This function opens the named file in the specified access mode and + * with the specified access property list. + * + * Note that H5Fopen() does not create a file if it does not already + * exist; see H5Fcreate(). + * + * The \p filename parameter specifies the name of the file to be + * opened. + * + * The \p fapl_id parameter specifies the file access property list. + * Use of #H5P_DEFAULT specifies that default I/O access properties + * are to be used. + * + * The \p flags parameter specifies whether the file will be opened in + * read-write or read-only mode, #H5F_ACC_RDWR or #H5F_ACC_RDONLY, + * respectively. More complex behaviors of file access are controlled + * through the file-access property list. + * + * The return value is a file identifier for the open file; this file + * identifier should be closed by calling H5Fclose() when it is no + * longer needed. + * + * \note #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use + * exactly one. + * + * \attention \Bold{Special cases — Multiple opens:} A file can often be opened + * with a new H5Fopen() call without closing an already-open + * identifier established in a previous H5Fopen() or H5Fcreate() + * call. Each such H5Fopen() call will return a unique identifier + * and the file can be accessed through any of these identifiers as + * long as the identifier remains valid. In such multiply-opened + * cases, the open calls must use the same flags argument and the + * file access property lists must use the same file close degree + * property setting (see the external link discussion below and + * H5Pset_fclose_degree()).\n + * In some cases, such as files on a local Unix file system, the + * HDF5 library can detect that a file is multiply opened and will + * maintain coherent access among the file identifiers.\n + * But in many other cases, such as parallel file systems or + * networked file systems, it is not always possible to detect + * multiple opens of the same physical file. In such cases, HDF5 + * will treat the file identifiers as though they are accessing + * different files and will be unable to maintain coherent access. + * Errors are likely to result in these cases. While unlikely, the + * HDF5 library may not be able to detect, and thus report, + * such errors.\n + * It is generally recommended that applications avoid multiple + * opens of the same file. + * + * \attention \Bold{Special restriction on multiple opens of a file first + * opened by means of an external link:} When an external link is + * followed, the external file is always opened with the weak file + * close degree property setting, #H5F_CLOSE_WEAK (see + * H5Lcreate_external() and H5Pset_fclose_degree()). If the file is + * reopened with H5Fopen while it remains held open from such an + * external link call, the file access property list used in the + * open call must include the file close degree setting + * #H5F_CLOSE_WEAK or the open will fail. + * + * \version 1.10.0 The #H5F_ACC_SWMR_WRITE and #H5F_ACC_SWMR_READ flags were added. + * + * \see H5Fclose() + * + */ +H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Returns a new identifier for a previously-opened HDF5 file + * + * \param[in] file_id Identifier of a file for which an additional identifier + * is required + * + * \return \hid_t{file} + * + * \details H5Freopen() returns a new file identifier for an already-open HDF5 + * file, as specified by \p file_id. Both identifiers share caches and + * other information. The only difference between the identifiers is + * that the new identifier is not mounted anywhere and no files are + * mounted on it. + * + * The new file identifier should be closed by calling H5Fclose() when + * it is no longer needed. + * + * \note Note that there is no circumstance under which H5Freopen() can + * actually open a closed file; the file must already be open and have an + * active \p file_id. E.g., one cannot close a file with H5Fclose() on + * \p file_id then use H5Freopen() on \p file_id to reopen it. + * + */ +H5_DLL hid_t H5Freopen(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Flushes all buffers associated with a file to storage + * + * \loc_id{object_id} + * \param[in] scope The scope of the flush action + * + * \return \herr_t + * + * \details H5Fflush() causes all buffers associated with a file to be + * immediately flushed to storage without removing the data from the + * cache. + * + * \p object_id can be any object associated with the file, including + * the file itself, a dataset, a group, an attribute, or a named + * datatype. + * + * \p scope specifies whether the scope of the flush action is + * global or local. Valid values are as follows: + * \scopes + * + * \attention HDF5 does not possess full control over buffering. H5Fflush() + * flushes the internal HDF5 buffers then asks the operating system + * (the OS) to flush the system buffers for the open files. After + * that, the OS is responsible for ensuring that the data is + * actually flushed to disk. + * + */ +H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); +/** + * \example H5Fclose.c + * After creating an HDF5 file with H5Fcreate(), we close it with + * H5Fclose(). + */ +/** + * \ingroup H5F + * + * \brief Terminates access to an HDF5 file + * + * \file_id + * \return \herr_t + * + * \details H5Fclose() terminates access to an HDF5 file (specified by + * \p file_id) by flushing all data to storage. + * + * If this is the last file identifier open for the file and no other + * access identifier is open (e.g., a dataset identifier, group + * identifier, or shared datatype identifier), the file will be fully + * closed and access will end. + * + * Use H5Fclose() as shown in the following example: + * \include H5Fclose.c + * + * \note \Bold{Delayed close:} Note the following deviation from the + * above-described behavior. If H5Fclose() is called for a file but one + * or more objects within the file remain open, those objects will remain + * accessible until they are individually closed. Thus, if the dataset + * \c data_sample is open when H5Fclose() is called for the file + * containing it, \c data_sample will remain open and accessible + * (including writable) until it is explicitly closed. The file will be + * automatically closed once all objects in the file have been closed.\n + * Be warned, however, that there are circumstances where it is not + * possible to delay closing a file. For example, an MPI-IO file close is + * a collective call; all of the processes that opened the file must + * close it collectively. The file cannot be closed at some time in the + * future by each process in an independent fashion. Another example is + * that an application using an AFS token-based file access privilege may + * destroy its AFS token after H5Fclose() has returned successfully. This + * would make any future access to the file, or any object within it, + * illegal.\n + * In such situations, applications must close all open objects in a file + * before calling H5Fclose. It is generally recommended to do so in all + * cases. + * + * \see H5Fopen() + * + */ +H5_DLL herr_t H5Fclose(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Deletes an HDF5 file + * + * \param[in] filename Name of the file to delete + * \fapl_id + * + * \return \herr_t + * + * \details H5Fdelete() deletes an HDF5 file \p filename with a file access + * property list \p fapl_id. The \p fapl_id should be configured with + * the same VOL connector or VFD that was used to open the file. + * + * This API was introduced for use with the Virtual Object Layer + * (VOL). With the VOL, HDF5 "files" can map to arbitrary storage + * schemes such as object stores and relational database tables. The + * data created by these implementations may be inconvenient for a + * user to remove without a detailed knowledge of the storage scheme. + * H5Fdelete() gives VOL connector authors the ability to add + * connector-specific delete code to their connectors so that users + * can remove these "files" without detailed knowledge of the storage + * scheme. + * + * For a VOL connector, H5Fdelete() deletes the file in a way that + * makes sense for the specified VOL connector. + * + * For the native HDF5 connector, HDF5 files will be deleted via the + * VFDs, each of which will have to be modified to delete the files it + * creates. + * + * For all implementations, H5Fdelete() will first check if the file + * is an HDF5 file via H5Fis_accessible(). This is done to ensure that + * H5Fdelete() cannot be used as an arbitrary file deletion call. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Fdelete(const char *filename, hid_t fapl_id); +/** + * \ingroup H5F + * + * \brief Returns a file creation property list identifier + * + * \file_id + * \return \hid_t{file creation property list} + * + * \details H5Fget_create_plist() returns the file creation property list + * identifier identifying the creation properties used to create this + * file. This function is useful for duplicating properties when + * creating another file. + * + * The creation property list identifier should be released with + * H5Pclose(). + * + */ +H5_DLL hid_t H5Fget_create_plist(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Returns a file access property list identifier + * + * \file_id + * \return \hid_t{file access property list} + * + * \details H5Fget_access_plist() returns the file access property list + * identifier of the specified file. + * + */ +H5_DLL hid_t H5Fget_access_plist(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Determines the read/write or read-only status of a file + * + * \file_id + * \param[out] intent Access mode flag as originally passed with H5Fopen() + * + * \return \herr_t + * + * \details Given the identifier of an open file, \p file_id, H5Fget_intent() + * retrieves the intended access mode" flag passed with H5Fopen() when + * the file was opened. + * + * The value of the flag is returned in \p intent. Valid values are as + * follows: + * \file_access + * + * \note The function will not return an error if intent is NULL; it will + * simply do nothing. + * + * \version 1.10.0 C function enhanced to work with SWMR functionality. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned *intent); +/** + * \ingroup H5F + * + * \brief Retrieves a file's file number that uniquely identifies an open file + * + * \file_id + * \param[out] fileno A buffer to hold the file number + * + * \return \herr_t + * + * \details H5Fget_fileno() retrieves a file number for a file specified by the + * file identifier \p file_id and the pointer \p fnumber to the file + * number. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno); +/** + * \ingroup H5F + * + * \brief Returns the number of open object identifiers for an open file + * + * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files + * \param[in] types Type of object for which identifiers are to be returned + * + * \return Returns the number of open objects if successful; otherwise returns + * a negative value. + * + * \details Given the identifier of an open file, file_id, and the desired + * object types, types, H5Fget_obj_count() returns the number of open + * object identifiers for the file. + * + * To retrieve a count of open identifiers for open objects in all + * HDF5 application files that are currently open, pass the value + * #H5F_OBJ_ALL in \p file_id. + * + * The types of objects to be counted are specified in types as + * follows: + * \obj_types + * + * Multiple object types can be combined with the + * logical \c OR operator (|). For example, the expression + * \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and + * groups. + * + * \version 1.6.8, 1.8.2 C function return type changed to \c ssize_t. + * \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types + * of objects to be counted. #H5F_OBJ_LOCAL restricts the + * search to objects opened through current file identifier. + * + */ +H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types); +/** + *------------------------------------------------------------------------- + * \ingroup H5F + * + * \brief Returns a list of open object identifiers + * + * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files + * \param[in] types Type of object for which identifiers are to be returned + * \param[in] max_objs Maximum number of object identifiers to place into + * \p obj_id_list + * \param[out] obj_id_list Pointer to the returned buffer of open object + * identifiers + * + * \return Returns number of objects placed into \p obj_id_list if successful; + * otherwise returns a negative value. + * + * \details Given the file identifier \p file_id and the type of objects to be + * identified, types, H5Fget_obj_ids() returns the list of identifiers + * for all open HDF5 objects fitting the specified criteria. + * + * To retrieve identifiers for open objects in all HDF5 application + * files that are currently open, pass the value #H5F_OBJ_ALL in + * \p file_id. + * + * The types of object identifiers to be retrieved are specified in + * types using the codes listed for the same parameter in + * H5Fget_obj_count(). + * + * To retrieve a count of open objects, use the H5Fget_obj_count() + * function. This count can be used to set the \p max_objs parameter. + * + * \version 1.8.2 C function return type changed to \c ssize_t and \p + * max_objs parameter datatype changed to \c size_t. + * \version 1.6.8 C function return type changed to \c ssize_t and \p + * max_objs parameter datatype changed to \c size_t. + * \since 1.6.0 + * + */ +H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list); +/** + * \ingroup H5F + * + * \brief Returns pointer to the file handle from the virtual file driver + * + * \file_id + * \fapl_id{fapl} + * \param[out] file_handle Pointer to the file handle being used by the + * low-level virtual file driver + * + * \return \herr_t + * + * \details Given the file identifier \p file_id and the file access property + * list \p fapl_id, H5Fget_vfd_handle() returns a pointer to the file + * handle from the low-level file driver currently being used by the + * HDF5 library for file I/O. + * + * \note For most drivers, the value of \p fapl_id will be #H5P_DEFAULT. For + * the \c FAMILY or \c MULTI drivers, this value should be defined + * through the property list functions: H5Pset_family_offset() for the + * \c FAMILY driver and H5Pset_multi_type() for the \c MULTI driver + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle); +/** + * \ingroup H5F + * + * \brief Mounts an HDF5 file + * + * \loc_id{loc} + * \param[in] name Name of the group onto which the file specified by \p child + * is to be mounted + * \file_id{child} + * \param[in] plist File mount property list identifier. Pass #H5P_DEFAULT! + * + * \return \herr_t + * + * \details H5Fmount() mounts the file specified by \p child onto the object + * specified by \p loc and \p name using the mount properties \p plist + * If the object specified by \p loc is a dataset, named datatype or + * attribute, then the file will be mounted at the location where the + * attribute, dataset, or named datatype is attached. + * + * \note To date, no file mount properties have been defined in HDF5. The + * proper value to pass for \p plist is #H5P_DEFAULT, indicating the + * default file mount property list. + * + */ +H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist); +/** + * \ingroup H5F + * + * \brief Unounts an HDF5 file + * + * \loc_id{loc} + * \param[in] name Name of the mount point + * + * \return \herr_t + * + * \details Given a mount point, H5Funmount() dissociates the mount point's + * file from the file mounted there. This function does not close + * either file. + * + * The mount point can be either the group in the parent or the root + * group of the mounted file (both groups have the same name). If the + * mount point was opened before the mount then it is the group in the + * parent; if it was opened after the mount then it is the root group + * of the child. + * + */ +H5_DLL herr_t H5Funmount(hid_t loc, const char *name); +/** + * \ingroup H5F + * + * \brief Returns the amount of free space in a file (in bytes) + * + * \file_id + * + * \return Returns the amount of free space in the file if successful; + * otherwise returns a negative value. + * + * \details Given the identifier of an open file, \p file_id, + * H5Fget_freespace() returns the amount of space that is unused by + * any objects in the file. + * + * The interpretation of this number depends on the configured free space + * management strategy. For example, if the HDF5 library only tracks free + * space in a file from a file open or create until that file is closed, + * then this routine will report the free space that has been created + * during that interval. + * + * \since 1.6.1 + * + */ H5_DLL hssize_t H5Fget_freespace(hid_t file_id); -H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size); -H5_DLL herr_t H5Fget_eoa(hid_t file_id, haddr_t *eoa); -H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); -H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len); -H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); -H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); -H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr); -H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr, - size_t *cur_size_ptr, int *cur_num_entries_ptr); -H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id); -H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); -H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *finfo); -H5_DLL herr_t H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info); -H5_DLL herr_t H5Fstart_swmr_write(hid_t file_id); -H5_DLL ssize_t H5Fget_free_sections(hid_t file_id, H5F_mem_t type, size_t nsects, - H5F_sect_info_t *sect_info /*out*/); -H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id); -H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t high); -H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id); -H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id); -H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, - /*OUT*/ hbool_t *is_enabled, - /*OUT*/ hbool_t *is_currently_logging); -H5_DLL herr_t H5Fformat_convert(hid_t fid); -H5_DLL herr_t H5Freset_page_buffering_stats(hid_t file_id); -H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], unsigned hits[2], - unsigned misses[2], unsigned evictions[2], unsigned bypasses[2]); -H5_DLL herr_t H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size); -H5_DLL herr_t H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize); -H5_DLL herr_t H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize); +/** + * \ingroup H5F + * + * \brief Returns the size of an HDF5 file (in bytes) + * + * \file_id + * \param[out] size Size of the file, in bytes + * + * \return \herr_t + * + * \details H5Fget_filesize() returns the size of the HDF5 file specified by + * \p file_id. + * + * The returned size is that of the entire file, as opposed to only + * the HDF5 portion of the file. I.e., size includes the user block, + * if any, the HDF5 portion of the file, and any data that may have + * been appended beyond the data written through the HDF5 library. + * + * \version 1.6.3 Fortran subroutine introduced in this release. + * + * \since 1.6.3 + * + */ +H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size); +/** + * \ingroup H5F + * + * \brief Retrieves the file's end-of-allocation (EOA) + * + * \file_id + * \param[out] eoa The file's EOA + * + * \return \herr_t + * + * \details H5Fget_eoa() retrieves the file's EOA and returns it in the + * parameter eoa. + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Fget_eoa(hid_t file_id, haddr_t *eoa); +/** + * \ingroup H5F + * + * \brief Sets the file' EOA to the maximum of (EOA, EOF) + increment + * + * \file_id + * \param[in] increment The number of bytes to be added to the maximum of + * (EOA, EOF) + * + * \return \herr_t + * + * \details H5Fincrement_filesize() sets the file's EOA to the maximum of (EOA, + * EOF) + \p increment. The EOA is the end-of-file address stored in + * the file's superblock while EOF is the file's actual end-of-file. + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); +/** + * \ingroup H5F + * + * \brief Retrieves a copy of the image of an existing, open file + * + * \file_id + * \param[out] buf_ptr Pointer to the buffer into which the image of the + * HDF5 file is to be copied. If \p buf_ptr is NULL, + * no data will be copied but the function’s return value + * will still indicate the buffer size required (or a + * negative value on error). + * \param[out] buf_len Size of the supplied buffer + * + * \return ssize_t + * + * \details H5Fget_file_image() retrieves a copy of the image of an existing, + * open file. This routine can be used with files opened using the + * SEC2 (or POSIX), STDIO, and Core (or Memory) virtual file drivers + * (VFDs). + * + * If the return value of H5Fget_file_image() is a positive value, it + * will be the length in bytes of the buffer required to store the + * file image. So if the file size is unknown, it can be safely + * determined with an initial H5Fget_file_image() call with buf_ptr + * set to NULL. The file image can then be retrieved with a second + * H5Fget_file_image() call with \p buf_len set to the initial call’s + * return value. + * + * While the current file size can also be retrieved with + * H5Fget_filesize(), that call may produce a larger value than is + * needed. The value returned by H5Fget_filesize() includes the user + * block, if it exists, and any unallocated space at the end of the + * file. It is safe in all situations to get the file size with + * H5Fget_file_image() and it often produces a value that is more + * appropriate for the size of a file image buffer. + * + * \note \Bold{Recommended Reading:} This function is part of the file image + * operations feature set. It is highly recommended to study the guide + * "HDF5 File Image Operations" before using this feature set.\n See the + * "See Also" section below for links to other elements of HDF5 file + * image operations. \todo Fix the references. + * + * \attention H5Pget_file_image() will fail, returning a negative value, if the + * file is too large for the supplied buffer. + * + * \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(), + * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks() + * + * \version 1.8.13 Fortran subroutine added in this release. + * + * \since 1.8.0 + * + */ +H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len); +/** + * \ingroup MDC + * + * \brief Obtains current metadata cache configuration for target file + * + * \file_id + * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance in which + * the current metadata cache configuration is to be + * reported. The fields of this structure are discussed + * \ref H5AC-cache-config-t "here". + * \return \herr_t + * + * \details H5Fget_mdc_config() loads the current metadata cache configuration + * into the instance of H5AC_cache_config_t pointed to by the \p config_ptr + * parameter. + * + * Note that the \c version field of \p config_ptr must be initialized + * --this allows the library to support old versions of the H5AC_cache_config_t + * structure. + * + * \par General configuration section + * <table> + * <tr> + * <td><em>int</em> <code>version</code> </td> + * <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should + * be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>rpt_fcn_enabled</code> </td> + * <td><p>OUT: Boolean flag indicating whether the adaptive cache resize report function is enabled. This + * field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is + * reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.</p><p>The + * report function is not supported code, and can be expected to change between versions of the + * library. Use it at your own risk.</p></td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>open_trace_file</code> </td> + * <td>OUT: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open + * a trace file for the cache. This field will always be set to <code>0</code> in this context.</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>close_trace_file</code> </td> + * <td>OUT: Boolean field indicating whether the current trace file (if any) should be closed. This field + * will always be set to <code>0</code> in this context.</td></tr> + * <tr> + * <td><em>char*</em><code>trace_file_name</code> </td> + * <td>OUT: Full path name of the trace file to be opened if the <code>open_trace_file</code> field is set + * to <code>1</code>. This field will always be set to the empty string in this context.</td></tr> + * <tr> + * <td><em>hbool_t</em> <code>evictions_enabled</code> </td> + * <td>OUT: Boolean flag indicating whether metadata cache entry evictions are + * enabled.</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>set_initial_size</code> </td> + * <td>OUT: Boolean flag indicating whether the cache should be created with a user specified initial + * maximum size.<p>If the configuration is loaded from the cache, this flag will always be set + * to <code>0</code>.</p></td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>initial_size</code> </td> + * <td>OUT: Initial maximum size of the cache in bytes, if applicable.<p>If the configuration is loaded + * from the cache, this field will contain the cache maximum size as of the time of the + * call.</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>min_clean_fraction</code> </td> + * <td>OUT: Float value specifying the minimum fraction of the cache that must be kept either clean or + * empty when possible.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>max_size</code> </td> + * <td>OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select + * as the maximum cache size.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>min_size</code> </td> + * <td>OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select + * as the maximum cache size.</td> + * </tr> + * <tr> + * <td><em>long int</em> <code>epoch_length</code> </td> + * <td>OUT: Number of cache accesses between runs of the adaptive cache resize + * code.</td> + * </tr> + * </table> + * + * \par Increment configuration section + * <table> + * <tr> + * <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code> </td> + * <td>OUT: Enumerated value indicating the operational mode of the automatic cache size increase code. At + * present, only the following values are legal:<p>\c H5C_incr__off: Automatic cache size increase is + * disabled.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled using the hit rate + * threshold algorithm.</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>lower_hr_threshold</code> </td> + * <td>OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm.</td> + * </tr> + * <tr> + * <td><em>double</em> <code>increment</code> </td> + * <td>OUT: The factor by which the current maximum cache size is multiplied to obtain an initial new + * maximum cache size if a size increase is triggered in the hit rate threshold cache size increase + * algorithm.</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>apply_max_increment</code> </td> + * <td>OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size + * increases.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>max_increment</code> </td> + * <td>OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step + * -- if applicable.</td> + * </tr> + * <tr> + * <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code> </td> + * <td>OUT: Enumerated value indicating the operational mode of the flash cache size increase code. At + * present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is + * disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add space + * algorithm.</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>flash_threshold</code> </td> + * <td>OUT: The factor by which the current maximum cache size is multiplied to obtain the minimum size + * entry / entry size increase which may trigger a flash cache size + * increase.</td> + * </tr> + * <tr> + * <td><em>double</em> <code>flash_multiple</code> </td> + * <td>OUT: The factor by which the size of the triggering entry / entry size increase is multiplied to + * obtain the initial cache size increment. This increment may be reduced to reflect existing free space + * in the cache and the <code>max_size</code> field above.</td> + * </tr> + * </table> + * + * \par Decrement configuration section + * <table> + * <tr><td colspan="2"><strong>Decrement configuration + * section:</strong></td> + * </tr> + * <tr> + * <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code> </td> + * <td>OUT: Enumerated value indicating the operational mode of the automatic cache size decrease code. At + * present, the following values are legal:<p>H5C_decr__off: Automatic cache size decrease is disabled, + * and the remaining decrement fields are ignored.</p><p>H5C_decr__threshold: Automatic cache size + * decrease is enabled using the hit rate threshold algorithm.</p><p>H5C_decr__age_out: Automatic cache + * size decrease is enabled using the ageout algorithm.</p><p>H5C_decr__age_out_with_threshold: + * Automatic cache size decrease is enabled using the ageout with hit rate threshold + * algorithm</p></td> + * </tr> + * <tr><td><em>double</em> <code>upper_hr_threshold</code> </td> + * <td>OUT: Upper hit rate threshold. This value is only used if the decr_mode is either + * H5C_decr__threshold or H5C_decr__age_out_with_threshold.</td> + * </tr> + * <tr> + * <td><em>double</em> <code>decrement</code> </td> + * <td>OUT: Factor by which the current max cache size is multiplied to obtain an initial value for the + * new cache size when cache size reduction is triggered in the hit rate threshold cache size reduction + * algorithm.</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>apply_max_decrement</code> </td> + * <td>OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size + * decreases.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>max_decrement</code> </td> + * <td>OUT: The maximum number of bytes by which cache size can be decreased if any single step, if + * applicable.</td> + * </tr> + * <tr> + * <td><em>int</em> <code>epochs_before_eviction</code> </td> + * <td>OUT: The minimum number of epochs that an entry must reside unaccessed in cache before being + * evicted under either of the ageout cache size reduction algorithms.</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>apply_empty_reserve</code> </td> + * <td>OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the + * ageout cache size reduction algorithms.</td> + * </tr> + * <tr> + * <td><em>double</em> <code>empty_reserve</code> </td> + * <td>OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable.</td> + * </tr> + * </table> + * + * \par Parallel configuration section + * <table> + * <tr><td><em>int</em> <code>dirty_bytes_threshold</code> </td> + * <td>OUT: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the + * metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the + * number of bytes of dirty metadata created since the last synchronization exceeds this limit.</p></td> + * </tr> + * </table> + * + * \since 1.8.0 + * + * \todo Fix the reference! + * + */ +H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup MDC + * + * \brief Attempts to configure metadata cache of target file + * + * \file_id + * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance + * containing the desired configuration. + * The fields of this structure are discussed + * \ref H5AC-cache-config-t "here". + * \return \herr_t + * + * \details H5Fset_mdc_config() attempts to configure the file's metadata cache + * according configuration supplied in \p config_ptr. + * + * \par General configuration fields + * <table> + * <tr> + * <td><em>int</em> <code>version</code></td> + * <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This + * field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined + * in H5ACpublic.h).</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>rpt_fcn_enabled</code></td> + * <td>IN: Boolean flag indicating whether the adaptive cache resize report function is enabled. This + * field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is reported + * via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.<p>The report function is not + * supported code, and can be expected to change between versions of the library. Use it at your own + * risk.</p></td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>open_trace_File</code></td> + * <td>IN: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open + * a trace file for the cache.<p>The trace file is a debuging feature that allows the capture of top level + * metadata cache requests for purposes of debugging and/or optimization. This field should normally be set + * to <code>0</code>, as trace file collection imposes considerable overhead.</p><p>This field should only be + * set to <code>1</code> when the <code>trace_file_name</code> contains the full path of the desired trace + * file, and either there is no open trace file on the cache, or the <code>close_trace_file</code> field is + * also <code>1</code>.</p><p>The trace file feature is unsupported unless used at the direction of The HDF + * Group. It is intended to allow The HDF Group to collect a trace of cache activity in cases of occult + * failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it + * absent the direction of The HDF Group, you are on your + * own.</p></td> + * </tr> + * <tr><td><em>hbool_t</em> <code>close_trace_file</code></td> + * <td>IN: Boolean field indicating whether the current trace file (if any) should be closed.<p>See the + * above comments on the <code>open_trace_file</code> field. This field should be set to <code>0</code> unless + * there is an open trace file on the cache that you wish to close.</p><p>The trace file feature is + * unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to collect + * a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to + * aid in reproduction in the lab. If you use it absent the direction of The HDF Group, you are on your + * own.</p></td> + * </tr> + * <tr> + * <td><em>char</em> <code>trace_file_name[]</code></td> + * <td>IN: Full path of the trace file to be opened if the <code>open_trace_file</code> field is set + * to <code>1</code>.<p>In the parallel case, an ascii representation of the mpi rank of the process will be + * appended to the file name to yield a unique trace file name for each process.</p><p>The length of the path + * must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN characters.</p><p>The trace file feature is + * unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to collect + * a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to + * aid in reproduction in the lab. If you use it absent the direction of The HDF Group, you are on your + * own.</p></td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>evictions_enabled</code></td> + * <td>IN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is + * initially set to enabled (<code>1</code>).<p>In rare circumstances, the raw data throughput requirements + * may be so high that the user wishes to postpone metadata writes so as to reserve I/O throughput for raw + * data. The <code>evictions_enabled</code> field exists to allow this. However, this is an extreme step, and + * you have no business doing it unless you have read the User Guide section on metadata caching, and have + * considered all other options carefully.</p><p>The <code>evictions_enabled</code> field may not be set to + * disabled (<code>0</code>) unless all adaptive cache resizing code is disabled via + * the <code>incr_mode</code>, <code>flash_incr_mode</code>, and <code>decr_mode</code> fields.</p><p>When + * this flag is set to disabled (<code>0</code>), the metadata cache will not attempt to evict entries to make + * space for new entries, and thus will grow without bound.</p><p>Evictions will be re-enabled when this field + * is set back to <code>1</code>. This should be done as soon as + * possible.</p></td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>set_initial_size</code></td> + * <td>IN: Boolean flag indicating whether the cache should be forced to the user specified initial + * size.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>initial_size</code></td> + * <td>IN: If <code>set_initial_size</code> is set to <code>1</code>, then <code>initial_size</code> must + * contain the desired initial size in bytes. This value must lie in the closed interval <code>[min_size, + * max_size]</code>. (see below)</td> + * </tr> + * <tr><td><em>double</em> <code>min_clean_fraction</code></td> + * <td>IN: This field specifies the minimum fraction of the cache that must be kept either clean or + * empty.<p>The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial case. + * In the parallel case, a larger value is needed -- + * see <a href="/display/HDF5/Metadata+Caching+in+HDF5">Metadata Caching in HDF5</a> in the collection + * "Advanced Topics in HDF5."</p></td> + * </tr> + * <tr><td><em>size_t</em> <code>max_size</code></td> + * <td>IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select as + * the maximum cache size.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>min_size</code></td> + * <td>IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select as + * the maximum cache size.</td> + * </tr> + * <tr><td><em>long int</em> <code>epoch_length</code></td> + * <td>IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good + * starting number.</td> + * </tr> + * </table> + * + * \par Increment configuration fields + * <table> + * <tr> + * <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code></td> + * <td>IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At + * present, only two values are legal:<p>\c H5C_incr__off: Automatic cache size increase is disabled, and the + * remaining increment fields are ignored.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled + * using the hit rate threshold + * algorithm.</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>lower_hr_threshold</code></td> + * <td>IN: Hit rate threshold used by the hit rate threshold cache size increment algorithm.<p>When the + * hit rate over an epoch is below this threshold and the cache is full, the maximum size of the cache is + * multiplied by increment (below), and then clipped as necessary to stay within max_size, and possibly + * max_increment.</p><p>This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good starting + * point.</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>increment</code></td> + * <td>IN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current + * maximum cache size to obtain a tentative new cache size.<p>The actual cache size increase will be clipped + * to satisfy the max_size specified in the general configuration, and possibly max_increment below.</p><p>The + * parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable value.</p><p>If you set it to 1.0, + * you will effectively disable cache size + * increases.</p></td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>apply_max_increment</code></td> + * <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size + * increases.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>max_increment</code></td> + * <td>IN: Maximum number of bytes by which cache size can be increased in a single step -- if + * applicable.</td> + * </tr> + * <tr> + * <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code></td> + * <td>IN: Enumerated value indicating the operational mode of the flash cache size increase code. At + * present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is + * disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add space + * algorithm.</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>flash_threshold</code></td> + * <td>IN: The factor by which the current maximum cache size is multiplied to obtain the minimum size + * entry / entry size increase which may trigger a flash cache size increase.<p>At present, this value must + * lie in the range [0.1, 1.0].</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>flash_multiple</code></td> + * <td>IN: The factor by which the size of the triggering entry / entry size increase is multiplied to + * obtain the initial cache size increment. This increment may be reduced to reflect existing free space in + * the cache and the <code>max_size</code> field above.<p>At present, this field must lie in the range [0.1, + * 10.0].</p></td> + * </tr> + * </table> + * + * \par Decrement configuration fields + * <table> + * <tr> + * <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code></td> + * <td>IN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At + * present, the following values are legal:<p>\c H5C_decr__off: Automatic cache size decrease is + * disabled.</p><p>\c H5C_decr__threshold: Automatic cache size decrease is enabled using the hit rate threshold + * algorithm.</p><p>\c H5C_decr__age_out: Automatic cache size decrease is enabled using the ageout + * algorithm.</p><p>\c H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the + * ageout with hit rate threshold + * algorithm</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>upper_hr_threshold</code></td> + * <td>IN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size + * decrement algorithms.<p>When \c decr_mode is \c H5C_decr__threshold, and the hit rate over a given epoch exceeds + * the supplied threshold, the current maximum cache size is multiplied by decrement to obtain a tentative new + * (and smaller) maximum cache size.</p><p>When \c decr_mode is \c H5C_decr__age_out_with_threshold, there is no + * attempt to find and evict aged out entries unless the hit rate in the previous epoch exceeded the supplied + * threshold.</p><p>This field must lie in the interval [0.0, 1.0].</p><p>For \c H5C_incr__threshold, .9995 or + * .99995 is a good place to start.</p><p>For \c H5C_decr__age_out_with_threshold, .999 might be more + * useful.</p></td> + * </tr> + * <tr> + * <td><em>double</em> <code>decrement</code></td> + * <td>IN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by + * which the current max cache size is multiplied to produce a tentative new cache size.<p>The actual cache + * size decrease will be clipped to satisfy the min_size specified in the general configuration, and possibly + * max_decrement below.</p><p>The parameter must be be in the interval [0.0, 1.0].</p><p>If you set it to 1.0, + * you will effectively disable cache size decreases. 0.9 is a reasonable starting + * point.</p></td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>apply_max_decrement</code></td> + * <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size + * decreases.</td> + * </tr> + * <tr> + * <td><em>size_t</em> <code>max_decrement</code></td> + * <td>IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step -- + * if applicable.</td> + * </tr> + * <tr> + * <td><em>int</em> <code>epochs_before_eviction</code></td> + * <td>IN: In the ageout based cache size reduction algorithms, this field contains the minimum number of + * epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to evict + * it. 3 is a reasonable value.</td> + * </tr> + * <tr> + * <td><em>hbool_t</em> <code>apply_empty_reserve</code></td> + * <td>IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty + * reserve when decreasing cache size.</td> + * </tr> + * <tr> + * <td><em>double</em> <code>empty_reserve</code></td> + * <td>IN: Empty reserve as a fraction of maximum cache size if applicable.<p>When so directed, the ageout + * based algorithms will not decrease the maximum cache size unless the empty reserve can be met.</p><p>The + * parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to + * start.</p></td> + * </tr> + * </table> + * + * \par Parallel configuration fields + * <table> + * <tr> + * <td><em>int</em> <code>dirty_bytes_threshold</code></td> + * <td>IN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the + * metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the number + * of bytes of dirty metadata created since the last synchronization exceeds this limit.</p><p>This field only + * applies to the parallel case. While it is ignored elsewhere, it can still draw a value out of bounds + * error.</p><p>It must be consistant across all caches on any given file.</p><p>By default, this field is set + * to 256 KB. It shouldn't be more than half the current maximum cache size times the minimum clean + * fraction.</p></td> + * </tr> + * </table> + * + * \since 1.8.0 + * + * \todo Fix the MDC document reference! + */ +H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup MDC + * + * \brief Obtains target file's metadata cache hit rate + * + * \file_id + * \param[out] hit_rate_ptr Pointer to the double in which the hit rate is returned. Note that + * \p hit_rate_ptr is undefined if the API call fails + * \return \herr_t + * + * \details H5Fget_mdc_hit_rate() queries the metadata cache of the target file to obtain its hit rate + * \Code{(cache hits / (cache hits + cache misses))} since the last time hit rate statistics + * were reset. If the cache has not been accessed since the last time the hit rate stats were + * reset, the hit rate is defined to be 0.0. + * + * The hit rate stats can be reset either manually (via H5Freset_mdc_hit_rate_stats()), or + * automatically. If the cache's adaptive resize code is enabled, the hit rate stats will be + * reset once per epoch. If they are reset manually as well, the cache may behave oddly. + * + * See the overview of the metadata cache in the special topics section of the user manual for + * details on the metadata cache and its adaptive resize algorithms. + * + */ +H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr); +/** + * \ingroup MDC + * + * \brief Obtains current metadata cache size data for specified file + * + * \file_id + * \param[out] max_size_ptr Pointer to the location in which the current cache maximum size is to be + * returned, or NULL if this datum is not desired + * \param[out] min_clean_size_ptr Pointer to the location in which the current cache minimum clean + * size is to be returned, or NULL if that datum is not desired + * \param[out] cur_size_ptr Pointer to the location in which the current cache size is to be returned, + * or NULL if that datum is not desired + * \param[out] cur_num_entries_ptr Pointer to the location in which the current number of entries in + * the cache is to be returned, or NULL if that datum is not desired + * \returns \herr_t + * + * \details H5Fget_mdc_size() queries the metadata cache of the target file for the desired size + * information, and returns this information in the locations indicated by the pointer + * parameters. If any pointer parameter is NULL, the associated data is not returned. + * + * If the API call fails, the values returned via the pointer parameters are undefined. + * + * If adaptive cache resizing is enabled, the cache maximum size and minimum clean size + * may change at the end of each epoch. Current size and current number of entries can + * change on each cache access. + * + * Current size can exceed maximum size under certain conditions. See the overview of the + * metadata cache in the special topics section of the user manual for a discussion of this. + * + */ +H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr, + size_t *cur_size_ptr, int *cur_num_entries_ptr); +/** + * \ingroup MDC + * + * \brief Resets hit rate statistics counters for the target file + * + * \file_id + * \returns \herr_t + * + * \details + * \parblock + * H5Freset_mdc_hit_rate_stats() resets the hit rate statistics counters in the metadata cache + * associated with the specified file. + * + * If the adaptive cache resizing code is enabled, the hit rate statistics are reset at the beginning + * of each epoch. This API call allows you to do the same thing from your program. + * + * The adaptive cache resizing code may behave oddly if you use this call when adaptive cache resizing + * is enabled. However, the call should be useful if you choose to control metadata cache size from your + * program. + * + * See "Metadata Caching in HDF5" for details about the metadata cache and the adaptive cache resizing + * algorithms. If you have not read, understood, and thought about the material covered in that + * documentation, + * you should not be using this API call. + * \endparblock + * + * \todo Fix the MDC document reference! + */ +H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \obj_id + * \param[out] name Buffer for the file name + * \param[in] size Size, in bytes, of the \p name buffer + * + * \return Returns the length of the file name if successful; otherwise returns + * a negative value. + * + * \details H5Fget_name() retrieves the name of the file to which the object \p + * obj_id belongs. The object can be a file, group, dataset, + * attribute, or named datatype. + * + * Up to \p size characters of the file name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. + * + * If the length of the name, which determines the required value of + * size, is unknown, a preliminary H5Fget_name() call can be made by + * setting \p name to NULL. The return value of this call will be the + * size of the file name; that value plus one (1) can then be assigned + * to size for a second H5Fget_name() call, which will retrieve the + * actual name. (The value passed in with the parameter \p size must + * be one greater than size in bytes of the actual name in order to + * accommodate the null terminator; if \p size is set to the exact + * size of the name, the last byte passed back will contain the null + * terminator and the last character will be missing from the name + * passed back to the calling application.) + * + * If an error occurs, the buffer pointed to by \p name is unchanged + * and the function returns a negative value. + * + * \since 1.6.3 + * + */ +H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \fgdta_obj_id + * \param[out] file_info Buffer for global file information + * + * \return \herr_t + * + * \details H5Fget_info2() returns global information for the file associated + * with the object identifier \p obj_id in the H5F_info2_t \c struct + * named \p file_info. + * + * \p obj_id is an identifier for any object in the file of interest. + * + * H5F_info2_t struct is defined in H5Fpublic.h as follows: + * \snippet this H5F_info2_t_snip + * + * The \c super sub-struct contains the following information: + * \li \c vers is the version number of the superblock. + * \li \c super_size is the size of the superblock. + * \li \c super_ext_size is the size of the superblock extension. + * + * The \c free sub-struct contains the following information: + * \li vers is the version number of the free-space manager. + * \li \c hdr_size is the size of the free-space manager header. + * \li \c tot_space is the total amount of free space in the file. + * + * The \c sohm sub-struct contains shared object header message + * information as follows: + * \li \c vers is the version number of the shared object header information. + * \li \c hdr_size is the size of the shared object header message. + * \li \c msgs_info is an H5_ih_info_t struct defined in H5public.h as + * follows: \snippet H5public.h H5_ih_info_t_snip + * \li \p index_size is the summed size of all the shared object + * header indexes. Each index might be either a B-tree or + * a list. + * \li \p heap_size is the size of the heap. + * + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *file_info); +/** + * \ingroup SWMR + * + * \brief Retrieves the collection of read retries for metadata entries with checksum + * + * \file_id + * \param[out] info Struct containing the collection of read retries for metadata + * entries with checksum + * \return \herr_t\n + * + * \details \Bold{Failure Modes:} + * \li When the input identifier is not a file identifier. + * \li When the pointer to the output structure is NULL. + * \li When the memory allocation for \p retries failed. + * + * \details H5Fget_metadata_read_retry_info() retrieves information regarding the number + * of read retries for metadata entries with checksum for the file \p file_id. + * This information is reported in the H5F_retry_info_t struct defined in + * H5Fpublic.h as follows: + * \snippet this H5F_retry_info_t_snip + * \c nbins is the number of bins for each \c retries[i] of metadata entry \c i. + * It is calculated based on the current number of read attempts used in the + * library and logarithmic base 10. + * + * If read retries are incurred for a metadata entry \c i, the library will + * allocate memory for \Code{retries[i] (nbins * sizeof(uint32_t)} and store + * the collection of retries there. If there are no retries for a metadata entry + * \c i, \Code{retries[i]} will be NULL. After a call to this routine, users should + * free each \Code{retries[i]} that is non-NULL, otherwise resource leak will occur. + * + * For the library default read attempts of 100 for SWMR access, nbins will be 2 + * as depicted below: + * \li \Code{retries[i][0]} is the number of 1 to 9 read retries. + * \li \Code{retries[i][1]} is the number of 10 to 99 read retries. + * For the library default read attempts of 1 for non-SWMR access, \c nbins will + * be 0 and each \Code{retries[i]} will be NULL. + * + * The following table lists the 21 metadata entries of \Code{retries[]}: + * <table> + * <tr> + * <th>Index for \Code{retries[]}</th> + * <th>Metadata entries<sup>*</sup></th> + * </tr> + * <tr><td>0</td><td>Object header (version 2)</td></tr> + * <tr><td>1</td><td>Object header chunk (version 2)</td></tr> + * <tr><td>2</td><td>B-tree header (version 2)</td></tr> + * <tr><td>3</td><td>B-tree internal node (version 2)</td></tr> + * <tr><td>4</td><td>B-tree leaf node (version 2)</td></tr> + * <tr><td>5</td><td>Fractal heap header</td></tr> + * <tr><td>6</td><td>Fractal heap direct block (optional checksum)</td></tr> + * <tr><td>7</td><td>Fractal heap indirect block</td></tr> + * <tr><td>8</td><td>Free-space header</td></tr> + * <tr><td>9</td><td>Free-space sections</td></tr> + * <tr><td>10</td><td>Shared object header message table</td></tr> + * <tr><td>11</td><td>Shared message record list</td></tr> + * <tr><td>12</td><td>Extensive array header</td></tr> + * <tr><td>13</td><td>Extensive array index block</td></tr> + * <tr><td>14</td><td>Extensive array super block</td></tr> + * <tr><td>15</td><td>Extensive array data block</td></tr> + * <tr><td>16</td><td>Extensive array data block page</td></tr> + * <tr><td>17</td><td>Fixed array super block</td></tr> + * <tr><td>18</td><td>Fixed array data block</td></tr> + * <tr><td>19</td><td>Fixed array data block page</td></tr> + * <tr><td>20</td><td>File's superblock (version 2)</td></tr> + * <tr><td colspan=2><sup>*</sup> All entries are of version 0 (zero) unless indicated otherwise.</td></tr> + * </table> + * + * \note On a system that is not atomic, the library might possibly read inconsistent + * metadata with checksum when performing single-writer/multiple-reader (SWMR) + * operations for an HDF5 file. Upon encountering such situations, the library + * will try reading the metadata again for a set number of times to attempt to + * obtain consistent data. The maximum number of read attempts used by the library + * will be either the value set via H5Pset_metadata_read_attempts() or the library + * default value when a value is not set.\n + * When the current number of metadata read attempts used in the library is unable + * to remedy the reading of inconsistent metadata on a system, the user can assess + * the information obtained via this routine to derive a different maximum value. + * The information can also be helpful for debugging purposes to identify potential + * issues with metadata flush dependencies and SWMR implementation in general. + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info); +/** + * \ingroup SWMR + * + * \brief Retrieves free-space section information for a file + * + * \file_id + * + * \return \herr_t + * + * \details H5Fstart_swmr_write() will activate SWMR writing mode for a file + * associated with \p file_id. This routine will prepare and ensure + * the file is safe for SWMR writing as follows: + * \li Check that the file is opened with write access (#H5F_ACC_RDWR). + * \li Check that the file is opened with the latest library format to + * ensure data structures with check-summed metadata are used. + * \li Check that the file is not already marked in SWMR writing mode. + * \li Enable reading retries for check-summed metadata to remedy + * possible checksum failures from reading inconsistent metadata + * on a system that is not atomic. + * \li Turn off usage of the library's accumulator to avoid possible + * ordering problem on a system that is not atomic. + * \li Perform a flush of the file’s data buffers and metadata to set + * a consistent state for starting SWMR write operations. + * + * Library objects are groups, datasets, and committed datatypes. For + * the current implementation, groups and datasets can remain open when + * activating SWMR writing mode, but not committed datatypes. Attributes + * attached to objects cannot remain open either. + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Fstart_swmr_write(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Retrieves free-space section information for a file + * + * \file_id + * \param[in] type The file memory allocation type + * \param[in] nsects The number of free-space sections + * \param[out] sect_info Array of instances of H5F_sect_info_t in which + * the free-space section information is to be returned + * + * \return Returns the number of free-space sections for the specified + * free-space manager in the file; otherwise returns a negative value. + * + * \details H5Fget_free_sections() retrieves free-space section information for + * the free-space manager with type that is associated with file + * \p file_id. If type is #H5FD_MEM_DEFAULT, this routine retrieves + * free-space section information for all the free-space managers in + * the file. + * + * Valid values for \p type are the following: + * \mem_types + * + * H5F_sect_info_t is defined as follows (in H5Fpublic.h): + * \snippet this H5F_sect_info_t_snip + * + * This routine retrieves free-space section information for \p nsects + * sections or at most the maximum number of sections in the specified + * free-space manager. If the number of sections is not known, a + * preliminary H5Fget_free_sections() call can be made by setting \p + * sect_info to NULL and the total number of free-space sections for + * the specified free-space manager will be returned. Users can then + * allocate space for entries in \p sect_info, each of which is + * defined as an H5F_sect_info_t \c struct. + * + * \attention \Bold{Failure Modes:} This routine will fail when the following + * is true: + * \li The library fails to retrieve the file creation property list + * associated with \p file_id. + * \li If the parameter \p sect_info is non-null, but the parameter + * \p nsects is equal to 0. + * \li The library fails to retrieve free-space section information + * for the file. + * + * \since 1.10.0 + * + */ +H5_DLL ssize_t H5Fget_free_sections(hid_t file_id, H5F_mem_t type, size_t nsects, + H5F_sect_info_t *sect_info /*out*/); +/** + * \ingroup H5F + * + * \brief Clears the external link open file cache + * + * \file_id + * \return \herr_t + * + * \details H5Fclear_elink_file_cache() evicts all the cached child files in + * the specified file’s external file cache, causing them to be closed + * if there is nothing else holding them open. + * + * H5Fclear_elink_file_cache() does not close the cache itself; + * subsequent external link traversals from the parent file will again + * cache the target file. See H5Pset_elink_file_cache_size() for + * information on closing the file cache. + * + * \see H5Pset_elink_file_cache_size(), H5Pget_elink_file_cache_size() + * + * \since 1.8.7 + * + */ +H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Enables the switch of version bounds setting for a file + * + * \file_id + * \param[in] low The earliest version of the library that will be used for + * writing objects + * \param[in] high The latest version of the library that will be used for + * writing objects + * + * \return \herr_t + * + * \details H5Fset_libver_bounds() enables the switch of version bounds setting + * for an open file associated with \p file_id. + * + * For the parameters \p low and \p high, see the description for + * H5Pset_libver_bounds(). + * + * \since 1.10.2 + * + */ +H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t high); +/** + * \ingroup MDC + * + * \brief Starts logging metadata cache events if logging was previously enabled + * + * \file_id + * + * \return \herr_t + * + * \details The metadata cache is a central part of the HDF5 library through + * which all \Emph{file metadata} reads and writes take place. File + * metadata is normally invisible to the user and is used by the + * library for purposes such as locating and indexing data. File + * metadata should not be confused with user metadata, which consists + * of attributes created by users and attached to HDF5 objects such + * as datasets via H5A API calls. + * + * Due to the complexity of the cache, a trace/logging feature has been + * created that can be used by HDF5 developers for debugging and performance + * analysis. The functions that control this functionality will normally be + * of use to a very limited number of developers outside of The HDF Group. + * The functions have been documented to help users create logs that can + * be sent with bug reports. + * + * Control of the log functionality is straightforward. Logging is enabled + * via the H5Pset_mdc_log_options() function, which will modify the file + * access property list used to open or create a file. This function has + * a flag that determines whether logging begins at file open or starts + * in a paused state. Log messages can then be controlled via the + * H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions. + * H5Pget_mdc_log_options() can be used to examine a file access property + * list, and H5Fget_mdc_logging_status() will return the current state of + * the logging flags. + * + * The log format is described in the \Emph{Metadata Cache Logging} document. + * + * \note Logging can only be started or stopped if metadata cache logging was enabled + * via H5Pset_mdc_log_options().\n + * When enabled and currently logging, the overhead of the logging feature will + * almost certainly be significant.\n + * The log file is opened when the HDF5 file is opened or created and not when + * this function is called for the first time.\n + * This function opens the log file and starts logging metadata cache operations + * for a particular file. Calling this function when logging has already been + * enabled will be considered an error. + * + * \since 1.10.0 + * + * \todo Fix the document reference! + * + */ +H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id); +/** + * \ingroup MDC + * + * \brief Stops logging metadata cache events if logging was previously enabled and is currently ongoing + * + * \file_id + * + * \return \herr_t + * + * \details The metadata cache is a central part of the HDF5 library through + * which all \Emph{file metadata} reads and writes take place. File + * metadata is normally invisible to the user and is used by the + * library for purposes such as locating and indexing data. File + * metadata should not be confused with user metadata, which consists + * of attributes created by users and attached to HDF5 objects such + * as datasets via H5A API calls. + * + * Due to the complexity of the cache, a trace/logging feature has been + * created that can be used by HDF5 developers for debugging and performance + * analysis. The functions that control this functionality will normally be + * of use to a very limited number of developers outside of The HDF Group. + * The functions have been documented to help users create logs that can + * be sent with bug reports. + * + * Control of the log functionality is straightforward. Logging is enabled + * via the H5Pset_mdc_log_options() function, which will modify the file + * access property list used to open or create a file. This function has + * a flag that determines whether logging begins at file open or starts + * in a paused state. Log messages can then be controlled via the + * H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions. + * H5Pget_mdc_log_options() can be used to examine a file access property + * list, and H5Fget_mdc_logging_status() will return the current state of + * the logging flags. + * + * The log format is described in the \Emph{Metadata Cache Logging} document. + * + * \note Logging can only be started or stopped if metadata cache logging was enabled + * via H5Pset_mdc_log_options().\n + * This function only suspends the logging operations. The log file will remain + * open and will not be closed until the HDF5 file is closed. + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id); +/** + * \ingroup MDC + * + * \brief Gets the current metadata cache logging status + * + * \file_id + * \param[out] is_enabled Whether logging is enabled + * \param[out] is_currently_logging Whether events are currently being logged + * \return \herr_t + * + * \details The metadata cache is a central part of the HDF5 library through + * which all \Emph{file metadata} reads and writes take place. File + * metadata is normally invisible to the user and is used by the + * library for purposes such as locating and indexing data. File + * metadata should not be confused with user metadata, which consists + * of attributes created by users and attached to HDF5 objects such + * as datasets via H5A API calls. + * + * Due to the complexity of the cache, a trace/logging feature has been + * created that can be used by HDF5 developers for debugging and performance + * analysis. The functions that control this functionality will normally be + * of use to a very limited number of developers outside of The HDF Group. + * The functions have been documented to help users create logs that can + * be sent with bug reports. + * + * Control of the log functionality is straightforward. Logging is enabled + * via the H5Pset_mdc_log_options() function, which will modify the file + * access property list used to open or create a file. This function has + * a flag that determines whether logging begins at file open or starts + * in a paused state. Log messages can then be controlled via the + * H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions. + * H5Pget_mdc_log_options() can be used to examine a file access property + * list, and H5Fget_mdc_logging_status() will return the current state of + * the logging flags. + * + * The log format is described in the \Emph{Metadata Cache Logging} document. + * + * \note Unlike H5Fstart_mdc_logging() and H5Fstop_mdc_logging(), this function can + * be called on any open file identifier. + * + * \since 1.10.0 + */ +H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled, + hbool_t *is_currently_logging); +/** + * \ingroup SWMR + * + * \todo Finish this! + */ +H5_DLL herr_t H5Fformat_convert(hid_t fid); +/** + * \ingroup H5F + * + * \brief Resets the page buffer statistics + * + * \file_id + * + * \return \herr_t + * + * \details H5Freset_page_buffering_stats() resets the page buffer statistics + * for a specified file identifier \p file_id. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5Freset_page_buffering_stats(hid_t file_id); +/** + * \ingroup H5F + * + * \brief Retrieves statistics about page access when it is enabled + * + * \file_id + * \param[out] accesses Two integer array for the number of metadata and raw + * data accesses to the page buffer + * \param[out] hits Two integer array for the number of metadata and raw data + * hits in the page buffer + * \param[out] misses Two integer array for the number of metadata and raw data + * misses in the page buffer + * \param[out] evictions Two integer array for the number of metadata and raw + * data evictions from the page buffer + * \param[out] bypasses Two integer array for the number of metadata and raw + * data accesses that bypass the page buffer + * + * \return \herr_t + * + * \details H5Fget_page_buffering_stats() retrieves page buffering statistics + * such as the number of metadata and raw data accesses (\p accesses), + * hits (\p hits), misses (\p misses), evictions (\p evictions), and + * accesses that bypass the page buffer (\p bypasses). + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], unsigned hits[2], + unsigned misses[2], unsigned evictions[2], unsigned bypasses[2]); +/** + * \ingroup MDC + * + * \brief Obtains information about a cache image if it exists + * + * \file_id + * \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not + * \param[out] image_size Length of the cache image if it exists, or 0 if it does not + * \returns \herr_t + * + * \details + * \parblock + * H5Fget_mdc_image_info() returns information about a cache image if it exists. + * + * When an HDF5 file is opened in Read/Write mode, any metadata cache image will + * be read and deleted from the file on the first metadata cache access (or, if + * persistent free space managers are enabled, on the first file space + * allocation / deallocation, or read of free space manager status, whichever + * comes first). + * + * Thus, if the file is opened Read/Write, H5Fget_mdc_image_info() should be called + * immediately after file open and before any other operation. If H5Fget_mdc_image_info() + * is called after the cache image is loaded, it will correctly report that no cache image + * exists, as the image will have already been read and deleted from the file. In the Read Only + * case, the function may be called at any time, as any cache image will not be deleted + * from the file. + * \endparblock + * + * \since 1.10.1 + */ +H5_DLL herr_t H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size); +/** + * \ingroup H5F + * + * \brief Retrieves the setting for whether or not a file will create minimized + * dataset object headers + * + * \file_id + * \param[out] minimize Flag indicating whether the library will or will not + * create minimized dataset object headers + * + * \return \herr_t + * + * \details H5Fget_dset_no_attrs_hint() retrieves the no dataset attributes + * hint setting for the file specified by the file identifier \p + * file_id. This setting is used to inform the library to create + * minimized dataset object headers when \c TRUE. + * + * The setting's value is returned in the boolean pointer minimize. + * + * \since 1.10.5 + * + */ +H5_DLL herr_t H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize); +/** + * \ingroup H5F + * + * \brief Sets the flag to create minimized dataset object headers + * + * \file_id + * \param[in] minimize Flag indicating whether the library will or will not + * create minimized dataset object headers + * + * \return \herr_t + * + * \details H5Fset_dset_no_attrs_hint() sets the no dataset attributes hint + * setting for the file specified by the file identifier \p file_id. + * If the boolean flag \p minimize is set to \c TRUE, then the library + * will create minimized dataset object headers in the file. + * \Bold{All} files that refer to the same file-on-disk will be + * affected by the most recent setting, regardless of the file + * identifier/handle (e.g., as returned by H5Fopen()). By setting the + * \p minimize flag to \c TRUE, the library expects that no attributes + * will be added to the dataset - attributes can be added, but they + * are appended with a continuation message, which can reduce + * performance. + * + * \attention This setting interacts with H5Pset_dset_no_attrs_hint(): if + * either is set to \c TRUE, then the created dataset's object header + * will be minimized. + * + * \since 1.10.5 + * + */ +H5_DLL herr_t H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize); #ifdef H5_HAVE_PARALLEL +/** + * \ingroup PH5F + * + * \brief Sets the MPI atomicity mode + * + * \file_id + * \param[in] flag Logical flag for atomicity setting. Valid values are: + * \li \c 1 -- Sets MPI file access to atomic mode. + * \li \c 0 -- Sets MPI file access to nonatomic mode. + * \returns \herr_t + * + * \par Motivation + * H5Fset_mpi_atomicity() is applicable only in parallel environments using MPI I/O. + * The function is one of the tools used to ensure sequential consistency. This means + * that a set of operations will behave as though they were performed in a serial + * order consistent with the program order. + * + * \details + * \parblock + * H5Fset_mpi_atomicity() sets MPI consistency semantics for data access to the file, + * \p file_id. + * + * If \p flag is set to \c 1, all file access operations will appear atomic, guaranteeing + * sequential consistency. If \p flag is set to \c 0, enforcement of atomic file access + * will be turned off. + * + * H5Fset_mpi_atomicity() is a collective function and all participating processes must + * pass the same values for \p file_id and \p flag. + * + * This function is available only when the HDF5 library is configured with parallel support + * (\Code{--enable-parallel}). It is useful only when used with the #H5FD_MPIO driver + * (see H5Pset_fapl_mpio()). + * \endparblock + * + * \attention + * \parblock + * H5Fset_mpi_atomicity() calls \Code{MPI_File_set_atomicity} underneath and is not supported + * if the execution platform does not support \Code{MPI_File_set_atomicity}. When it is + * supported and used, the performance of data access operations may drop significantly. + * + * In certain scenarios, even when \Code{MPI_File_set_atomicity} is supported, setting + * atomicity with H5Fset_mpi_atomicity() and \p flag set to 1 does not always yield + * strictly atomic updates. For example, some H5Dwrite() calls translate to multiple + * \Code{MPI_File_write_at} calls. This happens in all cases where the high-level file + * access routine translates to multiple lower level file access routines. + * The following scenarios will raise this issue: + * \li Non-contiguous file access using independent I/O + * \li Partial collective I/O using chunked access + * \li Collective I/O using filters or when data conversion is required + * + * This issue arises because MPI atomicity is a matter of MPI file access operations rather + * than HDF5 access operations. But the user is normally seeking atomicity at the HDF5 level. + * To accomplish this, the application must set a barrier after a write, H5Dwrite(), but before + * the next read, H5Dread(), in addition to calling H5Fset_mpi_atomicity().The barrier will + * guarantee that all underlying write operations execute atomically before the read + * operations starts. This ensures additional ordering semantics and will normally produce + * the desired behavior. + * \endparblock + * + * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5 + * + * \since 1.8.9 + * + * \todo Fix the reference! + */ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); +/** + * \ingroup PH5F + * + * \brief Retrieves the atomicity mode in use + * + * \file_id + * \param[out] flag Logical flag for atomicity setting. Valid values are: + * \li 1 -- MPI file access is set to atomic mode. + * \li 0 -- MPI file access is set to nonatomic mode. + * \returns \herr_t + * + * \details H5Fget_mpi_atomicity() retrieves the current consistency semantics mode for + * data access for the file \p file_id. + * + * Upon successful return, \p flag will be set to \c 1 if file access is set + * to atomic mode and \c 0 if file access is set to nonatomic mode. + * + * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5 + * + * \since 1.8.9 + * + * \todo Fix the reference! + */ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #endif /* H5_HAVE_PARALLEL */ @@ -294,19 +2170,95 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); /* Typedefs */ -/* Current "global" information about file */ +/** + * Current "global" information about file + */ +//! [H5F_info1_t_snip] typedef struct H5F_info1_t { - hsize_t super_ext_size; /* Superblock extension size */ + hsize_t super_ext_size; /**< Superblock extension size */ struct { - hsize_t hdr_size; /* Shared object header message header size */ - H5_ih_info_t msgs_info; /* Shared object header message index & heap size */ + hsize_t hdr_size; /**< Shared object header message header size */ + H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; } H5F_info1_t; +//! [H5F_info1_t_snip] /* Function prototypes */ -H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo); +/** + * \ingroup H5F + * + * \brief Retrieves name of file to which object belongs + * + * \fgdta_obj_id + * \param[out] file_info Buffer for global file information + * + * \return \herr_t + * + * \deprecated This function has been renamed from H5Fget_info() and is + * deprecated in favor of the macro #H5Fget_info or the function + * H5Fget_info2(). + * + * \details H5Fget_info1() returns global information for the file associated + * with the object identifier \p obj_id in the H5F_info1_t \c struct + * named \p file_info. + * + * \p obj_id is an identifier for any object in the file of interest. + * + * H5F_info1_t struct is defined in H5Fpublic.h as follows: + * \snippet this H5F_info1_t_snip + * + * \c super_ext_size is the size of the superblock extension. + * + * The \c sohm sub-struct contains shared object header message + * information as follows: + * \li \c hdr_size is the size of the shared object header message. + * \li \c msgs_info is an H5_ih_info_t struct defined in H5public.h as + * follows: \snippet H5public.h H5_ih_info_t_snip + * + * \li \p index_size is the summed size of all the shared object + * header indexes. Each index might be either a B-tree or + * a list. + * + * \version 1.10.0 C function H5Fget_info() renamed to H5Fget_info1() and + * deprecated in this release. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *file_info); +/** + * \ingroup H5F + * + * \brief Sets thelatest version of the library to be used for writing objects + * + * \file_id + * \param[in] latest_format Latest format flag + * + * \return \herr_t + * + * \deprecated When? + * + * \todo In which version was this function deprecated? + * + */ H5_DLL herr_t H5Fset_latest_format(hid_t file_id, hbool_t latest_format); -H5_DLL htri_t H5Fis_hdf5(const char *filename); +/** + * \ingroup H5F + * + * \brief Determines whether a file is in the HDF5 format + * + * \param[in] file_name File name + * + * \return \htri_t + * + * \deprecated When? + * + * \details H5Fis_hdf5() determines whether a file is in the HDF5 format. + * + * \todo In which version was this function deprecated? + * + */ +H5_DLL htri_t H5Fis_hdf5(const char *file_name); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Fsuper.c b/src/H5Fsuper.c index 9eee975..2cd6ddf 100644 --- a/src/H5Fsuper.c +++ b/src/H5Fsuper.c @@ -329,7 +329,7 @@ H5F__super_read(H5F_t *f, H5P_genplist_t *fa_plist, hbool_t initial_read) hbool_t skip_eof_check = FALSE; /* Whether to skip checking the EOF value */ #ifdef H5_HAVE_PARALLEL int mpi_size = 1; -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_PACKAGE_TAG(H5AC__SUPERBLOCK_TAG) @@ -879,12 +879,12 @@ H5F__super_read(H5F_t *f, H5P_genplist_t *fa_plist, hbool_t initial_read) /* Do the same kluge until we know for sure. VC */ #if 1 /* bug fix test code -- tidy this up if all goes well */ /* JRM */ - /* KLUGE ALERT!! - * - * H5F__super_ext_write_msg() expects f->shared->sblock to - * be set -- verify that it is NULL, and then set it. - * Set it back to NULL when we are done. - */ + /* KLUGE ALERT!! + * + * H5F__super_ext_write_msg() expects f->shared->sblock to + * be set -- verify that it is NULL, and then set it. + * Set it back to NULL when we are done. + */ HDassert(f->shared->sblock == NULL); f->shared->sblock = sblock; #endif /* JRM */ @@ -104,16 +104,10 @@ /* Local Prototypes */ /********************/ -/* Group close callback */ -static herr_t H5G__close_cb(H5VL_object_t *grp_vol_obj); - /*********************/ /* Package Variables */ /*********************/ -/* Package initialization variable */ -hbool_t H5_PKG_INIT_VAR = FALSE; - /*****************************/ /* Library Private Variables */ /*****************************/ @@ -122,182 +116,6 @@ hbool_t H5_PKG_INIT_VAR = FALSE; /* Local Variables */ /*******************/ -/* Group ID class */ -static const H5I_class_t H5I_GROUP_CLS[1] = {{ - H5I_GROUP, /* ID class value */ - 0, /* Class flags */ - 0, /* # of reserved IDs for class */ - (H5I_free_t)H5G__close_cb /* Callback routine for closing objects of this class */ -}}; - -/* Flag indicating "top" of interface has been initialized */ -static hbool_t H5G_top_package_initialize_s = FALSE; - -/*------------------------------------------------------------------------- - * Function: H5G_init - * - * Purpose: Initialize the interface from some other layer. - * - * Return: Success: non-negative - * - * Failure: negative - *------------------------------------------------------------------------- - */ -herr_t -H5G_init(void) -{ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_NOAPI(FAIL) - /* FUNC_ENTER() does all the work */ - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5G_init() */ - -/*------------------------------------------------------------------------- - * Function: H5G__init_package - * - * Purpose: Initializes the H5G interface. - * - * Return: Non-negative on success/Negative on failure - * - * Programmer: Robb Matzke - * Monday, January 5, 1998 - * - * Notes: The group creation properties are registered in the property - * list interface initialization routine (H5P_init_package) - * so that the file creation property class can inherit from it - * correctly. (Which allows the file creation property list to - * control the group creation properties of the root group of - * a file) QAK - 24/10/2005 - * - *------------------------------------------------------------------------- - */ -herr_t -H5G__init_package(void) -{ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_PACKAGE - - /* Initialize the atom group for the group IDs */ - if (H5I_register_type(H5I_GROUP_CLS) < 0) - HGOTO_ERROR(H5E_SYM, H5E_CANTINIT, FAIL, "unable to initialize interface") - - /* Mark "top" of interface as initialized, too */ - H5G_top_package_initialize_s = TRUE; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5G__init_package() */ - -/*------------------------------------------------------------------------- - * Function: H5G_top_term_package - * - * Purpose: Close the "top" of the interface, releasing IDs, etc. - * - * Return: Success: Positive if anything is done that might - * affect other interfaces; zero otherwise. - * Failure: Negative. - * - * Programmer: Quincey Koziol - * Sunday, September 13, 2015 - * - *------------------------------------------------------------------------- - */ -int -H5G_top_term_package(void) -{ - int n = 0; - - FUNC_ENTER_NOAPI_NOINIT_NOERR - - if (H5G_top_package_initialize_s) { - if (H5I_nmembers(H5I_GROUP) > 0) { - (void)H5I_clear_type(H5I_GROUP, FALSE, FALSE); - n++; /*H5I*/ - } /* end if */ - - /* Mark closed */ - if (0 == n) - H5G_top_package_initialize_s = FALSE; - } /* end if */ - - FUNC_LEAVE_NOAPI(n) -} /* end H5G_top_term_package() */ - -/*------------------------------------------------------------------------- - * Function: H5G_term_package - * - * Purpose: Terminates the H5G interface - * - * Note: Finishes shutting down the interface, after - * H5G_top_term_package() is called - * - * Return: Success: Positive if anything is done that might - * affect other interfaces; zero otherwise. - * Failure: Negative. - * - * Programmer: Robb Matzke - * Monday, January 5, 1998 - * - *------------------------------------------------------------------------- - */ -int -H5G_term_package(void) -{ - int n = 0; - - FUNC_ENTER_NOAPI_NOINIT_NOERR - - if (H5_PKG_INIT_VAR) { - /* Sanity checks */ - HDassert(0 == H5I_nmembers(H5I_GROUP)); - HDassert(FALSE == H5G_top_package_initialize_s); - - /* Destroy the group object id group */ - n += (H5I_dec_type_ref(H5I_GROUP) > 0); - - /* Mark closed */ - if (0 == n) - H5_PKG_INIT_VAR = FALSE; - } /* end if */ - - FUNC_LEAVE_NOAPI(n) -} /* end H5G_term_package() */ - -/*------------------------------------------------------------------------- - * Function: H5G__close_cb - * - * Purpose: Called when the ref count reaches zero on the group's ID - * - * Return: SUCCEED/FAIL - * - *------------------------------------------------------------------------- - */ -static herr_t -H5G__close_cb(H5VL_object_t *grp_vol_obj) -{ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_STATIC - - /* Sanity check */ - HDassert(grp_vol_obj); - - /* Close the group */ - if (H5VL_group_close(grp_vol_obj, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL) < 0) - HGOTO_ERROR(H5E_SYM, H5E_CLOSEERROR, FAIL, "unable to close group") - - /* Free the VOL object */ - if (H5VL_free_object(grp_vol_obj) < 0) - HGOTO_ERROR(H5E_SYM, H5E_CANTDEC, FAIL, "unable to free VOL object") - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5G__close_cb() */ - /*------------------------------------------------------------------------- * Function: H5Gcreate2 * @@ -370,9 +188,9 @@ H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t g H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) HGOTO_ERROR(H5E_SYM, H5E_CANTINIT, H5I_INVALID_HID, "unable to create group") - /* Get an atom for the group */ + /* Get an ID for the group */ if ((ret_value = H5VL_register(H5I_GROUP, grp, vol_obj->connector, TRUE)) < 0) - HGOTO_ERROR(H5E_SYM, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to atomize group handle") + HGOTO_ERROR(H5E_SYM, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to get ID for group handle") done: if (H5I_INVALID_HID == ret_value) @@ -417,9 +235,9 @@ done: hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id) { - void * grp = NULL; /* Structure for new group */ - H5VL_object_t * vol_obj = NULL; /* Object for loc_id */ - H5VL_loc_params_t loc_params; + void * grp = NULL; /* Structure for new group */ + 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) @@ -448,9 +266,9 @@ H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id) gapl_id, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL))) HGOTO_ERROR(H5E_SYM, H5E_CANTINIT, H5I_INVALID_HID, "unable to create group") - /* Get an atom for the group */ + /* Get an ID for the group */ if ((ret_value = H5VL_register(H5I_GROUP, grp, vol_obj->connector, TRUE)) < 0) - HGOTO_ERROR(H5E_SYM, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to atomize group handle") + HGOTO_ERROR(H5E_SYM, H5E_CANTREGISTER, H5I_INVALID_HID, "unable to get ID for group handle") done: /* Cleanup on failure */ @@ -566,7 +384,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Gget_info(hid_t loc_id, H5G_info_t *group_info) +H5Gget_info(hid_t loc_id, H5G_info_t *group_info /*out*/) { H5VL_object_t * vol_obj; H5I_type_t id_type; /* Type of ID */ @@ -574,7 +392,7 @@ H5Gget_info(hid_t loc_id, H5G_info_t *group_info) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", loc_id, group_info); + H5TRACE2("e", "ix", loc_id, group_info); /* Check args */ id_type = H5I_get_type(loc_id); @@ -609,14 +427,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *group_info, hid_t lapl_id) +H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *group_info /*out*/, hid_t lapl_id) { H5VL_object_t * vol_obj; H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "i*s*xi", loc_id, name, group_info, lapl_id); + H5TRACE4("e", "i*sxi", loc_id, name, group_info, lapl_id); /* Check args */ if (!name) @@ -661,14 +479,14 @@ done: */ herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, H5G_info_t *group_info, hid_t lapl_id) + hsize_t n, H5G_info_t *group_info /*out*/, hid_t lapl_id) { H5VL_object_t * vol_obj; H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "i*sIiIoh*xi", loc_id, group_name, idx_type, order, n, group_info, lapl_id); + H5TRACE7("e", "i*sIiIohxi", loc_id, group_name, idx_type, order, n, group_info, lapl_id); /* Check args */ if (!group_name) @@ -726,15 +544,15 @@ H5Gclose(hid_t group_id) FUNC_ENTER_API(FAIL) H5TRACE1("e", "i", group_id); - /* Check args */ - if (NULL == H5I_object_verify(group_id, H5I_GROUP)) - HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a group") + /* Check arguments */ + if (H5I_GROUP != H5I_get_type(group_id)) + HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a group ID") - /* Decrement the counter on the group atom. It will be freed if the count + /* Decrement the counter on the group ID. It will be freed if the count * reaches zero. */ if (H5I_dec_app_ref(group_id) < 0) - HGOTO_ERROR(H5E_SYM, H5E_CANTRELEASE, FAIL, "unable to close group") + HGOTO_ERROR(H5E_SYM, H5E_CANTDEC, FAIL, "decrementing group ID failed") done: FUNC_LEAVE_API(ret_value) diff --git a/src/H5Gdeprec.c b/src/H5Gdeprec.c index a731bcf..e72d225 100644 --- a/src/H5Gdeprec.c +++ b/src/H5Gdeprec.c @@ -724,7 +724,7 @@ done: *------------------------------------------------------------------------- */ int -H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf) +H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf /*out*/) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; @@ -732,7 +732,7 @@ H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf) int ret_value; /* Return value */ FUNC_ENTER_API(-1) - H5TRACE4("Is", "i*sz*s", loc_id, name, bufsize, buf); + H5TRACE4("Is", "i*szx", loc_id, name, bufsize, buf); if (!name || !*name) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, -1, "no name specified") @@ -800,7 +800,7 @@ H5Giterate(hid_t loc_id, const char *name, int *idx_p, H5G_iterate_t op, void *o herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*s*Isx*x", loc_id, name, idx_p, op, op_data); + H5TRACE5("e", "i*s*IsGi*x", loc_id, name, idx_p, op, op_data); /* Check args */ if (!name || !*name) @@ -858,7 +858,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs) +H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs /*out*/) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5I_type_t id_type; /* Type of ID */ @@ -867,7 +867,7 @@ H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*h", loc_id, num_objs); + H5TRACE2("e", "ix", loc_id, num_objs); /* Check args */ id_type = H5I_get_type(loc_id); @@ -1131,14 +1131,14 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size) +H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name /*out*/, size_t size) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; ssize_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("Zs", "ih*sz", loc_id, idx, name, size); + H5TRACE4("Zs", "ihxz", loc_id, idx, name, size); /* Set up collective metadata if appropriate */ if (H5CX_set_loc(loc_id) < 0) diff --git a/src/H5Gent.c b/src/H5Gent.c index 12a2caf..fb59d97 100644 --- a/src/H5Gent.c +++ b/src/H5Gent.c @@ -53,9 +53,6 @@ /* Package Variables */ /*********************/ -/* Declare extern the PQ free list for the wrapped strings */ -H5FL_BLK_EXTERN(str_buf); - /*****************************/ /* Library Private Variables */ /*****************************/ @@ -424,7 +421,7 @@ H5G__ent_convert(H5F_t *f, H5HL_t *heap, const char *name, const H5O_link_t *lnk HDassert(!stab_exists); } /* end else */ #endif /* NDEBUG */ - } /* end if */ + } /* end if */ else if (obj_type == H5O_TYPE_UNKNOWN) { /* Try to retrieve symbol table information for caching */ H5O_loc_t targ_oloc; /* Location of link target */ diff --git a/src/H5Gint.c b/src/H5Gint.c index 483e6b2..c4d6e64 100644 --- a/src/H5Gint.c +++ b/src/H5Gint.c @@ -84,11 +84,15 @@ typedef struct { static herr_t H5G__open_oid(H5G_t *grp); static herr_t H5G__visit_cb(const H5O_link_t *lnk, void *_udata); +static herr_t H5G__close_cb(H5VL_object_t *grp_vol_obj); /*********************/ /* Package Variables */ /*********************/ +/* Package initialization variable */ +hbool_t H5_PKG_INIT_VAR = FALSE; + /* Declare a free list to manage the H5G_t struct */ H5FL_DEFINE(H5G_t); H5FL_DEFINE(H5G_shared_t); @@ -104,6 +108,182 @@ H5FL_DEFINE(H5_obj_t); /* Local Variables */ /*******************/ +/* Group ID class */ +static const H5I_class_t H5I_GROUP_CLS[1] = {{ + H5I_GROUP, /* ID class value */ + 0, /* Class flags */ + 0, /* # of reserved IDs for class */ + (H5I_free_t)H5G__close_cb /* Callback routine for closing objects of this class */ +}}; + +/* Flag indicating "top" of interface has been initialized */ +static hbool_t H5G_top_package_initialize_s = FALSE; + +/*------------------------------------------------------------------------- + * Function: H5G_init + * + * Purpose: Initialize the interface from some other layer. + * + * Return: Success: non-negative + * + * Failure: negative + *------------------------------------------------------------------------- + */ +herr_t +H5G_init(void) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + /* FUNC_ENTER() does all the work */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5G_init() */ + +/*------------------------------------------------------------------------- + * Function: H5G__init_package + * + * Purpose: Initializes the H5G interface. + * + * Return: Non-negative on success/Negative on failure + * + * Programmer: Robb Matzke + * Monday, January 5, 1998 + * + * Notes: The group creation properties are registered in the property + * list interface initialization routine (H5P_init_package) + * so that the file creation property class can inherit from it + * correctly. (Which allows the file creation property list to + * control the group creation properties of the root group of + * a file) QAK - 24/10/2005 + * + *------------------------------------------------------------------------- + */ +herr_t +H5G__init_package(void) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_PACKAGE + + /* Initialize the ID group for the group IDs */ + if (H5I_register_type(H5I_GROUP_CLS) < 0) + HGOTO_ERROR(H5E_SYM, H5E_CANTINIT, FAIL, "unable to initialize interface") + + /* Mark "top" of interface as initialized, too */ + H5G_top_package_initialize_s = TRUE; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5G__init_package() */ + +/*------------------------------------------------------------------------- + * Function: H5G_top_term_package + * + * Purpose: Close the "top" of the interface, releasing IDs, etc. + * + * Return: Success: Positive if anything is done that might + * affect other interfaces; zero otherwise. + * Failure: Negative. + * + * Programmer: Quincey Koziol + * Sunday, September 13, 2015 + * + *------------------------------------------------------------------------- + */ +int +H5G_top_term_package(void) +{ + int n = 0; + + FUNC_ENTER_NOAPI_NOINIT_NOERR + + if (H5G_top_package_initialize_s) { + if (H5I_nmembers(H5I_GROUP) > 0) { + (void)H5I_clear_type(H5I_GROUP, FALSE, FALSE); + n++; /*H5I*/ + } /* end if */ + + /* Mark closed */ + if (0 == n) + H5G_top_package_initialize_s = FALSE; + } /* end if */ + + FUNC_LEAVE_NOAPI(n) +} /* end H5G_top_term_package() */ + +/*------------------------------------------------------------------------- + * Function: H5G_term_package + * + * Purpose: Terminates the H5G interface + * + * Note: Finishes shutting down the interface, after + * H5G_top_term_package() is called + * + * Return: Success: Positive if anything is done that might + * affect other interfaces; zero otherwise. + * Failure: Negative. + * + * Programmer: Robb Matzke + * Monday, January 5, 1998 + * + *------------------------------------------------------------------------- + */ +int +H5G_term_package(void) +{ + int n = 0; + + FUNC_ENTER_NOAPI_NOINIT_NOERR + + if (H5_PKG_INIT_VAR) { + /* Sanity checks */ + HDassert(0 == H5I_nmembers(H5I_GROUP)); + HDassert(FALSE == H5G_top_package_initialize_s); + + /* Destroy the group object id group */ + n += (H5I_dec_type_ref(H5I_GROUP) > 0); + + /* Mark closed */ + if (0 == n) + H5_PKG_INIT_VAR = FALSE; + } /* end if */ + + FUNC_LEAVE_NOAPI(n) +} /* end H5G_term_package() */ + +/*------------------------------------------------------------------------- + * Function: H5G__close_cb + * + * Purpose: Called when the ref count reaches zero on the group's ID + * + * Return: SUCCEED/FAIL + * + *------------------------------------------------------------------------- + */ +static herr_t +H5G__close_cb(H5VL_object_t *grp_vol_obj) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_STATIC + + /* Sanity check */ + HDassert(grp_vol_obj); + + /* Close the group */ + if (H5VL_group_close(grp_vol_obj, H5P_DATASET_XFER_DEFAULT, H5_REQUEST_NULL) < 0) + HGOTO_ERROR(H5E_SYM, H5E_CLOSEERROR, FAIL, "unable to close group") + + /* Free the VOL object */ + if (H5VL_free_object(grp_vol_obj) < 0) + HGOTO_ERROR(H5E_SYM, H5E_CANTDEC, FAIL, "unable to free VOL object") + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5G__close_cb() */ + /*------------------------------------------------------------------------- * Function: H5G__create_named * diff --git a/src/H5Gname.c b/src/H5Gname.c index d27428d..218b8d4 100644 --- a/src/H5Gname.c +++ b/src/H5Gname.c @@ -79,20 +79,14 @@ typedef struct H5G_gnba_iter_t { static htri_t H5G__common_path(const H5RS_str_t *fullpath_r, const H5RS_str_t *prefix_r); static H5RS_str_t *H5G__build_fullpath(const char *prefix, const char *name); -#ifdef NOT_YET -static H5RS_str_t *H5G__build_fullpath_refstr_refstr(const H5RS_str_t *prefix_r, const H5RS_str_t *name_r); -#endif /* NOT_YET */ -static herr_t H5G__name_move_path(H5RS_str_t **path_r_ptr, const char *full_suffix, const char *src_path, - const char *dst_path); -static int H5G__name_replace_cb(void *obj_ptr, hid_t obj_id, void *key); +static herr_t H5G__name_move_path(H5RS_str_t **path_r_ptr, const char *full_suffix, const char *src_path, + const char *dst_path); +static int H5G__name_replace_cb(void *obj_ptr, hid_t obj_id, void *key); /*********************/ /* Package Variables */ /*********************/ -/* Declare extern the PQ free list for the wrapped strings */ -H5FL_BLK_EXTERN(str_buf); - /*****************************/ /* Library Private Variables */ /*****************************/ @@ -277,11 +271,6 @@ done: static H5RS_str_t * H5G__build_fullpath(const char *prefix, const char *name) { - char * full_path; /* Full user path built */ - size_t orig_path_len; /* Original length of the path */ - size_t path_len; /* Length of the path */ - size_t name_len; /* Length of the name */ - unsigned need_sep; /* Flag to indicate if separator is needed */ H5RS_str_t *ret_value = NULL; /* Return value */ FUNC_ENTER_STATIC @@ -290,32 +279,12 @@ H5G__build_fullpath(const char *prefix, const char *name) HDassert(prefix); HDassert(name); - /* Get the length of the prefix */ - orig_path_len = path_len = HDstrlen(prefix); - - /* Determine if there is a trailing separator in the name */ - if (prefix[path_len - 1] == '/') - need_sep = 0; - else - need_sep = 1; - - /* Add in the length needed for the '/' separator and the relative path */ - name_len = HDstrlen(name); - path_len += name_len + need_sep; - - /* Allocate space for the path */ - if (NULL == (full_path = (char *)H5FL_BLK_MALLOC(str_buf, path_len + 1))) - HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, NULL, "memory allocation failed") - - /* Build full path */ - HDstrncpy(full_path, prefix, orig_path_len + 1); - if (need_sep) - HDstrncat(full_path, "/", (size_t)1); - HDstrncat(full_path, name, name_len); - - /* Create reference counted string for path */ - if (NULL == (ret_value = H5RS_own(full_path))) - HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, NULL, "memory allocation failed") + /* Create full path */ + if (NULL == (ret_value = H5RS_create(prefix))) + HGOTO_ERROR(H5E_SYM, H5E_CANTCREATE, NULL, "can't create ref-counted string") + if (prefix[HDstrlen(prefix) - 1] != '/') + H5RS_aputc(ret_value, '/'); /* Add separator, if the prefix doesn't end in one */ + H5RS_acat(ret_value, name); done: FUNC_LEAVE_NOAPI(ret_value) @@ -355,44 +324,6 @@ H5G_build_fullpath_refstr_str(H5RS_str_t *prefix_r, const char *name) FUNC_LEAVE_NOAPI(ret_value) } /* end H5G_build_fullpath_refstr_str() */ -#ifdef NOT_YET - -/*------------------------------------------------------------------------- - * Function: H5G_name_build_refstr_refstr - * - * Purpose: Build a full path from a prefix & base pair of reference counted - * strings - * - * Return: Pointer to reference counted string on success, NULL on error - * - * Programmer: Quincey Koziol - * - * Date: August 19, 2005 - * - *------------------------------------------------------------------------- - */ -static H5RS_str_t * -H5G__build_fullpath_refstr_refstr(const H5RS_str_t *prefix_r, const H5RS_str_t *name_r) -{ - const char *prefix; /* Pointer to raw string of prefix */ - const char *name; /* Pointer to raw string of name */ - H5RS_str_t *ret_value; /* Return value */ - - FUNC_ENTER_STATIC_NOERR - - /* Get the pointer to the prefix */ - prefix = H5RS_get_str(prefix_r); - - /* Get the pointer to the raw src user path */ - name = H5RS_get_str(name_r); - - /* Create reference counted string for path */ - ret_value = H5G__build_fullpath(prefix, name); - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5G__build_fullpath_refstr_refstr() */ -#endif /* NOT_YET */ - /*------------------------------------------------------------------------- * Function: H5G__name_init * @@ -681,27 +612,23 @@ H5G__name_move_path(H5RS_str_t **path_r_ptr, const char *full_suffix, const char path_len = HDstrlen(path); if (full_suffix_len < path_len) { const char *dst_suffix; /* Destination suffix that changes */ - size_t dst_suffix_len; /* Length of destination suffix */ const char *src_suffix; /* Source suffix that changes */ size_t path_prefix_len; /* Length of path prefix */ const char *path_prefix2; /* 2nd prefix for path */ size_t path_prefix2_len; /* Length of 2nd path prefix */ - const char *common_prefix; /* Common prefix for src & dst paths */ size_t common_prefix_len; /* Length of common prefix */ - char * new_path; /* Pointer to new path */ - size_t new_path_len; /* Length of new path */ + H5RS_str_t *rs; /* Ref-counted string for new path */ - /* Compute path prefix before full suffix*/ + /* Compute path prefix before full suffix */ path_prefix_len = path_len - full_suffix_len; /* Determine the common prefix for src & dst paths */ - common_prefix = src_path; common_prefix_len = 0; /* Find first character that is different */ while (*(src_path + common_prefix_len) == *(dst_path + common_prefix_len)) common_prefix_len++; /* Back up to previous '/' */ - while (*(common_prefix + common_prefix_len) != '/') + while (*(src_path + common_prefix_len) != '/') common_prefix_len--; /* Include '/' */ common_prefix_len++; @@ -710,33 +637,28 @@ H5G__name_move_path(H5RS_str_t **path_r_ptr, const char *full_suffix, const char src_suffix = src_path + (common_prefix_len - 1); /* Determine destination suffix */ - dst_suffix = dst_path + (common_prefix_len - 1); - dst_suffix_len = HDstrlen(dst_suffix); + dst_suffix = dst_path + (common_prefix_len - 1); - /* Compute path prefix before src suffix*/ + /* Compute path prefix before src suffix */ path_prefix2 = path; path_prefix2_len = path_prefix_len - HDstrlen(src_suffix); - /* Allocate space for the new path */ - new_path_len = path_prefix2_len + dst_suffix_len + full_suffix_len; - if (NULL == (new_path = (char *)H5FL_BLK_MALLOC(str_buf, new_path_len + 1))) - HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, FAIL, "memory allocation failed") + /* Allocate new ref-counted string */ + if (NULL == (rs = H5RS_create(NULL))) + HGOTO_ERROR(H5E_SYM, H5E_CANTCREATE, FAIL, "can't create ref-counted string") /* Create the new path */ - if (path_prefix2_len > 0) { - HDstrncpy(new_path, path_prefix2, path_prefix2_len + 1); - HDstrncpy(new_path + path_prefix2_len, dst_suffix, dst_suffix_len + 1); - } /* end if */ - else - HDstrncpy(new_path, dst_suffix, dst_suffix_len + 1); + if (path_prefix2_len > 0) + H5RS_ancat(rs, path_prefix2, path_prefix2_len); + H5RS_acat(rs, dst_suffix); if (full_suffix_len > 0) - HDstrncat(new_path, full_suffix, full_suffix_len); + H5RS_acat(rs, full_suffix); /* Release previous path */ H5RS_decr(*path_r_ptr); /* Take ownership of the new full path */ - *path_r_ptr = H5RS_own(new_path); + *path_r_ptr = rs; } /* end if */ done: @@ -853,33 +775,24 @@ H5G__name_replace_cb(void *obj_ptr, hid_t obj_id, void *key) case H5G_NAME_MOUNT: /* Check if object is in child mount hier. */ if (obj_in_child) { - const char *full_path; /* Full path of current object */ - const char *src_path; /* Full path of source object */ - size_t src_path_len; /* Length of source full path */ - char * new_full_path; /* New full path of object */ - size_t new_full_len; /* Length of new full path */ + const char *full_path; /* Full path of current object */ + const char *src_path; /* Full path of source object */ + H5RS_str_t *rs; /* Ref-counted string for new path */ /* Get pointers to paths of interest */ - full_path = H5RS_get_str(obj_path->full_path_r); - src_path = H5RS_get_str(names->src_full_path_r); - src_path_len = HDstrlen(src_path); - - /* Build new full path */ - - /* Allocate space for the new full path */ - new_full_len = src_path_len + HDstrlen(full_path); - if (NULL == (new_full_path = (char *)H5FL_BLK_MALLOC(str_buf, new_full_len + 1))) - HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, FAIL, "memory allocation failed") + full_path = H5RS_get_str(obj_path->full_path_r); + src_path = H5RS_get_str(names->src_full_path_r); - /* Create the new full path */ - HDstrncpy(new_full_path, src_path, src_path_len + 1); - HDstrncat(new_full_path, full_path, new_full_len); + /* Create new full path */ + if (NULL == (rs = H5RS_create(src_path))) + HGOTO_ERROR(H5E_SYM, H5E_CANTCREATE, FAIL, "can't create ref-counted string") + H5RS_acat(rs, full_path); /* Release previous full path */ H5RS_decr(obj_path->full_path_r); /* Take ownership of the new full path */ - obj_path->full_path_r = H5RS_own(new_full_path); + obj_path->full_path_r = rs; } /* end if */ /* Object must be in parent mount file hier. */ else { @@ -899,36 +812,30 @@ H5G__name_replace_cb(void *obj_ptr, hid_t obj_id, void *key) */ case H5G_NAME_UNMOUNT: if (obj_in_child) { - const char *full_path; /* Full path of current object */ - const char *full_suffix; /* Full path after source path */ - size_t full_suffix_len; /* Length of full path after source path */ - const char *src_path; /* Full path of source object */ - char * new_full_path; /* New full path of object */ + const char *full_path; /* Full path of current object */ + const char *full_suffix; /* Full path after source path */ + const char *src_path; /* Full path of source object */ + H5RS_str_t *rs; /* Ref-counted string for new path */ /* Get pointers to paths of interest */ full_path = H5RS_get_str(obj_path->full_path_r); src_path = H5RS_get_str(names->src_full_path_r); /* Construct full path suffix */ - full_suffix = full_path + HDstrlen(src_path); - full_suffix_len = HDstrlen(full_suffix); + full_suffix = full_path + HDstrlen(src_path); - /* Build new full path */ - - /* Create the new full path */ - if (NULL == (new_full_path = (char *)H5FL_BLK_MALLOC(str_buf, full_suffix_len + 1))) - HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, FAIL, "memory allocation failed") - HDstrncpy(new_full_path, full_suffix, full_suffix_len + 1); + /* Create new full path suffix */ + if (NULL == (rs = H5RS_create(full_suffix))) + HGOTO_ERROR(H5E_SYM, H5E_CANTCREATE, FAIL, "can't create ref-counted string") /* Release previous full path */ H5RS_decr(obj_path->full_path_r); /* Take ownership of the new full path */ - obj_path->full_path_r = H5RS_own(new_full_path); + obj_path->full_path_r = rs; /* Check if the object's user path should be invalidated */ - if (obj_path->user_path_r && - HDstrlen(new_full_path) < (size_t)H5RS_len(obj_path->user_path_r)) { + if (obj_path->user_path_r && H5RS_len(rs) < H5RS_len(obj_path->user_path_r)) { /* Free user path */ H5RS_decr(obj_path->user_path_r); obj_path->user_path_r = NULL; @@ -963,53 +870,42 @@ H5G__name_replace_cb(void *obj_ptr, hid_t obj_id, void *key) case H5G_NAME_MOVE: /* Link move case, check for relative names case */ /* Check if the src object moved is in the current object's path */ if (H5G__common_path(obj_path->full_path_r, names->src_full_path_r)) { - const char *full_path; /* Full path of current object */ - const char *full_suffix; /* Suffix of full path, after src_path */ - size_t full_suffix_len; /* Length of suffix of full path after src_path*/ - char * new_full_path; /* New full path of object */ - size_t new_full_len; /* Length of new full path */ - const char *src_path; /* Full path of source object */ - const char *dst_path; /* Full path of destination object */ - size_t dst_path_len; /* Length of destination's full path */ + const char *full_path; /* Full path of current object */ + const char *full_suffix; /* Suffix of full path, after src_path */ + const char *src_path; /* Full path of source object */ + const char *dst_path; /* Full path of destination object */ + H5RS_str_t *rs; /* Ref-counted string for new path */ /* Sanity check */ HDassert(names->dst_full_path_r); /* Get pointers to paths of interest */ - full_path = H5RS_get_str(obj_path->full_path_r); - src_path = H5RS_get_str(names->src_full_path_r); - dst_path = H5RS_get_str(names->dst_full_path_r); - dst_path_len = HDstrlen(dst_path); + full_path = H5RS_get_str(obj_path->full_path_r); + src_path = H5RS_get_str(names->src_full_path_r); + dst_path = H5RS_get_str(names->dst_full_path_r); /* Make certain that the source and destination names are full (not relative) paths */ HDassert(*src_path == '/'); HDassert(*dst_path == '/'); /* Get pointer to "full suffix" */ - full_suffix = full_path + HDstrlen(src_path); - full_suffix_len = HDstrlen(full_suffix); + full_suffix = full_path + HDstrlen(src_path); /* Update the user path, if one exists */ if (obj_path->user_path_r) if (H5G__name_move_path(&(obj_path->user_path_r), full_suffix, src_path, dst_path) < 0) HGOTO_ERROR(H5E_SYM, H5E_PATH, FAIL, "can't build user path name") - /* Build new full path */ - - /* Allocate space for the new full path */ - new_full_len = dst_path_len + full_suffix_len; - if (NULL == (new_full_path = (char *)H5FL_BLK_MALLOC(str_buf, new_full_len + 1))) - HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, FAIL, "memory allocation failed") - - /* Create the new full path */ - HDstrncpy(new_full_path, dst_path, dst_path_len + 1); - HDstrncat(new_full_path, full_suffix, full_suffix_len); + /* Create new full path */ + if (NULL == (rs = H5RS_create(dst_path))) + HGOTO_ERROR(H5E_SYM, H5E_CANTCREATE, FAIL, "can't create ref-counted string") + H5RS_acat(rs, full_suffix); /* Release previous full path */ H5RS_decr(obj_path->full_path_r); /* Take ownership of the new full path */ - obj_path->full_path_r = H5RS_own(new_full_path); + obj_path->full_path_r = rs; } /* end if */ break; diff --git a/src/H5Gprivate.h b/src/H5Gprivate.h index 14b7ae7..a9a2903 100644 --- a/src/H5Gprivate.h +++ b/src/H5Gprivate.h @@ -167,7 +167,7 @@ typedef herr_t (*H5G_traverse_t)(H5G_loc_t *grp_loc /*in*/, const char *name, typedef enum H5G_link_iterate_op_type_t { #ifndef H5_NO_DEPRECATED_SYMBOLS H5G_LINK_OP_OLD, /* "Old" application callback */ -#endif /* H5_NO_DEPRECATED_SYMBOLS */ +#endif /* H5_NO_DEPRECATED_SYMBOLS */ H5G_LINK_OP_NEW /* "New" application callback */ } H5G_link_iterate_op_type_t; @@ -176,7 +176,7 @@ typedef struct { union { #ifndef H5_NO_DEPRECATED_SYMBOLS H5G_iterate_t op_old; /* "Old" application callback for each link */ -#endif /* H5_NO_DEPRECATED_SYMBOLS */ +#endif /* H5_NO_DEPRECATED_SYMBOLS */ H5L_iterate2_t op_new; /* "New" application callback for each link */ } op_func; } H5G_link_iterate_t; diff --git a/src/H5Groot.c b/src/H5Groot.c index d7fbb49..29cb46e 100644 --- a/src/H5Groot.c +++ b/src/H5Groot.c @@ -246,8 +246,8 @@ H5G_mkroot(H5F_t *f, hbool_t create_root) HGOTO_ERROR(H5E_SYM, H5E_NOTFOUND, FAIL, "unable to verify symbol table") } /* end if */ #endif /* H5_STRICT_FORMAT_CHECKS */ - } /* end if */ - } /* end else */ + } /* end if */ + } /* end else */ /* Cache the root group's symbol table information in the root group symbol * table entry. It will have been allocated by now if it needs to be diff --git a/src/H5Gtraverse.c b/src/H5Gtraverse.c index 505718a..13be47a 100644 --- a/src/H5Gtraverse.c +++ b/src/H5Gtraverse.c @@ -198,7 +198,7 @@ H5G__traverse_ud(const H5G_loc_t *grp_loc /*in,out*/, const H5O_link_t *lnk, H5G else cb_return = (link_class->trav_func)(lnk->name, cur_grp, lnk->u.ud.udata, lnk->u.ud.size, H5CX_get_lapl(), H5CX_get_dxpl()); -#else /* H5_NO_DEPRECATED_SYMBOLS */ +#else /* H5_NO_DEPRECATED_SYMBOLS */ cb_return = (link_class->trav_func)(lnk->name, cur_grp, lnk->u.ud.udata, lnk->u.ud.size, H5CX_get_lapl(), H5CX_get_dxpl()); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5HFcache.c b/src/H5HFcache.c index 0e1304f..a9f89e0 100644 --- a/src/H5HFcache.c +++ b/src/H5HFcache.c @@ -1304,7 +1304,7 @@ H5HF__cache_iblock_serialize(const H5F_t *f, void *_image, size_t H5_ATTR_NDEBUG #ifndef NDEBUG unsigned nchildren = 0; /* Track # of children */ size_t max_child = 0; /* Track max. child entry used */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ uint32_t metadata_chksum; /* Computed metadata checksum value */ size_t u; /* Local index variable */ herr_t ret_value = SUCCEED; /* Return value */ @@ -1378,7 +1378,7 @@ H5HF__cache_iblock_serialize(const H5F_t *f, void *_image, size_t H5_ATTR_NDEBUG max_child = u; } /* end if */ #endif /* NDEBUG */ - } /* end for */ + } /* end for */ /* Compute checksum */ metadata_chksum = H5_checksum_metadata((uint8_t *)_image, (size_t)(image - (uint8_t *)_image), 0); @@ -548,7 +548,7 @@ H5HG_insert(H5F_t *f, size_t size, const void *obj, H5HG_t *hobj /*out*/) HDmemset(heap->obj[idx].begin + H5HG_SIZEOF_OBJHDR(f) + size, 0, need - (H5HG_SIZEOF_OBJHDR(f) + size)); #endif /* OLD_WAY */ - } /* end if */ + } /* end if */ heap_flags |= H5AC__DIRTIED_FLAG; /* Return value */ @@ -12,61 +12,32 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * FILE: H5I.c - Internal storage routines for handling "IDs" - * - * REMARKS: IDs which allow objects (void * currently) to be bundled - * into "types" for more general storage. - * - * DESIGN: The types are stored in an array of pointers to store each - * type in an element. Each "type" node contains a link to a - * hash table to manage the IDs in each type. Allowed types are - * values within the range 1 to H5I_MAX_NUM_TYPES and are given out - * at run-time. Types used by the library are stored in global - * variables defined in H5Ipublic.h. + * H5I.c - Public routines for handling IDs */ +/****************/ +/* Module Setup */ +/****************/ + #include "H5Imodule.h" /* This source code file is part of the H5I module */ -#define H5T_FRIEND /* Suppress error about including H5Tpkg */ +/***********/ +/* Headers */ +/***********/ #include "H5private.h" /* Generic Functions */ -#include "H5ACprivate.h" /* Metadata cache */ -#include "H5CXprivate.h" /* API Contexts */ -#include "H5Dprivate.h" /* Datasets */ #include "H5Eprivate.h" /* Error handling */ -#include "H5Fprivate.h" /* File access */ -#include "H5FLprivate.h" /* Free Lists */ -#include "H5Gprivate.h" /* Groups */ +#include "H5Fprivate.h" /* Files */ #include "H5Ipkg.h" /* IDs */ #include "H5MMprivate.h" /* Memory management */ -#include "H5Oprivate.h" /* Object headers */ -#include "H5SLprivate.h" /* Skip Lists */ -#include "H5Tpkg.h" /* Datatypes */ -#include "H5VLprivate.h" /* Virtual Object Layer */ +#include "H5Pprivate.h" /* Property lists */ +/****************/ /* Local Macros */ +/****************/ -/* Combine a Type number and an atom index into an atom */ -#define H5I_MAKE(g, i) ((((hid_t)(g)&TYPE_MASK) << ID_BITS) | ((hid_t)(i)&ID_MASK)) - -/* Local typedefs */ - -/* Atom information structure used */ -typedef struct H5I_id_info_t { - hid_t id; /* ID for this info */ - unsigned count; /* ref. count for this atom */ - unsigned app_count; /* ref. count of application visible atoms */ - const void *obj_ptr; /* pointer associated with the atom */ -} H5I_id_info_t; - -/* ID type structure used */ -typedef struct { - const H5I_class_t *cls; /* Pointer to ID class */ - unsigned init_count; /* # of times this type has been initialized*/ - uint64_t id_count; /* Current number of IDs held */ - uint64_t nextid; /* ID to use for the next atom */ - H5I_id_info_t * last_info; /* Info for most recent ID looked up */ - H5SL_t * ids; /* Pointer to skip list that stores IDs */ -} H5I_id_type_t; +/******************/ +/* Local Typedefs */ +/******************/ typedef struct { H5I_search_func_t app_cb; /* Application's callback routine */ @@ -79,119 +50,28 @@ typedef struct { void * op_data; /* Application's user data */ } H5I_iterate_pub_ud_t; -/* User data for iterator callback for retrieving an ID corresponding to an object pointer */ -typedef struct { - const void *object; /* object pointer to search for */ - H5I_type_t obj_type; /* type of object we are searching for */ - hid_t ret_id; /* ID returned */ -} H5I_get_id_ud_t; +/********************/ +/* Package Typedefs */ +/********************/ -/* User data for iterator callback for ID iteration */ -typedef struct { - H5I_search_func_t user_func; /* 'User' function to invoke */ - void * user_udata; /* User data to pass to 'user' function */ - hbool_t app_ref; /* Whether this is an appl. ref. call */ - H5I_type_t obj_type; /* Type of object we are iterating over */ -} H5I_iterate_ud_t; +/********************/ +/* Local Prototypes */ +/********************/ -/* User data for H5I__clear_type_cb */ -typedef struct { - H5I_id_type_t *type_ptr; /* Pointer to the type being cleard */ - hbool_t force; /* Whether to always remove the id */ - hbool_t app_ref; /* Whether this is an appl. ref. call */ -} H5I_clear_type_ud_t; - -/* Package initialization variable */ -hbool_t H5_PKG_INIT_VAR = FALSE; - -/*-------------------- Locally scoped variables -----------------------------*/ - -/* Array of pointers to atomic types */ -static H5I_id_type_t *H5I_id_type_list_g[H5I_MAX_NUM_TYPES]; - -/* Variable to keep track of the number of types allocated. Its value is the */ -/* next type ID to be handed out, so it is always one greater than the number */ -/* of types. */ -/* Starts at 1 instead of 0 because it makes trace output look nicer. If more */ -/* types (or IDs within a type) are needed, adjust TYPE_BITS in H5Ipkg.h */ -/* and/or increase size of hid_t */ -static int H5I_next_type = (int)H5I_NTYPES; - -/* Declare a free list to manage the H5I_id_info_t struct */ -H5FL_DEFINE_STATIC(H5I_id_info_t); - -/* Declare a free list to manage the H5I_id_type_t struct */ -H5FL_DEFINE_STATIC(H5I_id_type_t); - -/* Declare a free list to manage the H5I_class_t struct */ -H5FL_DEFINE_STATIC(H5I_class_t); - -H5FL_EXTERN(H5VL_object_t); - -/*--------------------- Local function prototypes ---------------------------*/ -static void * H5I__unwrap(void *obj_ptr, H5I_type_t type); -static htri_t H5I__clear_type_cb(void *_id, void *key, void *udata); -static int H5I__destroy_type(H5I_type_t type); -static void * H5I__remove_verify(hid_t id, H5I_type_t id_type); -static void * H5I__remove_common(H5I_id_type_t *type_ptr, hid_t id); -static int H5I__inc_type_ref(H5I_type_t type); -static int H5I__get_type_ref(H5I_type_t type); -static int H5I__search_cb(void *obj, hid_t id, void *_udata); -static H5I_id_info_t *H5I__find_id(hid_t id); -static int H5I__iterate_pub_cb(void *obj, hid_t id, void *udata); -static int H5I__find_id_cb(void *_item, void *_key, void *_udata); -static int H5I__id_dump_cb(void *_item, void *_key, void *_udata); +static int H5I__search_cb(void *obj, hid_t id, void *_udata); +static int H5I__iterate_pub_cb(void *obj, hid_t id, void *udata); -/*------------------------------------------------------------------------- - * Function: H5I_term_package - * - * Purpose: Terminate the H5I interface: release all memory, reset all - * global variables to initial values. This only happens if all - * types have been destroyed from other interfaces. - * - * Return: Success: Positive if any action was taken that might - * affect some other interface; zero otherwise. - * - * Failure: Negative - * - *------------------------------------------------------------------------- - */ -int -H5I_term_package(void) -{ - int n = 0; - - FUNC_ENTER_NOAPI_NOINIT_NOERR - - if (H5_PKG_INIT_VAR) { - H5I_id_type_t *type_ptr; /* Pointer to ID type */ - int type; /* Type of ID */ - - /* How many types are still being used? */ - for (type = 0; type < H5I_next_type; type++) - if ((type_ptr = H5I_id_type_list_g[type]) && type_ptr->ids) - n++; - - /* If no types are used then clean up */ - if (0 == n) { - for (type = 0; type < H5I_next_type; type++) { - type_ptr = H5I_id_type_list_g[type]; - if (type_ptr) { - HDassert(NULL == type_ptr->ids); - type_ptr = H5FL_FREE(H5I_id_type_t, type_ptr); - H5I_id_type_list_g[type] = NULL; - n++; - } /* end if */ - } /* end for */ - - /* Mark interface closed */ - if (0 == n) - H5_PKG_INIT_VAR = FALSE; - } /* end if */ - } /* end if */ - - FUNC_LEAVE_NOAPI(n) -} /* end H5I_term_package() */ +/*********************/ +/* Package Variables */ +/*********************/ + +/*****************************/ +/* Library Private Variables */ +/*****************************/ + +/*******************/ +/* Local Variables */ +/*******************/ /*------------------------------------------------------------------------- * Function: H5Iregister_type @@ -213,45 +93,45 @@ H5I_term_package(void) H5I_type_t H5Iregister_type(size_t H5_ATTR_DEBUG_API_USED hash_size, unsigned reserved, H5I_free_t free_func) { - H5I_class_t *cls = NULL; /* New ID class */ - H5I_type_t new_type; /* New ID type value */ + H5I_class_t *cls = NULL; /* New ID class */ + H5I_type_t new_type = H5I_BADID; /* New ID type value */ H5I_type_t ret_value = H5I_BADID; /* Return value */ FUNC_ENTER_API(H5I_BADID) - H5TRACE3("It", "zIux", hash_size, reserved, free_func); + H5TRACE3("It", "zIuIf", hash_size, reserved, free_func); /* Generate a new H5I_type_t value */ /* Increment the number of types */ - if (H5I_next_type < H5I_MAX_NUM_TYPES) { - new_type = (H5I_type_t)H5I_next_type; - H5I_next_type++; - } /* end if */ + if (H5I_next_type_g < H5I_MAX_NUM_TYPES) { + new_type = (H5I_type_t)H5I_next_type_g; + H5I_next_type_g++; + } else { hbool_t done; /* Indicate that search was successful */ - int i; /* Local index variable */ + int i; /* Look for a free type to give out */ done = FALSE; for (i = H5I_NTYPES; i < H5I_MAX_NUM_TYPES && done == FALSE; i++) { - if (NULL == H5I_id_type_list_g[i]) { + if (NULL == H5I_type_info_array_g[i]) { /* Found a free type ID */ new_type = (H5I_type_t)i; done = TRUE; - } /* end if */ - } /* end for */ + } + } /* Verify that we found a type to give out */ if (done == FALSE) HGOTO_ERROR(H5E_ATOM, H5E_NOSPACE, H5I_BADID, "Maximum number of ID types exceeded") - } /* end else */ + } /* Allocate new ID class */ - if (NULL == (cls = H5FL_CALLOC(H5I_class_t))) + if (NULL == (cls = H5MM_calloc(sizeof(H5I_class_t)))) HGOTO_ERROR(H5E_ATOM, H5E_CANTALLOC, H5I_BADID, "ID class allocation failed") /* Initialize class fields */ - cls->type_id = new_type; + cls->type = new_type; cls->flags = H5I_CLASS_IS_APPLICATION; cls->reserved = reserved; cls->free_func = free_func; @@ -267,72 +147,12 @@ done: /* Clean up on error */ if (ret_value < 0) if (cls) - cls = H5FL_FREE(H5I_class_t, cls); + cls = H5MM_xfree(cls); FUNC_LEAVE_API(ret_value) } /* end H5Iregister_type() */ /*------------------------------------------------------------------------- - * Function: H5I_register_type - * - * Purpose: Creates a new type of ID's to give out. - * The class is initialized or its reference count is incremented - * (if it is already initialized). - * - * Return: SUCCEED/FAIL - * - *------------------------------------------------------------------------- - */ -herr_t -H5I_register_type(const H5I_class_t *cls) -{ - H5I_id_type_t *type_ptr = NULL; /* Ptr to the atomic type*/ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_NOAPI(FAIL) - - /* Sanity check */ - HDassert(cls); - HDassert(cls->type_id > 0 && (int)cls->type_id < H5I_MAX_NUM_TYPES); - - /* Initialize the type */ - if (NULL == H5I_id_type_list_g[cls->type_id]) { - /* Allocate the type information for new type */ - if (NULL == (type_ptr = (H5I_id_type_t *)H5FL_CALLOC(H5I_id_type_t))) - HGOTO_ERROR(H5E_ATOM, H5E_CANTALLOC, FAIL, "ID type allocation failed") - H5I_id_type_list_g[cls->type_id] = type_ptr; - } /* end if */ - else { - /* Get the pointer to the existing type */ - type_ptr = H5I_id_type_list_g[cls->type_id]; - } /* end else */ - - /* Initialize the ID type structure for new types */ - if (type_ptr->init_count == 0) { - type_ptr->cls = cls; - type_ptr->id_count = 0; - type_ptr->nextid = cls->reserved; - type_ptr->last_info = NULL; - if (NULL == (type_ptr->ids = H5SL_create(H5SL_TYPE_HID, NULL))) - HGOTO_ERROR(H5E_ATOM, H5E_CANTCREATE, FAIL, "skip list creation failed") - } /* end if */ - - /* Increment the count of the times this type has been initialized */ - type_ptr->init_count++; - -done: - if (ret_value < 0) { /* Clean up on error */ - if (type_ptr) { - if (type_ptr->ids) - H5SL_close(type_ptr->ids); - (void)H5FL_FREE(H5I_id_type_t, type_ptr); - } /* end if */ - } /* end if */ - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_register_type() */ - -/*------------------------------------------------------------------------- * Function: H5Itype_exists * * Purpose: Query function to inform the user if a given type is @@ -353,10 +173,10 @@ H5Itype_exists(H5I_type_t type) /* Validate parameter */ if (H5I_IS_LIB_TYPE(type)) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "cannot call public function on library type") - if (type <= H5I_BADID || (int)type >= H5I_next_type) + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") - if (NULL == H5I_id_type_list_g[type]) + if (NULL == H5I_type_info_array_g[type]) ret_value = FALSE; done: @@ -373,8 +193,8 @@ done: * * Return: SUCCEED/FAIL * - * Programmer: James Laird - * Nathaniel Furrer + * Programmer: James Laird + * Nathaniel Furrer * Friday, April 23, 2004 * *------------------------------------------------------------------------- @@ -382,7 +202,7 @@ done: herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members) { - int ret_value = SUCCEED; /* Return value */ + herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) H5TRACE2("e", "It*h", type, num_members); @@ -394,9 +214,9 @@ H5Inmembers(H5I_type_t type, hsize_t *num_members) * the private interface handle it, because the public interface throws * an error when the supplied type does not exist. */ - if (type <= H5I_BADID || (int)type >= H5I_next_type) + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") - if (NULL == H5I_id_type_list_g[type]) + if (NULL == H5I_type_info_array_g[type]) HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "supplied type does not exist") if (num_members) { @@ -406,92 +226,13 @@ H5Inmembers(H5I_type_t type, hsize_t *num_members) HGOTO_ERROR(H5E_ATOM, H5E_CANTCOUNT, FAIL, "can't compute number of members") H5_CHECKED_ASSIGN(*num_members, hsize_t, members, int64_t); - } /* end if */ + } done: FUNC_LEAVE_API(ret_value) } /* end H5Inmembers() */ /*------------------------------------------------------------------------- - * Function: H5I_nmembers - * - * Purpose: Returns the number of members in a type. - * - * Return: Success: Number of members; zero if the type is empty - * or has been deleted. - * - * Failure: Negative - * - * Programmer: Robb Matzke - * Wednesday, March 24, 1999 - * - *------------------------------------------------------------------------- - */ -int64_t -H5I_nmembers(H5I_type_t type) -{ - H5I_id_type_t *type_ptr; /* Pointer to the ID type */ - int64_t ret_value = 0; /* Return value */ - - FUNC_ENTER_NOAPI(FAIL) - - /* Validate parameter */ - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") - if (NULL == (type_ptr = H5I_id_type_list_g[type]) || type_ptr->init_count <= 0) - HGOTO_DONE(0); - - /* Set return value */ - H5_CHECKED_ASSIGN(ret_value, int64_t, type_ptr->id_count, uint64_t); - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_nmembers() */ - -/*------------------------------------------------------------------------- - * Function: H5I__unwrap - * - * Purpose: Unwraps the object pointer for the 'item' that corresponds - * to an ID. - * - * Return: Pointer to the unwrapped pointer (can't fail) - * - * Programmer: Quincey Koziol - * Friday, October 19, 2018 - * - *------------------------------------------------------------------------- - */ -static void * -H5I__unwrap(void *obj_ptr, H5I_type_t type) -{ - void *ret_value = NULL; /* Return value */ - - FUNC_ENTER_STATIC_NOERR - - /* Sanity checks */ - HDassert(obj_ptr); - - /* The stored object pointer might be an H5VL_object_t, in which - * case we'll need to get the wrapped object struct (H5F_t *, etc.). - */ - if (H5I_FILE == type || H5I_GROUP == type || H5I_DATASET == type || H5I_ATTR == type) { - const H5VL_object_t *vol_obj; - - vol_obj = (const H5VL_object_t *)obj_ptr; - ret_value = H5VL_object_data(vol_obj); - } /* end if */ - else if (H5I_DATATYPE == type) { - H5T_t *dt = (H5T_t *)obj_ptr; - - ret_value = (void *)H5T_get_actual_type(dt); - } /* end if */ - else - ret_value = obj_ptr; - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__unwrap() */ - -/*------------------------------------------------------------------------- * Function: H5Iclear_type * * Purpose: Removes all objects from the type, calling the free @@ -500,8 +241,8 @@ H5I__unwrap(void *obj_ptr, H5I_type_t type) * * Return: SUCCEED/FAIL * - * Programmer: James Laird - * Nathaniel Furrer + * Programmer: James Laird + * Nathaniel Furrer * Friday, April 23, 2004 * *------------------------------------------------------------------------- @@ -524,116 +265,9 @@ done: } /* end H5Iclear_type() */ /*------------------------------------------------------------------------- - * Function: H5I_clear_type - * - * Purpose: Removes all objects from the type, calling the free - * function for each object regardless of the reference count. - * - * Return: SUCCEED/FAIL - * - * Programmer: Robb Matzke - * Wednesday, March 24, 1999 - * - *------------------------------------------------------------------------- - */ -herr_t -H5I_clear_type(H5I_type_t type, hbool_t force, hbool_t app_ref) -{ - H5I_clear_type_ud_t udata; /* udata struct for callback */ - int ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_NOAPI(FAIL) - - /* Validate parameters */ - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") - - udata.type_ptr = H5I_id_type_list_g[type]; - if (udata.type_ptr == NULL || udata.type_ptr->init_count <= 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") - - /* Finish constructing udata */ - udata.force = force; - udata.app_ref = app_ref; - - /* Attempt to free all ids in the type */ - if (H5SL_try_free_safe(udata.type_ptr->ids, H5I__clear_type_cb, &udata) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, FAIL, "can't free ids in type") - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_clear_type() */ - -/*------------------------------------------------------------------------- - * Function: H5I__clear_type_cb - * - * Purpose: Attempts to free the specified ID, calling the free - * function for the object. - * - * Return: TRUE/FALSE/FAIL - * - * Programmer: Neil Fortner - * Friday, July 10, 2015 - * - *------------------------------------------------------------------------- - */ -static htri_t -H5I__clear_type_cb(void *_id, void H5_ATTR_UNUSED *key, void *_udata) -{ - H5I_id_info_t * id = (H5I_id_info_t *)_id; /* Current ID being worked with */ - H5I_clear_type_ud_t *udata = (H5I_clear_type_ud_t *)_udata; /* udata struct */ - htri_t ret_value = FALSE; /* Return value */ - - FUNC_ENTER_STATIC_NOERR - - /* Sanity checks */ - HDassert(id); - HDassert(udata); - HDassert(udata->type_ptr); - - /* Do nothing to the object if the reference count is larger than - * one and forcing is off. - */ - if (udata->force || (id->count - (!udata->app_ref * id->app_count)) <= 1) { - /* Check for a 'free' function and call it, if it exists */ - if (udata->type_ptr->cls->free_func && - (udata->type_ptr->cls->free_func)((void *)id->obj_ptr) < 0) { /* (Casting away const OK -QAK) */ - if (udata->force) { -#ifdef H5I_DEBUG - if (H5DEBUG(I)) { - HDfprintf(H5DEBUG(I), - "H5I: free type=%d obj=0x%08lx " - "failure ignored\n", - (int)udata->type_ptr->cls->type_id, (unsigned long)(id->obj_ptr)); - } /* end if */ -#endif /*H5I_DEBUG*/ - - /* Indicate node should be removed from list */ - ret_value = TRUE; - } /* end if */ - } /* end if */ - else { - /* Indicate node should be removed from list */ - ret_value = TRUE; - } /* end else */ - - /* Remove ID if requested */ - if (ret_value) { - /* Free ID info */ - id = H5FL_FREE(H5I_id_info_t, id); - - /* Decrement the number of IDs in the type */ - udata->type_ptr->id_count--; - } /* end if */ - } /* end if */ - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__clear_type_cb() */ - -/*------------------------------------------------------------------------- * Function: H5Idestroy_type * - * Purpose: Destroys a type along with all atoms in that type + * Purpose: Destroys a type along with all IDs in that type * regardless of their reference counts. Destroying IDs * involves calling the free-func for each ID's object and * then adding the ID struct to the ID free list. Public @@ -641,8 +275,8 @@ H5I__clear_type_cb(void *_id, void H5_ATTR_UNUSED *key, void *_udata) * * Return: SUCCEED/FAIL * - * Programmer: Nathaniel Furrer - * James Laird + * Programmer: Nathaniel Furrer + * James Laird * *------------------------------------------------------------------------- */ @@ -664,56 +298,6 @@ done: } /* end H5Idestroy_type() */ /*------------------------------------------------------------------------- - * Function: H5I__destroy_type - * - * Purpose: Destroys a type along with all atoms in that type - * regardless of their reference counts. Destroying IDs - * involves calling the free-func for each ID's object and - * then adding the ID struct to the ID free list. - * - * Return: SUCCEED/FAIL - * - * Programmer: Nathaniel Furrer - * James Laird - * - *------------------------------------------------------------------------- - */ -static herr_t -H5I__destroy_type(H5I_type_t type) -{ - H5I_id_type_t *type_ptr; /* ptr to the atomic type */ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_STATIC - - /* Validate parameter */ - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") - - type_ptr = H5I_id_type_list_g[type]; - if (type_ptr == NULL || type_ptr->init_count <= 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") - - /* Close/clear/destroy all IDs for this type */ - H5E_BEGIN_TRY { H5I_clear_type(type, TRUE, FALSE); } - H5E_END_TRY /*don't care about errors*/ - - /* Check if we should release the ID class */ - if (type_ptr->cls->flags & H5I_CLASS_IS_APPLICATION) - type_ptr->cls = H5FL_FREE(H5I_class_t, (void *)type_ptr->cls); - - if (H5SL_close(type_ptr->ids) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTCLOSEOBJ, FAIL, "can't close skip list") - type_ptr->ids = NULL; - - type_ptr = H5FL_FREE(H5I_id_type_t, type_ptr); - H5I_id_type_list_g[type] = NULL; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__destroy_type() */ - -/*------------------------------------------------------------------------- * Function: H5Iregister * * Purpose: Public interface to H5I_register. @@ -732,7 +316,7 @@ H5Iregister(H5I_type_t type, const void *object) H5TRACE2("i", "It*x", type, object); if (H5I_IS_LIB_TYPE(type)) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "cannot call public function on library type") + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, H5I_INVALID_HID, "cannot call public function on library type") ret_value = H5I_register(type, object, TRUE); @@ -741,202 +325,6 @@ done: } /* end H5Iregister() */ /*------------------------------------------------------------------------- - * Function: H5I_register - * - * Purpose: Registers an OBJECT in a TYPE and returns an ID for it. - * This routine does _not_ check for unique-ness of the objects, - * if you register an object twice, you will get two different - * IDs for it. This routine does make certain that each ID in a - * type is unique. IDs are created by getting a unique number - * for the type the ID is in and incorporating the type into - * the ID which is returned to the user. - * - * Return: Success: New object ID - * Failure: H5I_INVALID_HID - * - *------------------------------------------------------------------------- - */ -hid_t -H5I_register(H5I_type_t type, const void *object, hbool_t app_ref) -{ - H5I_id_type_t *type_ptr = NULL; /* ptr to the type */ - H5I_id_info_t *id_ptr = NULL; /* ptr to the new ID information */ - hid_t new_id = -1; /* new ID */ - hid_t ret_value = H5I_INVALID_HID; /* return value */ - - FUNC_ENTER_NOAPI(FAIL) - - /* Check arguments */ - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, H5I_INVALID_HID, "invalid type number") - type_ptr = H5I_id_type_list_g[type]; - if ((NULL == type_ptr) || (type_ptr->init_count <= 0)) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, H5I_INVALID_HID, "invalid type") - if (NULL == (id_ptr = H5FL_MALLOC(H5I_id_info_t))) - HGOTO_ERROR(H5E_ATOM, H5E_NOSPACE, H5I_INVALID_HID, "memory allocation failed") - - /* Create the struct & its ID */ - new_id = H5I_MAKE(type, type_ptr->nextid); - id_ptr->id = new_id; - id_ptr->count = 1; /* initial reference count */ - id_ptr->app_count = !!app_ref; - id_ptr->obj_ptr = object; - - /* Insert into the type */ - if (H5SL_insert(type_ptr->ids, id_ptr, &id_ptr->id) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTINSERT, H5I_INVALID_HID, "can't insert ID node into skip list") - type_ptr->id_count++; - type_ptr->nextid++; - - /* Sanity check for the 'nextid' getting too large and wrapping around */ - HDassert(type_ptr->nextid <= ID_MASK); - - /* Set the most recent ID to this object */ - type_ptr->last_info = id_ptr; - - /* Set return value */ - ret_value = new_id; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_register() */ - -/*------------------------------------------------------------------------- - * Function: H5I_register_using_existing_id - * - * Purpose: Registers an OBJECT in a TYPE with the supplied ID for it. - * This routine will check to ensure the supplied ID is not already - * in use, and ensure that it is a valid ID for the given type, - * but will NOT check to ensure the OBJECT is not already - * registered (thus, it is possible to register one object under - * multiple IDs). - * - * NOTE: Intended for use in refresh calls, where we have to close - * and re-open the underlying data, then hook the object back - * up to the original ID. - * - * Return: SUCCEED/FAIL - * - *------------------------------------------------------------------------- - */ -herr_t -H5I_register_using_existing_id(H5I_type_t type, void *object, hbool_t app_ref, hid_t existing_id) -{ - H5I_id_type_t *type_ptr; /* ptr to the type */ - H5I_id_info_t *id_ptr; /* ptr to the new ID information */ - herr_t ret_value = SUCCEED; /* return value */ - - FUNC_ENTER_NOAPI(FAIL) - - /* Check arguments */ - HDassert(object); - - /* Make sure ID is not already in use */ - if (NULL != (id_ptr = H5I__find_id(existing_id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADRANGE, FAIL, "ID already in use") - - /* Make sure type number is valid */ - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") - - /* Get type pointer from list of types */ - type_ptr = H5I_id_type_list_g[type]; - - if (NULL == type_ptr || type_ptr->init_count <= 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") - - /* Make sure requested ID belongs to object's type */ - if (H5I_TYPE(existing_id) != type) - HGOTO_ERROR(H5E_ATOM, H5E_BADRANGE, FAIL, "invalid type for provided ID") - - /* Allocate new structure to house this ID */ - if (NULL == (id_ptr = H5FL_MALLOC(H5I_id_info_t))) - HGOTO_ERROR(H5E_ATOM, H5E_NOSPACE, FAIL, "memory allocation failed") - - /* Create the struct & insert requested ID */ - id_ptr->id = existing_id; - id_ptr->count = 1; /* initial reference count*/ - id_ptr->app_count = !!app_ref; - id_ptr->obj_ptr = object; - - /* Insert into the type */ - if (H5SL_insert(type_ptr->ids, id_ptr, &id_ptr->id) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTINSERT, FAIL, "can't insert ID node into skip list") - type_ptr->id_count++; - - /* Set the most recent ID to this object */ - type_ptr->last_info = id_ptr; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_register_using_existing_id() */ - -/*------------------------------------------------------------------------- - * Function: H5I_subst - * - * Purpose: Substitute a new object pointer for the specified ID. - * - * Return: Success: Non-NULL previous object pointer associated - * with the specified ID. - * Failure: NULL - * - * Programmer: Quincey Koziol - * Saturday, February 27, 2010 - * - *------------------------------------------------------------------------- - */ -void * -H5I_subst(hid_t id, const void *new_object) -{ - H5I_id_info_t *id_ptr; /* Pointer to the atom */ - void * ret_value = NULL; /* Return value */ - - FUNC_ENTER_NOAPI(NULL) - - /* General lookup of the ID */ - if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_NOTFOUND, NULL, "can't get ID ref count") - - /* Get the old object pointer to return */ - ret_value = (void *)id_ptr->obj_ptr; /* (Casting away const OK -QAK) */ - - /* Set the new object pointer for the ID */ - id_ptr->obj_ptr = new_object; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_subst() */ - -/*------------------------------------------------------------------------- - * Function: H5I_object - * - * Purpose: Find an object pointer for the specified ID. - * - * Return: Success: Non-NULL object pointer associated with the - * specified ID - * - * Failure: NULL - * - *------------------------------------------------------------------------- - */ -void * -H5I_object(hid_t id) -{ - H5I_id_info_t *id_ptr; /* Pointer to the new atom */ - void * ret_value = NULL; /* Return value */ - - FUNC_ENTER_NOAPI_NOERR - - /* General lookup of the ID */ - if (NULL != (id_ptr = H5I__find_id(id))) { - /* Get the object pointer to return */ - ret_value = (void *)id_ptr->obj_ptr; /* (Casting away const OK -QAK) */ - } - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_object() */ - -/*------------------------------------------------------------------------- * Function: H5Iobject_verify * * Purpose: Find an object pointer for the specified ID, verifying that @@ -950,93 +338,26 @@ H5I_object(hid_t id) *------------------------------------------------------------------------- */ void * -H5Iobject_verify(hid_t id, H5I_type_t id_type) +H5Iobject_verify(hid_t id, H5I_type_t type) { void *ret_value = NULL; /* Return value */ FUNC_ENTER_API(NULL) - H5TRACE2("*x", "iIt", id, id_type); + H5TRACE2("*x", "iIt", id, type); /* Validate parameters */ - if (H5I_IS_LIB_TYPE(id_type)) + if (H5I_IS_LIB_TYPE(type)) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, NULL, "cannot call public function on library type") - if (id_type < 1 || (int)id_type >= H5I_next_type) + if (type < 1 || (int)type >= H5I_next_type_g) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, NULL, "identifier has invalid type") - ret_value = H5I_object_verify(id, id_type); + ret_value = H5I_object_verify(id, type); done: FUNC_LEAVE_API(ret_value) } /* end H5Iobject_verify() */ /*------------------------------------------------------------------------- - * Function: H5I_object_verify - * - * Purpose: Find an object pointer for the specified ID, verifying that - * its in a particular type. - * - * Return: Success: Non-NULL object pointer associated with the - * specified ID. - * Failure: NULL - * - * Programmer: Quincey Koziol - * Wednesday, July 31, 2002 - * - *------------------------------------------------------------------------- - */ -void * -H5I_object_verify(hid_t id, H5I_type_t id_type) -{ - H5I_id_info_t *id_ptr = NULL; /* Pointer to the new atom */ - void * ret_value = NULL; /* Return value */ - - FUNC_ENTER_NOAPI_NOERR - - HDassert(id_type >= 1 && (int)id_type < H5I_next_type); - - /* Verify that the type of the ID is correct & lookup the ID */ - if (id_type == H5I_TYPE(id) && NULL != (id_ptr = H5I__find_id(id))) { - /* Get the object pointer to return */ - ret_value = (void *)id_ptr->obj_ptr; /* (Casting away const OK -QAK) */ - } - - FUNC_LEAVE_NOAPI(ret_value) -} /* H5I_object_verify() */ - -/*------------------------------------------------------------------------- - * Function: H5I_get_type - * - * Purpose: Given an object ID return the type to which it - * belongs. The ID need not be the ID of an object which - * currently exists because the type number is encoded - * in the object ID. - * - * Return: Success: A positive integer (corresponding to an H5I_type_t - * enum value for library ID types, but not for user - * ID types). - * Failure: H5I_BADID - * - * Programmer: Robb Matzke - * Friday, February 19, 1999 - * - *------------------------------------------------------------------------- - */ -H5I_type_t -H5I_get_type(hid_t id) -{ - H5I_type_t ret_value = H5I_BADID; /* Return value */ - - FUNC_ENTER_NOAPI_NOERR - - if (id > 0) - ret_value = H5I_TYPE(id); - - HDassert(ret_value >= H5I_BADID && (int)ret_value < H5I_next_type); - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_get_type() */ - -/*------------------------------------------------------------------------- * Function: H5Iget_type * * Purpose: The public version of H5I_get_type(), obtains a type number @@ -1061,7 +382,7 @@ H5Iget_type(hid_t id) ret_value = H5I_get_type(id); - if (ret_value <= H5I_BADID || (int)ret_value >= H5I_next_type || NULL == H5I_object(id)) + if (ret_value <= H5I_BADID || (int)ret_value >= H5I_next_type_g || NULL == H5I_object(id)) HGOTO_DONE(H5I_BADID); done: @@ -1069,54 +390,6 @@ done: } /* end H5Iget_type() */ /*------------------------------------------------------------------------- - * Function: H5I_is_file_object - * - * Purpose: Convenience function to determine if an ID represents - * a file object. - * - * In H5O calls, you can't use object_verify to ensure - * the ID was of the correct class since there's no - * H5I_OBJECT ID class. - * - * Return: Success: TRUE/FALSE - * Failure: FAIL - * - *------------------------------------------------------------------------- - */ -htri_t -H5I_is_file_object(hid_t id) -{ - H5I_type_t id_type = H5I_get_type(id); - htri_t ret_value = FAIL; - - FUNC_ENTER_NOAPI(FAIL); - - /* Fail if the ID type is out of range */ - if (id_type < 1 || id_type >= H5I_NTYPES) - HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "ID type out of range"); - - /* Return TRUE if the ID is a file object (dataset, group, map, or committed - * datatype), FALSE otherwise. - */ - if (H5I_DATASET == id_type || H5I_GROUP == id_type || H5I_MAP == id_type) - ret_value = TRUE; - else if (H5I_DATATYPE == id_type) { - - H5T_t *dt = NULL; - - if (NULL == (dt = (H5T_t *)H5I_object(id))) - HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "unable to get underlying datatype struct"); - - ret_value = H5T_is_named(dt); - } - else - ret_value = FALSE; - -done: - FUNC_LEAVE_NOAPI(ret_value); -} /* H5I_is_file_object() */ - -/*------------------------------------------------------------------------- * Function: H5Iremove_verify * * Purpose: Removes the specified ID from its type, first checking that the @@ -1128,145 +401,30 @@ done: * calling H5I_object(). * Failure: NULL * - * Programmer: James Laird - * Nathaniel Furrer + * Programmer: James Laird + * Nathaniel Furrer * *------------------------------------------------------------------------- */ void * -H5Iremove_verify(hid_t id, H5I_type_t id_type) +H5Iremove_verify(hid_t id, H5I_type_t type) { void *ret_value = NULL; /* Return value */ FUNC_ENTER_API(NULL) - H5TRACE2("*x", "iIt", id, id_type); + H5TRACE2("*x", "iIt", id, type); - if (H5I_IS_LIB_TYPE(id_type)) + if (H5I_IS_LIB_TYPE(type)) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, NULL, "cannot call public function on library type") /* Remove the id */ - ret_value = H5I__remove_verify(id, id_type); + ret_value = H5I__remove_verify(id, type); done: FUNC_LEAVE_API(ret_value) } /* end H5Iremove_verify() */ /*------------------------------------------------------------------------- - * Function: H5I__remove_verify - * - * Purpose: Removes the specified ID from its type, first checking that - * the ID's type is the same as the ID type supplied as an argument - * - * Return: Success: A pointer to the object that was removed, the - * same pointer which would have been found by - * calling H5I_object(). - * Failure: NULL - * - * Programmer: James Laird - * Nat Furrer - * - *------------------------------------------------------------------------- - */ -static void * -H5I__remove_verify(hid_t id, H5I_type_t id_type) -{ - void *ret_value = NULL; /*return value */ - - FUNC_ENTER_STATIC_NOERR - - /* Argument checking will be performed by H5I_remove() */ - - /* Verify that the type of the ID is correct */ - if (id_type == H5I_TYPE(id)) - ret_value = H5I_remove(id); - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__remove_verify() */ - -/*------------------------------------------------------------------------- - * Function: H5I__remove_common - * - * Purpose: Common code to remove a specified ID from its type. - * - * Return: Success: A pointer to the object that was removed, the - * same pointer which would have been found by - * calling H5I_object(). - * Failure: NULL - * - * Programmer: Quincey Koziol - * October 3, 2013 - * - *------------------------------------------------------------------------- - */ -static void * -H5I__remove_common(H5I_id_type_t *type_ptr, hid_t id) -{ - H5I_id_info_t *curr_id; /* Pointer to the current atom */ - void * ret_value = NULL; /* Return value */ - - FUNC_ENTER_STATIC - - /* Sanity check */ - HDassert(type_ptr); - - /* Get the ID node for the ID */ - if (NULL == (curr_id = (H5I_id_info_t *)H5SL_remove(type_ptr->ids, &id))) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, NULL, "can't remove ID node from skip list") - - /* Check if this ID was the last one accessed */ - if (type_ptr->last_info == curr_id) - type_ptr->last_info = NULL; - - ret_value = (void *)curr_id->obj_ptr; /* (Casting away const OK -QAK) */ - curr_id = H5FL_FREE(H5I_id_info_t, curr_id); - - /* Decrement the number of IDs in the type */ - (type_ptr->id_count)--; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__remove_common() */ - -/*------------------------------------------------------------------------- - * Function: H5I_remove - * - * Purpose: Removes the specified ID from its type. - * - * Return: Success: A pointer to the object that was removed, the - * same pointer which would have been found by - * calling H5I_object(). - * Failure: NULL - * - * Programmer: Unknown - * - *------------------------------------------------------------------------- - */ -void * -H5I_remove(hid_t id) -{ - H5I_id_type_t *type_ptr; /* Pointer to the atomic type */ - H5I_type_t type; /* Atom's atomic type */ - void * ret_value = NULL; /* Return value */ - - FUNC_ENTER_NOAPI(NULL) - - /* Check arguments */ - type = H5I_TYPE(id); - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, NULL, "invalid type number") - type_ptr = H5I_id_type_list_g[type]; - if (type_ptr == NULL || type_ptr->init_count <= 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, NULL, "invalid type") - - /* Remove the node from the type */ - if (NULL == (ret_value = H5I__remove_common(type_ptr, id))) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, NULL, "can't remove ID node") - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_remove() */ - -/*------------------------------------------------------------------------- * Function: H5Idec_ref * * Purpose: Decrements the number of references outstanding for an ID. @@ -1302,163 +460,6 @@ done: } /* end H5Idec_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_dec_ref - * - * Purpose: Decrements the number of references outstanding for an ID. - * This will fail if the type is not a reference counted type. - * The ID type's 'free' function will be called for the ID - * if the reference count for the ID reaches 0 and a free - * function has been defined at type creation time. - * - * Return: Success: New reference count - * - * Failure: -1 - * - *------------------------------------------------------------------------- - */ -int -H5I_dec_ref(hid_t id) -{ - H5I_id_info_t *id_ptr; /* Pointer to the new ID */ - int ret_value = 0; /* Return value */ - - FUNC_ENTER_NOAPI((-1)) - - /* Sanity check */ - HDassert(id >= 0); - - /* General lookup of the ID */ - if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") - - /* If this is the last reference to the object then invoke the type's - * free method on the object. If the free method is undefined or - * successful then remove the object from the type; otherwise leave - * the object in the type without decrementing the reference - * count. If the reference count is more than one then decrement the - * reference count without calling the free method. - * - * Beware: the free method may call other H5I functions. - * - * If an object is closing, we can remove the ID even though the free - * method might fail. This can happen when a mandatory filter fails to - * write when a dataset is closed and the chunk cache is flushed to the - * file. We have to close the dataset anyway. (SLU - 2010/9/7) - */ - if (1 == id_ptr->count) { - H5I_id_type_t *type_ptr; /*ptr to the type */ - - /* Get the ID's type */ - type_ptr = H5I_id_type_list_g[H5I_TYPE(id)]; - - /* (Casting away const OK -QAK) */ - if (!type_ptr->cls->free_func || (type_ptr->cls->free_func)((void *)id_ptr->obj_ptr) >= 0) { - /* Remove the node from the type */ - if (NULL == H5I__remove_common(type_ptr, id)) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, (-1), "can't remove ID node") - ret_value = 0; - } /* end if */ - else - ret_value = -1; - } /* end if */ - else { - --(id_ptr->count); - ret_value = (int)id_ptr->count; - } /* end else */ - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_dec_ref() */ - -/*------------------------------------------------------------------------- - * Function: H5I_dec_app_ref - * - * Purpose: H5I_dec_ref wrapper for case of modifying the application ref. - * count for an ID as well as normal reference count. - * - * Return: Success: New app. reference count - * Failure: -1 - * - * Programmer: Quincey Koziol - * Sept 16, 2010 - * - *------------------------------------------------------------------------- - */ -int -H5I_dec_app_ref(hid_t id) -{ - H5I_id_info_t *id_ptr; /* Pointer to the new ID */ - int ret_value = 0; /* Return value */ - - FUNC_ENTER_NOAPI((-1)) - - /* Sanity check */ - HDassert(id >= 0); - - /* Call regular decrement reference count routine */ - if ((ret_value = H5I_dec_ref(id)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, (-1), "can't decrement ID ref count") - - /* Check if the ID still exists */ - if (ret_value > 0) { - /* General lookup of the ID */ - if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") - - /* Adjust app_ref */ - --(id_ptr->app_count); - HDassert(id_ptr->count >= id_ptr->app_count); - - /* Set return value */ - ret_value = (int)id_ptr->app_count; - } /* end if */ - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_dec_app_ref() */ - -/*------------------------------------------------------------------------- - * Function: H5I_dec_app_ref_always_close - * - * Purpose: H5I_dec_app_ref wrapper for case of always closing the ID, - * even when the free routine fails - * - * Return: Success: New app. reference count - * Failure: -1 - * - *------------------------------------------------------------------------- - */ -int -H5I_dec_app_ref_always_close(hid_t id) -{ - int ret_value = 0; /* Return value */ - - FUNC_ENTER_NOAPI((-1)) - - /* Sanity check */ - HDassert(id >= 0); - - /* Call application decrement reference count routine */ - ret_value = H5I_dec_app_ref(id); - - /* Check for failure */ - if (ret_value < 0) { - /* - * If an object is closing, we can remove the ID even though the free - * method might fail. This can happen when a mandatory filter fails to - * write when a dataset is closed and the chunk cache is flushed to the - * file. We have to close the dataset anyway. (SLU - 2010/9/7) - */ - H5I_remove(id); - - HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, (-1), "can't decrement ID ref count") - } - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_dec_app_ref_always_close() */ - -/*------------------------------------------------------------------------- * Function: H5Iinc_ref * * Purpose: Increments the number of references outstanding for an ID. @@ -1471,7 +472,7 @@ done: int H5Iinc_ref(hid_t id) { - int ret_value; /* Return value */ + int ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) H5TRACE1("Is", "i", id); @@ -1489,43 +490,6 @@ done: } /* end H5Iinc_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_inc_ref - * - * Purpose: Increment the reference count for an object. - * - * Return: Success: The new reference count - * Failure: -1 - * - *------------------------------------------------------------------------- - */ -int -H5I_inc_ref(hid_t id, hbool_t app_ref) -{ - H5I_id_info_t *id_ptr; /* Pointer to the ID */ - int ret_value = 0; /* Return value */ - - FUNC_ENTER_NOAPI((-1)) - - /* Sanity check */ - HDassert(id >= 0); - - /* General lookup of the ID */ - if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") - - /* Adjust reference counts */ - ++(id_ptr->count); - if (app_ref) - ++(id_ptr->app_count); - - /* Set return value */ - ret_value = (int)(app_ref ? id_ptr->app_count : id_ptr->count); - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_inc_ref() */ - -/*------------------------------------------------------------------------- * Function: H5Iget_ref * * Purpose: Retrieves the number of references outstanding for an ID. @@ -1538,7 +502,7 @@ done: int H5Iget_ref(hid_t id) { - int ret_value; /* Return value */ + int ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) H5TRACE1("Is", "i", id); @@ -1556,38 +520,6 @@ done: } /* end H5Iget_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_get_ref - * - * Purpose: Retrieve the reference count for an object. - * - * Return: Success: The reference count - * Failure: -1 - * - *------------------------------------------------------------------------- - */ -int -H5I_get_ref(hid_t id, hbool_t app_ref) -{ - H5I_id_info_t *id_ptr; /* Pointer to the ID */ - int ret_value = 0; /* Return value */ - - FUNC_ENTER_NOAPI((-1)) - - /* Sanity check */ - HDassert(id >= 0); - - /* General lookup of the ID */ - if (NULL == (id_ptr = H5I__find_id(id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") - - /* Set return value */ - ret_value = (int)(app_ref ? id_ptr->app_count : id_ptr->count); - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_get_ref() */ - -/*------------------------------------------------------------------------- * Function: H5Iinc_type_ref * * Purpose: Increments the number of references outstanding for an ID type. @@ -1600,13 +532,13 @@ done: int H5Iinc_type_ref(H5I_type_t type) { - int ret_value; /* Return value */ + int ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) H5TRACE1("Is", "It", type); /* Check arguments */ - if (type <= 0 || (int)type >= H5I_next_type) + if (type <= 0 || (int)type >= H5I_next_type_g) HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "invalid ID type") if (H5I_IS_LIB_TYPE(type)) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "cannot call public function on library type") @@ -1620,44 +552,11 @@ done: } /* end H5Iinc_ref() */ /*------------------------------------------------------------------------- - * Function: H5I__inc_type_ref - * - * Purpose: Increment the reference count for an ID type. - * - * Return: Success: The new reference count - * Failure: -1 - * - *------------------------------------------------------------------------- - */ -static int -H5I__inc_type_ref(H5I_type_t type) -{ - H5I_id_type_t *type_ptr; /* Pointer to the type */ - int ret_value = -1; /* Return value */ - - FUNC_ENTER_STATIC - - /* Sanity check */ - HDassert(type > 0 && (int)type < H5I_next_type); - - /* Check arguments */ - type_ptr = H5I_id_type_list_g[type]; - if (NULL == type_ptr) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "invalid type") - - /* Set return value */ - ret_value = (int)(++(type_ptr->init_count)); - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__inc_type_ref() */ - -/*------------------------------------------------------------------------- * Function: H5Idec_type_ref * * Purpose: Decrements the reference count on an entire type of IDs. * If the type reference count becomes zero then the type is - * destroyed along with all atoms in that type regardless of + * destroyed along with all IDs in that type regardless of * their reference counts. Destroying IDs involves calling * the free-func for each ID's object and then adding the ID * struct to the ID free list. Public interface to @@ -1694,58 +593,6 @@ done: } /* end H5Idec_type_ref() */ /*------------------------------------------------------------------------- - * Function: H5I_dec_type_ref - * - * Purpose: Decrements the reference count on an entire type of IDs. - * If the type reference count becomes zero then the type is - * destroyed along with all atoms in that type regardless of - * their reference counts. Destroying IDs involves calling - * the free-func for each ID's object and then adding the ID - * struct to the ID free list. - * Returns the number of references to the type on success; a - * return value of 0 means that the type will have to be - * re-initialized before it can be used again (and should probably - * be set to H5I_UNINIT). - * - * Return: Success: Number of references to type - * Failure: -1 - * - *------------------------------------------------------------------------- - */ -int -H5I_dec_type_ref(H5I_type_t type) -{ - H5I_id_type_t *type_ptr; /* Pointer to the ID type */ - herr_t ret_value = 0; /* Return value */ - - FUNC_ENTER_NOAPI((-1)) - - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, (-1), "invalid type number") - - type_ptr = H5I_id_type_list_g[type]; - if (type_ptr == NULL || type_ptr->init_count <= 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "invalid type") - - /* Decrement the number of users of the atomic type. If this is the - * last user of the type then release all atoms from the type and - * free all memory it used. The free function is invoked for each atom - * being freed. - */ - if (1 == type_ptr->init_count) { - H5I__destroy_type(type); - ret_value = 0; - } /* end if */ - else { - --(type_ptr->init_count); - ret_value = (herr_t)type_ptr->init_count; - } /* end else */ - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_dec_type_ref() */ - -/*------------------------------------------------------------------------- * Function: H5Iget_type_ref * * Purpose: Retrieves the number of references outstanding for a type. @@ -1758,13 +605,13 @@ done: int H5Iget_type_ref(H5I_type_t type) { - int ret_value; /* Return value */ + int ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) H5TRACE1("Is", "It", type); /* Check arguments */ - if (type <= 0 || (int)type >= H5I_next_type) + if (type <= 0 || (int)type >= H5I_next_type_g) HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "invalid ID type") if (H5I_IS_LIB_TYPE(type)) HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "cannot call public function on library type") @@ -1778,40 +625,6 @@ done: } /* end H5Iget_ref() */ /*------------------------------------------------------------------------- - * Function: H5I__get_type_ref - * - * Purpose: Retrieve the reference count for an ID type. - * - * Return: Success: The reference count - * - * Failure: -1 - * - *------------------------------------------------------------------------- - */ -static int -H5I__get_type_ref(H5I_type_t type) -{ - H5I_id_type_t *type_ptr; /* Pointer to the type */ - int ret_value = -1; /* Return value */ - - FUNC_ENTER_STATIC - - /* Sanity check */ - HDassert(type >= 0); - - /* Check arguments */ - type_ptr = H5I_id_type_list_g[type]; - if (!type_ptr) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") - - /* Set return value */ - ret_value = (int)type_ptr->init_count; - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__get_type_ref() */ - -/*------------------------------------------------------------------------- * Function: H5Iis_valid * * Purpose: Check if the given id is valid. An id is valid if it is in @@ -1824,16 +637,16 @@ done: htri_t H5Iis_valid(hid_t id) { - H5I_id_info_t *id_ptr; /* ptr to the ID */ + H5I_id_info_t *info = NULL; /* Pointer to the ID info */ htri_t ret_value = TRUE; /* Return value */ FUNC_ENTER_API(FAIL) H5TRACE1("t", "i", id); /* Find the ID */ - if (NULL == (id_ptr = H5I__find_id(id))) + if (NULL == (info = H5I__find_id(id))) ret_value = FALSE; - else if (!id_ptr->app_count) /* Check if the found id is an internal id */ + else if (!info->app_count) /* Check if the found id is an internal id */ ret_value = FALSE; done: @@ -1897,11 +710,11 @@ H5I__search_cb(void *obj, hid_t id, void *_udata) void * H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key) { - H5I_search_ud_t udata; /* Context for iteration */ - void * ret_value; /* Return value */ + H5I_search_ud_t udata; /* Context for iteration */ + void * ret_value = NULL; /* Return value */ FUNC_ENTER_API(NULL) - H5TRACE3("*x", "Itx*x", type, func, key); + H5TRACE3("*x", "ItIS*x", type, func, key); /* Check arguments */ if (H5I_IS_LIB_TYPE(type)) @@ -1943,9 +756,9 @@ done: static int H5I__iterate_pub_cb(void H5_ATTR_UNUSED *obj, hid_t id, void *_udata) { - H5I_iterate_pub_ud_t *udata = (H5I_iterate_pub_ud_t *)_udata; /* User data for callback */ - herr_t cb_ret_val; /* User callback return value */ - int ret_value = H5_ITER_ERROR; /* Callback return value */ + H5I_iterate_pub_ud_t *udata = (H5I_iterate_pub_ud_t *)_udata; /* User data for callback */ + herr_t cb_ret_val = FAIL; /* User callback return value */ + int ret_value = H5_ITER_ERROR; /* Callback return value */ FUNC_ENTER_STATIC_NOERR @@ -1989,11 +802,11 @@ H5I__iterate_pub_cb(void H5_ATTR_UNUSED *obj, hid_t id, void *_udata) herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data) { - H5I_iterate_pub_ud_t int_udata; /* Internal user data */ - herr_t ret_value; /* Return value */ + H5I_iterate_pub_ud_t int_udata; /* Internal user data */ + herr_t ret_value = FAIL; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "Itx*x", type, op, op_data); + H5TRACE3("e", "ItII*x", type, op, op_data); /* Set up udata struct */ int_udata.op = op; @@ -2010,154 +823,48 @@ done: } /* end H5Iiterate() */ /*------------------------------------------------------------------------- - * Function: H5I__iterate_cb - * - * Purpose: Callback routine for H5I_iterate, invokes "user" callback - * function, and then sets return value, based on the result of - * that callback. - * - * Return: Success: H5_ITER_CONT (0) or H5_ITER_STOP (1) - * Failure: H5_ITER_ERROR (-1) - * - *------------------------------------------------------------------------- - */ -static int -H5I__iterate_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) -{ - H5I_id_info_t * item = (H5I_id_info_t *)_item; /* Pointer to the ID node */ - H5I_iterate_ud_t *udata = (H5I_iterate_ud_t *)_udata; /* User data for callback */ - int ret_value = H5_ITER_CONT; /* Callback return value */ - - FUNC_ENTER_STATIC_NOERR - - /* Only invoke the callback function if this ID is visible externally and - * its reference count is positive. - */ - if ((!udata->app_ref) || (item->app_count > 0)) { - H5I_type_t type = udata->obj_type; - void * obj_ptr; - herr_t cb_ret_val; - - /* The stored object pointer might be an H5VL_object_t, in which - * case we'll need to get the wrapped object struct (H5F_t *, etc.). - */ - obj_ptr = H5I__unwrap((void *)item->obj_ptr, type); - - /* Invoke callback function */ - cb_ret_val = - (*udata->user_func)((void *)obj_ptr, item->id, udata->user_udata); /* (Casting away const OK) */ - - /* Set the return value based on the callback's return value */ - if (cb_ret_val > 0) - ret_value = H5_ITER_STOP; /* terminate iteration early */ - else if (cb_ret_val < 0) - ret_value = H5_ITER_ERROR; /* indicate failure (which terminates iteration) */ - } /* end if */ - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__iterate_cb() */ - -/*------------------------------------------------------------------------- - * Function: H5I_iterate - * - * Purpose: Apply function FUNC to each member of type TYPE (with - * non-zero application reference count if app_ref is TRUE). - * Stop if FUNC returns a non zero value (i.e. anything - * other than H5_ITER_CONT). - * - * If FUNC returns a positive value (i.e. H5_ITER_STOP), - * return SUCCEED. - * - * If FUNC returns a negative value (i.e. H5_ITER_ERROR), - * return FAIL. + * Function: H5Iget_file_id * - * The FUNC should take a pointer to the object and the - * udata as arguments and return non-zero to terminate - * siteration, and zero to continue. + * Purpose: Obtains the file ID given an object ID. The user has to + * close this ID. * - * Limitation: Currently there is no way to start the iteration from - * where a previous iteration left off. + * Return: Success: The file ID associated with the object * - * Return: SUCCEED/FAIL + * Failure: H5I_INVALID_HID * *------------------------------------------------------------------------- */ -herr_t -H5I_iterate(H5I_type_t type, H5I_search_func_t func, void *udata, hbool_t app_ref) +hid_t +H5Iget_file_id(hid_t obj_id) { - H5I_id_type_t *type_ptr; /* Pointer to the type */ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_NOAPI(FAIL) - - /* Check arguments */ - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") - type_ptr = H5I_id_type_list_g[type]; - - /* Only iterate through ID list if it is initialized and there are IDs in type */ - if (type_ptr && type_ptr->init_count > 0 && type_ptr->id_count > 0) { - H5I_iterate_ud_t iter_udata; /* User data for iteration callback */ - herr_t iter_status; /* Iteration status */ - - /* Set up iterator user data */ - iter_udata.user_func = func; - iter_udata.user_udata = udata; - iter_udata.app_ref = app_ref; - iter_udata.obj_type = type; - - /* Iterate over IDs */ - if ((iter_status = H5SL_iterate(type_ptr->ids, H5I__iterate_cb, &iter_udata)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADITER, FAIL, "iteration failed") - } /* end if */ + H5I_type_t type; /* ID type */ + hid_t ret_value = H5I_INVALID_HID; /* Return value */ -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_iterate() */ + FUNC_ENTER_API(H5I_INVALID_HID) + H5TRACE1("i", "i", obj_id); -/*------------------------------------------------------------------------- - * Function: H5I__find_id - * - * Purpose: Given an object ID find the info struct that describes the - * object. - * - * Return: Success: A pointer to the object's info struct. - * - * Failure: NULL - * - *------------------------------------------------------------------------- - */ -static H5I_id_info_t * -H5I__find_id(hid_t id) -{ - H5I_type_t type; /*ID's type */ - H5I_id_type_t *type_ptr; /*ptr to the type */ - H5I_id_info_t *ret_value = NULL; /* Return value */ + /* Get object type */ + type = H5I_TYPE(obj_id); - FUNC_ENTER_STATIC_NOERR + /* Call internal function */ + if (H5I_FILE == type || H5I_DATATYPE == type || H5I_GROUP == type || H5I_DATASET == type || + H5I_ATTR == type) { + H5VL_object_t *vol_obj; /* Object of obj_id */ - /* Check arguments */ - type = H5I_TYPE(id); - if (type <= H5I_BADID || (int)type >= H5I_next_type) - HGOTO_DONE(NULL) - type_ptr = H5I_id_type_list_g[type]; - if (!type_ptr || type_ptr->init_count <= 0) - HGOTO_DONE(NULL) - - /* Check for same ID as we have looked up last time */ - if (type_ptr->last_info && type_ptr->last_info->id == id) - ret_value = type_ptr->last_info; - else { - /* Locate the ID node for the ID */ - ret_value = (H5I_id_info_t *)H5SL_search(type_ptr->ids, &id); + /* Get the VOL object */ + if (NULL == (vol_obj = H5VL_vol_object(obj_id))) + HGOTO_ERROR(H5E_ATOM, H5E_BADTYPE, H5I_INVALID_HID, "invalid location identifier") - /* Remember this ID */ - type_ptr->last_info = ret_value; - } /* end else */ + /* Get the file ID */ + if ((ret_value = H5F_get_file_id(vol_obj, type, TRUE)) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, H5I_INVALID_HID, "can't retrieve file ID") + } + else + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, H5I_INVALID_HID, "not an ID of a file object") done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__find_id() */ + FUNC_LEAVE_API(ret_value) +} /* end H5Iget_file_id() */ /*------------------------------------------------------------------------- * Function: H5Iget_name @@ -2168,10 +875,7 @@ done: * * Failure: -1 * - * NOTE: Not safe for arbitrary VOL connectors as it relies on - * private H5G calls. - * - * Comments: Public function + * Notes: * If 'name' is non-NULL then write up to 'size' bytes into that * buffer and always return the length of the entry name. * Otherwise 'size' is ignored and the function does not store the name, @@ -2186,9 +890,9 @@ done: ssize_t H5Iget_name(hid_t id, char *name /*out*/, size_t size) { - H5VL_object_t * vol_obj; /* Object of loc_id */ + H5VL_object_t * vol_obj = NULL; /* Object stored in ID */ H5VL_loc_params_t loc_params; - ssize_t ret_value; /* Return value */ + ssize_t ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) H5TRACE3("Zs", "ixz", id, name, size); @@ -2209,255 +913,3 @@ H5Iget_name(hid_t id, char *name /*out*/, size_t size) done: FUNC_LEAVE_API(ret_value) } /* end H5Iget_name() */ - -/*------------------------------------------------------------------------- - * Function: H5Iget_file_id - * - * Purpose: Obtains the file ID given an object ID. The user has to - * close this ID. - * - * Return: Success: The file ID associated with the object - * - * Failure: H5I_INVALID_HID - * - *------------------------------------------------------------------------- - */ -hid_t -H5Iget_file_id(hid_t obj_id) -{ - H5I_type_t type; /* ID type */ - hid_t ret_value = H5I_INVALID_HID; /* Return value */ - - FUNC_ENTER_API(FAIL) - H5TRACE1("i", "i", obj_id); - - /* Get object type */ - type = H5I_TYPE(obj_id); - - /* Call internal function */ - if (H5I_FILE == type || H5I_DATATYPE == type || H5I_GROUP == type || H5I_DATASET == type || - H5I_ATTR == type) { - H5VL_object_t *vol_obj; /* Object of obj_id */ - - /* Get the VOL object */ - if (NULL == (vol_obj = H5VL_vol_object(obj_id))) - HGOTO_ERROR(H5E_ATOM, H5E_BADTYPE, H5I_INVALID_HID, "invalid location identifier") - - /* Get the file ID */ - if ((ret_value = H5F_get_file_id(vol_obj, type, TRUE)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_CANTGET, H5I_INVALID_HID, "can't retrieve file ID") - } /* end if */ - else - HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, H5I_INVALID_HID, "not an ID of a file object") - -done: - FUNC_LEAVE_API(ret_value) -} /* end H5Iget_file_id() */ - -/*------------------------------------------------------------------------- - * Function: H5I__find_id_cb - * - * Purpose: Callback for searching for an ID with a specific pointer - * - * Return: Success: H5_ITER_CONT (0) or H5_ITER_STOP (1) - * Failure: H5_ITER_ERROR (-1) - * - *------------------------------------------------------------------------- - */ -static int -H5I__find_id_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) -{ - H5I_id_info_t * item = (H5I_id_info_t *)_item; /* Pointer to the ID node */ - H5I_get_id_ud_t *udata = (H5I_get_id_ud_t *)_udata; /* Pointer to user data */ - H5I_type_t type = udata->obj_type; - const void * obj_ptr = NULL; - int ret_value = H5_ITER_CONT; /* Return value */ - - FUNC_ENTER_STATIC_NOERR - - /* Sanity check */ - HDassert(item); - HDassert(udata); - - /* Get a pointer to the VOL connector's data */ - obj_ptr = H5I__unwrap(item->obj_ptr, type); - - /* Check for a match */ - if (obj_ptr == udata->object) { - udata->ret_id = item->id; - ret_value = H5_ITER_STOP; - } /* end if */ - - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I__find_id_cb() */ - -/*------------------------------------------------------------------------- - * Function: H5I_find_id - * - * Purpose: Return the ID of an object by searching through the ID list - * for the type. - * - * Return: SUCCEED/FAIL - * (id will be set to H5I_INVALID_HID on errors or not found) - * - *------------------------------------------------------------------------- - */ -herr_t -H5I_find_id(const void *object, H5I_type_t type, hid_t *id) -{ - H5I_id_type_t *type_ptr; /* Pointer to the type */ - herr_t ret_value = SUCCEED; /* Return value */ - - FUNC_ENTER_NOAPI(FAIL) - - HDassert(id); - - *id = H5I_INVALID_HID; - - type_ptr = H5I_id_type_list_g[type]; - if (!type_ptr || type_ptr->init_count <= 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") - - /* Only iterate through ID list if it is initialized and there are IDs in type */ - if (type_ptr->init_count > 0 && type_ptr->id_count > 0) { - H5I_get_id_ud_t udata; /* User data */ - herr_t iter_status; /* Iteration status */ - - /* Set up iterator user data */ - udata.object = object; - udata.obj_type = type; - udata.ret_id = H5I_INVALID_HID; - - /* Iterate over IDs for the ID type */ - if ((iter_status = H5SL_iterate(type_ptr->ids, H5I__find_id_cb, &udata)) < 0) - HGOTO_ERROR(H5E_ATOM, H5E_BADITER, FAIL, "iteration failed") - - *id = udata.ret_id; - } /* end if */ - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5I_find_id() */ - -/*------------------------------------------------------------------------- - * Function: H5I__id_dump_cb - * - * Purpose: Dump the contents of an ID to stderr for debugging. - * - * Return: H5_ITER_CONT (always) - * - *------------------------------------------------------------------------- - */ -static int -H5I__id_dump_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) -{ - H5I_id_info_t *item = (H5I_id_info_t *)_item; /* Pointer to the ID node */ - H5I_type_t type = *(H5I_type_t *)_udata; /* User data */ - H5G_name_t * path = NULL; /* Path to file object */ - const void * obj_ptr = NULL; /* Pointer to VOL connector object */ - - FUNC_ENTER_STATIC_NOERR - - HDfprintf(stderr, " id = %" PRIdHID "\n", item->id); - HDfprintf(stderr, " count = %u\n", item->count); - HDfprintf(stderr, " obj = 0x%8p\n", item->obj_ptr); - - /* Get the group location, so we get get the name */ - switch (type) { - case H5I_GROUP: { - const H5VL_object_t *vol_obj = (const H5VL_object_t *)item->obj_ptr; - - obj_ptr = H5VL_object_data(vol_obj); - if (H5_VOL_NATIVE == vol_obj->connector->cls->value) - path = H5G_nameof((const H5G_t *)obj_ptr); - break; - } - - case H5I_DATASET: { - const H5VL_object_t *vol_obj = (const H5VL_object_t *)item->obj_ptr; - - obj_ptr = H5VL_object_data(vol_obj); - if (H5_VOL_NATIVE == vol_obj->connector->cls->value) - path = H5D_nameof((const H5D_t *)obj_ptr); - break; - } - - case H5I_DATATYPE: { - const H5T_t *dt = (const H5T_t *)item->obj_ptr; - - obj_ptr = (void *)H5T_get_actual_type((H5T_t *)dt); /* Casting away const OK - QAK */ - path = H5T_nameof((const H5T_t *)obj_ptr); - break; - } - - /* TODO: Maps will have to be added when they are supported in the - * native VOL connector. - */ - case H5I_MAP: - - case H5I_UNINIT: - case H5I_BADID: - case H5I_FILE: - case H5I_DATASPACE: - case H5I_ATTR: - case H5I_VFL: - case H5I_VOL: - case H5I_GENPROP_CLS: - case H5I_GENPROP_LST: - case H5I_ERROR_CLASS: - case H5I_ERROR_MSG: - case H5I_ERROR_STACK: - case H5I_SPACE_SEL_ITER: - case H5I_NTYPES: - default: - break; /* Other types of IDs are not stored in files */ - } - - if (path) { - if (path->user_path_r) - HDfprintf(stderr, " user_path = %s\n", H5RS_get_str(path->user_path_r)); - if (path->full_path_r) - HDfprintf(stderr, " full_path = %s\n", H5RS_get_str(path->full_path_r)); - } - - FUNC_LEAVE_NOAPI(H5_ITER_CONT) -} /* end H5I__id_dump_cb() */ - -/*------------------------------------------------------------------------- - * Function: H5I_dump_ids_for_type - * - * Purpose: Dump the contents of a type to stderr for debugging. - * - * Return: SUCCEED/FAIL - * - *------------------------------------------------------------------------- - */ -herr_t -H5I_dump_ids_for_type(H5I_type_t type) -{ - H5I_id_type_t *type_ptr = NULL; - - FUNC_ENTER_NOAPI_NOERR - - HDfprintf(stderr, "Dumping ID type %d\n", (int)type); - type_ptr = H5I_id_type_list_g[type]; - - if (type_ptr) { - - /* Header */ - HDfprintf(stderr, " init_count = %u\n", type_ptr->init_count); - HDfprintf(stderr, " reserved = %u\n", type_ptr->cls->reserved); - HDfprintf(stderr, " id_count = %llu\n", (unsigned long long)type_ptr->id_count); - HDfprintf(stderr, " nextid = %llu\n", (unsigned long long)type_ptr->nextid); - - /* List */ - if (type_ptr->id_count > 0) { - HDfprintf(stderr, " List:\n"); - H5SL_iterate(type_ptr->ids, H5I__id_dump_cb, &type); - } - } - else - HDfprintf(stderr, "Global type info/tracking pointer for that type is NULL\n"); - - FUNC_LEAVE_NOAPI(SUCCEED) -} /* end H5I_dump_ids_for_type() */ diff --git a/src/H5Idbg.c b/src/H5Idbg.c new file mode 100644 index 0000000..80be9d0 --- /dev/null +++ b/src/H5Idbg.c @@ -0,0 +1,191 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * Copyright by the Board of Trustees of the University of Illinois. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * H5Idbg.c - Debugging routines for handling IDs + */ + +/****************/ +/* Module Setup */ +/****************/ + +#include "H5Imodule.h" /* This source code file is part of the H5I module */ + +/***********/ +/* Headers */ +/***********/ +#include "H5private.h" /* Generic Functions */ +#include "H5Dprivate.h" /* Datasets */ +#include "H5Eprivate.h" /* Error handling */ +#include "H5Gprivate.h" /* Groups */ +#include "H5Ipkg.h" /* IDs */ +#include "H5RSprivate.h" /* Reference-counted strings */ +#include "H5SLprivate.h" /* Skip Lists */ +#include "H5Tprivate.h" /* Datatypes */ +#include "H5VLprivate.h" /* Virtual Object Layer */ + +/****************/ +/* Local Macros */ +/****************/ + +/******************/ +/* Local Typedefs */ +/******************/ + +/********************/ +/* Package Typedefs */ +/********************/ + +/********************/ +/* Local Prototypes */ +/********************/ + +static int H5I__id_dump_cb(void *_item, void *_key, void *_udata); + +/*********************/ +/* Package Variables */ +/*********************/ + +/*****************************/ +/* Library Private Variables */ +/*****************************/ + +/*******************/ +/* Local Variables */ +/*******************/ + +/*------------------------------------------------------------------------- + * Function: H5I__id_dump_cb + * + * Purpose: Dump the contents of an ID to stderr for debugging. + * + * Return: H5_ITER_CONT (always) + * + *------------------------------------------------------------------------- + */ +static int +H5I__id_dump_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) +{ + H5I_id_info_t *info = (H5I_id_info_t *)_item; /* Pointer to the ID node */ + H5I_type_t type = *(H5I_type_t *)_udata; /* User data */ + H5G_name_t * path = NULL; /* Path to file object */ + const void * object = NULL; /* Pointer to VOL connector object */ + + FUNC_ENTER_STATIC_NOERR + + HDfprintf(stderr, " id = %" PRIdHID "\n", info->id); + HDfprintf(stderr, " count = %u\n", info->count); + HDfprintf(stderr, " obj = 0x%8p\n", info->object); + + /* Get the group location, so we get get the name */ + switch (type) { + case H5I_GROUP: { + const H5VL_object_t *vol_obj = (const H5VL_object_t *)info->object; + + object = H5VL_object_data(vol_obj); + if (H5_VOL_NATIVE == vol_obj->connector->cls->value) + path = H5G_nameof((const H5G_t *)object); + break; + } + + case H5I_DATASET: { + const H5VL_object_t *vol_obj = (const H5VL_object_t *)info->object; + + object = H5VL_object_data(vol_obj); + if (H5_VOL_NATIVE == vol_obj->connector->cls->value) + path = H5D_nameof((const H5D_t *)object); + break; + } + + case H5I_DATATYPE: { + const H5T_t *dt = (const H5T_t *)info->object; + + H5_GCC_DIAG_OFF("cast-qual") + object = (void *)H5T_get_actual_type((H5T_t *)dt); /* Casting away const OK - QAK */ + H5_GCC_DIAG_ON("cast-qual") + + path = H5T_nameof((const H5T_t *)object); + break; + } + + /* TODO: Maps will have to be added when they are supported in the + * native VOL connector. + */ + case H5I_MAP: + + case H5I_UNINIT: + case H5I_BADID: + case H5I_FILE: + case H5I_DATASPACE: + case H5I_ATTR: + case H5I_VFL: + case H5I_VOL: + case H5I_GENPROP_CLS: + case H5I_GENPROP_LST: + case H5I_ERROR_CLASS: + case H5I_ERROR_MSG: + case H5I_ERROR_STACK: + case H5I_SPACE_SEL_ITER: + case H5I_NTYPES: + default: + break; /* Other types of IDs are not stored in files */ + } + + if (path) { + if (path->user_path_r) + HDfprintf(stderr, " user_path = %s\n", H5RS_get_str(path->user_path_r)); + if (path->full_path_r) + HDfprintf(stderr, " full_path = %s\n", H5RS_get_str(path->full_path_r)); + } + + FUNC_LEAVE_NOAPI(H5_ITER_CONT) +} /* end H5I__id_dump_cb() */ + +/*------------------------------------------------------------------------- + * Function: H5I_dump_ids_for_type + * + * Purpose: Dump the contents of a type to stderr for debugging. + * + * Return: SUCCEED/FAIL + * + *------------------------------------------------------------------------- + */ +herr_t +H5I_dump_ids_for_type(H5I_type_t type) +{ + H5I_type_info_t *type_info = NULL; + + FUNC_ENTER_NOAPI_NOERR + + HDfprintf(stderr, "Dumping ID type %d\n", (int)type); + type_info = H5I_type_info_array_g[type]; + + if (type_info) { + + /* Header */ + HDfprintf(stderr, " init_count = %u\n", type_info->init_count); + HDfprintf(stderr, " reserved = %u\n", type_info->cls->reserved); + HDfprintf(stderr, " id_count = %llu\n", (unsigned long long)type_info->id_count); + HDfprintf(stderr, " nextid = %llu\n", (unsigned long long)type_info->nextid); + + /* List */ + if (type_info->id_count > 0) { + HDfprintf(stderr, " List:\n"); + H5SL_iterate(type_info->ids, H5I__id_dump_cb, &type); + } + } + else + HDfprintf(stderr, "Global type info/tracking pointer for that type is NULL\n"); + + FUNC_LEAVE_NOAPI(SUCCEED) +} /* end H5I_dump_ids_for_type() */ diff --git a/src/H5Iint.c b/src/H5Iint.c new file mode 100644 index 0000000..2e1145d --- /dev/null +++ b/src/H5Iint.c @@ -0,0 +1,1472 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * Copyright by the Board of Trustees of the University of Illinois. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * H5Iint.c - Private routines for handling IDs + */ + +/****************/ +/* Module Setup */ +/****************/ + +#include "H5Imodule.h" /* This source code file is part of the H5I module */ + +/***********/ +/* Headers */ +/***********/ +#include "H5private.h" /* Generic Functions */ +#include "H5Eprivate.h" /* Error handling */ +#include "H5FLprivate.h" /* Free Lists */ +#include "H5Ipkg.h" /* IDs */ +#include "H5MMprivate.h" /* Memory management */ +#include "H5SLprivate.h" /* Skip Lists */ +#include "H5Tprivate.h" /* Datatypes */ +#include "H5VLprivate.h" /* Virtual Object Layer */ + +/****************/ +/* Local Macros */ +/****************/ + +/* Combine a Type number and an ID index into an ID */ +#define H5I_MAKE(g, i) ((((hid_t)(g)&TYPE_MASK) << ID_BITS) | ((hid_t)(i)&ID_MASK)) + +/******************/ +/* Local Typedefs */ +/******************/ + +/* User data for iterator callback for retrieving an ID corresponding to an object pointer */ +typedef struct { + const void *object; /* object pointer to search for */ + H5I_type_t obj_type; /* type of object we are searching for */ + hid_t ret_id; /* ID returned */ +} H5I_get_id_ud_t; + +/* User data for iterator callback for ID iteration */ +typedef struct { + H5I_search_func_t user_func; /* 'User' function to invoke */ + void * user_udata; /* User data to pass to 'user' function */ + hbool_t app_ref; /* Whether this is an appl. ref. call */ + H5I_type_t obj_type; /* Type of object we are iterating over */ +} H5I_iterate_ud_t; + +/* User data for H5I__clear_type_cb */ +typedef struct { + H5I_type_info_t *type_info; /* Pointer to the type's info to be cleared */ + hbool_t force; /* Whether to always remove the ID */ + hbool_t app_ref; /* Whether this is an appl. ref. call */ +} H5I_clear_type_ud_t; + +/********************/ +/* Package Typedefs */ +/********************/ + +/********************/ +/* Local Prototypes */ +/********************/ + +static void * H5I__unwrap(void *object, H5I_type_t type); +static htri_t H5I__clear_type_cb(void *_id, void *key, void *udata); +static void * H5I__remove_common(H5I_type_info_t *type_info, hid_t id); +static int H5I__find_id_cb(void *_item, void *_key, void *_udata); + +/*********************/ +/* Package Variables */ +/*********************/ + +/* Package initialization variable */ +hbool_t H5_PKG_INIT_VAR = FALSE; + +/* Declared extern in H5Ipkg.h and documented there */ +H5I_type_info_t *H5I_type_info_array_g[H5I_MAX_NUM_TYPES]; +int H5I_next_type_g = (int)H5I_NTYPES; + +/* Declare a free list to manage the H5I_id_info_t struct */ +H5FL_DEFINE_STATIC(H5I_id_info_t); + +/*****************************/ +/* Library Private Variables */ +/*****************************/ + +/*******************/ +/* Local Variables */ +/*******************/ + +/*------------------------------------------------------------------------- + * Function: H5I_term_package + * + * Purpose: Terminate the H5I interface: release all memory, reset all + * global variables to initial values. This only happens if all + * types have been destroyed from other interfaces. + * + * Return: Success: Positive if any action was taken that might + * affect some other interface; zero otherwise. + * + * Failure: Negative + * + *------------------------------------------------------------------------- + */ +int +H5I_term_package(void) +{ + int in_use = 0; /* Number of ID types still in use */ + + FUNC_ENTER_NOAPI_NOINIT_NOERR + + if (H5_PKG_INIT_VAR) { + H5I_type_info_t *type_info = NULL; /* Pointer to ID type */ + int i; + + /* Count the number of types still in use */ + for (i = 0; i < H5I_next_type_g; i++) + if ((type_info = H5I_type_info_array_g[i]) && type_info->ids) + in_use++; + + /* If no types are still being used then clean up */ + if (0 == in_use) { + for (i = 0; i < H5I_next_type_g; i++) { + type_info = H5I_type_info_array_g[i]; + if (type_info) { + HDassert(NULL == type_info->ids); + type_info = H5MM_xfree(type_info); + H5I_type_info_array_g[i] = NULL; + in_use++; + } + } + + /* Mark interface closed */ + if (0 == in_use) + H5_PKG_INIT_VAR = FALSE; + } + } + + FUNC_LEAVE_NOAPI(in_use) +} /* end H5I_term_package() */ + +/*------------------------------------------------------------------------- + * Function: H5I_register_type + * + * Purpose: Creates a new type of ID's to give out. + * The class is initialized or its reference count is incremented + * (if it is already initialized). + * + * Return: SUCCEED/FAIL + * + *------------------------------------------------------------------------- + */ +herr_t +H5I_register_type(const H5I_class_t *cls) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the ID type*/ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + /* Sanity check */ + HDassert(cls); + HDassert(cls->type > 0 && (int)cls->type < H5I_MAX_NUM_TYPES); + + /* Initialize the type */ + if (NULL == H5I_type_info_array_g[cls->type]) { + /* Allocate the type information for new type */ + if (NULL == (type_info = (H5I_type_info_t *)H5MM_calloc(sizeof(H5I_type_info_t)))) + HGOTO_ERROR(H5E_ATOM, H5E_CANTALLOC, FAIL, "ID type allocation failed") + H5I_type_info_array_g[cls->type] = type_info; + } + else { + /* Get the pointer to the existing type */ + type_info = H5I_type_info_array_g[cls->type]; + } + + /* Initialize the ID type structure for new types */ + if (type_info->init_count == 0) { + type_info->cls = cls; + type_info->id_count = 0; + type_info->nextid = cls->reserved; + type_info->last_id_info = NULL; + if (NULL == (type_info->ids = H5SL_create(H5SL_TYPE_HID, NULL))) + HGOTO_ERROR(H5E_ATOM, H5E_CANTCREATE, FAIL, "skip list creation failed") + } + + /* Increment the count of the times this type has been initialized */ + type_info->init_count++; + +done: + /* Clean up on error */ + if (ret_value < 0) { + if (type_info) { + if (type_info->ids) + H5SL_close(type_info->ids); + H5MM_free(type_info); + } + } + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_register_type() */ + +/*------------------------------------------------------------------------- + * Function: H5I_nmembers + * + * Purpose: Returns the number of members in a type. + * + * Return: Success: Number of members; zero if the type is empty + * or has been deleted. + * + * Failure: Negative + * + * Programmer: Robb Matzke + * Wednesday, March 24, 1999 + * + *------------------------------------------------------------------------- + */ +int64_t +H5I_nmembers(H5I_type_t type) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the ID type */ + int64_t ret_value = 0; /* Return value */ + + FUNC_ENTER_NOAPI((-1)) + + /* Validate parameter */ + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") + if (NULL == (type_info = H5I_type_info_array_g[type]) || type_info->init_count <= 0) + HGOTO_DONE(0); + + /* Set return value */ + H5_CHECKED_ASSIGN(ret_value, int64_t, type_info->id_count, uint64_t); + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_nmembers() */ + +/*------------------------------------------------------------------------- + * Function: H5I__unwrap + * + * Purpose: Unwraps the object pointer for the 'item' that corresponds + * to an ID. + * + * Return: Pointer to the unwrapped pointer (can't fail) + * + * Programmer: Quincey Koziol + * Friday, October 19, 2018 + * + *------------------------------------------------------------------------- + */ +static void * +H5I__unwrap(void *object, H5I_type_t type) +{ + void *ret_value = NULL; /* Return value */ + + FUNC_ENTER_STATIC_NOERR + + /* Sanity checks */ + HDassert(object); + + /* The stored object pointer might be an H5VL_object_t, in which + * case we'll need to get the wrapped object struct (H5F_t *, etc.). + */ + if (H5I_FILE == type || H5I_GROUP == type || H5I_DATASET == type || H5I_ATTR == type) { + const H5VL_object_t *vol_obj; + + vol_obj = (const H5VL_object_t *)object; + ret_value = H5VL_object_data(vol_obj); + } + else if (H5I_DATATYPE == type) { + H5T_t *dt = (H5T_t *)object; + + ret_value = (void *)H5T_get_actual_type(dt); + } + else + ret_value = object; + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__unwrap() */ + +/*------------------------------------------------------------------------- + * Function: H5I_clear_type + * + * Purpose: Removes all objects from the type, calling the free + * function for each object regardless of the reference count. + * + * Return: SUCCEED/FAIL + * + * Programmer: Robb Matzke + * Wednesday, March 24, 1999 + * + *------------------------------------------------------------------------- + */ +herr_t +H5I_clear_type(H5I_type_t type, hbool_t force, hbool_t app_ref) +{ + H5I_clear_type_ud_t udata; /* udata struct for callback */ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + /* Validate parameters */ + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") + + udata.type_info = H5I_type_info_array_g[type]; + if (udata.type_info == NULL || udata.type_info->init_count <= 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") + + /* Finish constructing udata */ + udata.force = force; + udata.app_ref = app_ref; + + /* Attempt to free all ids in the type */ + if (H5SL_try_free_safe(udata.type_info->ids, H5I__clear_type_cb, &udata) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, FAIL, "can't free ids in type") + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_clear_type() */ + +/*------------------------------------------------------------------------- + * Function: H5I__clear_type_cb + * + * Purpose: Attempts to free the specified ID, calling the free + * function for the object. + * + * Return: TRUE/FALSE/FAIL + * + * Programmer: Neil Fortner + * Friday, July 10, 2015 + * + *------------------------------------------------------------------------- + */ +static htri_t +H5I__clear_type_cb(void *_info, void H5_ATTR_UNUSED *key, void *_udata) +{ + H5I_id_info_t * info = (H5I_id_info_t *)_info; /* Current ID info being worked with */ + H5I_clear_type_ud_t *udata = (H5I_clear_type_ud_t *)_udata; /* udata struct */ + htri_t ret_value = FALSE; /* Return value */ + + FUNC_ENTER_STATIC_NOERR + + /* Sanity checks */ + HDassert(info); + HDassert(udata); + HDassert(udata->type_info); + + /* Do nothing to the object if the reference count is larger than + * one and forcing is off. + */ + if (udata->force || (info->count - (!udata->app_ref * info->app_count)) <= 1) { + /* Check for a 'free' function and call it, if it exists */ + H5_GCC_DIAG_OFF("cast-qual") + if (udata->type_info->cls->free_func && + (udata->type_info->cls->free_func)((void *)info->object) < 0) { /* (Casting away const OK -QAK) */ + if (udata->force) { +#ifdef H5I_DEBUG + if (H5DEBUG(I)) { + HDfprintf(H5DEBUG(I), + "H5I: free type=%d obj=0x%08lx " + "failure ignored\n", + (int)udata->type_info->cls->type, (unsigned long)(info->object)); + } +#endif /* H5I_DEBUG */ + + /* Indicate node should be removed from list */ + ret_value = TRUE; + } + } + else { + /* Indicate node should be removed from list */ + ret_value = TRUE; + } + H5_GCC_DIAG_ON("cast-qual") + + /* Remove ID if requested */ + if (ret_value) { + /* Free ID info */ + info = H5FL_FREE(H5I_id_info_t, info); + + /* Decrement the number of IDs in the type */ + udata->type_info->id_count--; + } + } + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__clear_type_cb() */ + +/*------------------------------------------------------------------------- + * Function: H5I__destroy_type + * + * Purpose: Destroys a type along with all IDs in that type + * regardless of their reference counts. Destroying IDs + * involves calling the free-func for each ID's object and + * then adding the ID struct to the ID free list. + * + * Return: SUCCEED/FAIL + * + * Programmer: Nathaniel Furrer + * James Laird + * + *------------------------------------------------------------------------- + */ +herr_t +H5I__destroy_type(H5I_type_t type) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the ID type */ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_PACKAGE + + /* Validate parameter */ + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") + + type_info = H5I_type_info_array_g[type]; + if (type_info == NULL || type_info->init_count <= 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") + + /* Close/clear/destroy all IDs for this type */ + H5E_BEGIN_TRY { + H5I_clear_type(type, TRUE, FALSE); + } H5E_END_TRY /* don't care about errors */ + + /* Check if we should release the ID class */ + if (type_info->cls->flags & H5I_CLASS_IS_APPLICATION) + type_info->cls = H5MM_xfree_const(type_info->cls); + + if (H5SL_close(type_info->ids) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_CANTCLOSEOBJ, FAIL, "can't close skip list") + type_info->ids = NULL; + + type_info = H5MM_xfree(type_info); + + H5I_type_info_array_g[type] = NULL; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__destroy_type() */ + +/*------------------------------------------------------------------------- + * Function: H5I_register + * + * Purpose: Registers an OBJECT in a TYPE and returns an ID for it. + * This routine does _not_ check for unique-ness of the objects, + * if you register an object twice, you will get two different + * IDs for it. This routine does make certain that each ID in a + * type is unique. IDs are created by getting a unique number + * for the type the ID is in and incorporating the type into + * the ID which is returned to the user. + * + * Return: Success: New object ID + * Failure: H5I_INVALID_HID + * + *------------------------------------------------------------------------- + */ +hid_t +H5I_register(H5I_type_t type, const void *object, hbool_t app_ref) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the type */ + H5I_id_info_t * info = NULL; /* Pointer to the new ID information */ + hid_t new_id = H5I_INVALID_HID; /* New ID */ + hid_t ret_value = H5I_INVALID_HID; /* Return value */ + + FUNC_ENTER_NOAPI(H5I_INVALID_HID) + + /* Check arguments */ + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, H5I_INVALID_HID, "invalid type number") + type_info = H5I_type_info_array_g[type]; + if ((NULL == type_info) || (type_info->init_count <= 0)) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, H5I_INVALID_HID, "invalid type") + if (NULL == (info = H5FL_MALLOC(H5I_id_info_t))) + HGOTO_ERROR(H5E_ATOM, H5E_NOSPACE, H5I_INVALID_HID, "memory allocation failed") + + /* Create the struct & its ID */ + new_id = H5I_MAKE(type, type_info->nextid); + info->id = new_id; + info->count = 1; /* initial reference count */ + info->app_count = !!app_ref; + info->object = object; + + /* Insert into the type */ + if (H5SL_insert(type_info->ids, info, &info->id) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_CANTINSERT, H5I_INVALID_HID, "can't insert ID node into skip list") + type_info->id_count++; + type_info->nextid++; + + /* Sanity check for the 'nextid' getting too large and wrapping around */ + HDassert(type_info->nextid <= ID_MASK); + + /* Set the most recent ID to this object */ + type_info->last_id_info = info; + + /* Set return value */ + ret_value = new_id; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_register() */ + +/*------------------------------------------------------------------------- + * Function: H5I_register_using_existing_id + * + * Purpose: Registers an OBJECT in a TYPE with the supplied ID for it. + * This routine will check to ensure the supplied ID is not already + * in use, and ensure that it is a valid ID for the given type, + * but will NOT check to ensure the OBJECT is not already + * registered (thus, it is possible to register one object under + * multiple IDs). + * + * NOTE: Intended for use in refresh calls, where we have to close + * and re-open the underlying data, then hook the object back + * up to the original ID. + * + * Return: SUCCEED/FAIL + * + *------------------------------------------------------------------------- + */ +herr_t +H5I_register_using_existing_id(H5I_type_t type, void *object, hbool_t app_ref, hid_t existing_id) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the type */ + H5I_id_info_t * info = NULL; /* Pointer to the new ID information */ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + /* Check arguments */ + HDassert(object); + + /* Make sure ID is not already in use */ + if (NULL != (info = H5I__find_id(existing_id))) + HGOTO_ERROR(H5E_ATOM, H5E_BADRANGE, FAIL, "ID already in use") + + /* Make sure type number is valid */ + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") + + /* Get type pointer from list of types */ + type_info = H5I_type_info_array_g[type]; + + if (NULL == type_info || type_info->init_count <= 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") + + /* Make sure requested ID belongs to object's type */ + if (H5I_TYPE(existing_id) != type) + HGOTO_ERROR(H5E_ATOM, H5E_BADRANGE, FAIL, "invalid type for provided ID") + + /* Allocate new structure to house this ID */ + if (NULL == (info = H5FL_MALLOC(H5I_id_info_t))) + HGOTO_ERROR(H5E_ATOM, H5E_NOSPACE, FAIL, "memory allocation failed") + + /* Create the struct & insert requested ID */ + info->id = existing_id; + info->count = 1; /* initial reference count*/ + info->app_count = !!app_ref; + info->object = object; + + /* Insert into the type */ + if (H5SL_insert(type_info->ids, info, &info->id) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_CANTINSERT, FAIL, "can't insert ID node into skip list") + type_info->id_count++; + + /* Set the most recent ID to this object */ + type_info->last_id_info = info; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_register_using_existing_id() */ + +/*------------------------------------------------------------------------- + * Function: H5I_subst + * + * Purpose: Substitute a new object pointer for the specified ID. + * + * Return: Success: Non-NULL previous object pointer associated + * with the specified ID. + * Failure: NULL + * + * Programmer: Quincey Koziol + * Saturday, February 27, 2010 + * + *------------------------------------------------------------------------- + */ +void * +H5I_subst(hid_t id, const void *new_object) +{ + H5I_id_info_t *info = NULL; /* Pointer to the ID's info */ + void * ret_value = NULL; /* Return value */ + + FUNC_ENTER_NOAPI(NULL) + + /* General lookup of the ID */ + if (NULL == (info = H5I__find_id(id))) + HGOTO_ERROR(H5E_ATOM, H5E_NOTFOUND, NULL, "can't get ID ref count") + + /* Get the old object pointer to return */ + H5_GCC_DIAG_OFF("cast-qual") + ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ + H5_GCC_DIAG_ON("cast-qual") + + /* Set the new object pointer for the ID */ + info->object = new_object; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_subst() */ + +/*------------------------------------------------------------------------- + * Function: H5I_object + * + * Purpose: Find an object pointer for the specified ID. + * + * Return: Success: Non-NULL object pointer associated with the + * specified ID + * + * Failure: NULL + * + *------------------------------------------------------------------------- + */ +void * +H5I_object(hid_t id) +{ + H5I_id_info_t *info = NULL; /* Pointer to the ID info */ + void * ret_value = NULL; /* Return value */ + + FUNC_ENTER_NOAPI_NOERR + + /* General lookup of the ID */ + if (NULL != (info = H5I__find_id(id))) { + /* Get the object pointer to return */ + H5_GCC_DIAG_OFF("cast-qual") + ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ + H5_GCC_DIAG_ON("cast-qual") + } + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_object() */ + +/*------------------------------------------------------------------------- + * Function: H5I_object_verify + * + * Purpose: Find an object pointer for the specified ID, verifying that + * its in a particular type. + * + * Return: Success: Non-NULL object pointer associated with the + * specified ID. + * Failure: NULL + * + * Programmer: Quincey Koziol + * Wednesday, July 31, 2002 + * + *------------------------------------------------------------------------- + */ +void * +H5I_object_verify(hid_t id, H5I_type_t type) +{ + H5I_id_info_t *info = NULL; /* Pointer to the ID info */ + void * ret_value = NULL; /* Return value */ + + FUNC_ENTER_NOAPI_NOERR + + HDassert(type >= 1 && (int)type < H5I_next_type_g); + + /* Verify that the type of the ID is correct & lookup the ID */ + if (type == H5I_TYPE(id) && NULL != (info = H5I__find_id(id))) { + /* Get the object pointer to return */ + H5_GCC_DIAG_OFF("cast-qual") + ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ + H5_GCC_DIAG_ON("cast-qual") + } + + FUNC_LEAVE_NOAPI(ret_value) +} /* H5I_object_verify() */ + +/*------------------------------------------------------------------------- + * Function: H5I_get_type + * + * Purpose: Given an object ID return the type to which it + * belongs. The ID need not be the ID of an object which + * currently exists because the type number is encoded + * in the object ID. + * + * Return: Success: A positive integer (corresponding to an H5I_type_t + * enum value for library ID types, but not for user + * ID types). + * Failure: H5I_BADID + * + * Programmer: Robb Matzke + * Friday, February 19, 1999 + * + *------------------------------------------------------------------------- + */ +H5I_type_t +H5I_get_type(hid_t id) +{ + H5I_type_t ret_value = H5I_BADID; /* Return value */ + + FUNC_ENTER_NOAPI_NOERR + + if (id > 0) + ret_value = H5I_TYPE(id); + + HDassert(ret_value >= H5I_BADID && (int)ret_value < H5I_next_type_g); + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_get_type() */ + +/*------------------------------------------------------------------------- + * Function: H5I_is_file_object + * + * Purpose: Convenience function to determine if an ID represents + * a file object. + * + * In H5O calls, you can't use object_verify to ensure + * the ID was of the correct class since there's no + * H5I_OBJECT ID class. + * + * Return: Success: TRUE/FALSE + * Failure: FAIL + * + *------------------------------------------------------------------------- + */ +htri_t +H5I_is_file_object(hid_t id) +{ + H5I_type_t type = H5I_get_type(id); + htri_t ret_value = FAIL; + + FUNC_ENTER_NOAPI(FAIL); + + /* Fail if the ID type is out of range */ + if (type < 1 || type >= H5I_NTYPES) + HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "ID type out of range"); + + /* Return TRUE if the ID is a file object (dataset, group, map, or committed + * datatype), FALSE otherwise. + */ + if (H5I_DATASET == type || H5I_GROUP == type || H5I_MAP == type) + ret_value = TRUE; + else if (H5I_DATATYPE == type) { + + H5T_t *dt = NULL; + + if (NULL == (dt = (H5T_t *)H5I_object(id))) + HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "unable to get underlying datatype struct"); + + ret_value = H5T_is_named(dt); + } + else + ret_value = FALSE; + +done: + FUNC_LEAVE_NOAPI(ret_value); +} /* H5I_is_file_object() */ + +/*------------------------------------------------------------------------- + * Function: H5I__remove_verify + * + * Purpose: Removes the specified ID from its type, first checking that + * the ID's type is the same as the ID type supplied as an argument + * + * Return: Success: A pointer to the object that was removed, the + * same pointer which would have been found by + * calling H5I_object(). + * Failure: NULL + * + * Programmer: James Laird + * Nat Furrer + * + *------------------------------------------------------------------------- + */ +void * +H5I__remove_verify(hid_t id, H5I_type_t type) +{ + void *ret_value = NULL; /*return value */ + + FUNC_ENTER_STATIC_NOERR + + /* Argument checking will be performed by H5I_remove() */ + + /* Verify that the type of the ID is correct */ + if (type == H5I_TYPE(id)) + ret_value = H5I_remove(id); + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__remove_verify() */ + +/*------------------------------------------------------------------------- + * Function: H5I__remove_common + * + * Purpose: Common code to remove a specified ID from its type. + * + * Return: Success: A pointer to the object that was removed, the + * same pointer which would have been found by + * calling H5I_object(). + * Failure: NULL + * + * Programmer: Quincey Koziol + * October 3, 2013 + * + *------------------------------------------------------------------------- + */ +static void * +H5I__remove_common(H5I_type_info_t *type_info, hid_t id) +{ + H5I_id_info_t *info = NULL; /* Pointer to the current ID */ + void * ret_value = NULL; /* Return value */ + + FUNC_ENTER_STATIC + + /* Sanity check */ + HDassert(type_info); + + /* Get the ID node for the ID */ + if (NULL == (info = (H5I_id_info_t *)H5SL_remove(type_info->ids, &id))) + HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, NULL, "can't remove ID node from skip list") + + /* Check if this ID was the last one accessed */ + if (type_info->last_id_info == info) + type_info->last_id_info = NULL; + + H5_GCC_DIAG_OFF("cast-qual") + ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ + H5_GCC_DIAG_ON("cast-qual") + + info = H5FL_FREE(H5I_id_info_t, info); + + /* Decrement the number of IDs in the type */ + (type_info->id_count)--; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__remove_common() */ + +/*------------------------------------------------------------------------- + * Function: H5I_remove + * + * Purpose: Removes the specified ID from its type. + * + * Return: Success: A pointer to the object that was removed, the + * same pointer which would have been found by + * calling H5I_object(). + * Failure: NULL + * + *------------------------------------------------------------------------- + */ +void * +H5I_remove(hid_t id) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the ID type */ + H5I_type_t type = H5I_BADID; /* ID's type */ + void * ret_value = NULL; /* Return value */ + + FUNC_ENTER_NOAPI(NULL) + + /* Check arguments */ + type = H5I_TYPE(id); + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, NULL, "invalid type number") + type_info = H5I_type_info_array_g[type]; + if (type_info == NULL || type_info->init_count <= 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, NULL, "invalid type") + + /* Remove the node from the type */ + if (NULL == (ret_value = H5I__remove_common(type_info, id))) + HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, NULL, "can't remove ID node") + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_remove() */ + +/*------------------------------------------------------------------------- + * Function: H5I_dec_ref + * + * Purpose: Decrements the number of references outstanding for an ID. + * This will fail if the type is not a reference counted type. + * The ID type's 'free' function will be called for the ID + * if the reference count for the ID reaches 0 and a free + * function has been defined at type creation time. + * + * Return: Success: New reference count + * Failure: -1 + * + *------------------------------------------------------------------------- + */ +int +H5I_dec_ref(hid_t id) +{ + H5I_id_info_t *info = NULL; /* Pointer to the ID */ + int ret_value = 0; /* Return value */ + + FUNC_ENTER_NOAPI((-1)) + + /* Sanity check */ + HDassert(id >= 0); + + /* General lookup of the ID */ + if (NULL == (info = H5I__find_id(id))) + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") + + /* If this is the last reference to the object then invoke the type's + * free method on the object. If the free method is undefined or + * successful then remove the object from the type; otherwise leave + * the object in the type without decrementing the reference + * count. If the reference count is more than one then decrement the + * reference count without calling the free method. + * + * Beware: the free method may call other H5I functions. + * + * If an object is closing, we can remove the ID even though the free + * method might fail. This can happen when a mandatory filter fails to + * write when a dataset is closed and the chunk cache is flushed to the + * file. We have to close the dataset anyway. (SLU - 2010/9/7) + */ + if (1 == info->count) { + H5I_type_info_t *type_info; /*ptr to the type */ + + /* Get the ID's type */ + type_info = H5I_type_info_array_g[H5I_TYPE(id)]; + + H5_GCC_DIAG_OFF("cast-qual") + /* (Casting away const OK -QAK) */ + if (!type_info->cls->free_func || (type_info->cls->free_func)((void *)info->object) >= 0) { + /* Remove the node from the type */ + if (NULL == H5I__remove_common(type_info, id)) + HGOTO_ERROR(H5E_ATOM, H5E_CANTDELETE, (-1), "can't remove ID node") + ret_value = 0; + } /* end if */ + else + ret_value = -1; + H5_GCC_DIAG_ON("cast-qual") + } /* end if */ + else { + --(info->count); + ret_value = (int)info->count; + } /* end else */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_dec_ref() */ + +/*------------------------------------------------------------------------- + * Function: H5I_dec_app_ref + * + * Purpose: Wrapper for case of modifying the application ref. + * count for an ID as well as normal reference count. + * + * Return: Success: New app. reference count + * Failure: -1 + * + * Programmer: Quincey Koziol + * Sept 16, 2010 + * + *------------------------------------------------------------------------- + */ +int +H5I_dec_app_ref(hid_t id) +{ + int ret_value = 0; /* Return value */ + + FUNC_ENTER_NOAPI((-1)) + + /* Sanity check */ + HDassert(id >= 0); + + /* Call regular decrement reference count routine */ + if ((ret_value = H5I_dec_ref(id)) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, (-1), "can't decrement ID ref count") + + /* Check if the ID still exists */ + if (ret_value > 0) { + H5I_id_info_t *info = NULL; /* Pointer to the ID info */ + + /* General lookup of the ID */ + if (NULL == (info = H5I__find_id(id))) + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") + + /* Adjust app_ref */ + --(info->app_count); + HDassert(info->count >= info->app_count); + + /* Set return value */ + ret_value = (int)info->app_count; + } /* end if */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_dec_app_ref() */ + +/*------------------------------------------------------------------------- + * Function: H5I_dec_app_ref_always_close + * + * Purpose: Wrapper for case of always closing the ID, even when the free + * routine fails + * + * Return: Success: New app. reference count + * Failure: -1 + * + *------------------------------------------------------------------------- + */ +int +H5I_dec_app_ref_always_close(hid_t id) +{ + int ret_value = 0; /* Return value */ + + FUNC_ENTER_NOAPI((-1)) + + /* Sanity check */ + HDassert(id >= 0); + + /* Call application decrement reference count routine */ + ret_value = H5I_dec_app_ref(id); + + /* Check for failure */ + if (ret_value < 0) { + /* + * If an object is closing, we can remove the ID even though the free + * method might fail. This can happen when a mandatory filter fails to + * write when a dataset is closed and the chunk cache is flushed to the + * file. We have to close the dataset anyway. (SLU - 2010/9/7) + */ + H5I_remove(id); + + HGOTO_ERROR(H5E_ATOM, H5E_CANTDEC, (-1), "can't decrement ID ref count") + } + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_dec_app_ref_always_close() */ + +/*------------------------------------------------------------------------- + * Function: H5I_inc_ref + * + * Purpose: Increment the reference count for an object. + * + * Return: Success: The new reference count + * Failure: -1 + * + *------------------------------------------------------------------------- + */ +int +H5I_inc_ref(hid_t id, hbool_t app_ref) +{ + H5I_id_info_t *info = NULL; /* Pointer to the ID info */ + int ret_value = 0; /* Return value */ + + FUNC_ENTER_NOAPI((-1)) + + /* Sanity check */ + HDassert(id >= 0); + + /* General lookup of the ID */ + if (NULL == (info = H5I__find_id(id))) + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") + + /* Adjust reference counts */ + ++(info->count); + if (app_ref) + ++(info->app_count); + + /* Set return value */ + ret_value = (int)(app_ref ? info->app_count : info->count); + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_inc_ref() */ + +/*------------------------------------------------------------------------- + * Function: H5I_get_ref + * + * Purpose: Retrieve the reference count for an object. + * + * Return: Success: The reference count + * Failure: -1 + * + *------------------------------------------------------------------------- + */ +int +H5I_get_ref(hid_t id, hbool_t app_ref) +{ + H5I_id_info_t *info = NULL; /* Pointer to the ID */ + int ret_value = 0; /* Return value */ + + FUNC_ENTER_NOAPI((-1)) + + /* Sanity check */ + HDassert(id >= 0); + + /* General lookup of the ID */ + if (NULL == (info = H5I__find_id(id))) + HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, (-1), "can't locate ID") + + /* Set return value */ + ret_value = (int)(app_ref ? info->app_count : info->count); + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_get_ref() */ + +/*------------------------------------------------------------------------- + * Function: H5I__inc_type_ref + * + * Purpose: Increment the reference count for an ID type. + * + * Return: Success: The new reference count + * Failure: -1 + * + *------------------------------------------------------------------------- + */ +int +H5I__inc_type_ref(H5I_type_t type) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the type */ + int ret_value = -1; /* Return value */ + + FUNC_ENTER_STATIC + + /* Sanity check */ + HDassert(type > 0 && (int)type < H5I_next_type_g); + + /* Check arguments */ + type_info = H5I_type_info_array_g[type]; + if (NULL == type_info) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "invalid type") + + /* Set return value */ + ret_value = (int)(++(type_info->init_count)); + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__inc_type_ref() */ + +/*------------------------------------------------------------------------- + * Function: H5I_dec_type_ref + * + * Purpose: Decrements the reference count on an entire type of IDs. + * If the type reference count becomes zero then the type is + * destroyed along with all IDs in that type regardless of + * their reference counts. Destroying IDs involves calling + * the free-func for each ID's object and then adding the ID + * struct to the ID free list. + * Returns the number of references to the type on success; a + * return value of 0 means that the type will have to be + * re-initialized before it can be used again (and should probably + * be set to H5I_UNINIT). + * + * Return: Success: Number of references to type + * Failure: -1 + * + *------------------------------------------------------------------------- + */ +int +H5I_dec_type_ref(H5I_type_t type) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the ID type */ + herr_t ret_value = 0; /* Return value */ + + FUNC_ENTER_NOAPI((-1)) + + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, (-1), "invalid type number") + + type_info = H5I_type_info_array_g[type]; + if (type_info == NULL || type_info->init_count <= 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "invalid type") + + /* Decrement the number of users of the ID type. If this is the + * last user of the type then release all IDs from the type and + * free all memory it used. The free function is invoked for each ID + * being freed. + */ + if (1 == type_info->init_count) { + H5I__destroy_type(type); + ret_value = 0; + } + else { + --(type_info->init_count); + ret_value = (herr_t)type_info->init_count; + } + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_dec_type_ref() */ + +/*------------------------------------------------------------------------- + * Function: H5I__get_type_ref + * + * Purpose: Retrieve the reference count for an ID type. + * + * Return: Success: The reference count + * + * Failure: -1 + * + *------------------------------------------------------------------------- + */ +int +H5I__get_type_ref(H5I_type_t type) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the type */ + int ret_value = -1; /* Return value */ + + FUNC_ENTER_STATIC + + /* Sanity check */ + HDassert(type >= 0); + + /* Check arguments */ + type_info = H5I_type_info_array_g[type]; + if (!type_info) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, (-1), "invalid type") + + /* Set return value */ + ret_value = (int)type_info->init_count; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__get_type_ref() */ + +/*------------------------------------------------------------------------- + * Function: H5I__iterate_cb + * + * Purpose: Callback routine for H5I_iterate, invokes "user" callback + * function, and then sets return value, based on the result of + * that callback. + * + * Return: Success: H5_ITER_CONT (0) or H5_ITER_STOP (1) + * Failure: H5_ITER_ERROR (-1) + * + *------------------------------------------------------------------------- + */ +static int +H5I__iterate_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) +{ + H5I_id_info_t * info = (H5I_id_info_t *)_item; /* Pointer to the ID info */ + H5I_iterate_ud_t *udata = (H5I_iterate_ud_t *)_udata; /* User data for callback */ + int ret_value = H5_ITER_CONT; /* Callback return value */ + + FUNC_ENTER_STATIC_NOERR + + /* Only invoke the callback function if this ID is visible externally and + * its reference count is positive. + */ + if ((!udata->app_ref) || (info->app_count > 0)) { + H5I_type_t type = udata->obj_type; + void * object; + herr_t cb_ret_val; + + /* The stored object pointer might be an H5VL_object_t, in which + * case we'll need to get the wrapped object struct (H5F_t *, etc.). + */ + H5_GCC_DIAG_OFF("cast-qual") + object = H5I__unwrap((void *)info->object, type); /* Casting away const OK */ + H5_GCC_DIAG_ON("cast-qual") + + /* Invoke callback function */ + cb_ret_val = (*udata->user_func)((void *)object, info->id, udata->user_udata); + + /* Set the return value based on the callback's return value */ + if (cb_ret_val > 0) + ret_value = H5_ITER_STOP; /* terminate iteration early */ + else if (cb_ret_val < 0) + ret_value = H5_ITER_ERROR; /* indicate failure (which terminates iteration) */ + } + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__iterate_cb() */ + +/*------------------------------------------------------------------------- + * Function: H5I_iterate + * + * Purpose: Apply function FUNC to each member of type TYPE (with + * non-zero application reference count if app_ref is TRUE). + * Stop if FUNC returns a non zero value (i.e. anything + * other than H5_ITER_CONT). + * + * If FUNC returns a positive value (i.e. H5_ITER_STOP), + * return SUCCEED. + * + * If FUNC returns a negative value (i.e. H5_ITER_ERROR), + * return FAIL. + * + * The FUNC should take a pointer to the object and the + * udata as arguments and return non-zero to terminate + * siteration, and zero to continue. + * + * Limitation: Currently there is no way to start the iteration from + * where a previous iteration left off. + * + * Return: SUCCEED/FAIL + * + *------------------------------------------------------------------------- + */ +herr_t +H5I_iterate(H5I_type_t type, H5I_search_func_t func, void *udata, hbool_t app_ref) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the type */ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + /* Check arguments */ + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number") + type_info = H5I_type_info_array_g[type]; + + /* Only iterate through ID list if it is initialized and there are IDs in type */ + if (type_info && type_info->init_count > 0 && type_info->id_count > 0) { + H5I_iterate_ud_t iter_udata; /* User data for iteration callback */ + herr_t iter_status; /* Iteration status */ + + /* Set up iterator user data */ + iter_udata.user_func = func; + iter_udata.user_udata = udata; + iter_udata.app_ref = app_ref; + iter_udata.obj_type = type; + + /* Iterate over IDs */ + if ((iter_status = H5SL_iterate(type_info->ids, H5I__iterate_cb, &iter_udata)) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADITER, FAIL, "iteration failed") + } + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_iterate() */ + +/*------------------------------------------------------------------------- + * Function: H5I__find_id + * + * Purpose: Given an object ID find the info struct that describes the + * object. + * + * Return: Success: A pointer to the object's info struct. + * + * Failure: NULL + * + *------------------------------------------------------------------------- + */ +H5I_id_info_t * +H5I__find_id(hid_t id) +{ + H5I_type_t type; /* ID's type */ + H5I_type_info_t *type_info = NULL; /* Pointer to the type */ + H5I_id_info_t * ret_value = NULL; /* Return value */ + + FUNC_ENTER_PACKAGE_NOERR + + /* Check arguments */ + type = H5I_TYPE(id); + if (type <= H5I_BADID || (int)type >= H5I_next_type_g) + HGOTO_DONE(NULL) + type_info = H5I_type_info_array_g[type]; + if (!type_info || type_info->init_count <= 0) + HGOTO_DONE(NULL) + + /* Check for same ID as we have looked up last time */ + if (type_info->last_id_info && type_info->last_id_info->id == id) + ret_value = type_info->last_id_info; + else { + /* Locate the ID node for the ID */ + ret_value = (H5I_id_info_t *)H5SL_search(type_info->ids, &id); + + /* Remember this ID */ + type_info->last_id_info = ret_value; + } + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__find_id() */ + +/*------------------------------------------------------------------------- + * Function: H5I__find_id_cb + * + * Purpose: Callback for searching for an ID with a specific pointer + * + * Return: Success: H5_ITER_CONT (0) or H5_ITER_STOP (1) + * Failure: H5_ITER_ERROR (-1) + * + *------------------------------------------------------------------------- + */ +static int +H5I__find_id_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) +{ + H5I_id_info_t * info = (H5I_id_info_t *)_item; /* Pointer to the ID info */ + H5I_get_id_ud_t *udata = (H5I_get_id_ud_t *)_udata; /* Pointer to user data */ + H5I_type_t type = udata->obj_type; + const void * object = NULL; + int ret_value = H5_ITER_CONT; /* Return value */ + + FUNC_ENTER_STATIC_NOERR + + /* Sanity check */ + HDassert(info); + HDassert(udata); + + /* Get a pointer to the VOL connector's data */ + H5_GCC_DIAG_OFF("cast-qual") + object = H5I__unwrap((void *)info->object, type); /* Casting away const OK */ + H5_GCC_DIAG_ON("cast-qual") + + /* Check for a match */ + if (object == udata->object) { + udata->ret_id = info->id; + ret_value = H5_ITER_STOP; + } + + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I__find_id_cb() */ + +/*------------------------------------------------------------------------- + * Function: H5I_find_id + * + * Purpose: Return the ID of an object by searching through the ID list + * for the type. + * + * Return: SUCCEED/FAIL + * (id will be set to H5I_INVALID_HID on errors or not found) + * + *------------------------------------------------------------------------- + */ +herr_t +H5I_find_id(const void *object, H5I_type_t type, hid_t *id) +{ + H5I_type_info_t *type_info = NULL; /* Pointer to the type */ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + HDassert(id); + + *id = H5I_INVALID_HID; + + type_info = H5I_type_info_array_g[type]; + if (!type_info || type_info->init_count <= 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type") + + /* Only iterate through ID list if it is initialized and there are IDs in type */ + if (type_info->init_count > 0 && type_info->id_count > 0) { + H5I_get_id_ud_t udata; /* User data */ + herr_t iter_status; /* Iteration status */ + + /* Set up iterator user data */ + udata.object = object; + udata.obj_type = type; + udata.ret_id = H5I_INVALID_HID; + + /* Iterate over IDs for the ID type */ + if ((iter_status = H5SL_iterate(type_info->ids, H5I__find_id_cb, &udata)) < 0) + HGOTO_ERROR(H5E_ATOM, H5E_BADITER, FAIL, "iteration failed") + + *id = udata.ret_id; + } + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5I_find_id() */ diff --git a/src/H5Imodule.h b/src/H5Imodule.h index 62b1406..7fc6af0 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -11,22 +11,27 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Quincey Koziol - * Saturday, September 12, 2015 + * Programmer: Quincey Koziol + * Saturday, September 12, 2015 * - * Purpose: This file contains declarations which define macros for the - * H5I package. Including this header means that the source file - * is part of the H5I package. + * Purpose: This file contains declarations which define macros for the + * H5I package. Including this header means that the source file + * is part of the H5I package. */ #ifndef _H5Imodule_H #define _H5Imodule_H /* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error - * reporting macros. + * reporting macros. */ #define H5I_MODULE #define H5_MY_PKG H5I #define H5_MY_PKG_ERR H5E_ATOM #define H5_MY_PKG_INIT NO +/**\defgroup H5I H5I + * \brief Identifier Interface + * \todo Describe concisely what the functions in this module are about. + */ + #endif /* _H5Imodule_H */ diff --git a/src/H5Ipkg.h b/src/H5Ipkg.h index 25b4a97..5d9af13 100644 --- a/src/H5Ipkg.h +++ b/src/H5Ipkg.h @@ -30,13 +30,14 @@ #include "H5Iprivate.h" /* Other private headers needed by this file */ +#include "H5SLprivate.h" /* Skip Lists */ /**************************/ /* Package Private Macros */ /**************************/ /* - * Number of bits to use for ID Type in each atom. Increase if more types + * Number of bits to use for ID Type in each ID. Increase if more types * are needed (though this will decrease the number of available IDs per * type). This is the only number that must be changed since all other bit * field sizes and masks are calculated from TYPE_BITS. @@ -47,23 +48,62 @@ #define H5I_MAX_NUM_TYPES TYPE_MASK /* - * Number of bits to use for the Atom index in each atom (assumes 8-bit + * Number of bits to use for the ID index in each ID (assumes 8-bit * bytes). We don't use the sign bit. */ #define ID_BITS ((sizeof(hid_t) * 8) - (TYPE_BITS + 1)) #define ID_MASK (((hid_t)1 << ID_BITS) - 1) -/* Map an atom to an ID type number */ +/* Map an ID to an ID type number */ #define H5I_TYPE(a) ((H5I_type_t)(((hid_t)(a) >> ID_BITS) & TYPE_MASK)) /****************************/ /* Package Private Typedefs */ /****************************/ +/* ID information structure used */ +typedef struct H5I_id_info_t { + hid_t id; /* ID for this info */ + unsigned count; /* Ref. count for this ID */ + unsigned app_count; /* Ref. count of application visible IDs */ + const void *object; /* Pointer associated with the ID */ +} H5I_id_info_t; + +/* Type information structure used */ +typedef struct H5I_type_info_t { + const H5I_class_t *cls; /* Pointer to ID class */ + unsigned init_count; /* # of times this type has been initialized */ + uint64_t id_count; /* Current number of IDs held */ + uint64_t nextid; /* ID to use for the next object */ + H5I_id_info_t * last_id_info; /* Info for most recent ID looked up */ + H5SL_t * ids; /* Pointer to skip list that stores IDs */ +} H5I_type_info_t; + +/*****************************/ +/* Package Private Variables */ +/*****************************/ + +/* Array of pointers to ID types */ +H5_DLLVAR H5I_type_info_t *H5I_type_info_array_g[H5I_MAX_NUM_TYPES]; + +/* Variable to keep track of the number of types allocated. Its value is the */ +/* next type ID to be handed out, so it is always one greater than the number */ +/* of types. */ +/* Starts at 1 instead of 0 because it makes trace output look nicer. If more */ +/* types (or IDs within a type) are needed, adjust TYPE_BITS in H5Ipkg.h */ +/* and/or increase size of hid_t */ +H5_DLLVAR int H5I_next_type_g; + /******************************/ /* Package Private Prototypes */ /******************************/ +H5_DLL int H5I__destroy_type(H5I_type_t type); +H5_DLL void * H5I__remove_verify(hid_t id, H5I_type_t type); +H5_DLL int H5I__inc_type_ref(H5I_type_t type); +H5_DLL int H5I__get_type_ref(H5I_type_t type); +H5_DLL H5I_id_info_t *H5I__find_id(hid_t id); + /* Testing functions */ #ifdef H5I_TESTING H5_DLL ssize_t H5I__get_name_test(hid_t id, char *name /*out*/, size_t size, hbool_t *cached); diff --git a/src/H5Iprivate.h b/src/H5Iprivate.h index d4d1721..d8d80f9 100644 --- a/src/H5Iprivate.h +++ b/src/H5Iprivate.h @@ -42,7 +42,7 @@ /****************************/ typedef struct H5I_class_t { - H5I_type_t type_id; /* Class ID for the type */ + H5I_type_t type; /* Class "value" for the type */ unsigned flags; /* Class behavior flags */ unsigned reserved; /* Number of reserved IDs for this type */ /* [A specific number of type entries may be @@ -86,7 +86,7 @@ H5_DLL herr_t H5I_find_id(const void *object, H5I_type_t type, hid_t *id /*o /* Functions that manipulate objects */ H5_DLL void * H5I_object(hid_t id); -H5_DLL void * H5I_object_verify(hid_t id, H5I_type_t id_type); +H5_DLL void * H5I_object_verify(hid_t id, H5I_type_t type); H5_DLL void * H5I_remove(hid_t id); H5_DLL void * H5I_subst(hid_t id, const void *new_object); H5_DLL htri_t H5I_is_file_object(hid_t id); diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index 697777c..9c5b5d4 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -21,37 +21,41 @@ /* Public headers needed by this file */ #include "H5public.h" -/* - * Library type values. Start with `1' instead of `0' because it makes the - * tracing output look better when hid_t values are large numbers. Change the - * TYPE_BITS in H5I.c if the MAXID gets larger than 32 (an assertion will - * fail otherwise). +/** + * Library type values. + * \internal Library type values. Start with `1' instead of `0' because it + * makes the tracing output look better when hid_t values are large + * numbers. Change the TYPE_BITS in H5I.c if the MAXID gets larger + * than 32 (an assertion will fail otherwise). * - * When adding types here, add a section to the 'misc19' test in test/tmisc.c - * to verify that the H5I{inc|dec|get}_ref() routines work correctly with it. + * When adding types here, add a section to the 'misc19' test in + * test/tmisc.c to verify that the H5I{inc|dec|get}_ref() routines + * work correctly with it. \endinternal */ typedef enum H5I_type_t { - H5I_UNINIT = (-2), /* uninitialized type */ - H5I_BADID = (-1), /* invalid Type */ - H5I_FILE = 1, /* type ID for File objects */ - H5I_GROUP, /* type ID for Group objects */ - H5I_DATATYPE, /* type ID for Datatype objects */ - H5I_DATASPACE, /* type ID for Dataspace objects */ - H5I_DATASET, /* type ID for Dataset objects */ - H5I_MAP, /* type ID for Map objects */ - H5I_ATTR, /* type ID for Attribute objects */ - H5I_VFL, /* type ID for virtual file layer */ - H5I_VOL, /* type ID for virtual object layer */ - H5I_GENPROP_CLS, /* type ID for generic property list classes */ - H5I_GENPROP_LST, /* type ID for generic property lists */ - H5I_ERROR_CLASS, /* type ID for error classes */ - H5I_ERROR_MSG, /* type ID for error messages */ - H5I_ERROR_STACK, /* type ID for error stacks */ - H5I_SPACE_SEL_ITER, /* type ID for dataspace selection iterator */ - H5I_NTYPES /* number of library types, MUST BE LAST! */ + H5I_UNINIT = (-2), /**< uninitialized type */ + H5I_BADID = (-1), /**< invalid Type */ + H5I_FILE = 1, /**< type ID for File objects */ + H5I_GROUP, /**< type ID for Group objects */ + H5I_DATATYPE, /**< type ID for Datatype objects */ + H5I_DATASPACE, /**< type ID for Dataspace objects */ + H5I_DATASET, /**< type ID for Dataset objects */ + H5I_MAP, /**< type ID for Map objects */ + H5I_ATTR, /**< type ID for Attribute objects */ + H5I_VFL, /**< type ID for virtual file layer */ + H5I_VOL, /**< type ID for virtual object layer */ + H5I_GENPROP_CLS, /**< type ID for generic property list classes */ + H5I_GENPROP_LST, /**< type ID for generic property lists */ + H5I_ERROR_CLASS, /**< type ID for error classes */ + H5I_ERROR_MSG, /**< type ID for error messages */ + H5I_ERROR_STACK, /**< type ID for error stacks */ + H5I_SPACE_SEL_ITER, /**< type ID for dataspace selection iterator */ + H5I_NTYPES /**< number of library types, MUST BE LAST! */ } H5I_type_t; -/* Type of atoms to return to users */ +/** + * Type of IDs to return to users + */ typedef int64_t hid_t; #define PRIdHID PRId64 @@ -59,13 +63,18 @@ typedef int64_t hid_t; #define PRIXHID PRIX64 #define PRIoHID PRIo64 +/** + * The size of identifiers + */ #define H5_SIZEOF_HID_T H5_SIZEOF_INT64_T -/* An invalid object ID. This is also negative for error return. */ +/** + * An invalid object ID. This is also negative for error return. + */ #define H5I_INVALID_HID (-1) -/* - * Function for freeing objects. This function will be called with an object +/** + * A function for freeing objects. This function will be called with an object * ID type number and a pointer to the object. The function should free the * object and return non-negative to indicate that the object * can be removed from the ID type. If the function returns negative @@ -73,11 +82,19 @@ typedef int64_t hid_t; */ typedef herr_t (*H5I_free_t)(void *); -/* Type of the function to compare objects & keys */ +/** + * The type of a function to compare objects & keys + */ +//! [H5I_search_func_t_snip] typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key); +//! [H5I_search_func_t_snip] -/* Type of the H5Iiterate callback function */ +/** + * The type of H5Iiterate() callback functions + */ +//! [H5I_iterate_func_t_snip] typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata); +//! [H5I_iterate_func_t_snip] #ifdef __cplusplus extern "C" { @@ -85,26 +102,562 @@ extern "C" { /* Public API functions */ -H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); -H5_DLL void * H5Iobject_verify(hid_t id, H5I_type_t id_type); -H5_DLL void * H5Iremove_verify(hid_t id, H5I_type_t id_type); +/** + * \ingroup H5I + * + * \brief Registers an object under a type and returns an ID for it + * + * \param[in] type The identifier of the type of the new ID + * \param[in] object Pointer to object for which a new ID is created + * + * \return \hid_t{object} + * + * \details H5Iregister() allocates and returns a new ID for an object. + * + * \details The \p type parameter is the identifier for the ID type to which + * this new ID will belong. This identifier must have been created by + * a call to H5Iregister_type(). + * + * \details The \p object parameter is a pointer to the memory which the new ID + * will be a reference to. This pointer will be stored by the library + * and returned via a call to H5Iobject_verify(). + * + */ +H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); +/** + * \ingroup H5I + * + * \brief Returns the object referenced by an ID + * + * \param[in] id ID to be dereferenced + * \param[in] type The identifier type + + * + * \return Pointer to the object referenced by \p id on success, NULL on failure. + * + * \details H5Iobject_verify() returns a pointer to the memory referenced by id + * after verifying that \p id is of type \p type. This function is + * analogous to dereferencing a pointer in C with type checking. + * + * \note H5Iobject_verify() does not change the ID it is called on in any way + * (as opposed to H5Iremove_verify(), which removes the ID from its + * type’s hash table). + * + * \see H5Iregister() + * + */ +H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Removes an ID from its type + * + * \param[in] id The ID to be removed from its type + * \param[in] type The identifier type + + * + * \return Returns a pointer to the memory referred to by \p id on success, + * NULL on failure. + * + * \details H5Iremove_verify() first ensures that \p id belongs to \p type. + * If so, it removes \p id from its type and returns the pointer + * to the memory it referred to. This pointer is the same pointer that + * was placed in storage by H5Iregister(). If id does not belong to + * \p type, then NULL is returned. + * + * The \p id parameter is the ID which is to be removed from its type. + * + * The \p type parameter is the identifier for the ID type which \p id + * is supposed to belong to. This identifier must have been created by + * a call to H5Iregister_type(). + * + * \note This function does NOT deallocate the memory that \p id refers to. + * The pointer returned by H5Iregister() must be deallocated by the user + * to avoid memory leaks. + * + */ +H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Retrieves the type of an object + * + * \obj_id{id} + * + * \return Returns the object type if successful; otherwise #H5I_BADID. + * + * \details H5Iget_type() retrieves the type of the object identified by + * \p id. + * + * Valid types returned by the function are: + * \types + * + * If no valid type can be determined or the identifier submitted is + * invalid, the function returns #H5I_BADID. + * + * This function is of particular use in determining the type of + * object closing function (H5Dclose(), H5Gclose(), etc.) to call + * after a call to H5Rdereference(). + * + * \note Note that this function returns only the type of object that \p id + * would identify if it were valid; it does not determine whether \p id + * is valid identifier. Validity can be determined with a call to + * H5Iis_valid(). + * + */ H5_DLL H5I_type_t H5Iget_type(hid_t id); -H5_DLL hid_t H5Iget_file_id(hid_t id); -H5_DLL ssize_t H5Iget_name(hid_t id, char *name /*out*/, size_t size); -H5_DLL int H5Iinc_ref(hid_t id); -H5_DLL int H5Idec_ref(hid_t id); -H5_DLL int H5Iget_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Retrieves an identifier for the file containing the specified object + * + * \obj_id{id} + * + * \return \hid_t{file} + * + * \details H5Iget_file_id() returns the identifier of the file associated with + * the object referenced by \p id. + * + * \note Note that the HDF5 library permits an application to close a file + * while objects within the file remain open. If the file containing the + * object \p id is still open, H5Iget_file_id() will retrieve the + * existing file identifier. If there is no existing file identifier for + * the file, i.e., the file has been closed, H5Iget_file_id() will reopen + * the file and return a new file identifier. In either case, the file + * identifier must eventually be released using H5Fclose(). + * + * \since 1.6.3 + * + */ +H5_DLL hid_t H5Iget_file_id(hid_t id); +/** + * \ingroup H5I + * + * \brief Retrieves a name of an object based on the object identifier + * + * \obj_id{id} + * \param[out] name A buffer for thename associated with the identifier + * \param[in] size The size of the \p name buffer; usually the size of + * the name in bytes plus 1 for a NULL terminator + * + * \return ssize_t + * + * \details H5Iget_name() retrieves a name for the object identified by \p id. + * + * \details Up to size characters of the name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. + * + * If the length of the name, which determines the required value of + * \p size, is unknown, a preliminary H5Iget_name() call can be made. + * The return value of this call will be the size in bytes of the + * object name. That value, plus 1 for a NULL terminator, is then + * assigned to size for a second H5Iget_name() call, which will + * retrieve the actual name. + * + * If the object identified by \p id is an attribute, as determined + * via H5Iget_type(), H5Iget_name() retrieves the name of the object + * to which that attribute is attached. To retrieve the name of the + * attribute itself, use H5Aget_name(). + * + * If there is no name associated with the object identifier or if the + * name is NULL, H5Iget_name() returns 0 (zero). + * + * \note Note that an object in an HDF5 file may have multiple paths if there + * are multiple links pointing to it. This function may return any one of + * these paths. When possible, H5Iget_name() returns the path with which + * the object was opened. + * + * \since 1.6.0 + * + */ +H5_DLL ssize_t H5Iget_name(hid_t id, char *name /*out*/, size_t size); +/** + * \ingroup H5I + * + * \brief Increments the reference count for an object + * + * \obj_id{id} + * + * \return Returns a non-negative reference count of the object ID after + * incrementing it if successful; otherwise a negative value is + * returned. + * + * \details H5Iinc_ref() increments the reference count of the object + * identified by \p id. + * + * The reference count for an object ID is attached to the information + * about an object in memory and has no relation to the number of + * links to an object on disk. + * + * The reference count for a newly created object will be 1. Reference + * counts for objects may be explicitly modified with this function or + * with H5Idec_ref(). When an object ID's reference count reaches + * zero, the object will be closed. Calling an object ID's \c close + * function decrements the reference count for the ID which normally + * closes the object, but if the reference count for the ID has been + * incremented with this function, the object will only be closed when + * the reference count reaches zero with further calls to H5Idec_ref() + * or the object ID's \c close function. + * + * If the object ID was created by a collective parallel call (such as + * H5Dcreate(), H5Gopen(), etc.), the reference count should be + * modified by all the processes which have copies of the ID. + * Generally this means that group, dataset, attribute, file and named + * datatype IDs should be modified by all the processes and that all + * other types of IDs are safe to modify by individual processes. + * + * This function is of particular value when an application is + * maintaining multiple copies of an object ID. The object ID can be + * incremented when a copy is made. Each copy of the ID can then be + * safely closed or decremented and the HDF5 object will be closed + * when the reference count for that that object drops to zero. + * + * \since 1.6.2 + * + */ +H5_DLL int H5Iinc_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Decrements the reference count for an object + * + * \obj_id{id} + * + * \return Returns a non-negative reference count of the object ID after + * decrementing it, if successful; otherwise a negative value is + * returned. + * + * \details H5Idec_ref() decrements the reference count of the object + * identified by \p id. + * + * The reference count for an object ID is attached to the information + * about an object in memory and has no relation to the number of + * links to an object on disk. + * + * The reference count for a newly created object will be 1. Reference + * counts for objects may be explicitly modified with this function or + * with H5Iinc_ref(). When an object identifier’s reference count + * reaches zero, the object will be closed. Calling an object + * identifier’s \c close function decrements the reference count for + * the identifier which normally closes the object, but if the + * reference count for the identifier has been incremented with + * H5Iinc_ref(), the object will only be closed when the reference + * count reaches zero with further calls to this function or the + * object identifier’s \c close function. + * + * If the object ID was created by a collective parallel call (such as + * H5Dcreate(), H5Gopen(), etc.), the reference count should be + * modified by all the processes which have copies of the ID. + * Generally this means that group, dataset, attribute, file and named + * datatype IDs should be modified by all the processes and that all + * other types of IDs are safe to modify by individual processes. + * + * This function is of particular value when an application is + * maintaining multiple copies of an object ID. The object ID can be + * incremented when a copy is made. Each copy of the ID can then be + * safely closed or decremented and the HDF5 object will be closed + * when the reference count for that that object drops to zero. + * + * \since 1.6.2 + * + */ +H5_DLL int H5Idec_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Retrieves the reference count for an object + * + * \obj_id{id} + * + * \return Returns a non-negative current reference count of the object + * identifier if successful; otherwise a negative value is returned. + * + * \details H5Iget_ref() retrieves the reference count of the object identified + * by \p id. + * + * The reference count for an object identifier is attached to the + * information about an object in memory and has no relation to the + * number of links to an object on disk. + * + * The function H5Iis_valid() is used to determine whether a specific + * object identifier is valid. + * + * \since 1.6.2 + * + */ +H5_DLL int H5Iget_ref(hid_t id); +/** + * \ingroup H5I + * + * \brief Creates and returns a new ID type + * + * \param[in] hash_size Minimum hash table size (in entries) used to store IDs + * for the new type + * \param[in] reserved Number of reserved IDs for the new type + * \param[in] free_func Function used to deallocate space for a single ID + * + * \return Returns the type identifier on success, negative on failure. + * + * \details H5Iregister_type() allocates space for a new ID type and returns an + * identifier for it. + * + * The \p hash_size parameter indicates the minimum size of the hash + * table used to store IDs in the new type. + * + * The \p reserved parameter indicates the number of IDs in this new + * type to be reserved. Reserved IDs are valid IDs which are not + * associated with any storage within the library. + * + * The \p free_func parameter is a function pointer to a function + * which returns an herr_t and accepts a \c void*. The purpose of this + * function is to deallocate memory for a single ID. It will be called + * by H5Iclear_type() and H5Idestroy_type() on each ID. This function + * is NOT called by H5Iremove_verify(). The \c void* will be the same + * pointer which was passed in to the H5Iregister() function. The \p + * free_func function should return 0 on success and -1 on failure. + * + */ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func); -H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); -H5_DLL herr_t H5Idestroy_type(H5I_type_t type); -H5_DLL int H5Iinc_type_ref(H5I_type_t type); -H5_DLL int H5Idec_type_ref(H5I_type_t type); -H5_DLL int H5Iget_type_ref(H5I_type_t type); -H5_DLL void * H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); -H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); -H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); -H5_DLL htri_t H5Itype_exists(H5I_type_t type); -H5_DLL htri_t H5Iis_valid(hid_t id); +/** + * \ingroup H5I + * + * \brief Deletes all identifiers of the given type + * + * \param[in] type Identifier of identifier type which is to be cleared of identifiers + * \param[in] force Whether or not to force deletion of all identifiers + * + * \return \herr_t + * + * \details H5Iclear_type() deletes all identifiers of the type identified by + * the argument \p type. + * + * The identifier type's free function is first called on all of these + * identifiers to free their memory, then they are removed from the + * type. + * + * If the \p force flag is set to false, only those identifiers whose + * reference counts are equal to 1 will be deleted, and all other + * identifiers will be entirely unchanged. If the force flag is true, + * all identifiers of this type will be deleted. + * + */ +H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); +/** + * \ingroup H5I + * + * \brief Removes an identifier type and all identifiers within that type + * + * \param[in] type Identifier of identifier type which is to be destroyed + * + * \return \herr_t + * + * \details H5Idestroy_type deletes an entire identifier type \p type. All + * identifiers of this type are destroyed and no new identifiers of + * this type can be registered. + * + * The type’s free function is called on all of the identifiers which + * are deleted by this function, freeing their memory. In addition, + * all memory used by this type’s hash table is freed. + * + * Since the H5I_type_t values of destroyed identifier types are + * reused when new types are registered, it is a good idea to set the + * variable holding the value of the destroyed type to #H5I_UNINIT. + * + */ +H5_DLL herr_t H5Idestroy_type(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Increments the reference count on an ID type + * + * \param[in] type The identifier of the type whose reference count is to be incremented + * + * \return Returns the current reference count on success, negative on failure. + * + * \details H5Iinc_type_ref() increments the reference count on an ID type. The + * reference count is used by the library to indicate when an ID type + * can be destroyed. + * + * The type parameter is the identifier for the ID type whose + * reference count is to be incremented. This identifier must have + * been created by a call to H5Iregister_type(). + * + */ +H5_DLL int H5Iinc_type_ref(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Decrements the reference count on an identifier type + * + * \param[in] type The identifier of the type whose reference count is to be decremented + * + * \return Returns the current reference count on success, negative on failure. + * + * \details H5Idec_type_ref() decrements the reference count on an identifier + * type. The reference count is used by the library to indicate when + * an identifier type can be destroyed. If the reference count reaches + * zero, this function will destroy it. + * + * The type parameter is the identifier for the identifier type whose + * reference count is to be decremented. This identifier must have + * been created by a call to H5Iregister_type(). + * + */ +H5_DLL int H5Idec_type_ref(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Retrieves the reference count on an ID type + * + * \param[in] type The identifier of the type whose reference count is to be retieved + * + * \return Returns the current reference count on success, negative on failure. + * + * \details H5Iget_type_ref() retrieves the reference count on an ID type. The + * reference count is used by the library to indicate when an ID type + * can be destroyed. + * + * The type parameter is the identifier for the ID type whose + * reference count is to be retrieved. This identifier must have been + * created by a call to H5Iregister_type(). + * + */ +H5_DLL int H5Iget_type_ref(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Finds the memory referred to by an ID within the given ID type such + * that some criterion is satisfied + * + * \param[in] type The identifier of the type to be searched + * \param[in] func The function defining the search criteria + * \param[in] key A key for the search function + * + * \return Returns a pointer to the object which satisfies the search function + * on success, NULL on failure. + * + * \details H5Isearch() searches through a given ID type to find an object that + * satisfies the criteria defined by \p func. If such an object is + * found, the pointer to the memory containing this object is + * returned. Otherwise, NULL is returned. To do this, \p func is + * called on every member of type \p type. The first member to satisfy + * \p func is returned. + * + * The \p type parameter is the identifier for the ID type which is to + * be searched. This identifier must have been created by a call to + * H5Iregister_type(). + * + * The parameter \p func is a function pointer to a function which + * takes three parameters. The first parameter is a \c void* and will + * be a pointer to the object to be tested. This is the same object + * that was placed in storage using H5Iregister(). The second + * parameter is a hid_t and is the ID of the object to be tested. The + * last parameter is a \c void*. This is the \p key parameter and can + * be used however the user finds helpful, or it can be ignored if it + * is not needed. \p func returns 0 if the object it is testing does + * not pass its criteria. A non-zero value should be returned if the + * object does pass its criteria. H5I_search_func_t is defined in + * H5Ipublic.h and is shown below. + * \snippet this H5I_search_func_t_snip + * The \p key parameter will be passed to the search function as a + * parameter. It can be used to further define the search at run-time. + * + */ +H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); +/** + * \ingroup H5I + * + * \brief Calls a callback for each member of the identifier type specified + * + * \param[in] type The identifier type + * \param[in] op The callback function + * \param[in,out] op_data The data for the callback function + * + * \return The last value returned by \p op + * + * \details H5Iiterate() calls the callback function \p op for each member of + * the identifier type \p type. The callback function type for \p op, + * H5I_iterate_func_t, is defined in H5Ipublic.h as: + * \snippet this H5I_iterate_func_t_snip + * \p op takes as parameters the identifier and a pass through of + * \p op_data, and returns an herr_t. + * + * A positive return from op will cause the iteration to stop and + * H5Iiterate() will return the value returned by \p op. A negative + * return from \p op will cause the iteration to stop and H5Iiterate() + * will return failure. A zero return from \p op will allow iteration + * to continue, as long as there are other identifiers remaining in + * type. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); +/** + * \ingroup H5I + * + * \brief Returns the number of identifiers in a given identifier type + * + * \param[in] type The identifier type + * \param[out] num_members Number of identifiers of the specified identifier type + * + * \return \herr_t + * + * \details H5Inmembers() returns the number of identifiers of the identifier + * type specified in \p type. + * + * The number of identifiers is returned in \p num_members. If no + * identifiers of this type have been registered, the type does not + * exist, or it has been destroyed, \p num_members is returned with + * the value 0. + * + */ +H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); +/** + * \ingroup H5I + * + * \brief Determines whether an identifier type is registered + * + * \param[in] type Identifier type + * + * \return \htri_t + * + * \details H5Itype_exists() determines whether the given identifier type, + * \p type, is registered with the library. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Itype_exists(H5I_type_t type); +/** + * \ingroup H5I + * + * \brief Determines whether an identifier is valid + * + * \obj_id{id} + * + * \return \htri_t + * + * \details H5Iis_valid() determines whether the identifier \p id is valid. + * + * \details Valid identifiers are those that have been obtained by an + * application and can still be used to access the original target. + * Examples of invalid identifiers include: + * \li Out of range values: negative, for example + * \li Previously-valid identifiers that have been released: + * for example, a dataset identifier for which the dataset has + * been closed + * + * H5Iis_valid() can be used with any type of identifier: object + * identifier, property list identifier, attribute identifier, error + * message identifier, etc. When necessary, a call to H5Iget_type() + * can determine the type of the object that \p id identifies. + * + * \since 1.8.3 + * + */ +H5_DLL htri_t H5Iis_valid(hid_t id); #ifdef __cplusplus } diff --git a/src/H5Itest.c b/src/H5Itest.c index 83e0a84..ea0de2a 100644 --- a/src/H5Itest.c +++ b/src/H5Itest.c @@ -11,10 +11,8 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Quincey Koziol - * Tuesday, July 27, 2010 - * - * Purpose: ID testing functions. +/* + * H5Itest.c - ID testing functions */ /****************/ @@ -28,7 +26,6 @@ /* Headers */ /***********/ #include "H5private.h" /* Generic Functions */ -#include "H5ACprivate.h" /* Metadata cache */ #include "H5CXprivate.h" /* API Contexts */ #include "H5Eprivate.h" /* Error handling */ #include "H5Gprivate.h" /* Groups */ @@ -1078,7 +1078,7 @@ H5Lregister(const H5L_class_t *cls) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE1("e", "*x", cls); + H5TRACE1("e", "*#", cls); /* Check args */ if (cls == NULL) @@ -1279,7 +1279,7 @@ H5Literate2(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "iIiIo*hx*x", group_id, idx_type, order, idx_p, op, op_data); + H5TRACE6("e", "iIiIo*hLI*x", group_id, idx_type, order, idx_p, op, op_data); /* Check arguments */ id_type = H5I_get_type(group_id); @@ -1341,7 +1341,7 @@ H5Literate_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type, H herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIo*hx*xi", loc_id, group_name, idx_type, order, idx_p, op, op_data, lapl_id); + H5TRACE8("e", "i*sIiIo*hLI*xi", loc_id, group_name, idx_type, order, idx_p, op, op_data, lapl_id); /* Check arguments */ if (!group_name) @@ -1415,7 +1415,7 @@ H5Lvisit2(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterat herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "iIiIox*x", group_id, idx_type, order, op, op_data); + H5TRACE5("e", "iIiIoLI*x", group_id, idx_type, order, op, op_data); /* Check args */ id_type = H5I_get_type(group_id); @@ -1482,7 +1482,7 @@ H5Lvisit_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_ herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "i*sIiIox*xi", loc_id, group_name, idx_type, order, op, op_data, lapl_id); + H5TRACE7("e", "i*sIiIoLI*xi", loc_id, group_name, idx_type, order, op, op_data, lapl_id); /* Check args */ if (!group_name) diff --git a/src/H5Ldeprec.c b/src/H5Ldeprec.c index 843469f..2adc1fe 100644 --- a/src/H5Ldeprec.c +++ b/src/H5Ldeprec.c @@ -149,7 +149,7 @@ H5Literate1(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "iIiIo*hx*x", group_id, idx_type, order, idx_p, op, op_data); + H5TRACE6("e", "iIiIo*hLi*x", group_id, idx_type, order, idx_p, op, op_data); /* Check arguments */ id_type = H5I_get_type(group_id); @@ -226,7 +226,7 @@ H5Literate_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type, H herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIo*hx*xi", loc_id, group_name, idx_type, order, idx_p, op, op_data, lapl_id); + H5TRACE8("e", "i*sIiIo*hLi*xi", loc_id, group_name, idx_type, order, idx_p, op, op_data, lapl_id); /* Check arguments */ if (!group_name) @@ -487,7 +487,7 @@ H5Lvisit1(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterat herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "iIiIox*x", group_id, idx_type, order, op, op_data); + H5TRACE5("e", "iIiIoLi*x", group_id, idx_type, order, op, op_data); /* Check args */ id_type = H5I_get_type(group_id); @@ -570,7 +570,7 @@ H5Lvisit_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_ herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "i*sIiIox*xi", loc_id, group_name, idx_type, order, op, op_data, lapl_id); + H5TRACE7("e", "i*sIiIoLi*xi", loc_id, group_name, idx_type, order, op, op_data, lapl_id); /* Check args */ if (!group_name) diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index 043a865..ad737d6 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -29,4 +29,12 @@ #define H5_MY_PKG_ERR H5E_LINK #define H5_MY_PKG_INIT YES +/**\defgroup H5L H5L + * \brief Link Interface + * \todo Describe concisely what the functions in this module are about. + * + * \defgroup TRAV Link Traversal + * \ingroup H5L + */ + #endif /* _H5Lmodule_H */ diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index be920c2..e930a15 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -34,14 +34,21 @@ /* Public Macros */ /*****************/ -/* Maximum length of a link's name */ -/* (encoded in a 32-bit unsigned integer) */ +/** + * \brief Maximum length of a link's name + * + * The maximum length of a link's name is encoded in a 32-bit unsigned integer. + */ #define H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */ -/* Macro to indicate operation occurs on same location */ +/** + * \brief Macro to indicate operation occurs on same location + */ #define H5L_SAME_LOC (hid_t)0 -/* Current version of the H5L_class_t struct */ +/** + * \brief Current version of the H5L_class_t struct + */ #define H5L_LINK_CLASS_T_VERS 1 #ifdef __cplusplus @@ -52,88 +59,123 @@ extern "C" { /* Public Typedefs */ /*******************/ -/* Link class types. - * Values less than 64 are reserved for the HDF5 library's internal use. - * Values 64 to 255 are for "user-defined" link class types; these types are - * defined by HDF5 but their behavior can be overridden by users. - * Users who want to create new classes of links should contact the HDF5 - * development team at help@hdfgroup.org. - * These values can never change because they appear in HDF5 files. +/** + * \brief Link class types. + * + * Values less than 64 are reserved for the HDF5 library's internal use. Values + * 64 to 255 are for "user-defined" link class types; these types are defined + * by HDF5 but their behavior can be overridden by users. Users who want to + * create new classes of links should contact the HDF5 development team at + * mailto:help@hdfgroup.org. These values can never change because they appear + * in HDF5 files. */ typedef enum { - H5L_TYPE_ERROR = (-1), /* Invalid link type id */ - H5L_TYPE_HARD = 0, /* Hard link id */ - H5L_TYPE_SOFT = 1, /* Soft link id */ - H5L_TYPE_EXTERNAL = 64, /* External link id */ - H5L_TYPE_MAX = 255 /* Maximum link type id */ + H5L_TYPE_ERROR = (-1), /**< Invalid link type id */ + H5L_TYPE_HARD = 0, /**< Hard link id */ + H5L_TYPE_SOFT = 1, /**< Soft link id */ + H5L_TYPE_EXTERNAL = 64, /**< External link id */ + H5L_TYPE_MAX = 255 /**< Maximum link type id */ } H5L_type_t; -/* Maximum value link value for "built-in" link types */ +/** + * \brief Maximum value link value for "built-in" link types + */ #define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT -/* Link ids at or above this value are "user-defined" link types. */ +/** + * \brief Link ids at or above this value are "user-defined" link types. + */ #define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL +/** + * \brief Maximum link id value for "user-defined" link types. + */ +#define H5L_TYPE_UD_MAX H5L_TYPE_MAX -/* Information struct for link (for H5Lget_info2/H5Lget_info_by_idx2) - * H5O_token_t version used in VOL layer and future public API calls +/** + * \brief Information struct for links */ +//! [H5L_info2_t_snip] typedef struct { - H5L_type_t type; /* Type of link */ - hbool_t corder_valid; /* Indicate if creation order is valid */ - int64_t corder; /* Creation order */ - H5T_cset_t cset; /* Character set of link name */ + H5L_type_t type; /**< Type of link */ + hbool_t corder_valid; /**< Indicate if creation order is valid */ + int64_t corder; /**< Creation order */ + H5T_cset_t cset; /**< Character set of link name */ union { - H5O_token_t token; /* Token of location that hard link points to */ - size_t val_size; /* Size of a soft link or UD link value */ + H5O_token_t token; /**< Token of location that hard link points to */ + size_t val_size; /**< Size of a soft link or user-defined link value */ } u; } H5L_info2_t; +//! [H5L_info2_t_snip] /* The H5L_class_t struct can be used to override the behavior of a * "user-defined" link class. Users should populate the struct with callback * functions defined below. */ /* Callback prototypes for user-defined links */ -/* Link creation callback */ +/** + * \brief Link creation callback + */ typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id); - -/* Callback for when the link is moved */ +/** + * \brief Callback for link move + */ typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size); - -/* Callback for when the link is copied */ +/** + * \brief Callback for link copy + */ typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, size_t lnkdata_size); - -/* Callback during link traversal */ +/** + * \brief Callback during link traversal + */ typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id); - -/* Callback for when the link is deleted */ +/** + * \brief Callback for link deletion + */ typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, size_t lnkdata_size); - -/* Callback for querying the link */ -/* Returns the size of the buffer needed */ +/** + * \brief Callback for querying the link. + * + * Returns the size of the buffer needed. + */ typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size, void *buf /*out*/, size_t buf_size); +/** + * \brief Link prototype + * + * The H5L_class_t struct can be used to override the behavior of a + * "user-defined" link class. Users should populate the struct with callback + * functions defined elsewhere. + */ +//! [H5L_class_t_snip] typedef struct { - int version; /* Version number of this struct */ - H5L_type_t id; /* Link type ID */ - const char * comment; /* Comment for debugging */ - H5L_create_func_t create_func; /* Callback during link creation */ - H5L_move_func_t move_func; /* Callback after moving link */ - H5L_copy_func_t copy_func; /* Callback after copying link */ - H5L_traverse_func_t trav_func; /* Callback during link traversal */ - H5L_delete_func_t del_func; /* Callback for link deletion */ - H5L_query_func_t query_func; /* Callback for queries */ + int version; /**< Version number of this struct */ + H5L_type_t id; /**< Link type ID */ + const char * comment; /**< Comment for debugging */ + H5L_create_func_t create_func; /**< Callback during link creation */ + H5L_move_func_t move_func; /**< Callback after moving link */ + H5L_copy_func_t copy_func; /**< Callback after copying link */ + H5L_traverse_func_t trav_func; /**< Callback during link traversal */ + H5L_delete_func_t del_func; /**< Callback for link deletion */ + H5L_query_func_t query_func; /**< Callback for queries */ } H5L_class_t; +//! [H5L_class_t_snip] -/* Prototype for H5Literate2/H5Literate_by_name2() operator - * H5O_token_t version used in VOL layer and future public API calls +/** + * \brief Prototype for H5Literate2(), H5Literate_by_name2() operator + * + * The H5O_token_t version is used in the VOL layer and future public API calls. */ +//! [H5L_iterate2_t_snip] typedef herr_t (*H5L_iterate2_t)(hid_t group, const char *name, const H5L_info2_t *info, void *op_data); +//! [H5L_iterate2_t_snip] -/* Callback for external link traversal */ +/** + * \brief Callback for external link traversal + */ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char *parent_group_name, const char *child_file_name, const char *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data); @@ -145,49 +187,1407 @@ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char /*********************/ /* Public Prototypes */ /*********************/ +/** + * \ingroup H5L + * + * \brief Moves a link within an HDF5 file + * + * \fgdta_loc_id{src_loc} + * \param[in] src_name Original link name + * \fgdta_loc_id{dst_loc} + * \param[in] dst_name New link name + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Lmove() moves a link within an HDF5 file. The original link, + * \p src_name, is removed from \p src_loc and the new link, + * \p dst_name, is inserted at dst_loc. This change is + * accomplished as an atomic operation. + * + * \p src_loc and \p src_name identify the original link. + * \p src_loc is the original location identifier; \p src_name is + * the path to the link and is interpreted relative to \p src_loc. + * + * \p dst_loc and \p dst_name identify the new link. \p dst_loc is + * either a file or group identifier; \p dst_name is the path to + * the link and is interpreted relative to \p dst_loc. + * + * \p lcpl_id and \p lapl_id are the link creation and link access + * property lists, respectively, associated with the new link, + * \p dst_name. + * + * Through these property lists, several properties are available to + * govern the behavior of H5Lmove(). The property controlling creation + * of missing intermediate groups is set in the link creation property + * list with H5Pset_create_intermediate_group(); H5Lmove() ignores any + * other properties in the link creation property list. Properties + * controlling character encoding, link traversals, and external link + * prefixes are set in the link access property list with + * H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix(), + * respectively. + * + * \note Note that H5Lmove() does not modify the value of the link; the new + * link points to the same object as the original link pointed to. + * Furthermore, if the object pointed to by the original link was already + * open with a valid object identifier, that identifier will remain valid + * after the call to H5Lmove(). + * + * \attention Exercise care in moving links as it is possible to render data in + * a file inaccessible with H5Lmove(). If the link being moved is on + * the only path leading to an HDF5 object, that object may become + * permanently inaccessible in the file. + * + * \since 1.8.0 + * + *------------------------------------------------------------------------- + */ H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Creates an identical copy of a link with the same creation time and + * target. The new link can have a different name and be in a different + * location than the original. + * + * \fgdt_loc_id{src_loc} + * \param[in] src_name Name of the link to be copied + * \fgdt_loc_id{dst_loc} + * \param[in] dst_name Name to be assigned to the new copy + * \lcpl_id + * \lapl_id + * \return \herr_t + * + * \details H5Lcopy() copies the link specified by \p src_name from the location + * specified by \p src_loc_id to the location specified by + * \p dst_loc_id. The new copy of the link is created with the name + * \p dst_name. + * + * If \p dst_loc_id is a file identifier, \p dst_name will be + * interpreted relative to that file’s root group. + * + * The new link is created with the creation and access property lists + * specified by \p lcpl_id and \p lapl_id. The interpretation of + * \p lcpl_id is limited in the manner described in the next paragraph. + * + * H5Lcopy() retains the creation time and the target of the original + * link. However, since the link may be renamed, the character + * encoding is that specified in \p lcpl_id rather than that of the + * original link. Other link creation properties are ignored. + * + * If the link is a soft link, also known as a symbolic link, its + * target is interpreted relative to the location of the copy. + * + * Several properties are available to govern the behavior of + * H5Lcopy(). These properties are set in the link creation and access + * property lists, \p lcpl_id and \p lapl_id, respectively. The + * property controlling creation of missing intermediate groups is set + * in the link creation property list with + * H5Pset_create_intermediate_group(); this function ignores any + * other properties in the link creation property list. Properties + * controlling character encoding, link traversals, and external link + * prefixes are set in the link access property list with + * H5Pset_char_encoding(), H5Pset_nlinks(), and + * H5Pset_elink_prefix(). + * + * \note H5Lcopy() does not affect the object that the link points to. + * + * \attention H5Lcopy() cannot copy hard links across files as a hard link is + * not valid without a target object; to copy objects from one file + * to another, see H5Ocopy(). + * + * \see H5Ocopy() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Creates a hard link to an object + * + * \fgdta_loc_id{cur_loc} + * \param[in] cur_name Name of the target object, which must already exist + * \fgdta_loc_id{dst_loc} + * \param[in] dst_name The name of the new link + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Lcreate_hard() creates a new hard link to a pre-existing object + * in an HDF5 file. + * + * \p cur_loc and \p cur_name specify the location + * and name, respectively, of the target object, i.e., the object that + * the new hard link points to. \p dst_loc and \p dst_name specify the + * location and name, respectively, of the new hard link. + * + * \p cur_name and \p dst_name are interpreted relative to \p cur_loc + * and \p dst_loc, respectively. If \p cur_loc and \p dst_loc are the + * same location, the HDF5 macro #H5L_SAME_LOC can be used for either + * parameter (but not both). + * + * \p lcpl_id and \p lapl_id are the link creation and access property + * lists associated with the new link. + * + * \note Hard and soft links are for use only if the target object is in the + * current file. If the desired target object is in a different file from + * the new link, an external link may be created with + * H5Lcreate_external(). + * + * \note The HDF5 library keeps a count of all hard links pointing to an + * object; if the hard link count reaches zero (0), the object will be + * deleted from the file. Creating new hard links to an object will + * prevent it from being deleted if other links are removed. The + * library maintains no similar count for soft links and they can dangle. + * + * \note The new link may be one of many that point to that object. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Creates a soft link + * + * \param[in] link_target An HDF5 path name + * \fgdta_loc_id{link_loc_id} + * \param[in] link_name The name of the new link + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Lcreate_soft() creates a new soft link to an object in an HDF5 + * file. + * + * \p link_target specifies the HDF5 path name the soft link contains. + * \p link_target can be an arbitrary HDF5 path name and is + * interpreted only at lookup time. This path may be absolute in the + * file or relative to \p link_loc_id. + * + * \p link_loc_id and \p link_name specify the location and name, + * respectively, of the new soft link. \p link_name is interpreted + * relative to \p link_loc_id and must contain only the name of the soft + * link; \p link_name may not contain any additional path elements. + * + * If \p link_loc_id is a group identifier, the object pointed to by + * \p link_name will be accessed as a member of that group. If + * \p link_loc_id is a file identifier, the object will be accessed as a + * member of the file's root group. + * + * \p lcpl_id and \p lapl_id are the link creation and access property + * lists associated with the new link. + * + * For instance, if target_path is \c ./foo, \p link_loc_id specifies + * \c ./x/y/bar, and the name of the new link is \c new_link, then a + * subsequent request for \c ./x/y/bar/new_link will return same the + * object as would be found at \c ./foo. + * + * \note H5Lcreate_soft() is for use only if the target object is in the + * current file. If the desired target object is in a different file from + * the new link, use H5Lcreate_external() to create an external link. + * + * \note Soft links and external links are also known as symbolic links as they + * use a name to point to an object; hard links employ an object’s + * address in the file. + * + * \note Unlike hard links, a soft link in an HDF5 file is allowed to dangle, + * meaning that the target object need not exist at the time that the + * link is created. + * + * \note The HDF5 library does not keep a count of soft links as it does of + * hard links. + * + * \note The new link may be one of many that point to that object. + * + * \see H5Lcreate_hard(), H5Lcreate_external() + * + * \since 1.8.0 + * + + */ H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Removes a link from a group + * + * \fgdta_loc_id + * \param[in] name Name of the link to delete + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Ldelete() removes the link specified by \p name from the location + * \p loc_id. + * + * If the link being removed is a hard link, H5Ldelete() also + * decrements the link count for the object to which name points. + * Unless there is a duplicate hard link in that group, this action + * removes the object to which name points from the group that + * previously contained it. + * + * Object headers keep track of how many hard links refer to an + * object; when the hard link count, also referred to as the reference + * count, reaches zero, the object can be removed from the file. The + * file space associated will then be released, i.e., identified in + * memory as freespace. Objects which are open are not removed until + * all identifiers to the object are closed. + * + * \attention Exercise caution in the use of H5Ldelete(); if the link being + * removed is on the only path leading to an HDF5 object, that + * object may become permanently inaccessible in the file. + * + * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_external() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Removes the \Emph{n}-th link in a group + * + * \fgdta_loc_id + * \param[in] group_name Name of subject group + * \param[in] idx_type Index or field which determines the order + * \param[in] order Order within field or index + * \param[in] n Link for which to retrieve information + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Ldelete_by_idx() removes the \Emph{n}-th link in a group + * according to the specified order, \p order, in the specified index, + * \p index. + * + * If \p loc_id specifies the group in which the link resides, + * \p group_name can be a dot (\c .). + * + * \see H5Ldelete() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Returns the value of a link + * + * \fgdta_loc_id + * \param[in] name Link name + * \param[out] buf The buffer to hold the link value + * \param[in] size Maximum number of bytes of link value to be returned + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Lget_val() returns tha value of link \p name. For smbolic links, + * this is the path to which the link points, including the null + * terminator. For external and user-defined links, it is the link + * buffer. + * + * \p size is the size of \p buf and should be the size of the link + * value being returned. This size value can be determined through a + * call to H5Lget_info(); it is returned in the \c val_size field of + * the \ref H5L_info_t \c struct. + * + * If \p size is smaller than the size of the returned value, then the + * string stored in \p buf will be truncated to \p size bytes. For + * soft links, this means that the value will not be null terminated. + * + * In the case of external links, the target file and object names are + * extracted from \p buf by calling H5Lunpack_elink_val(). + * + * The link class of link \p name can be determined with a call to + * H5Lget_info(). + * + * \p lapl_id specifies the link access property list associated with + * the link \p name. In the general case, when default link access + * properties are acceptable, this can be passed in as #H5P_DEFAULT. An + * example of a situation that requires a non-default link access + * property list is when the link is an external link; an external + * link may require that a link prefix be set in a link access + * property list (see H5Pset_elink_prefix()). + * + * This function should be used only after H5Lget_info() has been + * called to verify that \p name is a symbolic link. This can be + * deteremined from the \c link_type field of the \ref H5L_info_t + * \c struct. + * + * \note This function will fail if called on a hard link. + * + * \see H5Lget_val_by_idx() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size_t size, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Retrieves value of the \Emph{n}-th link in a group, according to the order within an index + * + * \fgdta_loc_id + * \param[in] group_name Group name + * \param[in] idx_type Type of index + * \param[in] order Order within field or index + * \param[in] n Link position for which to retrieve information + * \param[out] buf The buffer to hold the link value + * \param[in] size Maximum number of bytes of link value to be returned + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Lget_val_by_idx() retrieves the value of the \Emph{n}-th link in + * a group, according to the specified order, \p order, within an + * index, \p index. + * + * For soft links, the value is an HDF5 path name. + * + * For external links, this is a compound value containing file and + * path name information; to use this external link information, it + * must first be decoded with H5Lunpack_elink_val() + * + * For user-defined links, this value will be described in the + * definition of the user-defined link type. + * + * \p loc_id specifies the location identifier of the group specified + * by \p group_name. + * + * \p group_name specifies the group in which the link exists. If + * \p loc_id already specifies the group in which the link exists, + * \p group_name must be a dot (\c .). + * + * The size in bytes of link_val is specified in \p size. The size + * value can be determined through a call to H5Lget_info_by_idx(); it + * is returned in the \c val_size field of the \ref H5L_info_t + * \c struct. If + * size is smaller than the size of the returned value, then the + * string stored in link_val will be truncated to size bytes. For soft + * links, this means that the value will not be null terminated. + * + * If the type of the link is unknown or uncertain, H5Lget_val_by_idx() + * should be called only after the type has been determined via a call + * to H5Lget_info_by_idx(). + * + * \note This function will fail if called on a hard link. + * + * \see H5Lget_val() + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, void *buf /*out*/, size_t size, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Determines whether a link with the specified name exists in a group + * + * \fgdta_loc_id + * \param[in] name Link name + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Lexists() allows an application to determine whether the link \p + * name exists in the location specified by \p loc_id. The link may be + * of any type; only the presence of a link with that name is checked. + * + * Note that H5Lexists() verifies only that the target link exists. If + * name includes either a relative path or an absolute path to the + * target link, intermediate steps along the path must be verified + * before the existence of the target link can be safely checked. If + * the path is not verified and an intermediate element of the path + * does not exist, H5Lexists() will fail. The example in the next + * paragraph illustrates one step-by-step method for verifying the + * existence of a link with a relative or absolute path. + * + * \Bold{Example:} Use the following steps to verify the existence of + * the link \c datasetD in the \c group group1/group2/softlink_to_group3/, + * where \c group1 is a member of the group specified by \c loc_id: + * + * 1. First use H5Lexists() to verify that \c group1 exists. + * 2. If \c group1 exists, use H5Lexists() again, this time with name + * set to \c group1/group2, to verify that \c group2 exists. + * 3. If \c group2 exists, use H5Lexists() with name set to + * \c group1/group2/softlink_to_group3 to verify that + * \c softlink_to_group3 exists. + * 4. If \c softlink_to_group3 exists, you can now safely use + * H5Lexists() with \c name set to + * \c group1/group2/softlink_to_group3/datasetD to verify that the + * target link, \c datasetD, exists. + * + * If the link to be verified is specified with an absolute path, the + * same approach should be used, but starting with the first link in + * the file’s root group. For instance, if \c datasetD were in + * \c /group1/group2/softlink_to_group3, the first call to H5Lexists() + * would have name set to \c /group1. + * + * Note that this is an outline and does not include all necessary + * details. Depending on circumstances, for example, you may need to + * verify that an intermediate link points to a group and that a soft + * link points to an existing target. + * + * \note The behavior of H5Lexists() was changed in the 1.10 release in the + * case where the root group, \c "/", is the name of the link. This + * change is described below: + * <ol> + * <li>Let \c file denote a valid HDF5 file identifier, and let \c lapl + * denote a valid link access property list identifier. A call to + * H5Lexists() with arguments \c file, \c "/", and \c lapl + * returns a positive value; in other words, + * \Code{H5Lexists(file, "/", lapl)} returns a positive value. + * In HDF5 version 1.8.16, this function returns 0.</li> + * <li>Let \c root denote a valid HDF5 group identifier that refers to the + * root group of an HDF5 file, and let \c lapl denote a valid link + * access property list identifier. A call to H5Lexists() with + * arguments c root, \c "/", and \c lapl returns a positive value; + * in other words, \Code{H5Lexists(root, "/", lapl)} returns a postive + * value. In HDF5 version 1.8.16, this function returns 0.</li> + * </ol> + * Note that the function accepts link names and path names. This is + * potentially misleading to callers, and we plan to separate the + * functionality for link names and path names in a future release. + * + * \attention H5Lexists() checks the existence of only the final element in a + * relative or absolute path; it does not check any other path + * elements. The function will therefore fail when both of the + * following conditions exist: + * - \c name is not local to the group specified by \c loc_id or, + * if \c loc_id is something other than a group identifier, \c name + * is not local to the root group. + * - Any element of the relative path or absolute path in name, + * except the target link, does not exist. + * + * \version 1.10.0 Function behavior changed in this release. (See the note.) + * \since 1.8.0 + * + */ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id); -H5_DLL herr_t H5Lget_info2(hid_t loc_id, const char *name, H5L_info2_t *linfo /*out*/, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Returns information about a link + * + * \fgdta_loc_id + * \param[in] name Link name + * \param[out] linfo Buffer in which link information is returned + * \lapl_id + * + * \return \herr_t + * + * \todo We need to get the location ID story straight! + * + * \details H5Lget_info2() returns information about the specified link through + * the \p linfo argument. + * + * The location identifier, \p loc_id, specifies the location of the + * link. A link name, \p name, interpreted relative to \p loc_id, + * specifies the link being queried. + * + * \p lapl_id is the link access property list associated with the + * link name. In the general case, when default link access properties + * are acceptable, this can be passed in as #H5P_DEFAULT. An example + * of a situation that requires a non-default link access property + * list is when the link is an external link; an external link may + * require that a link prefix be set in a link access property list + * (see H5Pset_elink_prefix()). + * + * H5Lget_info2() returns information about name in the data structure + * H5L_info2_t, which is described below and defined in H5Lpublic.h. + * This structure is returned in the buffer \p linfo. + * \snippet this H5L_info2_t_snip + * In the above struct, \c type specifies the link class. Valid values + * include the following: + * \link_types + * There will be additional valid values if user-defined links have + * been registered. + * + * \p corder specifies the link’s creation order position while + * \p corder_valid indicates whether the value in corder is valid. + * + * If \p corder_valid is \c TRUE, the value in \p corder is known to + * be valid; if \p corder_valid is \c FALSE, the value in \p corder is + * presumed to be invalid; \p corder starts at zero (0) and is + * incremented by one (1) as new links are created. But + * higher-numbered entries are not adjusted when a lower-numbered link + * is deleted; the deleted link's creation order position is simply + * left vacant. In such situations, the value of \p corder for the + * last link created will be larger than the number of links remaining + * in the group. + * + * \p cset specifies the character set in which the link name is + * encoded. Valid values include the following: + * \csets + * This value is set with H5Pset_char_encoding(). + * + * \c token is the location that a hard link points to, and + * \c val_size is the size of a soft link or user defined link value. + * H5O_token_t is used in the VOL layer. It is defined in H5public.h + * as: + * \snippet H5public.h H5O_token_t_snip + * + * If the link is a symbolic link, \c val_size will be the length of + * the link value, e.g., the length of the HDF5 path name with a null + * terminator. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Lget_info2(hid_t loc_id, const char *name, H5L_info2_t *linfo, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Retrieves metadata for a link in a group, according to the order + * within a field or index + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in] n Link position for which to retrieve information + * \param[out] linfo Buffer in which link information is returned + * \lapl_id + * + * \return \herr_t + * + * \details H5get_info_by_idx2() returns the metadata for a link in a group + * according to a specified field or index and a specified order. The + * link for which information is to be returned is specified by \p + * idx_type, \p order, and \p n as follows: + * + * - \p idx_type specifies the field by which the links in \p + * group_name are ordered. The links may be indexed on this field, + * in which case operations seeking specific links are likely to + * complete more quickly. + * - \p order specifies the order in which + * the links are to be referenced for the purposes of this function. + * - \p n specifies the position of the subject link. Note that this + * count is zero-based; 0 (zero) indicates that the function will + * return the value of the first link; if \p n is 5, the function + * will return the value of the sixth link; etc. + * + * For example, assume that \p idx_type, \p order, and \p n are + * #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME + * indicates that the links are accessed in lexicographic order by + * their names. #H5_ITER_DEC specifies that the list be traversed in + * reverse order, or in decremented order. And 5 specifies that this + * call to the function will return the metadata for the 6th link + * (\c n + 1) from the end. + * + * See H5Literate2() for a list of valid values and further discussion + * regarding \p idx_type and \p order. + * + * If \p loc_id specifies the group in which the link resides, + * \p group_name can be a dot (\c .). + * + * \since 1.12.0 + * + * \see H5Lget_info2() + * + * \todo Document H5Lget_info_by_idx() + * + */ H5_DLL herr_t H5Lget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo /*out*/, - hid_t lapl_id); + H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Retrieves name of the \Emph{n}-th link in a group, according to the + * order within a specified field or index + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in] n Link position for which to retrieve information + * \param[out] name Buffer in which link name is returned + * \param[in] size Size in bytes of \p name + * \lapl_id + * + * \return Returns the size of the link name if successful; otherwise returns a + * negative value. + * + * \details H5get_name_by_idx() retrieves the name of the \Emph{n}-th link in a + * group, according to the specified order, \p order, within a specified + * field or index, \p idx_type. + * + * \p idx_type specifies the index that is used. Valid values include + * the following: + * \indexes + * + * \p order specifies the order in which objects are inspected along + * the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * If \p loc_id specifies the group in which the link resides, + * \p group_name can be a dot (\c .). + * + * The size in bytes of name is specified in \p size. If \p size is + * unknown, it can be determined via an initial H5Lget_name_by_idx() + * call with name set to NULL; the function's return value will be the + * size of the name. + * + * \note Please note that in order for the specified index to correspond to the + * creation order index, \p order must be set to #H5_ITER_INC or + * #H5_ITER_DEC when calling H5Lget_name_by_idx(). \note The index \p n + * passed to H5Lget_name_by_idx() is the index of the link within the + * link table, sorted according to \p order and \p idx_type. If order is + * #H5_ITER_NATIVE, then the link table is not sorted, and it does not + * matter what \p idx_type is. Specifying #H5_ITER_NATIVE does not + * guarantee any particular order, only that it remains consistent. + * + * \since 1.8.0 + * + */ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size, hid_t lapl_id); -H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, - H5L_iterate2_t op, void *op_data); -H5_DLL herr_t H5Literate_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t *idx, H5L_iterate2_t op, void *op_data, - hid_t lapl_id); -H5_DLL herr_t H5Lvisit2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, - void *op_data); -H5_DLL herr_t H5Lvisit_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type, - H5_iter_order_t order, H5L_iterate2_t op, void *op_data, hid_t lapl_id); - +/** + * \ingroup TRAV + * + * \brief Iterates over links in a group, with user callback routine, + * according to the order within an index. + * + * \group_id{grp_id} + * \idx_type + * \order + * \param[in,out] idx Pointer to an iteration index to allow + * continuing a previous iteration + * \op + * \op_data + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Literate2() iterates through the links in a file or + * group, \p group_id, in the order of the specified + * index, \p idx_type, using a user-defined callback routine + * \p op. H5Literate2() does not recursively follow links into + * subgroups of the specified group. + * + * Three parameters are used to manage progress of the iteration: + * \p idx_type, \p order, and \p idx_p. + * + * \p idx_type specifies the index to be used. If the links have + * not been indexed by the index type, they will first be sorted by + * that index then the iteration will begin; if the links have been + * so indexed, the sorting step will be unnecessary, so the iteration + * may begin more quickly. + * + * \p order specifies the order in which objects are to be inspected + * along the index \p idx_type. + * + * \p idx_p tracks the iteration and allows an iteration to be + * resumed if it was stopped before all members were processed. It is + * passed in by the application with a starting point and returned by + * the library with the point at which the iteration stopped. + * + * \p op_data is a user-defined pointer to the data required to + * process links in the course of the iteration. This pointer is + * passed back to each step of the iteration in the \p op callback + * function's \p op_data parameter. \p op is invoked for each link + * encounter. + * + * \p op_data is passed to and from each iteration and can be used to + * supply or aggregate information across iterations. + * + * \remark Same pattern of behavior as H5Giterate(). + * + * \note This function is also available through the H5Literate() macro. + * + * \warning The behavior of H5Literate2() is undefined if the link + * membership of \p group_id changes during the iteration. + * This does not limit the ability to change link destinations + * while iterating, but caution is advised. + * + * + * \since 1.12.0 + * + * \see H5Literate_by_name2(), H5Lvisit2(), H5Lvisit_by_name2() + * + */ +H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, + H5L_iterate2_t op, void *op_data); +/** + * \ingroup TRAV + * + * \brief Iterates through links in a group + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in,out] idx iteration position at which to start (\Emph{IN}) or + * position at which an interrupted iteration may be restarted + * (\Emph{OUT}) + * \op + * \op_data + * \lapl_id + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Literate_by_name2() iterates through the links in a group + * specified by \p loc_id and \p group_name, in the order of the + * specified index, \p idx_type, using a user-defined callback routine + * \p op. H5Literate_by_name2() does not recursively follow links into + * subgroups of the specified group. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecessary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * \p idx_p allows an interrupted iteration to be resumed; it is + * passed in by the application with a starting point and returned by + * the library with the point at which the iteration stopped. + * + * \note H5Literate_by_name2() is not recursive. In particular, if a member of + * \p group_name is found to be a group, call it \c subgroup_a, + * H5Literate_by_name2() does not examine the members of \c subgroup_a. + * When recursive iteration is required, the application must handle the + * recursion, explicitly calling H5Literate_by_name2() on discovered + * subgroups. + * + * \note H5Literate_by_name2() assumes that the membership of the group being + * iterated over remains unchanged through the iteration; if any of the + * links in the group change during the iteration, the function’s + * behavior is undefined. Note, however, that objects pointed to by the + * links can be modified. + * + * \note H5Literate_by_name2() is the same as H5Literate2(), except that + * H5Literate2() always proceeds in alphanumeric order. + * + * \since 1.12.0 + * + * \see H5Literate(), H5Lvisit() + * + */ +H5_DLL herr_t H5Literate_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type, + H5_iter_order_t order, hsize_t *idx, H5L_iterate2_t op, void *op_data, + hid_t lapl_id); +/** + * \ingroup TRAV + * + * \brief Recursively visits all links starting from a specified group + * + * \group_id{grp_id} + * \idx_type + * \order + * \op + * \op_data + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \details H5Lvisit2() is a recursive iteration function to visit all links in + * and below a group in an HDF5 file, thus providing a mechanism for + * an application to perform a common set of operations across all of + * those links or a dynamically selected subset. For non-recursive + * iteration across the members of a group, see H5Literate2(). + * + * The group serving as the root of the iteration is specified by its + * group or file identifier, \p group_id. + * + * Two parameters are used to establish the iteration: \p idx_type and + * \p order. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecessary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * Note that the index type passed in \p idx_type is a best effort + * setting. If the application passes in a value indicating iteration + * in creation order and a group is encountered that was not tracked + * in creation order, that group will be iterated over in + * lexicographic order by name, or name order. (Name order is the + * native order used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * \p op is a callback function of type \ref H5L_iterate2_t that is invoked + * for each link encountered. + * \snippet this H5L_iterate2_t_snip + * + * The \ref H5L_info2_t struct is defined (in H5Lpublic.h) as follows: + * \snippet this H5L_info2_t_snip + * + * The possible return values from the callback function, and the + * effect of each, are as follows: + * \li Zero causes the visit iterator to continue, returning zero when + * all group members have been processed. + * \li A positive value causes the visit iterator to immediately + * return that positive value, indicating short-circuit success. + * \li A negative value causes the visit iterator to immediately + * return that value, indicating failure. + * + * The H5Lvisit2() \p op_data parameter is a user-defined pointer to + * the data required to process links in the course of the iteration. + * This pointer is passed back to each step of the iteration in the + * \p op callback function's \p op_data parameter. + * + * H5Lvisit2() and H5Ovisit2() are companion functions: one for + * examining and operating on links; the other for examining and + * operating on the objects that those links point to. Both functions + * ensure that by the time the function completes successfully, every + * link or object below the specified point in the file has been + * presented to the application for whatever processing the + * application requires. + * + * \since 1.12.0 + * + * \see H5Literate() + * + */ +H5_DLL herr_t H5Lvisit2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, + void *op_data); +/** + * \ingroup TRAV + * + * \brief Recursively visits all links starting from a specified group + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \op + * \op_data + * \lapl_id + * + * \return \herr_t + * + * \details H5Lvisit_by_name2() is a recursive iteration function to visit all + * links in and below a group in an HDF5 file, thus providing a + * mechanism for an application to perform a common set of operations + * across all of those links or a dynamically selected subset. For + * non-recursive iteration across the members of a group, see + * H5Literate2(). + * + * The group serving as the root of the iteration is specified by the + * \p loc_id / \p group_name parameter pair. \p loc_id specifies a + * file or group; group_name specifies either a group in the file + * (with an absolute name based in the file’s root group) or a group + * relative to \p loc_id. If \p loc_id fully specifies the group that + * is to serve as the root of the iteration, group_name should be '.' + * (a dot). (Note that when \p loc_id fully specifies the the group + * that is to serve as the root of the iteration, the user may wish to + * consider using H5Lvisit2() instead of H5Lvisit_by_name2().) + * + * Two parameters are used to establish the iteration: \p idx_type and + * \p order. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecesary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * Note that the index type passed in \p idx_type is a best effort + * setting. If the application passes in a value indicating iteration + * in creation order and a group is encountered that was not tracked + * in creation order, that group will be iterated over in + * lexicographic order by name, or name order. (Name order is the + * native order used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * The \p op callback function, the related \ref H5L_info2_t + * \c struct, and the effect that the callback function's return value + * has on the application are described in H5Lvisit2(). + * + * The H5Lvisit_by_name2() \p op_data parameter is a user-defined + * pointer to the data required to process links in the course of the + * iteration. This pointer is passed back to each step of the + * iteration in the callback function's \p op_data parameter. + * + * \p lapl_id is a link access property list. In the general case, + * when default link access properties are acceptable, this can be + * passed in as #H5P_DEFAULT. An example of a situation that requires + * a non-default link access property list is when the link is an + * external link; an external link may require that a link prefix be + * set in a link access property list (see H5Pset_elink_prefix()). + * + * H5Lvisit_by_name2() and H5Ovisit_by_name2() are companion + * functions: one for examining and operating on links; the other for + * examining and operating on the objects that those links point to. + * Both functions ensure that by the time the function completes + * successfully, every link or object below the specified point in the + * file has been presented to the application for whatever processing + * the application requires. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Lvisit_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type, + H5_iter_order_t order, H5L_iterate2_t op, void *op_data, hid_t lapl_id); /* UD link functions */ +/** + * \ingroup H5L + * + * \brief Creates a link of a user-defined type + * + * \loc_id{link_loc_id} + * \param[in] link_name Link name + * \param[in] link_type User-defined link class + * \param[in] udata User-supplied link information + * \param[in] udata_size Size of udata buffer + * \lcpl_id + * \lapl_id + * + * \return \herr_t + * + * \details H5Lcreate_ud() creates a link of user-defined type \p link_type + * named \p link_name at the location specified in \p link_loc_id with + * user-specified data \p udata. + * + * \p link_name is interpreted relative to \p link_loc_id. + * + * Valid values for the link class of the new link, \p link_type, + * include #H5L_TYPE_EXTERNAL and any user-defined link classes that + * have been registered with the library. See H5Lregister() for + * further information. + * + * The format of the information pointed to by \p udata is defined by + * the user. \p udata_size specifies the size of the \p udata buffer. + * \p udata may be NULL if \p udata_size is zero (0). + * + * The property lists specified by \p lcpl_id and \p lapl_id specify + * properties used to create and access the link. + * + * \note The external link type, #H5L_TYPE_EXTERNAL, included in the HDF5 + * library distribution, is implemented as a user-defined link type. This + * was done, in part, to provide a model for the implementation of other + * user-defined links. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id); +/** + * \ingroup H5LA + * + * \brief Registers a user-defined link class or changes behavior of an + * existing class + * + * \param[in] cls Pointer to a buffer containing the struct describing the + * user-defined link class + * + * \return \herr_t + * + * \details H5Lregister() registers a class of user-defined links, or changes + * the behavior of an existing class. + * + * \p cls is a pointer to a buffer containing a copy of the + * H5L_class_t struct. This struct is defined in H5Lpublic.h as + * follows: + * \snippet this H5L_class_t_snip + * + * The class definition passed with \p cls must include at least the + * following: + * \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS) + * \li A link class identifier, \c class_id + * \li A traversal function, \c trav_func + * + * Remaining \c struct members are optional and may be passed as NULL. + * + * The link class passed in \c class_id must be in the user-definable + * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX + * (see the table below) and will override + * any existing link class with that identifier. + * + * As distributed, valid values of \c class_id used in HDF5 include + * the following (defined in H5Lpublic.h): + * \link_types + * + * The hard and soft link class identifiers cannot be modified or + * reassigned, but the external link class is implemented as an + * example in the user-definable link class identifier range. + * H5Lregister() is used to register additional link classes. It could + * also be used to modify the behavior of the external link class, + * though that is not recommended. + * + * The following table summarizes existing link types and values and + * the reserved and user-definable link class identifier value ranges. + * <table> + * <tr> + * <th>Link class identifier or Value range</th> + * <th>Description</th> + * <th>Link class or label</th> + * </tr> + * <tr> + * <td>0 to 63</td> + * <td>Reserved range</td> + * <td></td> + * </tr> + * <tr> + * <td>64 to 255</td> + * <td>User-definable range</td> + * <td></td> + * </tr> + * <tr> + * <td>64</td> + * <td>Minimum user-defined value</td> + * <td>#H5L_TYPE_UD_MIN</td> + * </tr> + * <tr> + * <td>64</td> + * <td>External link</td> + * <td>#H5L_TYPE_EXTERNAL</td> + * </tr> + * <tr> + * <td>255</td> + * <td>Maximum user-defined value</td> + * <td>#H5L_TYPE_UD_MAX</td> + * </tr> + * <tr> + * <td>255</td> + * <td>Maximum value</td> + * <td>#H5L_TYPE_MAX</td> + * </tr> + * <tr> + * <td>-1</td> + * <td>Error</td> + * <td>#H5L_TYPE_ERROR</td> + * </tr> + * </table> + * + * Note that HDF5 internally registers user-defined link classes only + * by the numeric value of the link class identifier. An application, + * on the other hand, will generally use a name for a user-defined + * class, if for no other purpose than as a variable name. Assume, + * for example, that a complex link type is registered with the link + * class identifier 73 and that the code includes the following + * assignment: + * \code + * H5L_TYPE_COMPLEX_A = 73 + * \endcode + * The application can refer to the link class with a term, + * \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing + * the code, while HDF5 recognizes it by the more cryptic numeric + * identifier, 73. + * + * \attention Important details and considerations include the following: + * \li If you plan to distribute files or software with a + * user-defined link class, please contact the Help Desk at + * The HDF Group to help prevent collisions between \c class_id + * values. See below. + * \li As distributed with HDF5, the external link class is + * implemented as an example of a user-defined link class with + * #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in + * the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN + * unless you intend to overwrite or modify the behavior of + * external links. + * \li H5Lregister() can be used only with link class identifiers + * in the user-definable range (see table above). + * \li The hard and soft links defined by the HDF5 library, + * #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved + * range below #H5L_TYPE_UD_MIN and cannot be redefined or + * modified. + * \li H5Lis_registered() can be used to determine whether a desired + * link class identifier is available. \Emph{Note that this + * function will tell you only whether the link class identifier + * has been registered with the installed copy of HDF5; it + * cannot tell you whether the link class has been registered + * with The HDF Group.} + * \li #H5L_TYPE_MAX is the maximum allowed value for a link type + * identifier. + * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL. + * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX. + * \li #H5L_TYPE_ERROR indicates that an error has occurred. + * + * \note \Bold{Registration with The HDF Group:}\n + * There are sometimes reasons to take a broader approach to registering + * a user-defined link class than just invoking H5Lregister(). For + * example: + * \li A user-defined link class is intended for use across an + * organization, among collaborators, or across a community of users. + * \li An application or library overlying HDF5 invokes a user-defined + * link class that must be shipped with the software. + * \li Files are distributed that make use of a user-defined link class. + * \li Or simply, a specific user-defined link class is thought to be + * widely useful. + * + * In such cases, you are encouraged to register that link class with + * The HDF Group's Helpdesk. The HDF Group maintains a registry of known + * user-defined link classes and tracks the selected link class + * identifiers. This registry is intended to reduce the risk of + * collisions between \c class_id values and to help coordinate the use + * of specialized link classes. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lregister(const H5L_class_t *cls); +/** + * \ingroup H5LA + * + * \brief Unregisters a class of user-defined links + * + * \param[in] id User-defined link class identifier + * + * \return \herr_t + * + * \details H5Lunregister() unregisters a class of user-defined links, + * preventing them from being traversed, queried, moved, etc. + * + * \note A link class can be re-registered using H5Lregister(). + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lunregister(H5L_type_t id); +/** + * \ingroup H5LA + * + * \brief Determines whether a class of user-defined links is registered + * + * \param[in] id User-defined link class identifier + * + * \return \htri_t + * + * \details H5Lis_registered() tests whether a user-defined link class is + * currently registered, either by the HDF5 library or by the user + * through the use of H5Lregister(). + * + * \note A link class must be registered to create new links of that type or to + * traverse existing links of that type. + * + * \since 1.8.0 + * + */ H5_DLL htri_t H5Lis_registered(H5L_type_t id); /* External link functions */ +/** + * \ingroup H5L + * + * \brief Decodes external link information + * + * \param[in] ext_linkval Buffer containing external link information + * \param[in] link_size Size, in bytes, of the \p ext_linkval buffer + * \param[out] flags External link flags, packed as a bitmap (\Emph{Reserved as + * a bitmap for flags; no flags are currently defined, so the + * only valid value * is 0.}) + * \param[out] filename Returned filename \param[out] obj_path Returned + * object path, relative to \p filename + * + * \return \herr_t + * + * \details H5Lunpack_elink_val() decodes the external link information + * returned by H5Lget_val() in the \p ext_linkval buffer. + * + * \p ext_linkval should be the buffer set by H5Lget_val() and will + * consist of two NULL-terminated strings, the filename and object + * path, one after the other. + * + * Given this buffer, H5Lunpack_elink_val() creates pointers to the + * filename and object path within the buffer and returns them in + * \p filename and \p obj_path, unless they are passed in as NULL. + * + * H5Lunpack_elink_val() requires that \p ext_linkval contain a + * concatenated pair of null-terminated strings, so use of this + * function on a string that is not an external link \p udata buffer + * may result in a segmentation fault. This failure can be avoided by + * adhering to the following procedure: + * <ol> + * <li>Call H5Lget_info() to get the link type and the size of the + * link value.<li> + * <li>Verify that the link is an external link, i.e., that its link + * type is #H5L_TYPE_EXTERNAL.</li> + * <li>Call H5Lget_val() to get the link value.</li> + * <li>Call H5Lunpack_elink_val() to unpack that value.</li> + * </ol> + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_size, unsigned *flags, const char **filename /*out*/, const char **obj_path /*out*/); +/** + * \ingroup H5L + * + * \brief Creates an external link, a soft link to an object in a different file. + * + * \param[in] file_name Name of the target file containing the target object. + * \param[in] obj_name Path within the target file to the target object + * \fgdt_loc_id{link_loc_id} + * \param[in] link_name Name of the new link, relative to \p link_loc_id + * \lcpl_id + * \lapl_id + * \return \herr_t + * + * \details H5Lcreate_external() creates a new external link. An external link + * is a soft link to an object in a different HDF5 file from the + * location of the link, i.e., to an external object. + * + * \p file_name identifies the target file containing the target + * object; \p obj_name specifies the path of the target object within + * that file. \p obj_name must be an absolute pathname in + * \p file_name, i.e., it must start at the target file’s root group, + * but it is not interpreted until an application attempts to traverse + * it. + * + * \p link_loc_id and \p link_name specify the location and name, + * respectively, of the new link. \p link_name is interpreted relative + * to \p link_loc_id. + * + * \p lcpl_id is the link creation property list used in creating the + * new link. + * + * \p lapl_id is the link access property list used in traversing the + * new link. Note that an external file opened by the traversal of an + * external link is always opened with the weak file close degree + * property setting, #H5F_CLOSE_WEAK (see H5Pset_fclose_degree()); + * any file close degree property setting in \p lapl_id is ignored. + * + * An external link behaves similarly to a soft link, and like a soft + * link in an HDF5 file, it may dangle: the target file and object + * need not exist at the time that the external link is created. + * + * When the external link \p link_name is accessed, the library will + * search for the target file \p file_name as described below: + * + * - If \p file_name is a relative pathname, the following steps are + * performed: + * - The library will get the prefix(es) set in the environment + * variable \c HDF5_EXT_PREFIX and will try to prepend each prefix + * to \p file_name to form a new \p file_name. + * - If the new \p file_name does not exist or if \c HDF5_EXT_PREFIX + * is not set, the library will get the prefix set via + * H5Pset_elink_prefix() and prepend it to \p file_name to form a + * new \p file_name. + * - If the new \p file_name does not exist or no prefix is being + * set by H5Pset_elink_prefix(), then the path of the file + * associated with \p link_loc_id is obtained. This path can be + * the absolute path or the current working directory plus the + * relative path of that file when it is created/opened. The + * library will prepend this path to \p file_name to form a new + * \p file_name. + * - If the new \p file_name does not exist, then the library will + * look for \p file_name and will return failure/success + * accordingly. + * - If \p file_name is an absolute pathname, the library will first + * try to find \p file_name. If \p file_name does not exist, + * \p file_name is stripped of directory paths to form a new + * \p file_name. The search for the new \p file_name then follows + * the same steps as described above for a relative pathname. See + * examples below illustrating how target_file_name is stripped to + * form a new \p file_name. + * + * Note that \p file_name is considered to be an absolute pathname + * when the following condition is true: + * + * - For Unix, the first character of \p file_name is a slash (\c /). + * For example, consider a \p file_name of \c /tmp/A.h5. + * If that target file does not exist, the new \p file_name after + * stripping will be \c A.h5. + * - For Windows, there are 6 cases: + * -# \p file_name is an absolute drive with absolute pathname. + * For example, consider a \p file_name of \c /tmp/A.h5. If that + * target file does not exist, the new \p file_name after + * stripping will be \c A.h5. + * -# \p file_name is an absolute pathname without specifying drive + * name. For example, consider a \p file_name of \c /tmp/A.h5. + * If that target file does not exist, the new \p file_name after + * stripping will be \c A.h5. + * -# \p file_name is an absolute drive with relative pathname. + * For example, consider a \p file_name of \c /tmp/A.h5. If that + * target file does not exist, the new \p file_name after + * stripping will be \c tmp\A.h5. + * -# \p file_name is in UNC (Uniform Naming Convention) format with + * server name, share name, and pathname. For example, consider + * a \p file_name of \c /tmp/A.h5. If that target file does not + * exist, the new \p file_name after stripping will be \c A.h5. + * -# \p file_name is in Long UNC (Uniform Naming Convention) format + * with server name, share name, and pathname. For example, + * consider a \p file_name of \c /tmp/A.h5. If that target file + * does not exist, the new \p file_name after stripping will be + * \c A.h5. + * -# \p file_name is in Long UNC (Uniform Naming Convention) format + * with an absolute drive and an absolute pathname. For example, + * consider a \p file_name of \c /tmp/A.h5. If that target file + * does not exist, the new \p file_name after stripping will be + * \c A.h5. + * + * The library opens target file \p file_name with the file access + * property list that is set via H5Pset_elink_fapl() when the external + * link link_name is accessed. If no such property list is set, the + * library uses the file access property list associated with the file + * of \p link_loc_id to open the target file. + * + * If an application requires additional control over file access + * flags or the file access property list, see H5Pset_elink_cb(); this + * function enables the use of an external link callback function as + * described in H5L_elink_traverse_t(). + * + * \attention A file close degree property setting (H5Pset_fclose_degree()) in + * the external link file access property list or in the external + * link callback function will be ignored. A file opened by means of + * traversing an external link is always opened with the weak file + * close degree property setting, #H5F_CLOSE_WEAK . + * + * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_ud() + * + * \since 1.8.0 + */ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); @@ -205,49 +1605,507 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi /* Typedefs */ /* Information struct for link (for H5Lget_info1/H5Lget_info_by_idx1) */ +//! [H5L_info1_t_snip] typedef struct { - H5L_type_t type; /* Type of link */ - hbool_t corder_valid; /* Indicate if creation order is valid */ - int64_t corder; /* Creation order */ - H5T_cset_t cset; /* Character set of link name */ + H5L_type_t type; /**< Type of link */ + hbool_t corder_valid; /**< Indicate if creation order is valid */ + int64_t corder; /**< Creation order */ + H5T_cset_t cset; /**< Character set of link name */ union { - haddr_t address; /* Address hard link points to */ - size_t val_size; /* Size of a soft link or UD link value */ + haddr_t address; /**< Address hard link points to */ + size_t val_size; /**< Size of a soft link or UD link value */ } u; } H5L_info1_t; +//! [H5L_info1_t_snip] -/* Callback during link traversal */ +/** Callback during link traversal */ typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, size_t lnkdata_size, hid_t lapl_id); -/* User-defined link types */ +/** User-defined link types */ typedef struct { - int version; /* Version number of this struct */ - H5L_type_t id; /* Link type ID */ - const char * comment; /* Comment for debugging */ - H5L_create_func_t create_func; /* Callback during link creation */ - H5L_move_func_t move_func; /* Callback after moving link */ - H5L_copy_func_t copy_func; /* Callback after copying link */ - H5L_traverse_0_func_t trav_func; /* Callback during link traversal */ - H5L_delete_func_t del_func; /* Callback for link deletion */ - H5L_query_func_t query_func; /* Callback for queries */ + int version; /**< Version number of this struct */ + H5L_type_t id; /**< Link type ID */ + const char * comment; /**< Comment for debugging */ + H5L_create_func_t create_func; /**< Callback during link creation */ + H5L_move_func_t move_func; /**< Callback after moving link */ + H5L_copy_func_t copy_func; /**< Callback after copying link */ + H5L_traverse_0_func_t trav_func; /**< Callback during link traversal */ + H5L_delete_func_t del_func; /**< Callback for link deletion */ + H5L_query_func_t query_func; /**< Callback for queries */ } H5L_class_0_t; -/* Prototype for H5Literate1/H5Literate_by_name1() operator */ +/** Prototype for H5Literate1() / H5Literate_by_name1() operator */ +//! [H5L_iterate1_t_snip] typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info, void *op_data); +//! [H5L_iterate1_t_snip] /* Function prototypes */ +/** + * \ingroup H5L + * + * \brief Returns information about a link + * + * \fgdta_loc_id + * \param[in] name Link name + * \param[out] linfo Buffer in which link information is returned + * \lapl_id + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Lget_info2() or the macro H5Lget_info(). + * + * \todo We need to get the location ID story straight! + * + * \details H5Lget_info1() returns information about the specified link through + * the \p linfo argument. + * + * The location identifier, \p loc_id, specifies the location of the + * link. A link name, \p name, interpreted relative to \p loc_id, + * specifies the link being queried. + * + * \p lapl_id is the link access property list associated with the + * link \p name. In the general case, when default link access + * properties are acceptable, this can be passed in as #H5P_DEFAULT. + * An example of a situation that requires a non-default link access + * property list is when the link is an external link; an external + * link may require that a link prefix be set in a link access + * property list (see H5Pset_elink_prefix()). + * + * H5Lget_info1() returns information about name in the data structure + * \ref H5L_info1_t, which is described below and defined in + * H5Lpublic.h. This structure is returned in the buffer \p linfo. + * \snippet this H5L_info1_t_snip + * In the above struct, type specifies the link class. Valid values + * include the following: + * \link_types + * There will be additional valid values if user-defined links have + * been registered. + * + * \c corder specifies the link’s creation order position while + * \c corder_valid indicates whether the value in \c corder is valid. + * + * If \c corder_valid is \c TRUE, the value in \c corder is known to + * be valid; if \c corder_valid is \c FALSE, the value in \c corder is + * presumed to be invalid; + * + * \c corder starts at zero (0) and is incremented by one (1) as new + * links are created. But higher-numbered entries are not adjusted + * when a lower-numbered link is deleted; the deleted link’s creation + * order position is simply left vacant. In such situations, the value + * of \c corder for the last link created will be larger than the + * number of links remaining in the group. + * + * \c cset specifies the character set in which the link name is + * encoded. Valid values include the following: + * \csets + * This value is set with H5Pset_char_encoding(). + * + * \c address and \c val_size are returned for hard and symbolic + * links, respectively. Symbolic links include soft and external links + * and some user-defined links. + * + * If the link is a hard link, \c address specifies the file address + * that the link points to. + * + * If the link is a symbolic link, \c val_size will be the length of + * the link value, e.g., the length of the HDF5 path name with a null + * terminator. + * + * \version 1.12.0 Function was deprecated. + * \version 1.8.2 Fortran subroutine added in this release. + * \version 1.8.4 Fortran subroutine syntax changed in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lget_info1(hid_t loc_id, const char *name, H5L_info1_t *linfo /*out*/, hid_t lapl_id); +/** + * \ingroup H5L + * + * \brief Retrieves metadata for a link in a group, according to the order + * within a field or index + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in] n Link position for which to retrieve information + * \param[out] linfo Buffer in which link information is returned + * \lapl_id + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Lget_info_by_idx2() and the macro + * H5Lget_info_by_idx(). + * + * \details H5get_info_by_idx1() returns the metadata for a link in a group + * according to a specified field or index and a specified order. + * + * The link for which information is to be returned is specified by \p + * idx_type, \p order, and \p n as follows: + * + * - \p idx_type specifies the field by which the links in \p + * group_name are ordered. The links may be indexed on this field, + * in which case operations seeking specific links are likely to + * complete more quickly. + * - \p order specifies the order in which + * the links are to be referenced for the purposes of this function. + * - \p n specifies the position of the subject link. Note that this + * count is zero-based; 0 (zero) indicates that the function will + * return the value of the first link; if \p n is 5, the function + * will return the value of the sixth link; etc. + * + * For example, assume that \p idx_type, \p order, and \p n are + * #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME + * indicates that the links are accessed in lexicographic order by + * their names. #H5_ITER_DEC specifies that the list be traversed in + * reverse order, or in decremented order. And 5 specifies that this + * call to the function will return the metadata for the 6th link + * (\c n + 1) from the end. + * + * See H5Literate1() for a list of valid values and further discussion + * regarding \p idx_type and \p order. + * + * If \p loc_id specifies the group in which the link resides, + * \p group_name can be a dot (\c .). + * + * \version 1.12.0 Function was renamed to H5Lget_index_by_idx1() and deprecated. + * \version 1.8.4 Fortran subroutine syntax changed in this release. + * \version 1.8.2 Fortran subroutine added in this release. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5L_info1_t *linfo /*out*/, hid_t lapl_id); +/** + * \ingroup TRAV + * + * \brief Iterates over links in a group, with user callback routine, + * according to the order within an index. + * + * \group_id{grp_id} + * \idx_type + * \order + * \param[in,out] idx Pointer to an iteration index to allow + * continuing a previous iteration + * \op + * \op_data + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \deprecated Deprecated in favor of H5Literate2(). + * + * \details H5Literate1() iterates through the links in a file or + * group, \p group_id, in the order of the specified + * index, \p idx_type, using a user-defined callback routine + * \p op. H5Literate1() does not recursively follow links into + * subgroups of the specified group. + * + * Three parameters are used to manage progress of the iteration: + * \p idx_type, \p order, and \p idx_p. + * + * \p idx_type specifies the index to be used. If the links have + * not been indexed by the index type, they will first be sorted by + * that index then the iteration will begin; if the links have been + * so indexed, the sorting step will be unnecessary, so the iteration + * may begin more quickly. + * + * \p order specifies the order in which objects are to be inspected + * along the index \p idx_type. + * + * \p idx_p tracks the iteration and allows an iteration to be + * resumed if it was stopped before all members were processed. It is + * passed in by the application with a starting point and returned by + * the library with the point at which the iteration stopped. + * + * \p op_data is a user-defined pointer to the data required to + * process links in the course of the iteration. This pointer is + * passed back to each step of the iteration in the \p op callback + * function's \p op_data parameter. \p op is invoked for each link + * encounter. + * + * \p op_data is passed to and from each iteration and can be used to + * supply or aggregate information across iterations. + * + * \remark Same pattern of behavior as H5Giterate(). + * + * \note This function is also available through the H5Literate() macro. + * + * \warning The behavior of H5Literate1() is undefined if the link + * membership of \p group_id changes during the iteration. + * This does not limit the ability to change link destinations + * while iterating, but caution is advised. + * + * + * \version 1.12.0 Function was deprecated in this release. + * \since 1.8.0 + * + * \see H5Literate_by_name2(), H5Lvisit2(), H5Lvisit_by_name2() + * + */ H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate1_t op, void *op_data); +/** + * \ingroup TRAV + * + * \brief Iterates through links in a group by its name + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \param[in,out] idx iteration position at which to start (\Emph{IN}) or + * position at which an interrupted iteration may be restarted + * (\Emph{OUT}) + * \op + * \op_data + * \lapl_id + * + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Literate_by_name2() or the macro + * H5Literate_by_name(). + * + * \details H5Literate_by_name1() iterates through the links in a group + * specified by \p loc_id and \p group_name, in the order of the + * specified index, \p idx_type, using a user-defined callback routine + * \p op. H5Literate_by_name1() does not recursively follow links into + * subgroups of the specified group. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecessary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * \p idx allows an interrupted iteration to be resumed; it is + * passed in by the application with a starting point and returned by + * the library with the point at which the iteration stopped. + * + * \note H5Literate_by_name1() is not recursive. In particular, if a member of + * \p group_name is found to be a group, call it \c subgroup_a, + * H5Literate_by_name1() does not examine the members of \c subgroup_a. + * When recursive iteration is required, the application must handle the + * recursion, explicitly calling H5Literate_by_name1() on discovered + * subgroups. + * + * \note H5Literate_by_name1() assumes that the membership of the group being + * iterated over remains unchanged through the iteration; if any of the + * links in the group change during the iteration, the function’s + * behavior is undefined. Note, however, that objects pointed to by the + * links can be modified. + * + * \note H5Literate_by_name1() is the same as H5Giterate(), except that + * H5Giterate() always proceeds in lexicographic order. + * + * \version 1.12.0 Function H5Literate_by_name() was renamed to + * H5Literate_by_name1() and deprecated. + * \version 1.8.8 Fortran subroutine added. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Literate_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate1_t op, void *op_data, hid_t lapl_id); +/** + * \ingroup TRAV + * + * \brief Recursively visits all links starting from a specified group + * + * \group_id{grp_id} + * \idx_type + * \order + * \op + * \op_data + * + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Lvisit2() or the macro H5Lvisit(). + * + * \details H5Lvisit1() is a recursive iteration function to visit all links in + * and below a group in an HDF5 file, thus providing a mechanism for + * an application to perform a common set of operations across all of + * those links or a dynamically selected subset. For non-recursive + * iteration across the members of a group, see H5Literate1(). + * + * The group serving as the root of the iteration is specified by its + * group or file identifier, \p group_id. + * + * Two parameters are used to establish the iteration: \p idx_type and + * \p order. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecessary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * Note that the index type passed in \p idx_type is a best effort + * setting. If the application passes in a value indicating iteration + * in creation order and a group is encountered that was not tracked + * in creation order, that group will be iterated over in + * lexicographic order by name, or name order. (Name order is the + * native order used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * \p op is a callback function of type \ref H5L_iterate1_t that is invoked + * for each link encountered. + * \snippet this H5L_iterate1_t_snip + * + * The \ref H5L_info1_t struct is defined (in H5Lpublic.h) as follows: + * \snippet this H5L_info1_t_snip + * + * The possible return values from the callback function, and the + * effect of each, are as follows: + * \li Zero causes the visit iterator to continue, returning zero when + * all group members have been processed. + * \li A positive value causes the visit iterator to immediately + * return that positive value, indicating short-circuit success. + * \li A negative value causes the visit iterator to immediately + * return that value, indicating failure. + * + * The H5Lvisit1() \p op_data parameter is a user-defined pointer to + * the data required to process links in the course of the iteration. + * This pointer is passed back to each step of the iteration in the + * \p op callback function's \p op_data parameter. + * + * H5Lvisit1() and H5Ovisit1() are companion functions: one for + * examining and operating on links; the other for examining and + * operating on the objects that those links point to. Both functions + * ensure that by the time the function completes successfully, every + * link or object below the specified point in the file has been + * presented to the application for whatever processing the + * application requires. + * + * \version 1.12.0 Function was renamed from H5Lvisit() to H5Lvisit1() and + * deprecated. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lvisit1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data); +/** + * \ingroup TRAV + * + * \brief Recursively visits all links starting from a specified group + * + * \loc_id + * \param[in] group_name Group name + * \idx_type + * \order + * \op + * \op_data + * \lapl_id + * + * \return \success{The return value of the first operator that returns + * non-zero, or zero if all members were processed with no + * operator returning non-zero.} + * \return \failure{Negative if an error occurs in the library, or the negative + * value returned by one of the operators.} + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * the function H5Lvisit_by_name2() or the macro H5Lvisit_by_name(). + * + * \details H5Lvisit_by_name1() is a recursive iteration function to visit all + * links in and below a group in an HDF5 file, thus providing a + * mechanism for an application to perform a common set of operations + * across all of those links or a dynamically selected subset. For + * non-recursive iteration across the members of a group, see + * H5Literate1(). + * + * The group serving as the root of the iteration is specified by the + * \p loc_id / \p group_name parameter pair. \p loc_id specifies a + * file or group; group_name specifies either a group in the file + * (with an absolute name based in the file’s root group) or a group + * relative to \p loc_id. If \p loc_id fully specifies the group that + * is to serve as the root of the iteration, group_name should be '.' + * (a dot). (Note that when \p loc_id fully specifies the the group + * that is to serve as the root of the iteration, the user may wish to + * consider using H5Lvisit1() instead of H5Lvisit_by_name1().) + * + * Two parameters are used to establish the iteration: \p idx_type and + * \p order. + * + * \p idx_type specifies the index to be used. If the links have not + * been indexed by the index type, they will first be sorted by that + * index then the iteration will begin; if the links have been so + * indexed, the sorting step will be unnecesary, so the iteration may + * begin more quickly. Valid values include the following: + * \indexes + * + * Note that the index type passed in \p idx_type is a best effort + * setting. If the application passes in a value indicating iteration + * in creation order and a group is encountered that was not tracked + * in creation order, that group will be iterated over in + * lexicographic order by name, or name order. (Name order is the + * native order used by the HDF5 library and is always available.) + * + * \p order specifies the order in which objects are to be inspected + * along the index specified in \p idx_type. Valid values include the + * following: + * \orders + * + * The \p op callback function, the related \ref H5L_info1_t + * \c struct, and the effect that the callback function's return value + * has on the application are described in H5Lvisit1(). + * + * The H5Lvisit_by_name1() \p op_data parameter is a user-defined + * pointer to the data required to process links in the course of the + * iteration. This pointer is passed back to each step of the + * iteration in the callback function's \p op_data parameter. + * + * \p lapl_id is a link access property list. In the general case, + * when default link access properties are acceptable, this can be + * passed in as #H5P_DEFAULT. An example of a situation that requires + * a non-default link access property list is when the link is an + * external link; an external link may require that a link prefix be + * set in a link access property list (see H5Pset_elink_prefix()). + * + * H5Lvisit_by_name1() and H5Ovisit_by_name1() are companion + * functions: one for examining and operating on links; the other for + * examining and operating on the objects that those links point to. + * Both functions ensure that by the time the function completes + * successfully, every link or object below the specified point in the + * file has been presented to the application for whatever processing + * the application requires. + * + * \version 1.12.0 Function renamed from H5Lvisit_by_name() to + * H5Lvisit_by_name1() and deprecated. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Lvisit_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data, hid_t lapl_id); @@ -38,7 +38,6 @@ /********************/ /* Local Prototypes */ /********************/ - static herr_t H5M__close_cb(H5VL_object_t *map_vol_obj); /*********************/ @@ -618,13 +617,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id) +H5Mget_count(hid_t map_id, hsize_t *count /*out*/, hid_t dxpl_id) { H5VL_object_t *vol_obj; /* Map structure */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(H5I_INVALID_HID) - H5TRACE3("e", "i*hi", map_id, count, dxpl_id); + H5TRACE3("e", "ixi", map_id, count, dxpl_id); /* Check args */ if (NULL == (vol_obj = (H5VL_object_t *)H5I_object_verify(map_id, H5I_MAP))) @@ -845,7 +844,7 @@ H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "i*hix*xi", map_id, idx, key_mem_type_id, op, op_data, dxpl_id); + H5TRACE6("e", "i*hiMI*xi", map_id, idx, key_mem_type_id, op, op_data, dxpl_id); /* Check arguments */ if (key_mem_type_id < 0) @@ -873,7 +872,7 @@ H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, /* Iterate over keys */ if ((ret_value = H5VL_optional(vol_obj, H5VL_MAP_SPECIFIC, dxpl_id, H5_REQUEST_NULL, &loc_params, H5VL_MAP_ITER, idx, key_mem_type_id, op, op_data)) < 0) - HGOTO_ERROR(H5E_MAP, H5E_BADITER, ret_value, "unable to ierate over keys") + HGOTO_ERROR(H5E_MAP, H5E_BADITER, ret_value, "unable to iterate over keys") done: FUNC_LEAVE_API(ret_value) @@ -919,7 +918,7 @@ H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_m herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*s*hix*xii", loc_id, map_name, idx, key_mem_type_id, op, op_data, dxpl_id, lapl_id); + H5TRACE8("e", "i*s*hiMI*xii", loc_id, map_name, idx, key_mem_type_id, op, op_data, dxpl_id, lapl_id); /* Check arguments */ if (!map_name) @@ -1202,7 +1202,7 @@ H5MF_xfree(H5F_t *f, H5FD_mem_t alloc_type, haddr_t addr, hsize_t size) #ifdef H5MF_ALLOC_DEBUG_MORE HDfprintf(stderr, "%s: After H5FS_sect_add()\n", FUNC); #endif /* H5MF_ALLOC_DEBUG_MORE */ - } /* end if */ + } /* end if */ else { htri_t merged; /* Whether node was merged */ H5MF_sect_ud_t udata; /* User data for callback */ @@ -1369,7 +1369,7 @@ H5MF_try_extend(H5F_t *f, H5FD_mem_t alloc_type, haddr_t addr, hsize_t size, hsi #ifdef H5MF_ALLOC_DEBUG_MORE HDfprintf(stderr, "%s: H5MF__aggr_try_extend = %t\n", FUNC, ret_value); -#endif /* H5MF_ALLOC_DEBUG_MORE */ +#endif /* H5MF_ALLOC_DEBUG_MORE */ } /* end if */ /* If no extension so far, try to extend into a free-space section */ @@ -1395,7 +1395,7 @@ H5MF_try_extend(H5F_t *f, H5FD_mem_t alloc_type, haddr_t addr, hsize_t size, hsi "error extending block in free space manager") #ifdef H5MF_ALLOC_DEBUG_MORE HDfprintf(stderr, "%s: Try to H5FS_sect_try_extend = %t\n", FUNC, ret_value); -#endif /* H5MF_ALLOC_DEBUG_MORE */ +#endif /* H5MF_ALLOC_DEBUG_MORE */ } /* end if */ /* For paged aggregation and a metadata block: try to extend into page end threshold */ @@ -1406,7 +1406,7 @@ H5MF_try_extend(H5F_t *f, H5FD_mem_t alloc_type, haddr_t addr, hsize_t size, hsi ret_value = TRUE; #ifdef H5MF_ALLOC_DEBUG_MORE HDfprintf(stderr, "%s: Try to extend into the page end threshold = %t\n", FUNC, ret_value); -#endif /* H5MF_ALLOC_DEBUG_MORE */ +#endif /* H5MF_ALLOC_DEBUG_MORE */ } /* end if */ } /* end if */ } /* allow_extend */ @@ -2944,7 +2944,7 @@ H5MF_settle_raw_data_fsm(H5F_t *f, hbool_t *fsm_settled) HDassert(fs_stat.serial_sect_count > 0); HDassert(fs_stat.alloc_sect_size > 0); HDassert(fs_stat.alloc_sect_size == fs_stat.sect_size); -#endif /* NDEBUG */ +#endif /* NDEBUG */ } /* end if */ else { HDassert(!H5F_addr_defined(fs_stat.addr)); diff --git a/src/H5MFsection.c b/src/H5MFsection.c index 597da76..473c1dc 100644 --- a/src/H5MFsection.c +++ b/src/H5MFsection.c @@ -648,7 +648,7 @@ H5MF__sect_small_add(H5FS_section_info_t **_sect, unsigned *flags, void *_udata) #ifdef H5MF_ALLOC_DEBUG_MORE HDfprintf(stderr, "%s: section is dropped\n", FUNC); #endif /* H5MF_ALLOC_DEBUG_MORE */ - } /* end if */ + } /* end if */ /* Adjust the section if it is not at page end but its size + prem is at page end */ else if (prem <= H5F_PGEND_META_THRES(udata->f)) { (*sect)->sect_info.size += prem; @@ -656,7 +656,7 @@ H5MF__sect_small_add(H5FS_section_info_t **_sect, unsigned *flags, void *_udata) HDfprintf(stderr, "%s: section is adjusted {%a, %Hu}\n", FUNC, (*sect)->sect_info.addr, (*sect)->sect_info.size); #endif /* H5MF_ALLOC_DEBUG_MORE */ - } /* end if */ + } /* end if */ done: FUNC_LEAVE_NOAPI(ret_value) @@ -52,8 +52,7 @@ /* Memory allocation "block", wrapped around each allocation */ struct H5MM_block_t; /* Forward declaration for typedef */ typedef struct H5MM_block_t { - unsigned char - sig[H5MM_SIG_SIZE]; /* Signature for the block, to indicate it was allocated with H5MM* interface */ + unsigned char sig[H5MM_SIG_SIZE]; /* Signature for the block, to indicate it was allocated with H5MM* interface */ struct H5MM_block_t *next; /* Pointer to next block in the list of allocated blocks */ struct H5MM_block_t *prev; /* Pointer to previous block in the list of allocated blocks */ union { @@ -70,7 +69,7 @@ typedef struct H5MM_block_t { /********************/ /* Local Prototypes */ /********************/ -#if defined H5_MEMORY_ALLOC_SANITY_CHECK +#if defined H5_MEMORY_ALLOC_SANITY_CHECK static hbool_t H5MM__is_our_block(void *mem); static void H5MM__sanity_check_block(const H5MM_block_t *block); static void H5MM__sanity_check(void *mem); @@ -271,7 +270,7 @@ H5MM_malloc(size_t size) H5MM_block_head_s.u.info.in_use = TRUE; H5MM_init_s = TRUE; - } /* end if */ + } /* end if */ #endif /* H5_MEMORY_ALLOC_SANITY_CHECK */ if (size) { @@ -309,10 +308,10 @@ H5MM_malloc(size_t size) } /* end if */ else ret_value = NULL; -#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ +#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ ret_value = HDmalloc(size); #endif /* H5_MEMORY_ALLOC_SANITY_CHECK */ - } /* end if */ + } /* end if */ else ret_value = NULL; @@ -352,10 +351,10 @@ H5MM_calloc(size_t size) #if defined H5_MEMORY_ALLOC_SANITY_CHECK if (NULL != (ret_value = H5MM_malloc(size))) HDmemset(ret_value, 0, size); -#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ +#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ ret_value = HDcalloc((size_t)1, size); #endif /* H5_MEMORY_ALLOC_SANITY_CHECK */ - } /* end if */ + } /* end if */ else ret_value = NULL; @@ -417,14 +416,14 @@ H5MM_realloc(void *mem, size_t size) } else ret_value = H5MM_xfree(mem); -#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ +#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ ret_value = HDrealloc(mem, size); /* Some platforms do not return NULL if size is zero. */ if (0 == size) ret_value = NULL; #endif /* H5_MEMORY_ALLOC_SANITY_CHECK */ - } /* end else */ + } /* end else */ FUNC_LEAVE_NOAPI(ret_value) } /* end H5MM_realloc() */ @@ -542,10 +541,10 @@ H5MM_xfree(void *mem) } else HDfree(mem); -#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ +#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ HDfree(mem); #endif /* H5_MEMORY_ALLOC_SANITY_CHECK */ - } /* end if */ + } /* end if */ FUNC_LEAVE_NOAPI(NULL) } /* end H5MM_xfree() */ @@ -642,8 +641,8 @@ H5MM_get_alloc_stats(H5_alloc_stats_t *stats) stats->total_alloc_blocks_count = H5MM_total_alloc_blocks_count_s; stats->curr_alloc_blocks_count = H5MM_curr_alloc_blocks_count_s; stats->peak_alloc_blocks_count = H5MM_peak_alloc_blocks_count_s; - } /* end if */ -#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ + } /* end if */ +#else /* H5_MEMORY_ALLOC_SANITY_CHECK */ if (stats) HDmemset(stats, 0, sizeof(H5_alloc_stats_t)); #endif /* H5_MEMORY_ALLOC_SANITY_CHECK */ diff --git a/src/H5MMprivate.h b/src/H5MMprivate.h index d957686..7c34a98 100644 --- a/src/H5MMprivate.h +++ b/src/H5MMprivate.h @@ -48,7 +48,7 @@ H5_DLL void * H5MM_xfree(void *mem); H5_DLL void * H5MM_xfree_const(const void *mem); H5_DLL void * H5MM_memcpy(void *dest, const void *src, size_t n); H5_DLL herr_t H5MM_get_alloc_stats(H5_alloc_stats_t *stats); -#if defined H5_MEMORY_ALLOC_SANITY_CHECK +#if defined H5_MEMORY_ALLOC_SANITY_CHECK H5_DLL void H5MM_sanity_check_all(void); H5_DLL void H5MM_final_sanity_check(void); #endif /* H5_MEMORY_ALLOC_SANITY_CHECK */ @@ -522,14 +522,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields) +H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo /*out*/, unsigned fields) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*xIu", loc_id, oinfo, fields); + H5TRACE3("e", "ixIu", loc_id, oinfo, fields); /* Check args */ if (!oinfo) @@ -567,14 +567,15 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id) +H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_t *oinfo /*out*/, unsigned fields, + hid_t lapl_id) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*s*xIui", loc_id, name, oinfo, fields, lapl_id); + H5TRACE5("e", "i*sxIui", loc_id, name, oinfo, fields, lapl_id); /* Check args */ if (!name) @@ -625,14 +626,14 @@ done: */ herr_t H5Oget_info_by_idx3(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id) + hsize_t n, H5O_info2_t *oinfo /*out*/, unsigned fields, hid_t lapl_id) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIoh*xIui", loc_id, group_name, idx_type, order, n, oinfo, fields, lapl_id); + H5TRACE8("e", "i*sIiIohxIui", loc_id, group_name, idx_type, order, n, oinfo, fields, lapl_id); /* Check args */ if (!group_name || !*group_name) @@ -684,14 +685,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo, unsigned fields) +H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo /*out*/, unsigned fields) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*xIu", loc_id, oinfo, fields); + H5TRACE3("e", "ixIu", loc_id, oinfo, fields); /* Check args */ if (!oinfo) @@ -729,7 +730,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_native_info_t *oinfo, unsigned fields, +H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_native_info_t *oinfo /*out*/, unsigned fields, hid_t lapl_id) { H5VL_object_t * vol_obj; /* Object of loc_id */ @@ -737,7 +738,7 @@ H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_native_info_t *oi herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*s*xIui", loc_id, name, oinfo, fields, lapl_id); + H5TRACE5("e", "i*sxIui", loc_id, name, oinfo, fields, lapl_id); /* Check args */ if (!name) @@ -788,14 +789,14 @@ done: */ herr_t H5Oget_native_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, H5O_native_info_t *oinfo, unsigned fields, hid_t lapl_id) + hsize_t n, H5O_native_info_t *oinfo /*out*/, unsigned fields, hid_t lapl_id) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIoh*xIui", loc_id, group_name, idx_type, order, n, oinfo, fields, lapl_id); + H5TRACE8("e", "i*sIiIohxIui", loc_id, group_name, idx_type, order, n, oinfo, fields, lapl_id); /* Check args */ if (!group_name || !*group_name) @@ -953,14 +954,14 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize) +H5Oget_comment(hid_t obj_id, char *comment /*out*/, size_t bufsize) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; ssize_t ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE3("Zs", "i*sz", obj_id, comment, bufsize); + H5TRACE3("Zs", "ixz", obj_id, comment, bufsize); /* Get the object */ if (NULL == (vol_obj = H5VL_vol_object(obj_id))) @@ -996,14 +997,14 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id) +H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comment /*out*/, size_t bufsize, hid_t lapl_id) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; ssize_t ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE5("Zs", "i*s*szi", loc_id, name, comment, bufsize, lapl_id); + H5TRACE5("Zs", "i*sxzi", loc_id, name, comment, bufsize, lapl_id); /* Check args */ if (!name || !*name) @@ -1076,7 +1077,7 @@ H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate2 herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "iIiIox*xIu", obj_id, idx_type, order, op, op_data, fields); + H5TRACE6("e", "iIiIoOI*xIu", obj_id, idx_type, order, op, op_data, fields); /* Check args */ if (idx_type <= H5_INDEX_UNKNOWN || idx_type >= H5_INDEX_N) @@ -1150,7 +1151,7 @@ H5Ovisit_by_name3(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_it herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIox*xIui", loc_id, obj_name, idx_type, order, op, op_data, fields, lapl_id); + H5TRACE8("e", "i*sIiIoOI*xIui", loc_id, obj_name, idx_type, order, op, op_data, fields, lapl_id); /* Check args */ if (!obj_name) diff --git a/src/H5Ocache.c b/src/H5Ocache.c index 778e77e..a2ca561 100644 --- a/src/H5Ocache.c +++ b/src/H5Ocache.c @@ -995,10 +995,10 @@ H5O__cache_chk_notify(H5AC_notify_action_t action, void *_thing) default: #ifdef NDEBUG HGOTO_ERROR(H5E_OHDR, H5E_BADVALUE, FAIL, "unknown action from metadata cache") -#else /* NDEBUG */ +#else /* NDEBUG */ HDassert(0 && "Unknown action?!?"); #endif /* NDEBUG */ - } /* end switch */ + } /* end switch */ done: FUNC_LEAVE_NOAPI(ret_value) @@ -1284,7 +1284,7 @@ H5O__chunk_deserialize(H5O_t *oh, haddr_t addr, size_t len, const uint8_t *image unsigned chunkno; /* Current chunk's index */ #ifndef NDEBUG unsigned nullcnt; /* Count of null messages (for sanity checking gaps in chunks) */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ hbool_t mesgs_modified = FALSE; /* Whether any messages were modified when the object header was deserialized */ herr_t ret_value = SUCCEED; /* Return value */ diff --git a/src/H5Odeprec.c b/src/H5Odeprec.c index 1838234..7d1b721 100644 --- a/src/H5Odeprec.c +++ b/src/H5Odeprec.c @@ -385,14 +385,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_info1(hid_t loc_id, H5O_info1_t *oinfo) +H5Oget_info1(hid_t loc_id, H5O_info1_t *oinfo /*out*/) { H5VL_object_t * vol_obj = NULL; /* Object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", loc_id, oinfo); + H5TRACE2("e", "ix", loc_id, oinfo); /* Check args */ if (!oinfo) @@ -425,14 +425,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info1_t *oinfo, hid_t lapl_id) +H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info1_t *oinfo /*out*/, hid_t lapl_id) { H5VL_object_t * vol_obj = NULL; /* object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "i*s*xi", loc_id, name, oinfo, lapl_id); + H5TRACE4("e", "i*sxi", loc_id, name, oinfo, lapl_id); /* Check args */ if (!name) @@ -480,14 +480,14 @@ done: */ herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, H5O_info1_t *oinfo, hid_t lapl_id) + hsize_t n, H5O_info1_t *oinfo /*out*/, hid_t lapl_id) { H5VL_object_t * vol_obj = NULL; /* object of loc_id */ H5VL_loc_params_t loc_params; herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "i*sIiIoh*xi", loc_id, group_name, idx_type, order, n, oinfo, lapl_id); + H5TRACE7("e", "i*sIiIohxi", loc_id, group_name, idx_type, order, n, oinfo, lapl_id); /* Check args */ if (!group_name || !*group_name) @@ -538,7 +538,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_info2(hid_t loc_id, H5O_info1_t *oinfo, unsigned fields) +H5Oget_info2(hid_t loc_id, H5O_info1_t *oinfo /*out*/, unsigned fields) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; @@ -546,7 +546,7 @@ H5Oget_info2(hid_t loc_id, H5O_info1_t *oinfo, unsigned fields) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*xIu", loc_id, oinfo, fields); + H5TRACE3("e", "ixIu", loc_id, oinfo, fields); /* Check args */ if (!oinfo) @@ -593,7 +593,8 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id) +H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info1_t *oinfo /*out*/, unsigned fields, + hid_t lapl_id) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; @@ -601,7 +602,7 @@ H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info1_t *oinfo, unsigne herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*s*xIui", loc_id, name, oinfo, fields, lapl_id); + H5TRACE5("e", "i*sxIui", loc_id, name, oinfo, fields, lapl_id); /* Check args */ if (!name) @@ -661,7 +662,7 @@ done: */ herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, - hsize_t n, H5O_info1_t *oinfo, unsigned fields, hid_t lapl_id) + hsize_t n, H5O_info1_t *oinfo /*out*/, unsigned fields, hid_t lapl_id) { H5VL_object_t * vol_obj; /* Object of loc_id */ H5VL_loc_params_t loc_params; @@ -669,7 +670,7 @@ H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type, H herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIoh*xIui", loc_id, group_name, idx_type, order, n, oinfo, fields, lapl_id); + H5TRACE8("e", "i*sIiIohxIui", loc_id, group_name, idx_type, order, n, oinfo, fields, lapl_id); /* Check args */ if (!group_name || !*group_name) @@ -756,7 +757,7 @@ H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1 herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "iIiIox*x", obj_id, idx_type, order, op, op_data); + H5TRACE5("e", "iIiIoOi*x", obj_id, idx_type, order, op, op_data); /* Check args */ if (idx_type <= H5_INDEX_UNKNOWN || idx_type >= H5_INDEX_N) @@ -831,7 +832,7 @@ H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_it herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "i*sIiIox*xi", loc_id, obj_name, idx_type, order, op, op_data, lapl_id); + H5TRACE7("e", "i*sIiIoOi*xi", loc_id, obj_name, idx_type, order, op, op_data, lapl_id); /* Check args */ if (!obj_name) @@ -920,7 +921,7 @@ H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate1 herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE6("e", "iIiIox*xIu", obj_id, idx_type, order, op, op_data, fields); + H5TRACE6("e", "iIiIoOi*xIu", obj_id, idx_type, order, op, op_data, fields); /* Check args */ if (idx_type <= H5_INDEX_UNKNOWN || idx_type >= H5_INDEX_N) @@ -1009,7 +1010,7 @@ H5Ovisit_by_name2(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_it herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "i*sIiIox*xIui", loc_id, obj_name, idx_type, order, op, op_data, fields, lapl_id); + H5TRACE8("e", "i*sIiIoOi*xIui", loc_id, obj_name, idx_type, order, op, op_data, fields, lapl_id); /* Check args */ if (!obj_name) diff --git a/src/H5Odtype.c b/src/H5Odtype.c index c8cd954..b6e986d 100644 --- a/src/H5Odtype.c +++ b/src/H5Odtype.c @@ -81,7 +81,7 @@ static herr_t H5O__dtype_debug(H5F_t *f, const void *_mesg, FILE *stream, int in if (H5T__upgrade_version((DT), (VERS)) < 0) \ HGOTO_ERROR(H5E_DATATYPE, H5E_CANTSET, FAIL, "can't upgrade " CLASS " encoding version") \ *(IOF) |= H5O_DECODEIO_DIRTY; \ - } /* end if */ + } /* end if */ #endif /* H5_STRICT_FORMAT_CHECKS */ /* This message derives from H5O message class */ diff --git a/src/H5Oint.c b/src/H5Oint.c index 47e6502..0661726 100644 --- a/src/H5Oint.c +++ b/src/H5Oint.c @@ -102,25 +102,25 @@ const H5O_msg_class_t *const H5O_msg_class_g[] = { H5O_MSG_LAYOUT, /*0x0008 Data Layout */ #ifdef H5O_ENABLE_BOGUS H5O_MSG_BOGUS_VALID, /*0x0009 "Bogus valid" (for testing) */ -#else /* H5O_ENABLE_BOGUS */ +#else /* H5O_ENABLE_BOGUS */ NULL, /*0x0009 "Bogus valid" (for testing) */ -#endif /* H5O_ENABLE_BOGUS */ - H5O_MSG_GINFO, /*0x000A Group information */ - H5O_MSG_PLINE, /*0x000B Data storage -- filter pipeline */ - H5O_MSG_ATTR, /*0x000C Attribute */ - H5O_MSG_NAME, /*0x000D Object name */ - H5O_MSG_MTIME, /*0x000E Object modification date and time */ - H5O_MSG_SHMESG, /*0x000F File-wide shared message table */ - H5O_MSG_CONT, /*0x0010 Object header continuation */ - H5O_MSG_STAB, /*0x0011 Symbol table */ - H5O_MSG_MTIME_NEW, /*0x0012 New Object modification date and time */ - H5O_MSG_BTREEK, /*0x0013 Non-default v1 B-tree 'K' values */ - H5O_MSG_DRVINFO, /*0x0014 Driver info settings */ - H5O_MSG_AINFO, /*0x0015 Attribute information */ - H5O_MSG_REFCOUNT, /*0x0016 Object's ref. count */ - H5O_MSG_FSINFO, /*0x0017 Free-space manager info */ - H5O_MSG_MDCI, /*0x0018 Metadata cache image */ - H5O_MSG_UNKNOWN /*0x0019 Placeholder for unknown message */ +#endif /* H5O_ENABLE_BOGUS */ + H5O_MSG_GINFO, /*0x000A Group information */ + H5O_MSG_PLINE, /*0x000B Data storage -- filter pipeline */ + H5O_MSG_ATTR, /*0x000C Attribute */ + H5O_MSG_NAME, /*0x000D Object name */ + H5O_MSG_MTIME, /*0x000E Object modification date and time */ + H5O_MSG_SHMESG, /*0x000F File-wide shared message table */ + H5O_MSG_CONT, /*0x0010 Object header continuation */ + H5O_MSG_STAB, /*0x0011 Symbol table */ + H5O_MSG_MTIME_NEW, /*0x0012 New Object modification date and time */ + H5O_MSG_BTREEK, /*0x0013 Non-default v1 B-tree 'K' values */ + H5O_MSG_DRVINFO, /*0x0014 Driver info settings */ + H5O_MSG_AINFO, /*0x0015 Attribute information */ + H5O_MSG_REFCOUNT, /*0x0016 Object's ref. count */ + H5O_MSG_FSINFO, /*0x0017 Free-space manager info */ + H5O_MSG_MDCI, /*0x0018 Metadata cache image */ + H5O_MSG_UNKNOWN /*0x0019 Placeholder for unknown message */ }; /* Format version bounds for object header */ @@ -1076,7 +1076,7 @@ H5O_protect(const H5O_loc_t *loc, unsigned prot_flags, hbool_t pin_all_chunks) H5O_chunk_proxy_t *chk_proxy; /* Proxy for chunk, to bring it into memory */ #ifndef NDEBUG size_t chkcnt = oh->nchunks; /* Count of chunks (for sanity checking) */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ /* Bring the chunk into the cache */ /* (which adds to the object header) */ @@ -1124,7 +1124,7 @@ H5O_protect(const H5O_loc_t *loc, unsigned prot_flags, hbool_t pin_all_chunks) (oh->nmesgs + udata.common.merged_null_msgs) != udata.v1_pfx_nmesgs) HGOTO_ERROR(H5E_OHDR, H5E_CANTLOAD, NULL, "corrupt object header - incorrect # of messages") #endif /* H5_STRICT_FORMAT_CHECKS */ - } /* end if */ + } /* end if */ #ifdef H5O_DEBUG H5O__assert(oh); diff --git a/src/H5Opkg.h b/src/H5Opkg.h index eece6b0..fac5269 100644 --- a/src/H5Opkg.h +++ b/src/H5Opkg.h @@ -277,10 +277,10 @@ struct H5O_t { /* (This is to simulate a bug in earlier * versions of the library) */ -#endif /* H5O_ENABLE_BAD_MESG_COUNT */ +#endif /* H5O_ENABLE_BAD_MESG_COUNT */ #ifndef NDEBUG size_t ndecode_dirtied; /* Number of messages dirtied by decoding */ -#endif /* NDEBUG */ +#endif /* NDEBUG */ /* Chunk management information (not stored) */ size_t rc; /* Reference count of [continuation] chunks using this structure */ diff --git a/src/H5Oprivate.h b/src/H5Oprivate.h index 7638666..8e338cc 100644 --- a/src/H5Oprivate.h +++ b/src/H5Oprivate.h @@ -29,22 +29,22 @@ typedef struct H5O_t H5O_t; typedef struct H5O_fill_t H5O_fill_t; /* Include the public header file for this API */ -#include "H5Opublic.h" /* Object header functions */ +#include "H5Opublic.h" /* Object header functions */ /* Public headers needed by this file */ -#include "H5Dpublic.h" /* Dataset functions */ -#include "H5Lpublic.h" /* Link functions */ -#include "H5Spublic.h" /* Dataspace functions */ +#include "H5Dpublic.h" /* Dataset functions */ +#include "H5Lpublic.h" /* Link functions */ +#include "H5Spublic.h" /* Dataspace functions */ /* Private headers needed by this file */ -#include "H5private.h" /* Generic Functions */ -#include "H5ACprivate.h" /* Metadata cache */ +#include "H5private.h" /* Generic Functions */ +#include "H5ACprivate.h" /* Metadata cache */ #include "H5Fprivate.h" /* File access */ -#include "H5HGprivate.h" /* Global Heaps */ +#include "H5HGprivate.h" /* Global Heaps */ #include "H5SLprivate.h" /* Skip lists */ #include "H5Tprivate.h" /* Datatype functions */ -#include "H5VLprivate.h" -#include "H5Zprivate.h" /* I/O pipeline filters */ +#include "H5VLprivate.h" /* Virtual Object Layer */ +#include "H5Zprivate.h" /* I/O pipeline filters */ /* Forward references of package typedefs */ typedef struct H5O_msg_class_t H5O_msg_class_t; diff --git a/src/H5Osdspace.c b/src/H5Osdspace.c index b34eb76..83702eb 100644 --- a/src/H5Osdspace.c +++ b/src/H5Osdspace.c @@ -138,8 +138,11 @@ H5O__sdspace_decode(H5F_t *f, H5O_t H5_ATTR_UNUSED *open_oh, unsigned H5_ATTR_UN flags = *p++; /* Get or determine the type of the extent */ - if (version >= H5O_SDSPACE_VERSION_2) + if (version >= H5O_SDSPACE_VERSION_2) { sdim->type = (H5S_class_t)*p++; + if (sdim->type != H5S_SIMPLE && sdim->rank > 0) + HGOTO_ERROR(H5E_OHDR, H5E_BADVALUE, NULL, "invalid rank for scalar or NULL dataspace") + } /* end if */ else { /* Set the dataspace type to be simple or scalar as appropriate */ if (sdim->rank > 0) @@ -248,13 +251,15 @@ H5O__sdspace_encode(H5F_t *f, uint8_t *p, const void *_mesg) *p++ = 0; /*reserved*/ } /* end else */ - /* Current & maximum dimensions */ - if (sdim->rank > 0) { - for (u = 0; u < sdim->rank; u++) - H5F_ENCODE_LENGTH(f, p, sdim->size[u]); - if (flags & H5S_VALID_MAX) { + /* Encode dataspace dimensions for simple dataspaces */ + if (H5S_SIMPLE == sdim->type) { + /* Encode current & maximum dimensions */ + if (sdim->rank > 0) { for (u = 0; u < sdim->rank; u++) - H5F_ENCODE_LENGTH(f, p, sdim->max[u]); + H5F_ENCODE_LENGTH(f, p, sdim->size[u]); + if (flags & H5S_VALID_MAX) + for (u = 0; u < sdim->rank; u++) + H5F_ENCODE_LENGTH(f, p, sdim->max[u]); } /* end if */ } /* end if */ diff --git a/src/H5Oshared.h b/src/H5Oshared.h index aafa069..a8f76aa 100644 --- a/src/H5Oshared.h +++ b/src/H5Oshared.h @@ -72,10 +72,10 @@ H5O_SHARED_DECODE(H5F_t *f, H5O_t *open_oh, unsigned mesg_flags, unsigned *iofla #ifdef H5_STRICT_FORMAT_CHECKS if (*ioflags & H5O_DECODEIO_DIRTY) HGOTO_ERROR(H5E_OHDR, H5E_UNSUPPORTED, NULL, "unable to mark shared message dirty") -#else /* H5_STRICT_FORMAT_CHECKS */ +#else /* H5_STRICT_FORMAT_CHECKS */ *ioflags &= ~H5O_DECODEIO_DIRTY; #endif /* H5_STRICT_FORMAT_CHECKS */ - } /* end if */ + } /* end if */ else { /* Decode native message directly */ if (NULL == (ret_value = H5O_SHARED_DECODE_REAL(f, open_oh, mesg_flags, ioflags, p_size, p))) @@ -237,7 +237,7 @@ H5O_SHARED_DELETE(H5F_t *f, H5O_t *open_oh, void *_mesg) /* Decrement the reference count on the native message directly */ if (H5O_SHARED_DELETE_REAL(f, open_oh, _mesg) < 0) HGOTO_ERROR(H5E_OHDR, H5E_CANTDEC, FAIL, "unable to decrement ref count for native message") - } /* end else */ + } /* end else */ #endif /* H5O_SHARED_DELETE_REAL */ done: @@ -288,7 +288,7 @@ H5O_SHARED_LINK(H5F_t *f, H5O_t *open_oh, void *_mesg) /* Increment the reference count on the native message directly */ if (H5O_SHARED_LINK_REAL(f, open_oh, _mesg) < 0) HGOTO_ERROR(H5E_OHDR, H5E_CANTINC, FAIL, "unable to increment ref count for native message") - } /* end else */ + } /* end else */ #endif /* H5O_SHARED_LINK_REAL */ done: @@ -333,7 +333,7 @@ H5O_SHARED_COPY_FILE(H5F_t *file_src, void *_native_src, H5F_t *file_dst, hbool_ if (NULL == (dst_mesg = H5O_SHARED_COPY_FILE_REAL(file_src, H5O_SHARED_TYPE, _native_src, file_dst, recompute_size, cpy_info, udata))) HGOTO_ERROR(H5E_OHDR, H5E_CANTCOPY, NULL, "unable to copy native message to another file") -#else /* H5O_SHARED_COPY_FILE_REAL */ +#else /* H5O_SHARED_COPY_FILE_REAL */ /* No copy file callback defined, just copy the message itself */ if (NULL == (dst_mesg = (H5O_SHARED_TYPE->copy)(_native_src, NULL))) HGOTO_ERROR(H5E_OHDR, H5E_CANTCOPY, NULL, "unable to copy native message") @@ -173,7 +173,7 @@ H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t cls_create hid_t ret_value = H5I_INVALID_HID; /* Return value */ FUNC_ENTER_API(H5I_INVALID_HID) - H5TRACE8("i", "i*sx*xx*xx*x", parent, name, cls_create, create_data, cls_copy, copy_data, cls_close, + H5TRACE8("i", "i*sPc*xPo*xPl*x", parent, name, cls_create, create_data, cls_copy, copy_data, cls_close, close_data); /* Check arguments. */ @@ -414,8 +414,8 @@ H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value, H5P_p herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE11("e", "i*sz*xxxxxxxx", cls_id, name, size, def_value, prp_create, prp_set, prp_get, prp_delete, - prp_copy, prp_cmp, prp_close); + H5TRACE11("e", "i*sz*xPCPSPGPDPOPMPL", cls_id, name, size, def_value, prp_create, prp_set, prp_get, + prp_delete, prp_copy, prp_cmp, prp_close); /* Check arguments. */ if (NULL == (pclass = (H5P_genclass_t *)H5I_object_verify(cls_id, H5I_GENPROP_CLS))) @@ -598,7 +598,7 @@ H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_s herr_t ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE10("e", "i*sz*xxxxxxx", plist_id, name, size, value, prp_set, prp_get, prp_delete, prp_copy, + H5TRACE10("e", "i*sz*xPSPGPDPOPMPL", plist_id, name, size, value, prp_set, prp_get, prp_delete, prp_copy, prp_cmp, prp_close); /* Check arguments. */ @@ -756,14 +756,14 @@ done: REVISION LOG --------------------------------------------------------------------------*/ herr_t -H5Pget_size(hid_t id, const char *name, size_t *size) +H5Pget_size(hid_t id, const char *name, size_t *size /*out*/) { H5P_genclass_t *pclass; /* Property class to query */ H5P_genplist_t *plist; /* Property list to query */ herr_t ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*s*z", id, name, size); + H5TRACE3("e", "i*sx", id, name, size); /* Check arguments. */ if (H5I_GENPROP_LST != H5I_get_type(id) && H5I_GENPROP_CLS != H5I_get_type(id)) @@ -961,14 +961,14 @@ done: REVISION LOG --------------------------------------------------------------------------*/ herr_t -H5Pget_nprops(hid_t id, size_t *nprops) +H5Pget_nprops(hid_t id, size_t *nprops /*out*/) { H5P_genplist_t *plist; /* Property list to query */ H5P_genclass_t *pclass; /* Property class to query */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*z", id, nprops); + H5TRACE2("e", "ix", id, nprops); /* Check arguments. */ if (H5I_GENPROP_LST != H5I_get_type(id) && H5I_GENPROP_CLS != H5I_get_type(id)) @@ -1199,7 +1199,7 @@ H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data) int ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("Is", "i*Isx*x", id, idx, iter_func, iter_data); + H5TRACE4("Is", "i*IsPi*x", id, idx, iter_func, iter_data); /* Check arguments. */ if (H5I_GENPROP_LST != H5I_get_type(id) && H5I_GENPROP_CLS != H5I_get_type(id)) @@ -1262,13 +1262,13 @@ done: REVISION LOG --------------------------------------------------------------------------*/ herr_t -H5Pget(hid_t plist_id, const char *name, void *value) +H5Pget(hid_t plist_id, const char *name, void *value /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*s*x", plist_id, name, value); + H5TRACE3("e", "i*sx", plist_id, name, value); /* Check arguments. */ if (NULL == (plist = (H5P_genplist_t *)H5I_object_verify(plist_id, H5I_GENPROP_LST))) @@ -104,12 +104,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5PLget_loading_state(unsigned int *plugin_control_mask) +H5PLget_loading_state(unsigned *plugin_control_mask /*out*/) { herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE1("e", "*Iu", plugin_control_mask); + H5TRACE1("e", "x", plugin_control_mask); if (NULL == plugin_control_mask) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "plugin_control_mask parameter cannot be NULL") diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index 8bf11ce..6e6a088 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -27,4 +27,9 @@ #define H5_MY_PKG_ERR H5E_PLUGIN #define H5_MY_PKG_INIT YES +/**\defgroup H5PL H5PL + * \brief Plugins + * \todo Describe what programmatically controlling dynamically loaded plugins (H5PL) is all about + */ + #endif /* _H5PLmodule_H */ diff --git a/src/H5PLpath.c b/src/H5PLpath.c index 3879dc6..ff4dc0e 100644 --- a/src/H5PLpath.c +++ b/src/H5PLpath.c @@ -693,7 +693,7 @@ done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5PL__find_plugin_in_path() */ -#else /* H5_HAVE_WIN32_API */ +#else /* H5_HAVE_WIN32_API */ static herr_t H5PL__find_plugin_in_path(const H5PL_search_params_t *search_params, hbool_t *found, const char *dir, const void **plugin_info) diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h index a54cce0..a08c78d 100644 --- a/src/H5PLpublic.h +++ b/src/H5PLpublic.h @@ -28,14 +28,20 @@ */ #define H5PL_NO_PLUGIN "::" -/* Plugin type used by the plugin library */ +//! [H5PL_type_t_snip] + +/** + * Plugin type (bit-position) used by the plugin library + */ typedef enum H5PL_type_t { - H5PL_TYPE_ERROR = -1, /* Error */ - H5PL_TYPE_FILTER = 0, /* Filter */ - H5PL_TYPE_VOL = 1, /* VOL driver */ - H5PL_TYPE_NONE = 2 /* This must be last! */ + H5PL_TYPE_ERROR = -1, /**< Error */ + H5PL_TYPE_FILTER = 0, /**< Filter */ + H5PL_TYPE_VOL = 1, /**< VOL driver */ + H5PL_TYPE_NONE = 2 /**< Sentinel: This must be last! */ } H5PL_type_t; +//! [H5PL_type_t_snip] + /* Common dynamic plugin type flags used by the set/get_loading_state functions */ #define H5PL_FILTER_PLUGIN 0x0001 #define H5PL_VOL_PLUGIN 0x0002 @@ -46,15 +52,175 @@ extern "C" { #endif /* plugin state */ -H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_control_mask); -H5_DLL herr_t H5PLget_loading_state(unsigned int *plugin_control_mask /*out*/); -H5_DLL herr_t H5PLappend(const char *search_path); -H5_DLL herr_t H5PLprepend(const char *search_path); -H5_DLL herr_t H5PLreplace(const char *search_path, unsigned int index); -H5_DLL herr_t H5PLinsert(const char *search_path, unsigned int index); -H5_DLL herr_t H5PLremove(unsigned int index); +/** + * \ingroup H5PL + * \brief Controls the loadability of dynamic plugin types + * + * \param[in] plugin_control_mask The list of dynamic plugin types to enable or disable.\n + * A plugin bit set to 0 (zero) prevents use of that dynamic plugin.\n + * A plugin bit set to 1 (one) enables use of that dynamic plugin.\n + * Setting \p plugin_control_mask to a negative value enables all dynamic + * plugin types.\n + * Setting \p plugin_control_mask to 0 (zero) disables all dynamic plugin\n + * types. + * \return \herr_t + * + * \details H5PLset_loading_state() uses one argument to enable or disable individual plugin types. + * + * \details The \p plugin_control_mask parameter is an encoded integer in which each bit controls a specific + * plugin type. Bit positions allocated to date are specified in \ref H5PL_type_t as follows: + * \snippet this H5PL_type_t_snip + * + * A plugin bit set to 0 (zero) prevents the use of the dynamic plugin type corresponding to that bit + * position. A plugin bit set to 1 (one) allows the use of that dynamic plugin type. + * + * All dynamic plugin types can be enabled by setting \p plugin_control_mask to a negative value. A + * value of 0 (zero) will disable all dynamic plugin types. + * + * The loading of external dynamic plugins can be controlled during runtime with an environment + * variable, \c HDF5_PLUGIN_PRELOAD. H5PLset_loading_state() inspects the \c HDF5_PLUGIN_PRELOAD + * environment variable every time it is called. If the environment variable is set to the special + * \c :: string, all dynamic plugins are disabled. + * + * \warning The environment variable \c HDF5_PLUGIN_PRELOAD controls the loading of dynamic plugin types at + * runtime. If it is set to disable all plugin types, then it will disable them for \Emph{all} + * running programs that access the same variable instance. + * + * \since 1.8.15 + * + */ +H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_control_mask); +/** + * \ingroup H5PL + * \brief Queries the loadability of dynamic plugin types + * + * \param[out] plugin_control_mask List of dynamic plugin types that are enabled or disabled.\n + * A plugin bit set to 0 (zero) indicates that that the dynamic plugin type is + * disabled.\n + * A plugin bit set to 1 (one) indicates that that the dynamic plugin type is + * enabled.\n + * If the value of \p plugin_control_mask is negative, all dynamic plugin types + * are enabled.\n + * If the value of \p plugin_control_mask is 0 (zero), all dynamic plugins + * are disabled. + * \return \herr_t + * + * \details H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugins + * (e.g.: filters, VOL drivers) will be loaded by the HDF5 library. + * + * Bit positions allocated to date are specified in \ref H5PL_type_t as follows: + * \snippet this H5PL_type_t_snip + * + * \since 1.8.15 + * + */ +H5_DLL herr_t H5PLget_loading_state(unsigned int *plugin_control_mask /*out*/); +/** + * \ingroup H5PL + * \brief Inserts a plugin path at the end of the plugin search path list + * + * \param[in] search_path A plugin path + * \return \herr_t + * + * \details H5PLappend() inserts a plugin path at the end of the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLappend(const char *search_path); +/** + * \ingroup H5PL + * \brief Inserts a plugin path at the beginning of the plugin search path list + * + * \param[in] search_path A plugin path + * \return \herr_t + * + * \details H5PLprepend() inserts a plugin path at the end of the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLprepend(const char *search_path); +/** + * \ingroup H5PL + * \brief Replaces the path at the specified index in the plugin search path list + * + * \param[in] search_path A plugin path + * \param[in] index Index + * \return \herr_t + * + * \details H5PLreplace() replaces a plugin path at the specified index in the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLreplace(const char *search_path, unsigned int index); +/** + * \ingroup H5PL + * \brief Inserts a path at the specified index in the plugin search path list + * + * \param[in] search_path A plugin path + * \param[in] index Index + * \return \herr_t + * + * \details H5PLinsert() inserts a plugin path at the specified index in the plugin search path list, + * moving other paths after \p index. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLinsert(const char *search_path, unsigned int index); +/** + * \ingroup H5PL + * \brief Removes a plugin path at a specified index from the plugin search path list + * + * \param[in] index Index + * \return \herr_t + * + * \details H5PLremove() removes a plugin path at the specified \p index and compacts the plugin search path + * list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLremove(unsigned int index); +/** + * \ingroup H5PL + * \brief Queries the plugin search path list at the specified index + * + * \param[in] index Index + * \param[out] path_buf Pathname + * \param[in] buf_size Size of \p path_buf + * \return Returns the length of the path, a non-negative value, if successful; otherwise returns a negative + * value. + * + * \details H5PLget() queries the plugin path at a specified index. If \p path_buf is non-NULL then it writes + * up to \p buf_size bytes into that buffer and always returns the length of the path name. + * + * If \p path_buf is NULL, this function will simply return the number of characters required to + * store the path name, ignoring \p path_buf and \p buf_size. + * + * If an error occurs then the buffer pointed to by \p path_buf (NULL or non-NULL) is unchanged and + * the function returns a negative value. If a zero is returned for the name's length, then there is + * no path name associated with the index. and the \p path_buf buffer will be unchanged. + * + * \since 1.10.1 + * + */ H5_DLL ssize_t H5PLget(unsigned int index, char *path_buf /*out*/, size_t buf_size); -H5_DLL herr_t H5PLsize(unsigned int *num_paths /*out*/); +/** + * \ingroup H5PL + * \brief Retrieves the number of stored plugin paths + * + * \param[out] num_paths Current length of the plugin search path list + * \return \herr_t + * + * \details H5PLsize() retrieves the number of paths stored in the plugin search path list. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5PLsize(unsigned int *num_paths /*out*/); #ifdef __cplusplus } diff --git a/src/H5Pdapl.c b/src/H5Pdapl.c index 057509e..cf62bce 100644 --- a/src/H5Pdapl.c +++ b/src/H5Pdapl.c @@ -804,14 +804,15 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_chunk_cache(hid_t dapl_id, size_t *rdcc_nslots, size_t *rdcc_nbytes, double *rdcc_w0) +H5Pget_chunk_cache(hid_t dapl_id, size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/, + double *rdcc_w0 /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ H5P_genplist_t *def_plist; /* Default file access property list */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "i*z*z*d", dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0); + H5TRACE4("e", "ixxx", dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(dapl_id, H5P_DATASET_ACCESS))) @@ -1103,13 +1104,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_virtual_view(hid_t plist_id, H5D_vds_view_t *view) +H5Pget_virtual_view(hid_t plist_id, H5D_vds_view_t *view /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Dv", plist_id, view); + H5TRACE2("e", "ix", plist_id, view); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_ACCESS))) @@ -1246,13 +1247,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_virtual_printf_gap(hid_t plist_id, hsize_t *gap_size) +H5Pget_virtual_printf_gap(hid_t plist_id, hsize_t *gap_size /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*h", plist_id, gap_size); + H5TRACE2("e", "ix", plist_id, gap_size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_ACCESS))) @@ -1292,7 +1293,7 @@ H5Pset_append_flush(hid_t plist_id, unsigned ndims, const hsize_t *boundary, H5D herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "iIu*hx*x", plist_id, ndims, boundary, func, udata); + H5TRACE5("e", "iIu*hDA*x", plist_id, ndims, boundary, func, udata); /* Check arguments */ if (0 == ndims) @@ -1345,7 +1346,8 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_append_flush(hid_t plist_id, unsigned ndims, hsize_t boundary[], H5D_append_cb_t *func, void **udata) +H5Pget_append_flush(hid_t plist_id, unsigned ndims, hsize_t boundary[], H5D_append_cb_t *func /*out*/, + void **udata /*out*/) { H5P_genplist_t * plist; /* property list pointer */ H5D_append_flush_t info; @@ -1353,7 +1355,7 @@ H5Pget_append_flush(hid_t plist_id, unsigned ndims, hsize_t boundary[], H5D_appe herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "iIu*h*x**x", plist_id, ndims, boundary, func, udata); + H5TRACE5("e", "iIu*hxx", plist_id, ndims, boundary, func, udata); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_ACCESS))) @@ -1428,7 +1430,7 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Pget_efile_prefix(hid_t plist_id, char *prefix, size_t size) +H5Pget_efile_prefix(hid_t plist_id, char *prefix /*out*/, size_t size) { H5P_genplist_t *plist; /* Property list pointer */ char * my_prefix; /* Library's copy of the prefix */ @@ -1436,7 +1438,7 @@ H5Pget_efile_prefix(hid_t plist_id, char *prefix, size_t size) ssize_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("Zs", "i*sz", plist_id, prefix, size); + H5TRACE3("Zs", "ixz", plist_id, prefix, size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_ACCESS))) @@ -1518,7 +1520,7 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Pget_virtual_prefix(hid_t plist_id, char *prefix, size_t size) +H5Pget_virtual_prefix(hid_t plist_id, char *prefix /*out*/, size_t size) { H5P_genplist_t *plist; /* Property list pointer */ char * my_prefix; /* Library's copy of the prefix */ @@ -1526,7 +1528,7 @@ H5Pget_virtual_prefix(hid_t plist_id, char *prefix, size_t size) ssize_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("Zs", "i*sz", plist_id, prefix, size); + H5TRACE3("Zs", "ixz", plist_id, prefix, size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_ACCESS))) diff --git a/src/H5Pdcpl.c b/src/H5Pdcpl.c index 8c525e5..685313e 100644 --- a/src/H5Pdcpl.c +++ b/src/H5Pdcpl.c @@ -313,7 +313,7 @@ static const H5O_layout_t H5D_def_layout_compact_g = H5D_DEF_LAYOUT_COMPACT; static const H5O_layout_t H5D_def_layout_contig_g = H5D_DEF_LAYOUT_CONTIG; static const H5O_layout_t H5D_def_layout_chunk_g = H5D_DEF_LAYOUT_CHUNK; static const H5O_layout_t H5D_def_layout_virtual_g = H5D_DEF_LAYOUT_VIRTUAL; -#else /* H5_HAVE_C99_DESIGNATED_INITIALIZER */ +#else /* H5_HAVE_C99_DESIGNATED_INITIALIZER */ static H5O_layout_t H5D_def_layout_compact_g = H5D_DEF_LAYOUT_COMPACT; static H5O_layout_t H5D_def_layout_contig_g = H5D_DEF_LAYOUT_CONTIG; static H5O_layout_t H5D_def_layout_chunk_g = H5D_DEF_LAYOUT_CHUNK; @@ -2773,14 +2773,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_chunk_opts(hid_t plist_id, unsigned *options) +H5Pget_chunk_opts(hid_t plist_id, unsigned *options /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ H5O_layout_t layout; /* Layout information for setting chunk info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Iu", plist_id, options); + H5TRACE2("e", "ix", plist_id, options); #ifndef H5_HAVE_C99_DESIGNATED_INITIALIZER /* If the compiler doesn't support C99 designated initializers, check if @@ -3800,14 +3800,14 @@ done: *----------------------------------------------------------------------------- */ herr_t -H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize) +H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize /*out*/) { hbool_t setting = FALSE; H5P_genplist_t *plist = NULL; herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*b", dcpl_id, minimize); + H5TRACE2("e", "ix", dcpl_id, minimize); if (NULL == minimize) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "receiving pointer cannot be NULL") diff --git a/src/H5Pdeprec.c b/src/H5Pdeprec.c index d80c153..d44cd5c 100644 --- a/src/H5Pdeprec.c +++ b/src/H5Pdeprec.c @@ -220,8 +220,8 @@ H5Pregister1(hid_t cls_id, const char *name, size_t size, void *def_value, H5P_p herr_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE10("e", "i*sz*xxxxxxx", cls_id, name, size, def_value, prp_create, prp_set, prp_get, prp_delete, - prp_copy, prp_close); + H5TRACE10("e", "i*sz*xPCPSPGPDPOPL", cls_id, name, size, def_value, prp_create, prp_set, prp_get, + prp_delete, prp_copy, prp_close); /* Check arguments. */ if (NULL == (pclass = (H5P_genclass_t *)H5I_object_verify(cls_id, H5I_GENPROP_CLS))) @@ -404,7 +404,7 @@ H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_s herr_t ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE9("e", "i*sz*xxxxxx", plist_id, name, size, value, prp_set, prp_get, prp_delete, prp_copy, + H5TRACE9("e", "i*sz*xPSPGPDPOPL", plist_id, name, size, value, prp_set, prp_get, prp_delete, prp_copy, prp_close); /* Check arguments. */ @@ -545,7 +545,7 @@ H5Pset_file_space(hid_t plist_id, H5F_file_space_type_t strategy, hsize_t thresh herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "iFfh", plist_id, strategy, threshold); + H5TRACE3("e", "iFth", plist_id, strategy, threshold); if ((unsigned)in_strategy >= H5F_FILE_SPACE_NTYPES) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid strategy") @@ -606,7 +606,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_file_space(hid_t plist_id, H5F_file_space_type_t *strategy, hsize_t *threshold) +H5Pget_file_space(hid_t plist_id, H5F_file_space_type_t *strategy /*out*/, hsize_t *threshold /*out*/) { H5F_fspace_strategy_t new_strategy; /* File space strategy type */ hbool_t new_persist; /* Persisting free-space or not */ @@ -614,7 +614,7 @@ H5Pget_file_space(hid_t plist_id, H5F_file_space_type_t *strategy, hsize_t *thre herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*Ff*h", plist_id, strategy, threshold); + H5TRACE3("e", "ixx", plist_id, strategy, threshold); /* Get current file space info */ if (H5Pget_file_space_strategy(plist_id, &new_strategy, &new_persist, &new_threshold) < 0) diff --git a/src/H5Pdxpl.c b/src/H5Pdxpl.c index 09eadfa..abe8166 100644 --- a/src/H5Pdxpl.c +++ b/src/H5Pdxpl.c @@ -1314,7 +1314,7 @@ H5Pset_filter_callback(hid_t plist_id, H5Z_filter_func_t func, void *op_data) H5Z_cb_t cb_struct; FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ix*x", plist_id, func, op_data); + H5TRACE3("e", "iZF*x", plist_id, func, op_data); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_XFER))) @@ -1353,7 +1353,7 @@ H5Pset_type_conv_cb(hid_t plist_id, H5T_conv_except_func_t op, void *operate_dat H5T_conv_cb_t cb_struct; FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ix*x", plist_id, op, operate_data); + H5TRACE3("e", "iTE*x", plist_id, op, operate_data); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_XFER))) @@ -1385,14 +1385,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_type_conv_cb(hid_t plist_id, H5T_conv_except_func_t *op, void **operate_data) +H5Pget_type_conv_cb(hid_t plist_id, H5T_conv_except_func_t *op /*out*/, void **operate_data /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ H5T_conv_cb_t cb_struct; herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*x**x", plist_id, op, operate_data); + H5TRACE3("e", "ixx", plist_id, op, operate_data); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_XFER))) @@ -1577,7 +1577,7 @@ H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "ix*xx*x", plist_id, alloc_func, alloc_info, free_func, free_info); + H5TRACE5("e", "iMa*xMf*x", plist_id, alloc_func, alloc_info, free_func, free_info); /* Check arguments */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_XFER))) @@ -1945,13 +1945,14 @@ H5P__dxfr_mpio_chunk_opt_hard_dec(const void **_pp, void *_value) *------------------------------------------------------------------------- */ herr_t -H5Pget_mpio_actual_chunk_opt_mode(hid_t plist_id, H5D_mpio_actual_chunk_opt_mode_t *actual_chunk_opt_mode) +H5Pget_mpio_actual_chunk_opt_mode(hid_t plist_id, + H5D_mpio_actual_chunk_opt_mode_t *actual_chunk_opt_mode /*out*/) { H5P_genplist_t *plist; herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Do", plist_id, actual_chunk_opt_mode); + H5TRACE2("e", "ix", plist_id, actual_chunk_opt_mode); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_XFER))) @@ -1980,13 +1981,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_mpio_actual_io_mode(hid_t plist_id, H5D_mpio_actual_io_mode_t *actual_io_mode) +H5Pget_mpio_actual_io_mode(hid_t plist_id, H5D_mpio_actual_io_mode_t *actual_io_mode /*out*/) { H5P_genplist_t *plist; herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Di", plist_id, actual_io_mode); + H5TRACE2("e", "ix", plist_id, actual_io_mode); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_XFER))) @@ -2013,14 +2014,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no_collective_cause, - uint32_t *global_no_collective_cause) +H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no_collective_cause /*out*/, + uint32_t *global_no_collective_cause /*out*/) { H5P_genplist_t *plist; herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*Iu*Iu", plist_id, local_no_collective_cause, global_no_collective_cause); + H5TRACE3("e", "ixx", plist_id, local_no_collective_cause, global_no_collective_cause); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_DATASET_XFER))) diff --git a/src/H5Pfapl.c b/src/H5Pfapl.c index f9a730d..dd14e92 100644 --- a/src/H5Pfapl.c +++ b/src/H5Pfapl.c @@ -493,7 +493,7 @@ static const hbool_t H5F_def_coll_md_write_flag_g = H5F_ACS_COLL_MD_WRITE_FLAG_DEF; /* Default setting for the collective metedata write flag */ static const MPI_Comm H5F_def_mpi_params_comm_g = H5F_ACS_MPI_PARAMS_COMM_DEF; /* Default MPI communicator */ static const MPI_Info H5F_def_mpi_params_info_g = H5F_ACS_MPI_PARAMS_INFO_DEF; /* Default MPI info struct */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ static const H5AC_cache_image_config_t H5F_def_mdc_initCacheImageCfg_g = H5F_ACS_META_CACHE_INIT_IMAGE_CONFIG_DEF; /* Default metadata cache image settings */ static const size_t H5F_def_page_buf_size_g = H5F_ACS_PAGE_BUFFER_SIZE_DEF; /* Default page buffer size */ @@ -1551,13 +1551,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_family_offset(hid_t fapl_id, hsize_t *offset) +H5Pget_family_offset(hid_t fapl_id, hsize_t *offset /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*h", fapl_id, offset); + H5TRACE2("e", "ix", fapl_id, offset); /* Get the plist structure */ if (H5P_DEFAULT == fapl_id) @@ -1629,13 +1629,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type) +H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Mt", fapl_id, type); + H5TRACE2("e", "ix", fapl_id, type); /* Get the plist structure */ if (H5P_DEFAULT == fapl_id) @@ -1723,13 +1723,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_cache(hid_t plist_id, int *mdc_nelmts, size_t *rdcc_nslots, size_t *rdcc_nbytes, double *rdcc_w0) +H5Pget_cache(hid_t plist_id, int *mdc_nelmts, size_t *rdcc_nslots /*out*/, size_t *rdcc_nbytes /*out*/, + double *rdcc_w0 /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*Is*z*z*d", plist_id, mdc_nelmts, rdcc_nslots, rdcc_nbytes, rdcc_w0); + H5TRACE5("e", "i*Isxxx", plist_id, mdc_nelmts, rdcc_nslots, rdcc_nbytes, rdcc_w0); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -1775,7 +1776,7 @@ H5Pset_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr) herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", plist_id, config_ptr); + H5TRACE2("e", "i*CC", plist_id, config_ptr); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -1816,23 +1817,22 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr) +H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", plist_id, config_ptr); + H5TRACE2("e", "ix", plist_id, config); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "can't find object for ID") - /* validate the config_ptr */ - if (config_ptr == NULL) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL config_ptr on entry.") - - if (config_ptr->version != H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION) + /* validate the config ptr */ + if (config == NULL) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL config ptr on entry.") + if (config->version != H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "Unknown image config version.") /* If we ever support multiple versions of H5AC_cache_config_t, we @@ -1841,7 +1841,7 @@ H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr) */ /* Get the current initial metadata cache resize configuration */ - if (H5P_get(plist, H5F_ACS_META_CACHE_INIT_IMAGE_CONFIG_NAME, config_ptr) < 0) + if (H5P_get(plist, H5F_ACS_META_CACHE_INIT_IMAGE_CONFIG_NAME, config) < 0) HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, FAIL, "can't get metadata cache initial image config") done: @@ -1868,7 +1868,7 @@ H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr) herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", plist_id, config_ptr); + H5TRACE2("e", "i*Cc", plist_id, config_ptr); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -1897,7 +1897,7 @@ done: * Purpose: Retrieve the metadata cache initial resize configuration * from the target FAPL. * - * Observe that the function will fail if config_ptr is + * Observe that the function will fail if config is * NULL, or if config_ptr->version specifies an unknown * version of H5AC_cache_config_t. * @@ -1909,23 +1909,22 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr) +H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", plist_id, config_ptr); + H5TRACE2("e", "ix", plist_id, config); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "can't find object for ID") - /* validate the config_ptr */ - if (config_ptr == NULL) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL config_ptr on entry.") - - if (config_ptr->version != H5AC__CURR_CACHE_CONFIG_VERSION) + /* validate the config ptr */ + if (config == NULL) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL config ptr on entry.") + if (config->version != H5AC__CURR_CACHE_CONFIG_VERSION) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "Unknown config version.") /* If we ever support multiple versions of H5AC_cache_config_t, we @@ -1934,7 +1933,7 @@ H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr) */ /* Get the current initial metadata cache resize configuration */ - if (H5P_get(plist, H5F_ACS_META_CACHE_INIT_CONFIG_NAME, config_ptr) < 0) + if (H5P_get(plist, H5F_ACS_META_CACHE_INIT_CONFIG_NAME, config) < 0) HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, FAIL, "can't get metadata cache initial resize config") done: @@ -2067,13 +2066,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_fclose_degree(hid_t plist_id, H5F_close_degree_t *degree) +H5Pget_fclose_degree(hid_t plist_id, H5F_close_degree_t *degree /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Fd", plist_id, degree); + H5TRACE2("e", "ix", plist_id, degree); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -2438,7 +2437,6 @@ H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_t high) /* Check args */ if (low < 0 || low > H5F_LIBVER_LATEST) HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "low bound is not valid") - if (high < 0 || high > H5F_LIBVER_LATEST) HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "high bound is not valid") @@ -2490,15 +2488,13 @@ H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low /*out*/, H5F_libver_t *hi HGOTO_ERROR(H5E_ATOM, H5E_BADATOM, FAIL, "can't find object for ID") /* Get values */ - if (low) { + if (low) if (H5P_get(plist, H5F_ACS_LIBVER_LOW_BOUND_NAME, low) < 0) HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, FAIL, "can't get low bound for library format versions") - } - if (high) { + if (high) if (H5P_get(plist, H5F_ACS_LIBVER_HIGH_BOUND_NAME, high) < 0) HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, FAIL, "can't get high bound for library format versions") - } done: FUNC_LEAVE_API(ret_value) @@ -2558,13 +2554,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size) +H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Iu", plist_id, efc_size); + H5TRACE2("e", "ix", plist_id, efc_size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -2663,22 +2659,22 @@ done: /*------------------------------------------------------------------------- * Function: H5Pget_file_image * - * Purpose: If the file image exists and buf_ptr_ptr is not NULL, + * Purpose: If the file image exists and buf is not NULL, * allocate a buffer of the correct size, copy the image into * the new buffer, and return the buffer to the caller in - * *buf_ptr_ptr. Do this using the file image callbacks + * *buf. Do this using the file image callbacks * if defined. * * NB: It is the responsibility of the caller to free the - * buffer whose address is returned in *buf_ptr_ptr. Do + * buffer whose address is returned in *buf. Do * this using free if the file image callbacks are not * defined, or with whatever method is appropriate if * the callbacks are defined. * - * If buf_ptr_ptr is not NULL, and no image exists, set - * *buf_ptr_ptr to NULL. + * If buf is not NULL, and no image exists, set + * *buf to NULL. * - * If buf_len_ptr is not NULL, set *buf_len_ptr equal + * If buf_len is not NULL, set *buf_len equal * to the length of the file image if it exists, and * to 0 if it does not. * @@ -2690,14 +2686,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr) +H5Pget_file_image(hid_t fapl_id, void **buf /*out*/, size_t *buf_len /*out*/) { H5P_genplist_t * fapl; /* Property list pointer */ H5FD_file_image_info_t image_info; /* File image info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i**x*z", fapl_id, buf_ptr_ptr, buf_len_ptr); + H5TRACE3("e", "ixx", fapl_id, buf, buf_len); /* Get the plist structure */ if (NULL == (fapl = H5P_object_verify(fapl_id, H5P_FILE_ACCESS))) @@ -2712,11 +2708,11 @@ H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr) ((image_info.buffer == NULL) && (image_info.size == 0))); /* Set output size */ - if (buf_len_ptr != NULL) - *buf_len_ptr = image_info.size; + if (buf_len != NULL) + *buf_len = image_info.size; /* Duplicate the image if desired, using callbacks if available */ - if (buf_ptr_ptr != NULL) { + if (buf != NULL) { void *copy_ptr = NULL; /* Copy of memory image */ if (image_info.buffer != NULL) { @@ -2741,7 +2737,7 @@ H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr) H5MM_memcpy(copy_ptr, image_info.buffer, image_info.size); } /* end if */ - *buf_ptr_ptr = copy_ptr; + *buf = copy_ptr; } /* end if */ done: @@ -2772,7 +2768,7 @@ H5Pset_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callback herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, callbacks_ptr); + H5TRACE2("e", "i*DI", fapl_id, callbacks_ptr); /* Get the plist structure */ if (NULL == (fapl = H5P_object_verify(fapl_id, H5P_FILE_ACCESS))) @@ -2826,7 +2822,7 @@ done: } /* end H5Pset_file_image_callbacks() */ /*------------------------------------------------------------------------- - * Function: H5Pget_file_image_callbacks + * Function: H5Pget_file_image_callbacks * * Purpose: Sets the callbacks for file images. Some file drivers allow * the use of user-defined callbacks for allocating, freeing and @@ -2841,14 +2837,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr) +H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks /*out*/) { H5P_genplist_t * fapl; /* Property list pointer */ H5FD_file_image_info_t info; /* File image info */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*x", fapl_id, callbacks_ptr); + H5TRACE2("e", "ix", fapl_id, callbacks); /* Get the plist structure */ if (NULL == (fapl = H5P_object_verify(fapl_id, H5P_FILE_ACCESS))) @@ -2861,17 +2857,17 @@ H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callback /* verify file image field consistency */ HDassert(((info.buffer != NULL) && (info.size > 0)) || ((info.buffer == NULL) && (info.size == 0))); - /* verify that callbacks_ptr is not NULL */ - if (NULL == callbacks_ptr) - HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL callbacks_ptr") + /* verify that callbacks is not NULL */ + if (NULL == callbacks) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "NULL callbacks ptr") /* Transfer values to parameters */ - *callbacks_ptr = info.callbacks; + *callbacks = info.callbacks; /* Copy udata if it exists */ if (info.callbacks.udata != NULL) { HDassert(info.callbacks.udata_copy); - if ((callbacks_ptr->udata = info.callbacks.udata_copy(info.callbacks.udata)) == 0) + if ((callbacks->udata = info.callbacks.udata_copy(info.callbacks.udata)) == 0) HGOTO_ERROR(H5E_PLIST, H5E_CANTSET, FAIL, "can't copy udata") } /* end if */ @@ -4149,7 +4145,7 @@ H5Pset_object_flush_cb(hid_t plist_id, H5F_flush_cb_t func, void *udata) herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ix*x", plist_id, func, udata); + H5TRACE3("e", "iFF*x", plist_id, func, udata); /* Check if the callback function is NULL and the user data is non-NULL. * This is almost certainly an error as the user data will not be used. */ @@ -4185,14 +4181,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func, void **udata) +H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func /*out*/, void **udata /*out*/) { H5P_genplist_t * plist; /* Property list pointer */ H5F_object_flush_t flush_info; herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*x**x", plist_id, func, udata); + H5TRACE3("e", "ixx", plist_id, func, udata); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -4272,15 +4268,15 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled, char *location, size_t *location_size, - hbool_t *start_on_access) +H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled /*out*/, char *location /*out*/, + size_t *location_size /*out*/, hbool_t *start_on_access /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ char * location_ptr; /* Pointer to location string */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*b*s*z*b", plist_id, is_enabled, location, location_size, start_on_access); + H5TRACE5("e", "ixxxx", plist_id, is_enabled, location, location_size, start_on_access); /* Get the property list structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -4309,7 +4305,7 @@ H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled, char *location, size *location_size = HDstrlen(location_ptr) + 1; else *location_size = 0; - } + } /* end if */ done: FUNC_LEAVE_API(ret_value) @@ -4583,13 +4579,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close) +H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close /*out*/) { H5P_genplist_t *plist; /* property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*b", fapl_id, evict_on_close); + H5TRACE2("e", "ix", fapl_id, evict_on_close); /* Compare the property list's class against the other class */ if (TRUE != H5P_isa_class(fapl_id, H5P_FILE_ACCESS)) @@ -4670,13 +4666,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled) +H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking /*out*/, hbool_t *ignore_when_disabled /*out*/) { H5P_genplist_t *plist; /* property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*b*b", fapl_id, use_file_locking, ignore_when_disabled); + H5TRACE3("e", "ixx", fapl_id, use_file_locking, ignore_when_disabled); /* Make sure this is a fapl */ if (TRUE != H5P_isa_class(fapl_id, H5P_FILE_ACCESS)) @@ -4844,12 +4840,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collective) +H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collective /*out*/) { herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*b", plist_id, is_collective); + H5TRACE2("e", "ix", plist_id, is_collective); /* Compare the property list's class against the other class */ /* (Dataset, group, attribute, and named datype access property lists @@ -4933,13 +4929,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_mpi_params(hid_t plist_id, MPI_Comm *comm, MPI_Info *info) +H5Pget_mpi_params(hid_t plist_id, MPI_Comm *comm /*out*/, MPI_Info *info /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*Mc*Mi", plist_id, comm, info); + H5TRACE3("e", "ixx", plist_id, comm, info); /* Make sure that the property list is a fapl */ if (TRUE != H5P_isa_class(plist_id, H5P_FILE_ACCESS)) @@ -5383,13 +5379,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective) +H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*b", plist_id, is_collective); + H5TRACE2("e", "ix", plist_id, is_collective); /* Compare the property list's class against the other class */ if (TRUE != H5P_isa_class(plist_id, H5P_FILE_ACCESS)) @@ -5470,13 +5466,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned *min_meta_perc, unsigned *min_raw_perc) +H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size /*out*/, unsigned *min_meta_perc /*out*/, + unsigned *min_raw_perc /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "i*z*Iu*Iu", plist_id, buf_size, min_meta_perc, min_raw_perc); + H5TRACE4("e", "ixxx", plist_id, buf_size, min_meta_perc, min_raw_perc); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_ACCESS))) @@ -5620,13 +5617,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_vol_id(hid_t plist_id, hid_t *vol_id) +H5Pget_vol_id(hid_t plist_id, hid_t *vol_id /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*i", plist_id, vol_id); + H5TRACE2("e", "ix", plist_id, vol_id); /* Get property list for ID */ if (NULL == (plist = (H5P_genplist_t *)H5I_object_verify(plist_id, H5I_GENPROP_LST))) @@ -5666,13 +5663,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_vol_info(hid_t plist_id, void **vol_info) +H5Pget_vol_info(hid_t plist_id, void **vol_info /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i**x", plist_id, vol_info); + H5TRACE2("e", "ix", plist_id, vol_info); /* Get property list for ID */ if (NULL == (plist = (H5P_genplist_t *)H5I_object_verify(plist_id, H5I_GENPROP_LST))) diff --git a/src/H5Pfcpl.c b/src/H5Pfcpl.c index fbf9aac..5da0e4c 100644 --- a/src/H5Pfcpl.c +++ b/src/H5Pfcpl.c @@ -366,13 +366,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_userblock(hid_t plist_id, hsize_t *size) +H5Pget_userblock(hid_t plist_id, hsize_t *size /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*h", plist_id, size); + H5TRACE2("e", "ix", plist_id, size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_CREATE))) @@ -458,13 +458,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_sizes(hid_t plist_id, size_t *sizeof_addr, size_t *sizeof_size) +H5Pget_sizes(hid_t plist_id, size_t *sizeof_addr /*out*/, size_t *sizeof_size /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*z*z", plist_id, sizeof_addr, sizeof_size); + H5TRACE3("e", "ixx", plist_id, sizeof_addr, sizeof_size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_CREATE))) @@ -564,7 +564,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_sym_k(hid_t plist_id, unsigned *ik /*out */, unsigned *lk /*out */) +H5Pget_sym_k(hid_t plist_id, unsigned *ik /*out*/, unsigned *lk /*out*/) { unsigned btree_k[H5B_NUM_BTREE_ID]; H5P_genplist_t *plist; /* Property list pointer */ @@ -654,7 +654,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_istore_k(hid_t plist_id, unsigned *ik /*out */) +H5Pget_istore_k(hid_t plist_id, unsigned *ik /*out*/) { unsigned btree_k[H5B_NUM_BTREE_ID]; H5P_genplist_t *plist; /* Property list pointer */ @@ -825,13 +825,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_shared_mesg_nindexes(hid_t plist_id, unsigned *nindexes) +H5Pget_shared_mesg_nindexes(hid_t plist_id, unsigned *nindexes /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Iu", plist_id, nindexes); + H5TRACE2("e", "ix", plist_id, nindexes); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_CREATE))) @@ -924,8 +924,8 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags, - unsigned *min_mesg_size) +H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags /*out*/, + unsigned *min_mesg_size /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ unsigned nindexes; /* Number of SOHM indexes */ @@ -934,7 +934,7 @@ H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "iIu*Iu*Iu", plist_id, index_num, mesg_type_flags, min_mesg_size); + H5TRACE4("e", "iIuxx", plist_id, index_num, mesg_type_flags, min_mesg_size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_CREATE))) @@ -1219,13 +1219,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_shared_mesg_phase_change(hid_t plist_id, unsigned *max_list, unsigned *min_btree) +H5Pget_shared_mesg_phase_change(hid_t plist_id, unsigned *max_list /*out*/, unsigned *min_btree /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*Iu*Iu", plist_id, max_list, min_btree); + H5TRACE3("e", "ixx", plist_id, max_list, min_btree); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_CREATE))) @@ -1304,14 +1304,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t *strategy, hbool_t *persist, - hsize_t *threshold) +H5Pget_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t *strategy /*out*/, hbool_t *persist /*out*/, + hsize_t *threshold /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "i*Ff*b*h", plist_id, strategy, persist, threshold); + H5TRACE4("e", "ixxx", plist_id, strategy, persist, threshold); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_CREATE))) @@ -1455,13 +1455,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_file_space_page_size(hid_t plist_id, hsize_t *fsp_size) +H5Pget_file_space_page_size(hid_t plist_id, hsize_t *fsp_size /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*h", plist_id, fsp_size); + H5TRACE2("e", "ix", plist_id, fsp_size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_FILE_CREATE))) diff --git a/src/H5Pint.c b/src/H5Pint.c index 001f62b..f67e4d7 100644 --- a/src/H5Pint.c +++ b/src/H5Pint.c @@ -5012,9 +5012,9 @@ done: herr_t H5P_close(void *_plist) { - H5P_genclass_t *tclass; /* Temporary class pointer */ + H5P_genclass_t *tclass; /* Temporary class pointer */ H5P_genplist_t *plist = (H5P_genplist_t *)_plist; - H5SL_t * seen = NULL; /* Skip list to hold names of properties already seen */ + H5SL_t * seen = NULL; /* Skip list to hold names of properties already seen */ size_t nseen; /* Number of items 'seen' */ hbool_t has_parent_class; /* Flag to indicate that this property list's class has a parent */ size_t ndel; /* Number of items deleted */ diff --git a/src/H5Plapl.c b/src/H5Plapl.c index 8640b89..08cc5c8 100644 --- a/src/H5Plapl.c +++ b/src/H5Plapl.c @@ -946,13 +946,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_nlinks(hid_t plist_id, size_t *nlinks) +H5Pget_nlinks(hid_t plist_id, size_t *nlinks /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*z", plist_id, nlinks); + H5TRACE2("e", "ix", plist_id, nlinks); if (!nlinks) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid pointer passed in"); @@ -1021,7 +1021,7 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Pget_elink_prefix(hid_t plist_id, char *prefix, size_t size) +H5Pget_elink_prefix(hid_t plist_id, char *prefix /*out*/, size_t size) { H5P_genplist_t *plist; /* Property list pointer */ char * my_prefix; /* Library's copy of the prefix */ @@ -1029,7 +1029,7 @@ H5Pget_elink_prefix(hid_t plist_id, char *prefix, size_t size) ssize_t ret_value; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("Zs", "i*sz", plist_id, prefix, size); + H5TRACE3("Zs", "ixz", plist_id, prefix, size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_LINK_ACCESS))) @@ -1180,13 +1180,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_elink_acc_flags(hid_t lapl_id, unsigned *flags) +H5Pget_elink_acc_flags(hid_t lapl_id, unsigned *flags /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Iu", lapl_id, flags); + H5TRACE2("e", "ix", lapl_id, flags); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(lapl_id, H5P_LINK_ACCESS))) @@ -1223,7 +1223,7 @@ H5Pset_elink_cb(hid_t lapl_id, H5L_elink_traverse_t func, void *op_data) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ix*x", lapl_id, func, op_data); + H5TRACE3("e", "iLt*x", lapl_id, func, op_data); /* Check if the callback function is NULL and the user data is non-NULL. * This is almost certainly an error as the user data will not be used. */ @@ -1260,14 +1260,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_elink_cb(hid_t lapl_id, H5L_elink_traverse_t *func, void **op_data) +H5Pget_elink_cb(hid_t lapl_id, H5L_elink_traverse_t *func /*out*/, void **op_data /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ H5L_elink_cb_t cb_info; /* Callback info struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*x**x", lapl_id, func, op_data); + H5TRACE3("e", "ixx", lapl_id, func, op_data); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(lapl_id, H5P_LINK_ACCESS))) diff --git a/src/H5Pmapl.c b/src/H5Pmapl.c index a1f0fae..ca9c5c0 100644 --- a/src/H5Pmapl.c +++ b/src/H5Pmapl.c @@ -182,13 +182,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_map_iterate_hints(hid_t mapl_id, size_t *key_prefetch_size, size_t *key_alloc_size) +H5Pget_map_iterate_hints(hid_t mapl_id, size_t *key_prefetch_size /*out*/, size_t *key_alloc_size /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*z*z", mapl_id, key_prefetch_size, key_alloc_size); + H5TRACE3("e", "ixx", mapl_id, key_prefetch_size, key_alloc_size); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(mapl_id, H5P_MAP_ACCESS))) diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index d8cc430..b9e1180 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -29,4 +29,47 @@ #define H5_MY_PKG_ERR H5E_PLIST #define H5_MY_PKG_INIT YES +/**\defgroup H5P H5P + * \brief Property List Interface + * + * \details The HDF5 Property List Interface provides a mechanism to take + * advantage of more powerful or unusual features in HDF5. + * + * HDF5 objects have properties or characteristics associated with + * them, and there are default properties that handle the most + * common needs. These default properties can be modified using the + * HDF5 Property List Interface. For example, the data storage + * layout property of a dataset is contiguous by default. For better + * performance, the layout can be modified to be chunked or chunked + * and compressed. + * + * \todo Describe concisely what the functions in this module are about. + * \todo Clicking on "more" after "Property List Interface" at the top does not work + * + * \defgroup GPLO General Property List Operations + * \ingroup H5P + * \defgroup GPLOA General Property List Operations (Advanced) + * \ingroup H5P + * \defgroup FCPL File Creation Properties + * \ingroup H5P + * \defgroup FAPL File Access Properties + * \ingroup H5P + * \defgroup GCPL Group Creation Properties + * \ingroup H5P + * \defgroup ALCAPL Attribute and Link Creation Properties + * \ingroup H5P + * \defgroup LAPL Link Access Properties + * \ingroup H5P + * \defgroup DCPL Dataset Creation Properties + * \ingroup H5P + * \defgroup DAPL Dataset Access Properties + * \ingroup H5P + * \defgroup DXPL Dataset Transfer Properties + * \ingroup H5P + * \defgroup OCPL Object Creation Properties + * \ingroup H5P + * \defgroup OCPPL Object Copy Properties + * \ingroup H5P + */ + #endif /* _H5Pmodule_H */ diff --git a/src/H5Pocpl.c b/src/H5Pocpl.c index bd6be75..387ecdc 100644 --- a/src/H5Pocpl.c +++ b/src/H5Pocpl.c @@ -251,13 +251,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense) +H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact /*out*/, unsigned *min_dense /*out*/) { H5P_genplist_t *plist; /* Property list pointer */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*Iu*Iu", plist_id, max_compact, min_dense); + H5TRACE3("e", "ixx", plist_id, max_compact, min_dense); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_OBJECT_CREATE))) @@ -342,12 +342,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_attr_creation_order(hid_t plist_id, unsigned *crt_order_flags) +H5Pget_attr_creation_order(hid_t plist_id, unsigned *crt_order_flags /*out*/) { herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*Iu", plist_id, crt_order_flags); + H5TRACE2("e", "ix", plist_id, crt_order_flags); /* Get values */ if (crt_order_flags) { @@ -445,12 +445,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_obj_track_times(hid_t plist_id, hbool_t *track_times) +H5Pget_obj_track_times(hid_t plist_id, hbool_t *track_times /*out*/) { herr_t ret_value = SUCCEED; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("e", "i*b", plist_id, track_times); + H5TRACE2("e", "ix", plist_id, track_times); /* Get values */ if (track_times) { @@ -931,13 +931,13 @@ done: herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, size_t *cd_nelmts /*in_out*/, unsigned cd_values[] /*out*/, size_t namelen, - char name[] /*out*/, unsigned *filter_config) + char name[] /*out*/, unsigned *filter_config /*out*/) { H5P_genplist_t *plist; /* Property list */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE8("e", "iZfx*zxzx*Iu", plist_id, id, flags, cd_nelmts, cd_values, namelen, name, filter_config); + H5TRACE8("e", "iZfx*zxzxx", plist_id, id, flags, cd_nelmts, cd_values, namelen, name, filter_config); /* Check args */ if (cd_nelmts || cd_values) { diff --git a/src/H5Pocpypl.c b/src/H5Pocpypl.c index 1f4b31e..f05afb0 100644 --- a/src/H5Pocpypl.c +++ b/src/H5Pocpypl.c @@ -837,7 +837,7 @@ H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, void *op_data) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "ix*x", plist_id, func, op_data); + H5TRACE3("e", "iOs*x", plist_id, func, op_data); /* Check if the callback function is NULL and the user data is non-NULL. * This is almost certainly an error as the user data will not be used. */ @@ -878,14 +878,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, void **op_data) +H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func /*out*/, void **op_data /*out*/) { H5P_genplist_t * plist; /* Property list pointer */ H5O_mcdt_cb_info_t cb_info; /* Callback info struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*x**x", plist_id, func, op_data); + H5TRACE3("e", "ixx", plist_id, func, op_data); /* Get the plist structure */ if (NULL == (plist = H5P_object_verify(plist_id, H5P_OBJECT_COPY))) diff --git a/src/H5Ppkg.h b/src/H5Ppkg.h index 166f1f2..075eae0 100644 --- a/src/H5Ppkg.h +++ b/src/H5Ppkg.h @@ -86,8 +86,7 @@ struct H5P_genclass_t { char * name; /* Name of property list class */ H5P_plist_type_t type; /* Type of property */ size_t nprops; /* Number of properties in class */ - unsigned - plists; /* Number of property lists that have been created since the last modification to the class */ + unsigned plists; /* Number of property lists that have been created since the last modification to the class */ unsigned classes; /* Number of classes that have been derived since the last modification to the class */ unsigned ref_count; /* Number of outstanding ID's open on this class object */ hbool_t deleted; /* Whether this class has been deleted and is waiting for dependent classes & proplists diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index ffcdd99..a978895 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -232,11 +232,153 @@ H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g; /*********************/ /* Generic property list routines */ + +/** + * \ingroup GPLO + * + * \brief Terminates access to a property list + * + * \plist_id + * + * \return \herr_t + * + * \details H5Pclose() terminates access to a property list. All property + * lists should be closed when the application is finished + * accessing them. This frees resources used by the property + * list. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pclose(hid_t plist_id); +/** + * \ingroup GPLO + * + * \brief Creates a new property list as an instance of a property list class + * + * \plistcls_id{cls_id} + * + * \return \hid_t{property list} + * + * \details H5Pcreate() creates a new property list as an instance of + * some property list class. The new property list is initialized + * with default values for the specified class. The classes are as + * follows: + * + * <table> + * <tr> + * <th>Class Identifier</th> + * <th>Class Name</th> + * <th>Comments</th> + * </tr> + * <tr> + * <td>#H5P_ATTRIBUTE_CREATE</td> + * <td>attribute create</td> + * <td>Properties for attribute creation</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_ACCESS</td> + * <td>dataset access</td> + * <td>Properties for dataset access</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_CREATE</td> + * <td>dataset create</td> + * <td>Properties for dataset creation</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_XFER</td> + * <td>data transfer</td> + * <td>Properties for raw data transfer</td> + * </tr> + * <tr> + * <td>#H5P_DATATYPE_ACCESS</td> + * <td>datatype access</td> + * <td>Properties for datatype access</td> + * </tr> + * <tr> + * <td>#H5P_DATATYPE_CREATE</td> + * <td>datatype create</td> + * <td>Properties for datatype creation</td> + * </tr> + * <tr> + * <td>#H5P_FILE_ACCESS</td> + * <td>file access</td> + * <td>Properties for file access</td> + * </tr> + * <tr> + * <td>#H5P_FILE_CREATE</td> + * <td>file create</td> + * <td>Properties for file creation</td> + * </tr> + * <tr> + * <td>#H5P_FILE_MOUNT</td> + * <td>file mount</td> + * <td>Properties for file mounting</td> + * </tr> + * <tr valign="top"> + * <td>#H5P_GROUP_ACCESS</td> + * <td>group access</td> + * <td>Properties for group access</td> + * </tr> + * <tr> + * <td>#H5P_GROUP_CREATE</td> + * <td>group create</td> + * <td>Properties for group creation</td> + * </tr> + * <tr> + * <td>#H5P_LINK_ACCESS</td> + * <td>link access</td> + * <td>Properties governing link traversal when accessing objects</td> + * </tr> + * <tr> + * <td>#H5P_LINK_CREATE</td> + * <td>link create</td> + * <td>Properties governing link creation</td> + * </tr> + * <tr> + * <td>#H5P_OBJECT_COPY</td> + * <td>object copy</td> + * <td>Properties governing the object copying process</td> + * </tr> + * <tr> + * <td>#H5P_OBJECT_CREATE</td> + * <td>object create</td> + * <td>Properties for object creation</td> + * </tr> + * <tr> + * <td>#H5P_STRING_CREATE</td> + * <td>string create</td> + * <td>Properties for character encoding when encoding strings or + * object names</td> + * </tr> + * <tr> + * <td>#H5P_VOL_INITIALIZE</td> + * <td>vol initialize</td> + * <td>Properties for VOL initialization</td> + * </tr> + * </table> + * + * This property list must eventually be closed with H5Pclose(); + * otherwise, errors are likely to occur. + * + * \version 1.12.0 The #H5P_VOL_INITIALIZE property list class was added + * \version 1.8.15 For each class, the class name returned by + * H5Pget_class_name() was added. + * The list of possible Fortran values was updated. + * \version 1.8.0 The following property list classes were added at this + * release: #H5P_DATASET_ACCESS, #H5P_GROUP_CREATE, + * #H5P_GROUP_ACCESS, #H5P_DATATYPE_CREATE, + * #H5P_DATATYPE_ACCESS, #H5P_ATTRIBUTE_CREATE + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Pcreate(hid_t cls_id); H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t cls_create, void *create_data, H5P_cls_copy_func_t cls_copy, void *copy_data, H5P_cls_close_func_t cls_close, void *close_data); H5_DLL char * H5Pget_class_name(hid_t pclass_id); -H5_DLL hid_t H5Pcreate(hid_t cls_id); H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, @@ -262,10 +404,80 @@ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); H5_DLL herr_t H5Pclose_class(hid_t plist_id); -H5_DLL herr_t H5Pclose(hid_t plist_id); H5_DLL hid_t H5Pcopy(hid_t plist_id); /* Object creation property list (OCPL) routines */ + +/** + * \ingroup OCPL + * + * \brief Returns information about a filter in a pipeline + * + * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in + * H5Ppublic.h + * + * \plist_id{plist_id} + * \param[in] idx Sequence number within the filter pipeline of the filter + * for which information is sought + * \param[out] flags Bit vector specifying certain general properties of the + * filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * \param[out] filter_config Bit field, as described in H5Zget_filter_info() + * + * \return Returns a negative value on failure, and the filter identifier + * if successful (see #H5Z_filter_t): + * - #H5Z_FILTER_DEFLATE Data compression filter, + * employing the gzip algorithm + * - #H5Z_FILTER_SHUFFLE Data shuffling filter + * - #H5Z_FILTER_FLETCHER32 Error detection filter, employing the + * Fletcher32 checksum algorithm + * - #H5Z_FILTER_SZIP Data compression filter, employing the + * SZIP algorithm + * - #H5Z_FILTER_NBIT Data compression filter, employing the + * N-bit algorithm + * - #H5Z_FILTER_SCALEOFFSET Data compression filter, employing the + * scale-offset algorithm + * + * \details H5Pget_filter2() returns information about a filter specified by + * its filter number, in a filter pipeline specified by the property + * list with which it is associated. + * + * \p plist_id must be a dataset or group creation property list. + * + * \p idx is a value between zero and N-1, as described in + * H5Pget_nfilters(). The function will return a negative value if + * the filter number is out of range. + * + * The structure of the \p flags argument is discussed in + * H5Pset_filter(). + * + * On input, \p cd_nelmts indicates the number of entries in the + * \p cd_values array, as allocated by the caller; on return, + * \p cd_nelmts contains the number of values defined by the filter. + * + * If \p name is a pointer to an array of at least \p namelen bytes, + * the filter name will be copied into that array. The name will be + * null terminated if \p namelen is large enough. The filter name + * returned will be the name appearing in the file, the name + * registered for the filter, or an empty string. + * + * \p filter_config is the bit field described in + * H5Zget_filter_info(). + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \since 1.8.0 + * + */ +H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx, + unsigned int *flags/*out*/, + size_t *cd_nelmts/*out*/, + unsigned cd_values[]/*out*/, + size_t namelen, char name[], + unsigned *filter_config /*out*/); H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense); H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags); @@ -277,9 +489,6 @@ H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int c_values[]); H5_DLL int H5Pget_nfilters(hid_t plist_id); -H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, - size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, - char name[], unsigned *filter_config /*out*/); H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[] /*out*/, unsigned *filter_config /*out*/); @@ -379,10 +588,592 @@ H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned unsigned *min_raw_per); /* Dataset creation property list (DCPL) routines */ -H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); + +/** + * \ingroup DCPL + * + * \brief Retrieves the size of chunks for the raw data of a chunked + * layout dataset + * + * \dcpl_id{plist_id} + * \param[in] max_ndims Size of the \p dims array + * \param[out] dim Array to store the chunk dimensions + * + * \return Returns chunk dimensionality if successful; + * otherwise returns a negative value. + * + * \details H5Pget_chunk() retrieves the size of chunks for the raw data + * of a chunked layout dataset. This function is only valid for + * dataset creation property lists. At most, \p max_ndims elements + * of \p dim will be initialized. + * + * \since 1.0.0 + * + */ +H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[]/*out*/); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Retrieves the edge chunk option setting from a dataset creation + * property list + * + * \dcpl_id{plist_id} + * \param[out] opts Edge chunk option flag. Valid values are described in + * H5Pset_chunk_opts(). The option status can be + * retrieved using the bitwise AND operator ( & ). For + * example, the expression + * (opts&#H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS) will + * evaluate to #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS if + * that option has been enabled. Otherwise, it will + * evaluate to 0 (zero). + * + * \return \herr_t + * + * \details H5Pget_chunk_opts() retrieves the edge chunk option setting + * stored in the dataset creation property list \p plist_id. + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Retrieves the time when fill values are written to a dataset + * + * \dcpl_id{plist_id} + * \param[out] fill_time Setting for the timing of writing fill values to + * the dataset + * + * \return \herr_t + * + * \details H5Pget_fill_time() examines the dataset creation property list + * \p plist_id to determine when fill values are to be written to + * a dataset. Valid values returned in \p fill_time are as + * follows: + * + * <table> + * <tr> + * <td>#H5D_FILL_TIME_IFSET</td> + * <td>Fill values are written to the dataset when storage + * space is allocated only if there is a user-defined fill + * value, i.e., one set with H5Pset_fill_value(). (Default) + * </td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_ALLOC</td> + * <td>Fill values are written to the dataset when storage + * space is allocated.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_NEVER</td> + * <td>Fill values are never written to the dataset.</td> + * </tr> + * </table> + * + * \note H5Pget_fill_time() is designed to work in coordination with the + * dataset fill value and dataset storage allocation time properties, + * retrieved with the functions H5Pget_fill_value() and + * H5Pget_alloc_time(). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t + *fill_time/*out*/); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Retrieves a dataset fill value + * + * \dcpl_id{plist_id} + * \param[in] type_id Datatype identifier for the value passed via + * \p value + * \param[out] value Pointer to buffer to contain the returned + * fill value + * + * \return \herr_t + * + * \details H5Pget_fill_value() returns the dataset fill value defined in + * the dataset creation property list \p plist_id. The fill value + * is returned through the \p value pointer and will be converted + * to the datatype specified by \p type_id. This datatype may + * differ from the fill value datatype in the property list, but + * the HDF5 library must be able to convert between the two + * datatypes. + * + * If the fill value is undefined, i.e., set to NULL in the + * property list, H5Pget_fill_value() will return an error. + * H5Pfill_value_defined() should be used to check for this + * condition before H5Pget_fill_value() is called. + * + * Memory must be allocated by the calling application. + * + * \note H5Pget_fill_value() is designed to coordinate with the dataset + * storage allocation time and fill value write time properties, + * which can be retrieved with the functions H5Pget_alloc_time() + * and H5Pget_fill_time(), respectively. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, + void *value/*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Returns the layout of the raw data for a dataset + * + * \dcpl_id{plist_id} + * + * \return Returns the layout type (a non-negative value) of a dataset + * creation property list if successful. Valid return values are: + * - #H5D_COMPACT: Raw data is stored in the object header in the + * file. + * - #H5D_CONTIGUOUS: Raw data is stored separately from the object + * header in one contiguous chunk in the file. + * - #H5D_CHUNKED: Raw data is stored separately from the object + * header in chunks in separate locations in the + * file. + * - #H5D_VIRTUAL: Raw data is drawn from multiple datasets in + * different files. + * \return + * Otherwise, returns a negative value indicating failure. + * + * \details H5Pget_layout() returns the layout of the raw data for a + * dataset. This function is only valid for dataset creation + * property lists. + * + * Note that a compact storage layout may affect writing data to + * the dataset with parallel applications. See the H5Dwrite() + * documentation for details. + * + * \version 1.10.0 #H5D_VIRTUAL added in this release. + * + * \since 1.0.0 + * + */ H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id); -H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]); -H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Sets the size of the chunks used to store a chunked layout + * dataset + * + * \dcpl_id{plist_id} + * \param[in] ndims The number of dimensions of each chunk + * \param[in] dim An array defining the size, in dataset elements, of + * each chunk + * + * \return \herr_t + * \details H5Pset_chunk() sets the size of the chunks used to store a + * chunked layout dataset. This function is only valid for dataset + * creation property lists. + * + * The \p ndims parameter currently must be the same size as the + * rank of the dataset. + * + * The values of the \p dim array define the size of the chunks + * to store the dataset's raw data. The unit of measure for \p dim + * values is dataset elements. + * + * As a side-effect of this function, the layout of the dataset is + * changed to #H5D_CHUNKED, if it is not already so set. + * + * \note Chunk size cannot exceed the size of a fixed-size dataset. For + * example, a dataset consisting of a 5x4 fixed-size array cannot be + * defined with 10x10 chunks. Chunk maximums: + * - The maximum number of elements in a chunk is 2<sup>32</sup>-1 which + * is equal to 4,294,967,295. If the number of elements in a chunk is + * set via H5Pset_chunk() to a value greater than 2<sup>32</sup>-1, + * then H5Pset_chunk() will fail. + * - The maximum size for any chunk is 4GB. If a chunk that is larger + * than 4GB attempts to be written with H5Dwrite(), then H5Dwrite() + * will fail. + * + * \see H5Pset_layout(), H5Dwrite() + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets the edge chunk option in a dataset creation property list + * + * \dcpl_id{plist_id} + * \param[in] opts Edge chunk option flag. Valid values are: + * \li #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS + * When enabled, filters are not applied to partial + * edge chunks. When disabled, partial edge chunks are + * filtered. Enabling this option will improve + * performance when appending to the dataset and, when + * compression filters are used, prevent reallocation + * of these chunks. Datasets created with this option + * enabled will be inaccessible with HDF5 library + * versions before Release 1.10. Default: \e Disabled + * \li 0 (zero) Disables option; partial edge chunks + * will be compressed. + * + * \return \herr_t + * + * \details H5Pset_chunk_opts() sets the edge chunk option in the + * dataset creation property list \p dcpl_id. + * + * The available option is detailed in the parameters section. + * Only chunks that are not completely filled by the dataset’s + * dataspace are affected by this option. Such chunks are + * referred to as partial edge chunks. + * + * \note \b Motivation: H5Pset_chunk_opts() is used to specify storage + * options for chunks on the edge of a dataset’s dataspace. This + * capability allows the user to tune performance in cases where + * the dataset size may not be a multiple of the chunk size and + * the handling of partial edge chunks can impact performance. + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets the time when fill values are written to a dataset + * + * \dcpl_id{plist_id} + * \param[in] fill_time When to write fill values to a dataset + * + * \return \herr_t + * + * \details H5Pset_fill_time() sets up the timing for writing fill values + * to a dataset. This property is set in the dataset creation + * property list \p plist_id. Timing is specified in \p fill_time + * with one of the following values: + * + * <table> + * <tr> + * <td>#H5D_FILL_TIME_IFSET</td> + * <td>Write fill values to the dataset when storage space is + * allocated only if there is a user-defined fill value, + * i.e.,one set with H5Pset_fill_value(). (Default)</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_ALLOC</td> + * <td>Write fill values to the dataset when storage space is + * allocated.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_NEVER</td> + * <td>Never write fill values to the dataset.</td> + * </tr> + * </table> + * + * \note H5Pset_fill_time() is designed for coordination with the dataset + * fill value and dataset storage allocation time properties, set + * with the functions H5Pset_fill_value() and H5Pset_alloc_time(). + * See H5Dcreate() for further cross-references. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets the fill value for a dataset + * + * \dcpl_id{plist_id} + * \param[in] type_id Datatype of \p value + * \param[in] value Pointer to buffer containing value to use as + * fill value + * + * \return \herr_t + * + * \details H5Pset_fill_value() sets the fill value for a dataset in the + * dataset creation property list. \p value is interpreted as + * being of datatype \p type_id. This datatype may differ from + * that of the dataset, but the HDF5 library must be able to + * convert \p value to the dataset datatype when the dataset is + * created. + * + * The default fill value is 0 (zero), which is interpreted + * according to the actual dataset datatype. + * + * Setting \p value to NULL indicates that the fill value is to + * be undefined. + * + * \note Applications sometimes write data only to portions of an allocated + * dataset. It is often useful in such cases to fill the unused space + * with a known fill value. This function allows the user application + * to set that fill value; the functions H5Dfill() and + * H5Pset_fill_time(), respectively, provide the ability to apply the + * fill value on demand or to set up its automatic application. + * + * \note A fill value should be defined so that it is appropriate for the + * application. While the HDF5 default fill value is 0 (zero), it is + * often appropriate to use another value. It might be useful, for + * example, to use a value that is known to be impossible for the + * application to legitimately generate. + * + * \note H5Pset_fill_value() is designed to work in concert with + * H5Pset_alloc_time() and H5Pset_fill_time(). H5Pset_alloc_time() + * and H5Pset_fill_time() govern the timing of dataset storage + * allocation and fill value write operations and can be important in + * tuning application performance. + * + * \note See H5Dcreate() for further cross-references. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, + const void *value); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets up use of the shuffle filter + * + * \dcpl_id{plist_id} + * + * \return \herr_t + * + * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE, + * in the dataset creation property list \p plist_id. The shuffle + * filter de-interlaces a block of data by reordering the bytes. + * All the bytes from one consistent byte position of each data + * element are placed together in one block; all bytes from a + * second consistent byte position of each data element are placed + * together a second block; etc. For example, given three data + * elements of a 4-byte datatype stored as 012301230123, shuffling + * will re-order data as 000111222333. This can be a valuable step + * in an effective compression algorithm because the bytes in each + * byte position are often closely related to each other and + * putting them together can increase the compression ratio. + * + * As implied above, the primary value of the shuffle filter lies + * in its coordinated use with a compression filter; it does not + * provide data compression when used alone. When the shuffle + * filter is applied to a dataset immediately prior to the use of + * a compression filter, the compression ratio achieved is often + * superior to that achieved by the use of a compression filter + * without the shuffle filter. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Sets the type of storage used to store the raw data for a dataset + * + * \dcpl_id{plist_id} + * \param[in] layout Type of storage layout for raw data + * + * \return \herr_t + * \details H5Pset_layout() sets the type of storage used to store the raw + * data for a dataset. This function is only valid for dataset + * creation property lists. + * + * Valid values for \p layout are: + * - #H5D_COMPACT: Store raw data in the dataset object header + * in file. This should only be used for datasets + * with small amounts of raw data. The raw data + * size limit is 64K (65520 bytes). Attempting + * to create a dataset with raw data larger than + * this limit will cause the H5Dcreate() call to + * fail. + * - #H5D_CONTIGUOUS: Store raw data separately from the object + * header in one large chunk in the file. + * - #H5D_CHUNKED: Store raw data separately from the object header + * as chunks of data in separate locations in + * the file. + * - #H5D_VIRTUAL: Draw raw data from multiple datasets in + * different files. + * + * Note that a compact storage layout may affect writing data to + * the dataset with parallel applications. See the note in + * H5Dwrite() documentation for details. + * \version 1.10.0 #H5D_VIRTUAL added in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Sets up use of the SZIP compression filter + * + * \dcpl_id{plist_id} + * \param[in] options_mask A bit-mask conveying the desired SZIP options; + * Valid values are #H5_SZIP_EC_OPTION_MASK and + * #H5_SZIP_NN_OPTION_MASK. + * \param[in] pixels_per_block The number of pixels or data elements in each + * data block + * + * \return \herr_t + * + * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP, + * for a dataset. SZIP is a compression method designed for use with + * scientific data. + * + * Before proceeding, all users should review the “Limitations” + * section below. + * + * Users familiar with SZIP outside the HDF5 context may benefit + * from reviewing the Note “For Users Familiar with SZIP in Other + * Contexts” below. + * + * In the text below, the term pixel refers to an HDF5 data element. + * This terminology derives from SZIP compression's use with image + * data, where pixel referred to an image pixel. + * + * The SZIP \p bits_per_pixel value (see Note, below) is automatically + * set, based on the HDF5 datatype. SZIP can be used with atomic + * datatypes that may have size of 8, 16, 32, or 64 bits. + * Specifically, a dataset with a datatype that is 8-, 16-, 32-, or + * 64-bit signed or unsigned integer; char; or 32- or 64-bit float + * can be compressed with SZIP. See Note, below, for further + * discussion of the the SZIP \p bits_per_pixel setting. + * + * SZIP options are passed in an options mask, \p options_mask, + * as follows. + * + * <table> + * <tr> + * <th>Option</th> + * <th>Description (Mutually exclusive; select one.)</th> + * </tr> + * <tr> + * <td>#H5_SZIP_EC_OPTION_MASK</td> + * <td>Selects entropy coding method</td> + * </tr> + * <tr> + * <td>#H5_SZIP_NN_OPTION_MASK</td> + * <td>Selects nearest neighbor coding method</td> + * </tr> + * </table> + * + * The following guidelines can be used in determining which + * option to select: + * + * - The entropy coding method, the EC option specified by + * #H5_SZIP_EC_OPTION_MASK, is best suited for data that has been + * processed. The EC method works best for small numbers. + * - The nearest neighbor coding method, the NN option specified + * by #H5_SZIP_NN_OPTION_MASK, preprocesses the data then the + * applies EC method as above. + * + * Other factors may affect results, but the above criteria + * provides a good starting point for optimizing data compression. + * + * SZIP compresses data block by block, with a user-tunable block + * size. This block size is passed in the parameter + * \p pixels_per_block and must be even and not greater than 32, + * with typical values being 8, 10, 16, or 32. This parameter + * affects compression ratio; the more pixel values vary, the + * smaller this number should be to achieve better performance. + * + * In HDF5, compression can be applied only to chunked datasets. + * If \p pixels_per_block is bigger than the total number of + * elements in a dataset chunk, H5Pset_szip() will succeed but + * the subsequent call to H5Dcreate() will fail; the conflict + * can be detected only when the property list is used. + * + * To achieve optimal performance for SZIP compression, it is + * recommended that a chunk's fastest-changing dimension be equal + * to N times \p pixels_per_block where N is the maximum number of + * blocks per scan line allowed by the SZIP library. In the + * current version of SZIP, N is set to 128. + * + * SZIP compression is an optional HDF5 filter. + * + * \b Limitations: + * + * - SZIP compression cannot be applied to compound, array, + * variable-length, enumeration, or any other user-defined + * datatypes. If an SZIP filter is set in a dataset creation + * property list used to create a dataset containing a + * non-allowed datatype, the call to H5Dcreate() will fail; the + * conflict can be detected only when the property list is used. + * - Users should be aware that there are factors that affect one’s + * rights and ability to use SZIP compression by reviewing the + * SZIP copyright notice. + * + * \note \b For \b Users \b Familiar \b with \b SZIP \b in \b Other \b Contexts: + * + * \note The following notes are of interest primarily to those who have + * used SZIP compression outside of the HDF5 context. + * In non-HDF5 applications, SZIP typically requires that the user + * application supply additional parameters: + * - \p pixels_in_object, the number of pixels in the object to + * be compressed + * - \p bits_per_pixel, the number of bits per pixel + * - \p pixels_per_scanline, the number of pixels per scan line + * + * \note These values need not be independently supplied in the HDF5 + * environment as they are derived from the datatype and dataspace, + * which are already known. In particular, HDF5 sets + * \p pixels_in_object to the number of elements in a chunk and + * \p bits_per_pixel to the size of the element or pixel datatype. + * + * \note The following algorithm is used to set \p pixels_per_scanline: + * - If the size of a chunk's fastest-changing dimension, size, + * is greater than 4K, set \p pixels_per_scanline to 128 times + * \p pixels_per_block. + * - If size is less than 4K but greater than \p pixels_per_block, + * set \p pixels_per_scanline to the minimum of size and 128 + * times \p pixels_per_block. + * - If size is less than \p pixels_per_block but greater than the + * number elements in the chunk, set \p pixels_per_scanline to + * the minimum of the number elements in the chunk and 128 times + * \p pixels_per_block. + * + * \note The HDF5 datatype may have precision that is less than the full + * size of the data element, e.g., an 11-bit integer can be defined + * using H5Tset_precision(). To a certain extent, SZIP can take + * advantage of the precision of the datatype to improve compression: + * - If the HDF5 datatype size is 24-bit or less and the offset of + * the bits in the HDF5 datatype is zero (see H5Tset_offset() or + * H5Tget_offset()), the data is the in lowest N bits of the data + * element. In this case, the SZIP \p bits_per_pixel is set to the + * precision of the HDF5 datatype. + * - If the offset is not zero, the SZIP \p bits_per_pixel will be + * set to the number of bits in the full size of the data element. + * - If the HDF5 datatype precision is 25-bit to 32-bit, the SZIP + * \p bits_per_pixel will be set to 32. + * - If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP + * \p bits_per_pixel will be set to 64. + * + * \note HDF5 always modifies the options mask provided by the user to set up + * usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of + * LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the + * datatype. + * + * \since 1.6.0 + * + *-------------------------------------------------------------------------- + */ +H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name, const char *src_dset_name, hid_t src_space_id); H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count /*out*/); @@ -391,22 +1182,14 @@ H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index); H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size); H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size); H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size); -H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts); -H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts); H5_DLL int H5Pget_external_count(hid_t plist_id); H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out*/, off_t *offset /*out*/, hsize_t *size /*out*/); -H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); -H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); H5_DLL herr_t H5Pset_nbit(hid_t plist_id); H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor); -H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value); -H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out*/); H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status); H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time); H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*out*/); -H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time); -H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*/); H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize); H5_DLL herr_t H5Pset_dset_no_attrs_hint(hid_t dcpl_id, hbool_t minimize); @@ -526,6 +1309,59 @@ H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, vo H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close); H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc); +/** + *------------------------------------------------------------------------- + * \ingroup OCPL + * + * \brief Returns information about a filter in a pipeline (DEPRECATED) + * + * \todo H5Pget_filter1() prototype does not match source in H5Pocpl.c. + * Also, it is not in a deprecated file. Is that okay? + * + * \plist_id{plist_id} + * \param[in] filter Sequence number within the filter pipeline of the filter + * for which information is sought + * \param[out] flags Bit vector specifying certain general properties of + * the filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * + * \return Returns the filter identifier if successful; Otherwise returns + * a negative value. See: #H5Z_filter_t + * + * \details H5Pget_filter1() returns information about a filter, specified + * by its filter number, in a filter pipeline, specified by the + * property list with which it is associated. + * + * \p plist_id must be a dataset or group creation property list. + * + * \p filter is a value between zero and N-1, as described in + * H5Pget_nfilters(). The function will return a negative value + * if the filter number is out of range. + * + * The structure of the \p flags argument is discussed in + * H5Pset_filter(). + * + * On input, \p cd_nelmts indicates the number of entries in the + * \p cd_values array, as allocated by the caller; on return, + * \p cd_nelmts contains the number of values defined by the filter. + * + * If \p name is a pointer to an array of at least \p namelen + * bytes, the filter name will be copied into that array. The name + * will be null terminated if \p namelen is large enough. The + * filter name returned will be the name appearing in the file, the + * name registered for the filter, or an empty string. + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \version 1.8.0 N-bit and scale-offset filters added. + * \version 1.8.0 Function H5Pget_filter() renamed to H5Pget_filter1() and + * deprecated in this release. + * \version 1.6.4 \p filter parameter type changed to unsigned. + * + */ H5_DLL H5Z_filter_t H5Pget_filter1(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[]); @@ -724,7 +724,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type) +H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type /*out*/) { hid_t loc_id; /* Reference location ID */ H5VL_object_t * vol_obj = NULL; /* Object of loc_id */ @@ -733,7 +733,7 @@ H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type) herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "*Rri*Ot", ref_ptr, rapl_id, obj_type); + H5TRACE3("e", "*Rrix", ref_ptr, rapl_id, obj_type); /* Check args */ if (ref_ptr == NULL) @@ -784,13 +784,13 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Rget_file_name(const H5R_ref_t *ref_ptr, char *buf, size_t size) +H5Rget_file_name(const H5R_ref_t *ref_ptr, char *buf /*out*/, size_t size) { hid_t loc_id; /* Reference location ID */ ssize_t ret_value; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE3("Zs", "*Rr*sz", ref_ptr, buf, size); + H5TRACE3("Zs", "*Rrxz", ref_ptr, buf, size); /* Check args */ if (ref_ptr == NULL) @@ -833,7 +833,7 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *buf, size_t size) +H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *buf /*out*/, size_t size) { hid_t loc_id; /* Reference location ID */ H5VL_object_t * vol_obj = NULL; /* Object of loc_id */ @@ -842,7 +842,7 @@ H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *buf, size_t size) ssize_t ret_value = 0; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE4("Zs", "*Rri*sz", ref_ptr, rapl_id, buf, size); + H5TRACE4("Zs", "*Rrixz", ref_ptr, rapl_id, buf, size); /* Check args */ if (ref_ptr == NULL) @@ -892,12 +892,12 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *buf, size_t size) +H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *buf /*out*/, size_t size) { ssize_t ret_value; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE3("Zs", "*Rr*sz", ref_ptr, buf, size); + H5TRACE3("Zs", "*Rrxz", ref_ptr, buf, size); /* Check args */ if (ref_ptr == NULL) @@ -15,25 +15,76 @@ * Reference counted string algorithms. * * These are used for various internal strings which get copied multiple times. + * They also efficiently handle dynamically allocations and appends. * */ -#include "H5Eprivate.h" /* Error handling */ -#include "H5FLprivate.h" /* Free lists */ -#include "H5RSprivate.h" /* Reference-counted strings */ +/****************/ +/* Module Setup */ +/****************/ + +#include "H5RSmodule.h" /* This source code file is part of the H5RS module */ + +/***********/ +/* Headers */ +/***********/ +#include "H5private.h" /* Generic Functions */ +#include "H5Eprivate.h" /* Error handling */ +#include "H5FLprivate.h" /* Free lists */ +#include "H5RSprivate.h" /* Reference-counted strings */ + +/****************/ +/* Local Macros */ +/****************/ + +/* Initial buffer size to allocate */ +#define H5RS_ALLOC_SIZE 256 + +/******************/ +/* Local Typedefs */ +/******************/ /* Private typedefs & structs */ struct H5RS_str_t { char * s; /* String to be reference counted */ - unsigned wrapped; /* Indicates that the string to be ref-counted is not copied */ + char * end; /* Pointer to terminating NUL character at the end of the string */ + size_t len; /* Current length of the string */ + size_t max; /* Size of allocated buffer */ + hbool_t wrapped; /* Indicates that the string to be ref-counted is not copied */ unsigned n; /* Reference count of number of pointers sharing string */ }; +/********************/ +/* Package Typedefs */ +/********************/ + +/********************/ +/* Local Prototypes */ +/********************/ +static herr_t H5RS__xstrdup(H5RS_str_t *rs, const char *s); +static herr_t H5RS__prepare_for_append(H5RS_str_t *rs); +static herr_t H5RS__resize_for_append(H5RS_str_t *rs, size_t len); + +/*********************/ +/* Package Variables */ +/*********************/ + +/* Package initialization variable */ +hbool_t H5_PKG_INIT_VAR = FALSE; + +/*****************************/ +/* Library Private Variables */ +/*****************************/ + +/*******************/ +/* Local Variables */ +/*******************/ + /* Declare a free list to manage the H5RS_str_t struct */ H5FL_DEFINE_STATIC(H5RS_str_t); /* Declare the PQ free list for the wrapped strings */ -H5FL_BLK_DEFINE(str_buf); +H5FL_BLK_DEFINE_STATIC(str_buf); /*-------------------------------------------------------------------------- NAME @@ -41,11 +92,12 @@ H5FL_BLK_DEFINE(str_buf); PURPOSE Duplicate the string being reference counted USAGE - char *H5RS__xstrdup(s) + herr_t H5RS__xstrdup(rs, s) + H5RS_str_t *rs; IN/OUT: Ref-counted string to hold duplicated string const char *s; IN: String to duplicate RETURNS - Returns a pointer to a new string on success, NULL on failure. + Non-negative on success/Negative on failure DESCRIPTION Duplicate a string buffer being reference counted. Use this instead of [H5MM_][x]strdup, in order to use the free-list memory routines. @@ -54,28 +106,148 @@ H5FL_BLK_DEFINE(str_buf); EXAMPLES REVISION LOG --------------------------------------------------------------------------*/ -static char * -H5RS__xstrdup(const char *s) +static herr_t +H5RS__xstrdup(H5RS_str_t *rs, const char *s) { - char *ret_value; /* Return value */ + herr_t ret_value = SUCCEED; /* Return value */ - FUNC_ENTER_STATIC_NOERR + FUNC_ENTER_STATIC - if (s) { - size_t len = HDstrlen(s) + 1; + /* Sanity check */ + HDassert(rs); - ret_value = (char *)H5FL_BLK_MALLOC(str_buf, len); - HDassert(ret_value); - HDstrncpy(ret_value, s, len); + if (s) { + size_t len = HDstrlen(s); + + /* Determine size of buffer to allocate */ + rs->max = H5RS_ALLOC_SIZE; + while ((len + 1) > rs->max) + rs->max *= 2; + + /* Allocate the underlying string */ + if (NULL == (rs->s = (char *)H5FL_BLK_MALLOC(str_buf, rs->max))) + HGOTO_ERROR(H5E_RS, H5E_CANTALLOC, FAIL, "memory allocation failed") + if (len) + HDmemcpy(rs->s, s, len); + rs->end = rs->s + len; + *rs->end = '\0'; + rs->len = len; } /* end if */ - else - ret_value = NULL; + else { + /* Free previous string, if one */ + if (rs->s) { + H5FL_BLK_FREE(str_buf, rs->s); + rs->s = rs->end = NULL; + rs->max = rs->len = 0; + } /* end if */ + else { + /* Sanity checks */ + HDassert(NULL == rs->end); + HDassert(0 == rs->max); + HDassert(0 == rs->len); + } /* end else */ + } /* end else */ +done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5RS__xstrdup() */ /*-------------------------------------------------------------------------- NAME + H5RS__prepare_for_append + PURPOSE + Prepare a ref-counted string for an append + USAGE + herr_t H5RS__prepare_for_append(rs) + H5RS_str_t *rs; IN/OUT: Ref-counted string to hold duplicated string + RETURNS + Non-negative on success/Negative on failure + DESCRIPTION + Allocate space for a string, or duplicate a wrapped string, in preparation + for appending another string. + GLOBAL VARIABLES + COMMENTS, BUGS, ASSUMPTIONS + EXAMPLES + REVISION LOG +--------------------------------------------------------------------------*/ +static herr_t +H5RS__prepare_for_append(H5RS_str_t *rs) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_STATIC + + /* Sanity check */ + HDassert(rs); + + if (NULL == rs->s) { + rs->max = H5RS_ALLOC_SIZE; + if (NULL == (rs->s = (char *)H5FL_BLK_MALLOC(str_buf, rs->max))) + HGOTO_ERROR(H5E_RS, H5E_CANTALLOC, FAIL, "memory allocation failed") + rs->end = rs->s; + *rs->s = '\0'; + rs->len = 0; + } /* end if */ + else { + /* If the ref-counted string started life as a wrapper around an + * existing string, duplicate the string now, so we can modify it. + */ + if (rs->wrapped) { + if (H5RS__xstrdup(rs, rs->s) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTCOPY, FAIL, "can't copy string") + rs->wrapped = FALSE; + } /* end if */ + } /* end else */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5RS__prepare_for_append() */ + +/*-------------------------------------------------------------------------- + NAME + H5RS__resize_for_append + PURPOSE + Resize ref-counted string buffer to accommodate appending another string + USAGE + herr_t H5RS__resize_for_append(rs, len) + H5RS_str_t *rs; IN/OUT: Ref-counted string to hold duplicated string + size_t len; IN: Additional length to accommodate + RETURNS + Non-negative on success/Negative on failure + DESCRIPTION + Resize a ref-counted string buffer to be large enough to accommodate + another string of a specified length. + GLOBAL VARIABLES + COMMENTS, BUGS, ASSUMPTIONS + EXAMPLES + REVISION LOG +--------------------------------------------------------------------------*/ +static herr_t +H5RS__resize_for_append(H5RS_str_t *rs, size_t len) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_STATIC + + /* Sanity check */ + HDassert(rs); + + /* Check if buffer should be re-allocated */ + if (len >= (rs->max - rs->len)) { + /* Allocate a large enough buffer */ + while (len >= (rs->max - rs->len)) + rs->max *= 2; + if (NULL == (rs->s = (char *)H5FL_BLK_REALLOC(str_buf, rs->s, rs->max))) + HGOTO_ERROR(H5E_RS, H5E_CANTALLOC, FAIL, "memory allocation failed") + rs->end = rs->s + rs->len; + } /* end if */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5RS__resize() */ + +/*-------------------------------------------------------------------------- + NAME H5RS_create PURPOSE Create a reference counted string @@ -96,18 +268,19 @@ H5RS__xstrdup(const char *s) H5RS_str_t * H5RS_create(const char *s) { - H5RS_str_t *ret_value; /* Return value */ + H5RS_str_t *ret_value = NULL; /* Return value */ FUNC_ENTER_NOAPI(NULL) /* Allocate ref-counted string structure */ - if (NULL == (ret_value = H5FL_MALLOC(H5RS_str_t))) - HGOTO_ERROR(H5E_RS, H5E_NOSPACE, NULL, "memory allocation failed") + if (NULL == (ret_value = H5FL_CALLOC(H5RS_str_t))) + HGOTO_ERROR(H5E_RS, H5E_CANTALLOC, NULL, "memory allocation failed") /* Set the internal fields */ - ret_value->s = H5RS__xstrdup(s); - ret_value->wrapped = 0; - ret_value->n = 1; + if (s) + if (H5RS__xstrdup(ret_value, s) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTCOPY, NULL, "can't copy string") + ret_value->n = 1; done: FUNC_LEAVE_NOAPI(ret_value) @@ -135,63 +308,233 @@ done: H5RS_str_t * H5RS_wrap(const char *s) { - H5RS_str_t *ret_value; /* Return value */ + H5RS_str_t *ret_value = NULL; /* Return value */ FUNC_ENTER_NOAPI(NULL) /* Allocate ref-counted string structure */ if (NULL == (ret_value = H5FL_MALLOC(H5RS_str_t))) - HGOTO_ERROR(H5E_RS, H5E_NOSPACE, NULL, "memory allocation failed") + HGOTO_ERROR(H5E_RS, H5E_CANTALLOC, NULL, "memory allocation failed") /* Set the internal fields */ - ret_value->s = (char *)s; - ret_value->wrapped = 1; + ret_value->s = (char *)s; + ret_value->len = HDstrlen(s); + ret_value->end = ret_value->s + ret_value->len; + + ret_value->wrapped = TRUE; + ret_value->max = 0; /* Wrapped, not allocated */ ret_value->n = 1; done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5RS_wrap() */ -/*-------------------------------------------------------------------------- - NAME - H5RS_own - PURPOSE - Transfer ownership of a regular string to a reference counted string - USAGE - H5RS_str_t *H5RS_own(s) - const char *s; IN: String to transfer ownership of +/*------------------------------------------------------------------------- + * Function: H5RS_asprintf_cat + * + * Purpose: This function appends formatted output to a ref-counted string, + * allocating the managed string if necessary. The formatting + * string is printf() compatible. + * + * Return: SUCCEED / FAIL + * + * Programmer: Quincey Koziol + * Friday, September 18, 2020 + * + *------------------------------------------------------------------------- + */ +/* Disable warning for "format not a string literal" here -QAK */ +/* + * This pragma only needs to surround the sprintf() calls with + * format_templ in the code below, but early (4.4.7, at least) gcc only + * allows diagnostic pragmas to be toggled outside of functions. + */ +H5_GCC_DIAG_OFF("format-nonliteral") +H5_ATTR_FORMAT(printf, 2, 3) +herr_t +H5RS_asprintf_cat(H5RS_str_t *rs, const char *fmt, ...) +{ + va_list args1, args2; + size_t out_len; + herr_t ret_value = SUCCEED; /* Return value */ - RETURNS - Returns a pointer to a new ref-counted string on success, NULL on failure. - DESCRIPTION - Transfer ownership of a dynamically allocated string to a reference counted - string. The routine which passed in the string should not attempt to free - it, the reference counting string routines will do that when the reference - count drops to zero. - GLOBAL VARIABLES - COMMENTS, BUGS, ASSUMPTIONS - EXAMPLES - REVISION LOG ---------------------------------------------------------------------------*/ -H5RS_str_t * -H5RS_own(char *s) + FUNC_ENTER_NOAPI(FAIL) + + /* Sanity checks */ + HDassert(rs); + HDassert(fmt); + + /* Prepare the [possibly wrapped or empty] ref-counted string for an append */ + if (H5RS__prepare_for_append(rs) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTINIT, FAIL, "can't initialize ref-counted string") + + /* Attempt to write formatted output into the managed string */ + HDva_start(args1, fmt); + HDva_copy(args2, args1); + while ((out_len = (size_t)HDvsnprintf(rs->end, (rs->max - rs->len), fmt, args1)) >= (rs->max - rs->len)) { + /* Allocate a large enough buffer */ + if (H5RS__resize_for_append(rs, out_len) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTRESIZE, FAIL, "can't resize ref-counted string buffer") + + /* Restart the va_list */ + HDva_end(args1); + HDva_copy(args1, args2); + } /* end while */ + + /* Increment the size & end of the string */ + rs->len += out_len; + rs->end += out_len; + + /* Finish access to varargs */ + HDva_end(args1); + HDva_end(args2); + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5RS_asprintf_cat() */ +H5_GCC_DIAG_ON("format-nonliteral") + +/*------------------------------------------------------------------------- + * Function: H5RS_acat + * + * Purpose: This function appends a character string to a ref-counted string, + * allocating the managed string if necessary. + * + * Return: SUCCEED / FAIL + * + * Programmer: Quincey Koziol + * Friday, September 18, 2020 + * + *------------------------------------------------------------------------- + */ +herr_t +H5RS_acat(H5RS_str_t *rs, const char *s) { - H5RS_str_t *ret_value; /* Return value */ + herr_t ret_value = SUCCEED; /* Return value */ - FUNC_ENTER_NOAPI(NULL) + FUNC_ENTER_NOAPI(FAIL) - /* Allocate ref-counted string structure */ - if (NULL == (ret_value = H5FL_MALLOC(H5RS_str_t))) - HGOTO_ERROR(H5E_RS, H5E_NOSPACE, NULL, "memory allocation failed") + /* Sanity checks */ + HDassert(rs); + HDassert(s); - /* Set the internal fields */ - ret_value->s = s; - ret_value->wrapped = 0; - ret_value->n = 1; + /* Concatenate the provided string on to the managed string */ + if (*s) { + size_t len = HDstrlen(s); + + /* Allocate the underlying string, if necessary */ + if (H5RS__prepare_for_append(rs) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTINIT, FAIL, "can't initialize ref-counted string") + + /* Increase the managed string's buffer size if necessary */ + if ((rs->len + len) >= rs->max) + if (H5RS__resize_for_append(rs, len) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTRESIZE, FAIL, "can't resize ref-counted string buffer") + + /* Append the string */ + HDmemcpy(rs->end, s, len); + rs->end += len; + *rs->end = '\0'; + rs->len += len; + } /* end if */ done: FUNC_LEAVE_NOAPI(ret_value) -} /* end H5RS_own() */ +} /* end H5RS_acat() */ + +/*------------------------------------------------------------------------- + * Function: H5RS_ancat + * + * Purpose: This function appends at most 'n' characters from a string + * to a ref-counted string, allocating the managed string if + * necessary. + * + * Return: SUCCEED / FAIL + * + * Programmer: Quincey Koziol + * Friday, September 18, 2020 + * + *------------------------------------------------------------------------- + */ +herr_t +H5RS_ancat(H5RS_str_t *rs, const char *s, size_t n) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + /* Sanity checks */ + HDassert(rs); + HDassert(s); + + /* Concatenate the provided string on to the managed string */ + if (n && *s) { + size_t len = HDstrlen(s); + + /* Limit characters to copy to the minimum of 'n' and 'len' */ + n = MIN(len, n); + + /* Allocate the underlying string, if necessary */ + if (H5RS__prepare_for_append(rs) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTINIT, FAIL, "can't initialize ref-counted string") + + /* Increase the managed string's buffer size if necessary */ + if ((rs->len + n) >= rs->max) + if (H5RS__resize_for_append(rs, n) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTRESIZE, FAIL, "can't resize ref-counted string buffer") + + /* Append the string */ + HDmemcpy(rs->end, s, n); + rs->end += n; + *rs->end = '\0'; + rs->len += n; + } /* end if */ + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5RS_ancat() */ + +/*------------------------------------------------------------------------- + * Function: H5RS_aputc + * + * Purpose: This function appends a character to a ref-counted string, + * allocating the managed string if necessary. + * + * Return: SUCCEED / FAIL + * + * Programmer: Quincey Koziol + * Friday, September 18, 2020 + * + *------------------------------------------------------------------------- + */ +herr_t +H5RS_aputc(H5RS_str_t *rs, int c) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + /* Sanity checks */ + HDassert(rs); + HDassert(c); + + /* Allocate the underlying string, if necessary */ + if (H5RS__prepare_for_append(rs) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTINIT, FAIL, "can't initialize ref-counted string") + + /* Increase the managed string's buffer size if necessary */ + if ((rs->len + 1) >= rs->max) + if (H5RS__resize_for_append(rs, 1) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTRESIZE, FAIL, "can't resize ref-counted string buffer") + + /* Append the current character */ + *rs->end++ = (char)c; + rs->len++; + *rs->end = '\0'; + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5RS_aputc() */ /*-------------------------------------------------------------------------- NAME @@ -252,7 +595,9 @@ H5RS_decr(H5RS_str_t *rs) herr_t H5RS_incr(H5RS_str_t *rs) { - FUNC_ENTER_NOAPI_NOINIT_NOERR + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) /* Sanity check */ HDassert(rs); @@ -263,14 +608,16 @@ H5RS_incr(H5RS_str_t *rs) * scope appropriately. */ if (rs->wrapped) { - rs->s = H5RS__xstrdup(rs->s); - rs->wrapped = 0; + if (H5RS__xstrdup(rs, rs->s) < 0) + HGOTO_ERROR(H5E_RS, H5E_CANTCOPY, FAIL, "can't copy string") + rs->wrapped = FALSE; } /* end if */ /* Increment reference count for string */ rs->n++; - FUNC_LEAVE_NOAPI(SUCCEED) +done: + FUNC_LEAVE_NOAPI(ret_value) } /* end H5RS_incr() */ /*-------------------------------------------------------------------------- @@ -307,53 +654,6 @@ H5RS_dup(H5RS_str_t *ret_value) /*-------------------------------------------------------------------------- NAME - H5RS_dup_str - PURPOSE - "Duplicate" a regular string into a ref-counted string - USAGE - H5RS_str_t H5RS_dup_str(s) - const char *s; IN: Regular string to duplicate - - RETURNS - Returns a pointer to ref-counted string on success, NULL on failure. - DESCRIPTION - Duplicate a regular string into a ref-counted string. - GLOBAL VARIABLES - COMMENTS, BUGS, ASSUMPTIONS - EXAMPLES - REVISION LOG ---------------------------------------------------------------------------*/ -H5RS_str_t * -H5RS_dup_str(const char *s) -{ - char * new_str; /* Duplicate of string */ - size_t path_len; /* Length of the path */ - H5RS_str_t *ret_value; - - FUNC_ENTER_NOAPI(NULL) - - /* Sanity check */ - HDassert(s); - - /* Get the length of the string */ - path_len = HDstrlen(s); - - /* Allocate space for the string */ - if (NULL == (new_str = (char *)H5FL_BLK_MALLOC(str_buf, path_len + 1))) - HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, NULL, "memory allocation failed") - - /* Copy name for full path */ - HDstrncpy(new_str, s, (path_len + 1)); - - /* Create reference counted string for path */ - ret_value = H5RS_own(new_str); - -done: - FUNC_LEAVE_NOAPI(ret_value) -} /* end H5RS_dup_str() */ - -/*-------------------------------------------------------------------------- - NAME H5RS_cmp PURPOSE Compare two ref-counted strings diff --git a/src/H5RSmodule.h b/src/H5RSmodule.h new file mode 100644 index 0000000..9b4819f --- /dev/null +++ b/src/H5RSmodule.h @@ -0,0 +1,32 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * Programmer: Quincey Koziol + * Saturday, October 10, 2020 + * + * Purpose: This file contains declarations which define macros for the + * H5RS package. Including this header means that the source file + * is part of the H5RS package. + */ +#ifndef _H5RSmodule_H +#define _H5RSmodule_H + +/* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error + * reporting macros. + */ +#define H5RS_MODULE +#define H5_MY_PKG H5RS +#define H5_MY_PKG_ERR H5E_RS +#define H5_MY_PKG_INIT NO + +#endif /* _H5RSmodule_H */ diff --git a/src/H5RSprivate.h b/src/H5RSprivate.h index d1f24cf..eb9e8d8 100644 --- a/src/H5RSprivate.h +++ b/src/H5RSprivate.h @@ -45,11 +45,13 @@ typedef struct H5RS_str_t H5RS_str_t; /********************/ H5_DLL H5RS_str_t *H5RS_create(const char *s); H5_DLL H5RS_str_t *H5RS_wrap(const char *s); -H5_DLL H5RS_str_t *H5RS_own(char *s); H5_DLL herr_t H5RS_decr(H5RS_str_t *rs); H5_DLL herr_t H5RS_incr(H5RS_str_t *rs); H5_DLL H5RS_str_t *H5RS_dup(H5RS_str_t *s); -H5_DLL H5RS_str_t *H5RS_dup_str(const char *s); +H5_DLL herr_t H5RS_asprintf_cat(H5RS_str_t *rs, const char *fmt, ...) H5_ATTR_FORMAT(printf, 2, 3); +H5_DLL herr_t H5RS_acat(H5RS_str_t *rs, const char *s); +H5_DLL herr_t H5RS_ancat(H5RS_str_t *rs, const char *s, size_t len); +H5_DLL herr_t H5RS_aputc(H5RS_str_t *rs, int c); H5_DLL int H5RS_cmp(const H5RS_str_t *rs1, const H5RS_str_t *rs2); H5_DLL ssize_t H5RS_len(const H5RS_str_t *rs); H5_DLL char * H5RS_get_str(const H5RS_str_t *rs); diff --git a/src/H5Rdeprec.c b/src/H5Rdeprec.c index 1ec0350..6eb3def 100644 --- a/src/H5Rdeprec.c +++ b/src/H5Rdeprec.c @@ -481,7 +481,7 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type) +H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type /*out*/) { H5VL_object_t * vol_obj = NULL; /* Object of loc_id */ H5I_type_t vol_obj_type = H5I_BADID; /* Object type of loc_id */ @@ -491,7 +491,7 @@ H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "iRt*x*Ot", id, ref_type, ref, obj_type); + H5TRACE4("e", "iRt*xx", id, ref_type, ref, obj_type); /* Check args */ if (buf == NULL) @@ -693,7 +693,7 @@ done: *------------------------------------------------------------------------- */ ssize_t -H5Rget_name(hid_t id, H5R_type_t ref_type, const void *ref, char *name, size_t size) +H5Rget_name(hid_t id, H5R_type_t ref_type, const void *ref, char *name /*out*/, size_t size) { H5VL_object_t * vol_obj = NULL; /* Object of loc_id */ H5I_type_t vol_obj_type = H5I_BADID; /* Object type of loc_id */ @@ -703,7 +703,7 @@ H5Rget_name(hid_t id, H5R_type_t ref_type, const void *ref, char *name, size_t s ssize_t ret_value = -1; /* Return value */ FUNC_ENTER_API((-1)) - H5TRACE5("Zs", "iRt*x*sz", id, ref_type, ref, name, size); + H5TRACE5("Zs", "iRt*xxz", id, ref_type, ref, name, size); /* Check args */ if (buf == NULL) diff --git a/src/H5Rint.c b/src/H5Rint.c index 8f3163a..60f8131 100644 --- a/src/H5Rint.c +++ b/src/H5Rint.c @@ -746,8 +746,10 @@ H5R__copy(const H5R_ref_priv_t *src_ref, H5R_ref_priv_t *dst_ref) dst_ref->info.obj.filename = NULL; /* Set location ID and hold reference to it */ - if (H5R__set_loc_id(dst_ref, src_ref->loc_id, TRUE, TRUE) < 0) - HGOTO_ERROR(H5E_REFERENCE, H5E_CANTSET, FAIL, "cannot set reference location ID") + dst_ref->loc_id = src_ref->loc_id; + if (H5I_inc_ref(dst_ref->loc_id, TRUE) < 0) + HGOTO_ERROR(H5E_REFERENCE, H5E_CANTINC, FAIL, "incrementing location ID failed") + dst_ref->app_ref = TRUE; } done: @@ -2233,7 +2233,7 @@ H5SL_release(H5SL_t *slist) HGOTO_ERROR(H5E_SLIST, H5E_CANTFREE, FAIL, "can't release skip list nodes") done: - FUNC_LEAVE_NOAPI(SUCCEED) + FUNC_LEAVE_NOAPI(ret_value) } /* end H5SL_release() */ /*-------------------------------------------------------------------------- @@ -266,7 +266,7 @@ H5SM__type_to_flag(unsigned type_id, unsigned *type_flag) switch (type_id) { case H5O_FILL_ID: type_id = H5O_FILL_NEW_ID; - /* Fall through... */ + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case H5O_SDSPACE_ID: @@ -1092,7 +1092,7 @@ H5SM_try_share(H5F_t *f, H5O_t *open_oh, unsigned defer_flags, unsigned type_id, if (defer_flags & H5SM_WAS_DEFERRED) #ifndef NDEBUG deferred_type = ((H5O_shared_t *)mesg)->type; -#else /* NDEBUG */ +#else /* NDEBUG */ if ((((H5O_shared_t *)mesg)->type != H5O_SHARE_TYPE_HERE) && (((H5O_shared_t *)mesg)->type != H5O_SHARE_TYPE_SOHM)) HGOTO_DONE(FALSE); @@ -1411,7 +1411,7 @@ H5SM__write_mesg(H5F_t *f, H5O_t *open_oh, H5SM_index_header_t *header, hbool_t if (defer) HDmemset(&shared.u, 0, sizeof(shared.u)); #endif /* H5_USING_MEMCHECKER */ - } /* end if */ + } /* end if */ else { htri_t share_in_ohdr; /* Whether the new message can be shared in another object's header */ @@ -1770,7 +1770,7 @@ H5SM__decr_ref(void *record, void *op_data, hbool_t *changed) */ static herr_t H5SM__delete_from_index(H5F_t *f, H5O_t *open_oh, H5SM_index_header_t *header, const H5O_shared_t *mesg, - unsigned *cache_flags, size_t * /*out*/ mesg_size, void ** /*out*/ encoded_mesg) + unsigned *cache_flags, size_t *mesg_size /*out*/, void **encoded_mesg /*out*/) { H5SM_list_t * list = NULL; H5SM_mesg_key_t key; diff --git a/src/H5Shyper.c b/src/H5Shyper.c index 6b3d750..4f53d49 100644 --- a/src/H5Shyper.c +++ b/src/H5Shyper.c @@ -2126,7 +2126,7 @@ H5S__hyper_iter_get_seq_list_opt(H5S_sel_iter_t *iter, size_t maxseq, size_t max /* Decrement number of blocks */ fast_dim_count--; } /* end while */ -#else /* NO_DUFFS_DEVICE */ +#else /* NO_DUFFS_DEVICE */ { size_t duffs_index; /* Counting index for Duff's device */ @@ -2138,31 +2138,38 @@ H5S__hyper_iter_get_seq_list_opt(H5S_sel_iter_t *iter, size_t maxseq, size_t max case 0: do { DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 7: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 6: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 5: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 4: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 3: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 2: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 1: DUFF_GUTS } while (--duffs_index > 0); } /* end switch */ } -#endif /* NO_DUFFS_DEVICE */ +#endif /* NO_DUFFS_DEVICE */ #undef DUFF_GUTS /* Increment offset in destination buffer */ @@ -4766,13 +4773,13 @@ H5S__get_select_hyper_blocklist(H5S_t *space, hsize_t startblock, hsize_t numblo --------------------------------------------------------------------------*/ herr_t H5Sget_select_hyper_blocklist(hid_t spaceid, hsize_t startblock, hsize_t numblocks, - hsize_t buf[/*numblocks*/]) + hsize_t buf[/*numblocks*/] /*out*/) { H5S_t *space; /* Dataspace to modify selection of */ herr_t ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "ihh*[a2]h", spaceid, startblock, numblocks, buf); + H5TRACE4("e", "ihhx", spaceid, startblock, numblocks, buf); /* Check args */ if (buf == NULL) @@ -10101,7 +10108,7 @@ H5S_select_hyperslab(H5S_t *space, H5S_seloper_t op, const hsize_t start[], cons case H5S_SEL_POINTS: /* Can't combine hyperslab operations and point selections currently */ if (op == H5S_SELECT_SET) /* Allow only "set" operation to proceed */ break; - /* Else fall through to error */ + /* FALLTHROUGH (to error) */ H5_ATTR_FALLTHROUGH case H5S_SEL_ERROR: @@ -11742,7 +11749,7 @@ done: for (u = 0; u < H5S_MAX_RANK; u++) HDassert(!udata.ps_span_info[u]); - } /* end block */ + } /* end block */ #endif /* NDEBUG */ FUNC_LEAVE_NOAPI(ret_value) @@ -12351,14 +12358,15 @@ done: REVISION LOG --------------------------------------------------------------------------*/ herr_t -H5Sget_regular_hyperslab(hid_t spaceid, hsize_t start[], hsize_t stride[], hsize_t count[], hsize_t block[]) +H5Sget_regular_hyperslab(hid_t spaceid, hsize_t start[] /*out*/, hsize_t stride[] /*out*/, + hsize_t count[] /*out*/, hsize_t block[] /*out*/) { H5S_t * space; /* Dataspace to query */ unsigned u; /* Local index variable */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "i*h*h*h*h", spaceid, start, stride, count, block); + H5TRACE5("e", "ixxxx", spaceid, start, stride, count, block); /* Check args */ if (NULL == (space = (H5S_t *)H5I_object_verify(spaceid, H5I_DATASPACE))) diff --git a/src/H5Smodule.h b/src/H5Smodule.h index 11494ee..6e8208b 100644 --- a/src/H5Smodule.h +++ b/src/H5Smodule.h @@ -29,4 +29,31 @@ #define H5_MY_PKG_ERR H5E_DATASPACE #define H5_MY_PKG_INIT YES +/**\defgroup H5S H5S + * \brief Dataspace Interface + * + * \details The Dataspace Interface provides functions for creating and + * working with dataspaces. + * + * A dataspace has two roles: + * + * \li It contains the spatial information (logical layout) of a + * dataset stored in a file. + * \li It describes an application’s data buffers and data elements + * participating in I/O. In other words, it can be used to + * select a portion or subset of a dataset. + * + * The spatial information of a dataset in a file includes the + * rank and dimensions of the dataset, which are a permanent part + * of the dataset definition. It can have dimensions that are fixed + * (unchanging) or unlimited, which means they can grow in size + * (or are extendible). + * + * A dataspace can consist of: + * \li no elements (NULL) + * \li a single element (scalar), or + * \li a simple array. + * + */ + #endif /* _H5Smodule_H */ diff --git a/src/H5Spkg.h b/src/H5Spkg.h index 76b2753..adb528e 100644 --- a/src/H5Spkg.h +++ b/src/H5Spkg.h @@ -280,26 +280,21 @@ typedef struct { H5S_sel_copy_func_t copy; /* Method to make a copy of a selection */ H5S_sel_release_func_t release; /* Method to release current selection */ H5S_sel_is_valid_func_t is_valid; /* Method to determine if current selection is valid for dataspace */ - H5S_sel_serial_size_func_t - serial_size; /* Method to determine number of bytes required to store current selection */ + H5S_sel_serial_size_func_t serial_size; /* Method to determine number of bytes required to store current selection */ H5S_sel_serialize_func_t serialize; /* Method to store current selection in "serialized" form (a byte sequence suitable for storing on disk) */ H5S_sel_deserialize_func_t deserialize; /* Method to store create selection from "serialized" form (a byte sequence suitable for storing on disk) */ - H5S_sel_bounds_func_t - bounds; /* Method to determine to smallest n-D bounding box containing the current selection */ - H5S_sel_offset_func_t - offset; /* Method to determine linear offset of initial element in selection within dataspace */ + H5S_sel_bounds_func_t bounds; /* Method to determine to smallest n-D bounding box containing the current selection */ + H5S_sel_offset_func_t offset; /* Method to determine linear offset of initial element in selection within dataspace */ H5S_sel_unlim_dim_func_t unlim_dim; /* Method to get unlimited dimension of selection (or -1 for none) */ H5S_sel_num_elem_non_unlim_func_t num_elem_non_unlim; /* Method to get the number of elements in a slice through the unlimited dimension */ H5S_sel_is_contiguous_func_t is_contiguous; /* Method to determine if current selection is contiguous */ H5S_sel_is_single_func_t is_single; /* Method to determine if current selection is a single block */ H5S_sel_is_regular_func_t is_regular; /* Method to determine if current selection is "regular" */ - H5S_sel_shape_same_func_t - shape_same; /* Method to determine if two dataspaces' selections are the same shape */ - H5S_sel_intersect_block_func_t - intersect_block; /* Method to determine if a dataspaces' selection intersects a block */ + H5S_sel_shape_same_func_t shape_same; /* Method to determine if two dataspaces' selections are the same shape */ + H5S_sel_intersect_block_func_t intersect_block; /* Method to determine if a dataspaces' selection intersects a block */ H5S_sel_adjust_u_func_t adjust_u; /* Method to adjust a selection by an offset */ H5S_sel_adjust_s_func_t adjust_s; /* Method to adjust a selection by an offset (signed) */ H5S_sel_project_scalar project_scalar; /* Method to construct scalar dataspace projection */ @@ -352,20 +347,13 @@ typedef struct H5S_sel_iter_class_t { H5S_sel_type type; /* Type of selection (all, none, points or hyperslab) */ /* Methods on selections */ - H5S_sel_iter_coords_func_t - iter_coords; /* Method to retrieve the current coordinates of iterator for current selection */ - H5S_sel_iter_block_func_t - iter_block; /* Method to retrieve the current block of iterator for current selection */ - H5S_sel_iter_nelmts_func_t - iter_nelmts; /* Method to determine number of elements left in iterator for current selection */ - H5S_sel_iter_has_next_block_func_t - iter_has_next_block; /* Method to query if there is another block left in the selection */ - H5S_sel_iter_next_func_t - iter_next; /* Method to move selection iterator to the next element in the selection */ - H5S_sel_iter_next_block_func_t - iter_next_block; /* Method to move selection iterator to the next block in the selection */ - H5S_sel_iter_get_seq_list_func_t - iter_get_seq_list; /* Method to retrieve a list of offset/length sequences for selection iterator */ + H5S_sel_iter_coords_func_t iter_coords; /* Method to retrieve the current coordinates of iterator for current selection */ + H5S_sel_iter_block_func_t iter_block; /* Method to retrieve the current block of iterator for current selection */ + H5S_sel_iter_nelmts_func_t iter_nelmts; /* Method to determine number of elements left in iterator for current selection */ + H5S_sel_iter_has_next_block_func_t iter_has_next_block; /* Method to query if there is another block left in the selection */ + H5S_sel_iter_next_func_t iter_next; /* Method to move selection iterator to the next element in the selection */ + H5S_sel_iter_next_block_func_t iter_next_block; /* Method to move selection iterator to the next block in the selection */ + H5S_sel_iter_get_seq_list_func_t iter_get_seq_list; /* Method to retrieve a list of offset/length sequences for selection iterator */ H5S_sel_iter_release_func_t iter_release; /* Method to release iterator for current selection */ } H5S_sel_iter_class_t; diff --git a/src/H5Spoint.c b/src/H5Spoint.c index 3e65836..c58e7a7 100644 --- a/src/H5Spoint.c +++ b/src/H5Spoint.c @@ -1572,13 +1572,14 @@ H5S__get_select_elem_pointlist(const H5S_t *space, hsize_t startpoint, hsize_t n REVISION LOG --------------------------------------------------------------------------*/ herr_t -H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, hsize_t buf[/*numpoints*/]) +H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, + hsize_t buf[/*numpoints*/] /*out*/) { H5S_t *space; /* Dataspace to modify selection of */ herr_t ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE4("e", "ihh*[a2]h", spaceid, startpoint, numpoints, buf); + H5TRACE4("e", "ihhx", spaceid, startpoint, numpoints, buf); /* Check args */ if (NULL == buf) diff --git a/src/H5Spublic.h b/src/H5Spublic.h index f0aa6dc..c16af93 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -120,17 +120,288 @@ typedef enum { extern "C" { #endif -/* Operations on dataspaces */ +/* Operations on dataspaces and dataspace selections */ + +/** + * \ingroup H5S + * + * \brief Releases and terminates access to a dataspace + * + * \space_id + * + * \return \herr_t + * + * \details H5Sclose() releases a dataspace. Further access through the + * dataspace identifier is illegal. Failure to release a dataspace with this + * call will result in resource leaks. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sclose(hid_t space_id); +/** + * \ingroup H5S + * + * \brief Creates a new dataspace of a specified type + * + * \param[in] type Type of dataspace to be created + * + * \return \hid_t{dataspace} + * + * \details H5Screate() creates a new dataspace of a particular type. Currently + * supported types are #H5S_SCALAR, #H5S_SIMPLE, and #H5S_NULL. + * + * Further dataspace types may be added later. + * + * A scalar dataspace, #H5S_SCALAR, has a single element, though that + * element may be of a complex datatype, such as a compound or array + * datatype. By convention, the rank of a scalar dataspace is always \p 0 + * (zero); think of it geometrically as a single, dimensionless point, + * though that point can be complex. + * + * A simple dataspace, #H5S_SIMPLE, consists of a regular array of elements. + * + * A null dataspace, #H5S_NULL, has no data elements. + * + * The dataspace identifier returned by this function can be released with + * H5Sclose() so that resource leaks will not occur. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ H5_DLL hid_t H5Screate(H5S_class_t type); +/** + * \ingroup H5S + * \brief Creates a new simple dataspace and opens it for access + * + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims Array specifying the size of each dimension + * \param[in] maxdims Array specifying the maximum size of each dimension + * + * \return \hid_t{dataspace} + * + * \details H5Screate_simple() creates a new simple dataspace and opens it + * for access, returning a dataspace identifier. + * + * \p rank is the number of dimensions used in the dataspace. + * + * \p dims is a one-dimensional array of size rank specifying the + * size of each dimension of the dataset. \p maxdims is an array of the + * same size specifying the upper limit on the size of each dimension. + * + * Any element of \p dims can be \p 0 (zero). Note that no data can + * be written to a dataset if the size of any dimension of its current + * dataspace is \p 0. This is sometimes a useful initial state for a dataset. + * + * \p maxdims may be the null pointer, in which case the upper limit is + * the same as \p dims. Otherwise, no element of \p maxdims + * should be smaller than the corresponding element of \p dims. + * + * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of the + * corresponding dimension is unlimited. + * + * Any dataset with an unlimited dimension must also be chunked; see + * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims does + * not equal \p maxdims. + * + * The dataspace identifier returned from this function must be released with + * H5Sclose() or resource leaks will occur. + * + * \note Once a dataspace has been created, specific regions or elements in + * the dataspace can be selected and selections can be removed, as well. + * For example, H5Sselect_hyperslab() selects a region in a dataspace and + * H5Sselect_elements() selects array elements in a dataspace. These + * functions are used for subsetting. H5Sselect_none() removes all + * selections from a dataspace and is used in Parallel HDF5 when a process + * does not have or need to write data. + * + * \version 1.4.0 Fortran subroutine introduced. + * + * \since 1.0.0 + * + */ H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Determines the number of elements in a dataspace selection + * + * \space_id{spaceid} + * + * \return Returns the number of elements in the selection if successful; + * otherwise returns a negative value. + * + * \details H5Sget_select_npoints() determines the number of elements in + * the current selection of a dataspace. It works with any + * selection type, and is the correct way to retrieve the number + * of elements in a selection. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); +/*-------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Retrieves dataspace dimension size and maximum size + * + * \space_id + * \param[out] dims Pointer to array to store the size of each dimension + * \param[out] maxdims Pointer to array to store the maximum size of each + * dimension + * + * \return Returns the number of dimensions in the dataspace if successful; + * otherwise returns a negative value. + * + * \details H5Sget_simple_extent_dims() returns the size and maximum sizes + * of each dimension of a dataspace \p space_id through the \p dims + * and \p maxdims parameters. + * + * Either or both of \p dims and \p maxdims may be NULL. + * + * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1), + * the maximum size of that dimension is unlimited. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], + hsize_t maxdims[]); +/*-------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Determines the dimensionality of a dataspace + * + * \space_id + * + * \return Returns the number of dimensions in the dataspace if successful; + * otherwise returns a negative value. + * + * \details H5Sget_simple_extent_ndims() determines the dimensionality (or + * rank) of a dataspace. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Selects a hyperslab region to add to the current selected region + * + * \space_id + * \param[in] op Operation to perform on current selection + * \param[in] start Offset of start of hyperslab + * \param[in] stride Hyperslab stride + * \param[in] count Number of blocks included in hyperslab + * \param[in] block Size of block in hyperslab + * + * \return \herr_t + * + * \details H5Sselect_hyperslab() selects a hyperslab region to add to the + * current selected region for the dataspace specified by + * \p space_id. + * + * The \p start, \p stride, \p count, and \p block arrays must be the + * same size as the rank of the dataspace. For example, if the + * dataspace is 4-dimensional, each of these parameters must be a + * 1-dimensional array of size 4. + * + * The selection operator \p op determines how the new selection + * is to be combined with the already existing selection for the + * dataspace. The following operators are supported: + * + * <table> + * <tr> + * <td>#H5S_SELECT_SET</td> + * <td>Replaces the existing selection with the + * parameters from this call. Overlapping blocks + * are not supported with this operator.</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_OR</td> + * <td>Adds the new selection to the existing selection. + * (Binary OR)</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_AND</td> + * <td>Retains only the overlapping portions of the + * new selection and the existing selection. + * (Binary AND)</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_XOR</td> + * <td>Retains only the elements that are members of + * the new selection or the existing selection, + * excluding elements that are members of both + * selections. (Binary exclusive-OR, XOR) + * </td> + * </tr> + * <tr> + * <td>#H5S_SELECT_NOTB</td> + * <td>Retains only elements of the existing selection + * that are not in the new selection.</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_NOTA</td> + * <td>Retains only elements of the new selection that + * are not in the existing selection.</td> + * </tr> + * </table> + * + * The \p start array specifies the offset of the starting element + * of the specified hyperslab. + * + * The \p stride array chooses array locations from the dataspace with + * each value in the \p stride array determining how many elements to + * move in each dimension. Setting a value in the \p stride array to + * \p 1 moves to each element in that dimension of the dataspace; + * setting a value of \p 2 in allocation in the \p stride array moves + * to every other element in that dimension of the dataspace. In + * other words, the \p stride determines the number of elements to + * move from the \p start location in each dimension. Stride values + * of \p 0 are not allowed. If the \p stride parameter is NULL, a + * contiguous hyperslab is selected (as if each value in the \p stride + * array were set to \p 1). + * + * The \p count array determines how many blocks to select from the + * dataspace, in each dimension. + * + * The \p block array determines the size of the element block + * selected from the dataspace. If the \p block parameter is set to + * NULL, the block size defaults to a single element in each dimension + * (as if each value in the \p block array were set to \p 1). + * + * For example, consider a 2-dimensional dataspace with hyperslab + * selection settings as follows: the \p start offset is specified as + * [1,1], \p stride is [4,4], \p count is [3,7], and \p block is [2,2]. + * In C, these settings will specify a hyperslab consisting of 21 + * 2x2 blocks of array elements starting with location (1,1) with the + * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.; + * in Fortran, they will specify a hyperslab consisting of 21 2x2 + * blocks of array elements starting with location (2,2) with the + * selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc. + * + * Regions selected with this function call default to C order + * iteration when I/O is performed. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, + const hsize_t start[], const hsize_t stride[], const hsize_t count[], + const hsize_t block[]); H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]); H5_DLL hid_t H5Scopy(hid_t space_id); -H5_DLL herr_t H5Sclose(hid_t space_id); H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl); H5_DLL hid_t H5Sdecode(const void *buf); H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id); -H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); -H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]); H5_DLL htri_t H5Sis_simple(hid_t space_id); H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id); H5_DLL herr_t H5Sset_extent_none(hid_t space_id); @@ -139,7 +410,6 @@ H5_DLL htri_t H5Sextent_equal(hid_t sid1, hid_t sid2); /* Operations on dataspace selections */ H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid); -H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id); H5_DLL htri_t H5Sselect_valid(hid_t spaceid); H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset); @@ -153,8 +423,6 @@ H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_ H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid); H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, hsize_t buf[/*numpoints*/]); -H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], - const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]); H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]); H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); diff --git a/src/H5Sselect.c b/src/H5Sselect.c index 023ab80..231f35e 100644 --- a/src/H5Sselect.c +++ b/src/H5Sselect.c @@ -602,13 +602,13 @@ done: REVISION LOG --------------------------------------------------------------------------*/ herr_t -H5Sget_select_bounds(hid_t spaceid, hsize_t start[], hsize_t end[]) +H5Sget_select_bounds(hid_t spaceid, hsize_t start[] /*out*/, hsize_t end[] /*out*/) { H5S_t *space; /* Dataspace to modify selection of */ herr_t ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("e", "i*h*h", spaceid, start, end); + H5TRACE3("e", "ixx", spaceid, start, end); /* Check args */ if (start == NULL || end == NULL) @@ -3056,14 +3056,14 @@ done: REVISION LOG --------------------------------------------------------------------------*/ herr_t -H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq, size_t maxbytes, size_t *nseq, size_t *nbytes, - hsize_t *off, size_t *len) +H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq, size_t maxbytes, size_t *nseq /*out*/, + size_t *nbytes /*out*/, hsize_t *off /*out*/, size_t *len /*out*/) { H5S_sel_iter_t *sel_iter; /* Dataspace selection iterator to operate on */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE7("e", "izz*z*z*h*z", sel_iter_id, maxseq, maxbytes, nseq, nbytes, off, len); + H5TRACE7("e", "izzxxxx", sel_iter_id, maxseq, maxbytes, nseq, nbytes, off, len); /* Check args */ if (NULL == (sel_iter = (H5S_sel_iter_t *)H5I_object_verify(sel_iter_id, H5I_SPACE_SEL_ITER))) @@ -2714,7 +2714,7 @@ H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_c herr_t ret_value = SUCCEED; /*return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "Te*siix", pers, name, src_id, dst_id, func); + H5TRACE5("e", "Te*siiTC", pers, name, src_id, dst_id, func); /* Check args */ if (H5T_PERS_HARD != pers && H5T_PERS_SOFT != pers) @@ -2867,7 +2867,7 @@ H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API(FAIL) - H5TRACE5("e", "Te*siix", pers, name, src_id, dst_id, func); + H5TRACE5("e", "Te*siiTC", pers, name, src_id, dst_id, func); /* Check arguments */ if (src_id > 0 && (NULL == (src = (H5T_t *)H5I_object_verify(src_id, H5I_DATATYPE)))) @@ -2901,14 +2901,14 @@ done: *------------------------------------------------------------------------- */ H5T_conv_t -H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata) +H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata /*out*/) { H5T_t * src, *dst; H5T_path_t *path; H5T_conv_t ret_value; /* Return value */ FUNC_ENTER_API(NULL) - H5TRACE3("x", "ii**x", src_id, dst_id, pcdata); + H5TRACE3("TC", "iix", src_id, dst_id, pcdata); /* Check args */ if (NULL == (src = (H5T_t *)H5I_object_verify(src_id, H5I_DATATYPE)) || @@ -11,31 +11,80 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* private headers */ -#include "H5private.h" /*library */ -#include "H5Eprivate.h" /*error handling */ -#include "H5MMprivate.h" /*memory management functions */ +/* + * Purpose: This file contains the framework for ensuring that the global + * library lock is held when an API routine is called. This + * framework works in concert with the FUNC_ENTER_API / FUNC_LEAVE_API + * macros defined in H5private.h. + * + * Note: Because this threadsafety framework operates outside the library, + * it does not use the error stack and only uses the "namecheck only" + * FUNC_ENTER_* / FUNC_LEAVE_* macros. + */ + +/****************/ +/* Module Setup */ +/****************/ + +/***********/ +/* Headers */ +/***********/ +#include "H5private.h" /* Generic Functions */ +#include "H5Eprivate.h" /* Error handling */ +#include "H5MMprivate.h" /* Memory management */ #ifdef H5_HAVE_THREADSAFE -/* Module specific data structures */ +/****************/ +/* Local Macros */ +/****************/ -/* cancelability structure */ +/******************/ +/* Local Typedefs */ +/******************/ + +/* Cancelability structure */ typedef struct H5TS_cancel_struct { int previous_state; unsigned int cancel_count; } H5TS_cancel_t; +/* Function pointer typedef for thread callback function */ +typedef void *(*H5TS_thread_cb_t)(void *); + +/********************/ +/* Local Prototypes */ +/********************/ +static void H5TS__key_destructor(void *key_val); + +/*********************/ +/* Package Variables */ +/*********************/ + +/*****************************/ +/* Library Private Variables */ +/*****************************/ + /* Global variable definitions */ #ifdef H5_HAVE_WIN_THREADS H5TS_once_t H5TS_first_init_g; -#else /* H5_HAVE_WIN_THREADS */ +#else /* H5_HAVE_WIN_THREADS */ H5TS_once_t H5TS_first_init_g = PTHREAD_ONCE_INIT; #endif /* H5_HAVE_WIN_THREADS */ -H5TS_key_t H5TS_errstk_key_g; -H5TS_key_t H5TS_funcstk_key_g; -H5TS_key_t H5TS_apictx_key_g; -H5TS_key_t H5TS_cancel_key_g; + +/* Thread-local keys, used by other interfaces */ +H5TS_key_t H5TS_errstk_key_g; /* Error stack */ +#ifdef H5_HAVE_CODESTACK +H5TS_key_t H5TS_funcstk_key_g; /* Function stack */ +#endif /* H5_HAVE_CODESTACK */ +H5TS_key_t H5TS_apictx_key_g; /* API context */ + +/*******************/ +/* Local Variables */ +/*******************/ + +/* Thread-local keys, used in this module */ +static H5TS_key_t H5TS_cancel_key_s; /* Thread cancellation state */ #ifndef H5_HAVE_WIN_THREADS @@ -64,12 +113,13 @@ static H5TS_key_t H5TS_tid_key; /*-------------------------------------------------------------------------- * NAME - * H5TS_key_destructor + * H5TS__key_destructor * * USAGE - * H5TS_key_destructor() + * H5TS__key_destructor() * * RETURNS + * None * * DESCRIPTION * Frees the memory for a key. Called by each thread as it exits. @@ -82,12 +132,16 @@ static H5TS_key_t H5TS_tid_key; *-------------------------------------------------------------------------- */ static void -H5TS_key_destructor(void *key_val) +H5TS__key_destructor(void *key_val) { + FUNC_ENTER_STATIC_NAMECHECK_ONLY + /* Use HDfree here instead of H5MM_xfree(), to avoid calling the H5CS routines */ if (key_val != NULL) HDfree(key_val); -} + + FUNC_LEAVE_NOAPI_VOID_NAMECHECK_ONLY +} /* end H5TS__key_destructor() */ #ifndef H5_HAVE_WIN_THREADS @@ -114,10 +168,10 @@ H5TS_tid_destructor(void *_v) return; /* TBD use an atomic CAS */ - pthread_mutex_lock(&H5TS_tid_mtx); + HDpthread_mutex_lock(&H5TS_tid_mtx); tid->next = H5TS_tid_next_free; H5TS_tid_next_free = tid; - pthread_mutex_unlock(&H5TS_tid_mtx); + HDpthread_mutex_unlock(&H5TS_tid_mtx); } /*-------------------------------------------------------------------------- @@ -137,8 +191,8 @@ H5TS_tid_destructor(void *_v) static void H5TS_tid_init(void) { - pthread_mutex_init(&H5TS_tid_mtx, NULL); - pthread_key_create(&H5TS_tid_key, H5TS_tid_destructor); + HDpthread_mutex_init(&H5TS_tid_mtx, NULL); + HDpthread_key_create(&H5TS_tid_key, H5TS_tid_destructor); } /*-------------------------------------------------------------------------- @@ -168,7 +222,7 @@ H5TS_tid_init(void) uint64_t H5TS_thread_id(void) { - H5TS_tid_t *tid = pthread_getspecific(H5TS_tid_key); + H5TS_tid_t *tid = HDpthread_getspecific(H5TS_tid_key); H5TS_tid_t proto_tid; /* An ID is already assigned. */ @@ -182,20 +236,19 @@ H5TS_thread_id(void) * point `tid` at `proto_tid` if we need to allocate some * memory. */ - pthread_mutex_lock(&H5TS_tid_mtx); + HDpthread_mutex_lock(&H5TS_tid_mtx); if ((tid = H5TS_tid_next_free) != NULL) H5TS_tid_next_free = tid->next; else if (H5TS_tid_next_id != UINT64_MAX) { tid = &proto_tid; tid->id = ++H5TS_tid_next_id; } - pthread_mutex_unlock(&H5TS_tid_mtx); + HDpthread_mutex_unlock(&H5TS_tid_mtx); /* If a prototype ID record was established, copy it to the heap. */ - if (tid == &proto_tid) { + if (tid == &proto_tid) if ((tid = HDmalloc(sizeof(*tid))) != NULL) *tid = proto_tid; - } if (tid == NULL) return 0; @@ -204,7 +257,7 @@ H5TS_thread_id(void) * to it. */ tid->next = NULL; - if (pthread_setspecific(H5TS_tid_key, tid) != 0) { + if (HDpthread_setspecific(H5TS_tid_key, tid) != 0) { H5TS_tid_destructor(tid); return 0; } @@ -237,6 +290,8 @@ H5TS_pthread_first_thread_init(void) H5_g.H5_libinit_g = FALSE; /* Library hasn't been initialized */ H5_g.H5_libterm_g = FALSE; /* Library isn't being shutdown */ + FUNC_ENTER_NOAPI_NAMECHECK_ONLY + #ifdef H5_HAVE_WIN32_API #ifdef PTW32_STATIC_LIB pthread_win32_process_attach_np(); @@ -244,25 +299,29 @@ H5TS_pthread_first_thread_init(void) #endif /* initialize global API mutex lock */ - pthread_mutex_init(&H5_g.init_lock.atomic_lock, NULL); - pthread_cond_init(&H5_g.init_lock.cond_var, NULL); + HDpthread_mutex_init(&H5_g.init_lock.atomic_lock, NULL); + HDpthread_cond_init(&H5_g.init_lock.cond_var, NULL); H5_g.init_lock.lock_count = 0; /* Initialize integer thread identifiers. */ H5TS_tid_init(); /* initialize key for thread-specific error stacks */ - pthread_key_create(&H5TS_errstk_key_g, H5TS_key_destructor); + HDpthread_key_create(&H5TS_errstk_key_g, H5TS__key_destructor); +#ifdef H5_HAVE_CODESTACK /* initialize key for thread-specific function stacks */ - pthread_key_create(&H5TS_funcstk_key_g, H5TS_key_destructor); + HDpthread_key_create(&H5TS_funcstk_key_g, H5TS__key_destructor); +#endif /* H5_HAVE_CODESTACK */ /* initialize key for thread-specific API contexts */ - pthread_key_create(&H5TS_apictx_key_g, H5TS_key_destructor); + HDpthread_key_create(&H5TS_apictx_key_g, H5TS__key_destructor); /* initialize key for thread cancellability mechanism */ - pthread_key_create(&H5TS_cancel_key_g, H5TS_key_destructor); -} + HDpthread_key_create(&H5TS_cancel_key_s, H5TS__key_destructor); + + FUNC_LEAVE_NOAPI_VOID_NAMECHECK_ONLY +} /* end H5TS_pthread_first_thread_init() */ #endif /* H5_HAVE_WIN_THREADS */ /*-------------------------------------------------------------------------- @@ -288,32 +347,39 @@ H5TS_pthread_first_thread_init(void) herr_t H5TS_mutex_lock(H5TS_mutex_t *mutex) { + herr_t ret_value = 0; + + FUNC_ENTER_NOAPI_NAMECHECK_ONLY + #ifdef H5_HAVE_WIN_THREADS EnterCriticalSection(&mutex->CriticalSection); - return 0; -#else /* H5_HAVE_WIN_THREADS */ - herr_t ret_value = pthread_mutex_lock(&mutex->atomic_lock); - +#else /* H5_HAVE_WIN_THREADS */ + /* Acquire the library lock */ + ret_value = HDpthread_mutex_lock(&mutex->atomic_lock); if (ret_value) - return ret_value; + HGOTO_DONE(ret_value); - if (mutex->lock_count && pthread_equal(pthread_self(), mutex->owner_thread)) { + /* Check if this thread already owns the lock */ + if (mutex->lock_count && HDpthread_equal(HDpthread_self(), mutex->owner_thread)) /* already owned by self - increment count */ mutex->lock_count++; - } else { - /* if owned by other thread, wait for condition signal */ + /* Wait until the lock is released by current owner thread */ while (mutex->lock_count) - pthread_cond_wait(&mutex->cond_var, &mutex->atomic_lock); + HDpthread_cond_wait(&mutex->cond_var, &mutex->atomic_lock); /* After we've received the signal, take ownership of the mutex */ - mutex->owner_thread = pthread_self(); + mutex->owner_thread = HDpthread_self(); mutex->lock_count = 1; - } + } /* end else */ - return pthread_mutex_unlock(&mutex->atomic_lock); + /* Release the library lock */ + ret_value = HDpthread_mutex_unlock(&mutex->atomic_lock); #endif /* H5_HAVE_WIN_THREADS */ -} + +done: + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) +} /* end H5TS_mutex_lock() */ /*-------------------------------------------------------------------------- * NAME @@ -338,30 +404,36 @@ H5TS_mutex_lock(H5TS_mutex_t *mutex) herr_t H5TS_mutex_unlock(H5TS_mutex_t *mutex) { + herr_t ret_value = 0; + + FUNC_ENTER_NOAPI_NAMECHECK_ONLY + #ifdef H5_HAVE_WIN_THREADS /* Releases ownership of the specified critical section object. */ LeaveCriticalSection(&mutex->CriticalSection); - return 0; -#else /* H5_HAVE_WIN_THREADS */ - herr_t ret_value = pthread_mutex_lock(&mutex->atomic_lock); +#else /* H5_HAVE_WIN_THREADS */ + /* Decrement the lock count for this thread */ + ret_value = HDpthread_mutex_lock(&mutex->atomic_lock); if (ret_value) - return ret_value; - + HGOTO_DONE(ret_value); mutex->lock_count--; + ret_value = HDpthread_mutex_unlock(&mutex->atomic_lock); - ret_value = pthread_mutex_unlock(&mutex->atomic_lock); - + /* If the lock count drops to zero, signal the condition variable, to + * wake another thread. + */ if (mutex->lock_count == 0) { int err; - err = pthread_cond_signal(&mutex->cond_var); + err = HDpthread_cond_signal(&mutex->cond_var); if (err != 0) ret_value = err; } /* end if */ - - return ret_value; #endif /* H5_HAVE_WIN_THREADS */ + +done: + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) } /* H5TS_mutex_unlock */ /*-------------------------------------------------------------------------- @@ -375,12 +447,12 @@ H5TS_mutex_unlock(H5TS_mutex_t *mutex) * 0 on success non-zero error code on error. * * DESCRIPTION - * Creates a cancelation counter for a thread if it is the first time + * Creates a cancellation counter for a thread if it is the first time * the thread is entering the library. * * if counter value is zero, then set cancelability type of the thread * to PTHREAD_CANCEL_DISABLE as thread is entering the library and store - * the previous cancelability type into cancelation counter. + * the previous cancelability type into cancellation counter. * Increase the counter value by 1. * * PROGRAMMER: Chee Wai LEE @@ -391,15 +463,20 @@ H5TS_mutex_unlock(H5TS_mutex_t *mutex) herr_t H5TS_cancel_count_inc(void) { -#ifdef H5_HAVE_WIN_THREADS - /* unsupported; just return 0 */ - return SUCCEED; -#else /* H5_HAVE_WIN_THREADS */ +#ifndef H5_HAVE_WIN_THREADS H5TS_cancel_t *cancel_counter; - herr_t ret_value = SUCCEED; +#endif /* H5_HAVE_WIN_THREADS */ + herr_t ret_value = SUCCEED; + + FUNC_ENTER_NOAPI_NAMECHECK_ONLY - cancel_counter = (H5TS_cancel_t *)H5TS_get_thread_local_value(H5TS_cancel_key_g); +#ifdef H5_HAVE_WIN_THREADS + /* unsupported */ +#else /* H5_HAVE_WIN_THREADS */ + /* Acquire the thread's cancellation counter */ + cancel_counter = (H5TS_cancel_t *)H5TS_get_thread_local_value(H5TS_cancel_key_s); + /* Check if it's created yet */ if (!cancel_counter) { /* * First time thread calls library - create new counter and associate @@ -409,24 +486,31 @@ H5TS_cancel_count_inc(void) * order to avoid codestack calls. */ cancel_counter = (H5TS_cancel_t *)HDcalloc(1, sizeof(H5TS_cancel_t)); + if (NULL == cancel_counter) + HGOTO_DONE(FAIL); + + /* Set the thread's cancellation counter with the new object */ + ret_value = HDpthread_setspecific(H5TS_cancel_key_s, (void *)cancel_counter); + if (ret_value) { + HDfree(cancel_counter); + HGOTO_DONE(FAIL); + } /* end if */ + } /* end if */ - if (!cancel_counter) { - HERROR(H5E_RESOURCE, H5E_NOSPACE, "memory allocation failed"); - return FAIL; - } - - ret_value = pthread_setspecific(H5TS_cancel_key_g, (void *)cancel_counter); - } - + /* Check if thread entering library */ if (cancel_counter->cancel_count == 0) - /* thread entering library */ - ret_value = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, &cancel_counter->previous_state); + /* Set cancellation state to 'disable', and remember previous state */ + ret_value = HDpthread_setcancelstate(PTHREAD_CANCEL_DISABLE, &cancel_counter->previous_state); + /* Increment # of times the library API was re-entered, to avoid resetting + * previous cancellation state until the final API routine is returning. + */ ++cancel_counter->cancel_count; - - return ret_value; #endif /* H5_HAVE_WIN_THREADS */ -} + +done: + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) +} /* end H5TS_cancel_count_inc() */ /*-------------------------------------------------------------------------- * NAME @@ -440,7 +524,7 @@ H5TS_cancel_count_inc(void) * * DESCRIPTION * If counter value is one, then set cancelability type of the thread - * to the previous cancelability type stored in the cancelation counter. + * to the previous cancelability type stored in the cancellation counter. * (the thread is leaving the library). * * Decrement the counter value by 1. @@ -453,23 +537,30 @@ H5TS_cancel_count_inc(void) herr_t H5TS_cancel_count_dec(void) { -#ifdef H5_HAVE_WIN_THREADS - /* unsupported; will just return 0 */ - return SUCCEED; -#else /* H5_HAVE_WIN_THREADS */ - register H5TS_cancel_t *cancel_counter; - herr_t ret_value = SUCCEED; +#ifndef H5_HAVE_WIN_THREADS + H5TS_cancel_t *cancel_counter; +#endif /* H5_HAVE_WIN_THREADS */ + herr_t ret_value = SUCCEED; - cancel_counter = (H5TS_cancel_t *)H5TS_get_thread_local_value(H5TS_cancel_key_g); + FUNC_ENTER_NOAPI_NAMECHECK_ONLY +#ifdef H5_HAVE_WIN_THREADS + /* unsupported */ +#else /* H5_HAVE_WIN_THREADS */ + /* Acquire the thread's cancellation counter */ + cancel_counter = (H5TS_cancel_t *)H5TS_get_thread_local_value(H5TS_cancel_key_s); + + /* Check for leaving last API routine */ if (cancel_counter->cancel_count == 1) - ret_value = pthread_setcancelstate(cancel_counter->previous_state, NULL); + /* Reset to previous thread cancellation state, if last API */ + ret_value = HDpthread_setcancelstate(cancel_counter->previous_state, NULL); + /* Decrement cancellation counter */ --cancel_counter->cancel_count; - - return ret_value; #endif /* H5_HAVE_WIN_THREADS */ -} + + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) +} /* end H5TS_cancel_count_dec() */ #ifdef H5_HAVE_WIN_THREADS /*-------------------------------------------------------------------------- @@ -489,6 +580,8 @@ H5TS_win32_process_enter(PINIT_ONCE InitOnce, PVOID Parameter, PVOID *lpContex) { BOOL ret_value = TRUE; + FUNC_ENTER_NOAPI_NAMECHECK_ONLY + /* Initialize the critical section (can't fail) */ InitializeCriticalSection(&H5_g.init_lock.CriticalSection); @@ -504,11 +597,9 @@ H5TS_win32_process_enter(PINIT_ONCE InitOnce, PVOID Parameter, PVOID *lpContex) if (TLS_OUT_OF_INDEXES == (H5TS_apictx_key_g = TlsAlloc())) ret_value = FALSE; - return ret_value; + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) } /* H5TS_win32_process_enter() */ -#endif /* H5_HAVE_WIN_THREADS */ -#ifdef H5_HAVE_WIN_THREADS /*-------------------------------------------------------------------------- * NAME * H5TS_win32_thread_enter @@ -526,6 +617,8 @@ H5TS_win32_thread_enter(void) { herr_t ret_value = SUCCEED; + FUNC_ENTER_NOAPI_NAMECHECK_ONLY + /* Currently a placeholder function. TLS setup is performed * elsewhere in the library. * @@ -534,11 +627,9 @@ H5TS_win32_thread_enter(void) * is used. */ - return ret_value; + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) } /* H5TS_win32_thread_enter() */ -#endif /* H5_HAVE_WIN_THREADS */ -#ifdef H5_HAVE_WIN_THREADS /*-------------------------------------------------------------------------- * NAME * H5TS_win32_process_exit @@ -554,6 +645,7 @@ H5TS_win32_thread_enter(void) void H5TS_win32_process_exit(void) { + FUNC_ENTER_NOAPI_NAMECHECK_ONLY /* Windows uses a different thread local storage mechanism which does * not support auto-freeing like pthreads' keys. @@ -572,11 +664,9 @@ H5TS_win32_process_exit(void) #endif /* H5_HAVE_CODESTACK */ TlsFree(H5TS_apictx_key_g); - return; + FUNC_LEAVE_NOAPI_VOID_NAMECHECK_ONLY } /* H5TS_win32_process_exit() */ -#endif /* H5_HAVE_WIN_THREADS */ -#ifdef H5_HAVE_WIN_THREADS /*-------------------------------------------------------------------------- * NAME * H5TS_win32_thread_exit @@ -595,6 +685,8 @@ H5TS_win32_thread_exit(void) LPVOID lpvData; herr_t ret_value = SUCCEED; + FUNC_ENTER_NOAPI_NAMECHECK_ONLY + /* Windows uses a different thread local storage mechanism which does * not support auto-freeing like pthreads' keys. * @@ -618,7 +710,7 @@ H5TS_win32_thread_exit(void) if (lpvData) LocalFree((HLOCAL)lpvData); - return ret_value; + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) } /* H5TS_win32_thread_exit() */ #endif /* H5_HAVE_WIN_THREADS */ @@ -638,12 +730,13 @@ H5TS_win32_thread_exit(void) *-------------------------------------------------------------------------- */ H5TS_thread_t -H5TS_create_thread(void *(*func)(void *), H5TS_attr_t *attr, void *udata) +H5TS_create_thread(H5TS_thread_cb_t func, H5TS_attr_t *attr, void *udata) { H5TS_thread_t ret_value; -#ifdef H5_HAVE_WIN_THREADS + FUNC_ENTER_NOAPI_NAMECHECK_ONLY +#ifdef H5_HAVE_WIN_THREADS /* When calling C runtime functions, you should use _beginthread or * _beginthreadex instead of CreateThread. Threads created with * CreateThread risk being killed in low-memory situations. Since we @@ -658,12 +751,11 @@ H5TS_create_thread(void *(*func)(void *), H5TS_attr_t *attr, void *udata) #else /* H5_HAVE_WIN_THREADS */ - pthread_create(&ret_value, attr, (void *(*)(void *))func, udata); + HDpthread_create(&ret_value, attr, (void *(*)(void *))func, udata); #endif /* H5_HAVE_WIN_THREADS */ - return ret_value; - + FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) } /* H5TS_create_thread */ #endif /* H5_HAVE_THREADSAFE */ diff --git a/src/H5TSprivate.h b/src/H5TSprivate.h index 700d879..dc85145 100644 --- a/src/H5TSprivate.h +++ b/src/H5TSprivate.h @@ -27,7 +27,7 @@ #ifdef H5_HAVE_THREADSAFE /* Public headers needed by this file */ #ifdef LATER -#include "H5TSpublic.h" /*Public API prototypes */ +#include "H5TSpublic.h" /* Public API prototypes */ #endif /* LATER */ #ifdef H5_HAVE_WIN_THREADS @@ -38,6 +38,8 @@ typedef struct H5TS_mutex_struct { CRITICAL_SECTION CriticalSection; } H5TS_mutex_t; + +/* Portability wrappers around Windows Threads types */ typedef CRITICAL_SECTION H5TS_mutex_simple_t; typedef HANDLE H5TS_thread_t; typedef HANDLE H5TS_attr_t; @@ -50,7 +52,7 @@ typedef INIT_ONCE H5TS_once_t; #define H5TS_SCOPE_PROCESS 0 #define H5TS_CALL_CONV WINAPI -/* Functions */ +/* Portability function aliases */ #define H5TS_get_thread_local_value(key) TlsGetValue(key) #define H5TS_set_thread_local_value(key, value) TlsSetValue(key, value) #define H5TS_attr_init(attr_ptr) 0 @@ -80,6 +82,8 @@ typedef struct H5TS_mutex_struct { pthread_cond_t cond_var; /* condition variable */ unsigned int lock_count; } H5TS_mutex_t; + +/* Portability wrappers around pthread types */ typedef pthread_t H5TS_thread_t; typedef pthread_attr_t H5TS_attr_t; typedef pthread_mutex_t H5TS_mutex_simple_t; @@ -91,7 +95,7 @@ typedef pthread_once_t H5TS_once_t; #define H5TS_SCOPE_PROCESS PTHREAD_SCOPE_PROCESS #define H5TS_CALL_CONV /* unused - Windows only */ -/* Functions */ +/* Portability function aliases */ #define H5TS_get_thread_local_value(key) pthread_getspecific(key) #define H5TS_set_thread_local_value(key, value) pthread_setspecific(key, value) #define H5TS_attr_init(attr_ptr) pthread_attr_init((attr_ptr)) @@ -101,31 +105,31 @@ typedef pthread_once_t H5TS_once_t; #define H5TS_mutex_init(mutex) pthread_mutex_init(mutex, NULL) #define H5TS_mutex_lock_simple(mutex) pthread_mutex_lock(mutex) #define H5TS_mutex_unlock_simple(mutex) pthread_mutex_unlock(mutex) + +/* Pthread-only routines */ H5_DLL uint64_t H5TS_thread_id(void); +H5_DLL void H5TS_pthread_first_thread_init(void); #endif /* H5_HAVE_WIN_THREADS */ -/* External global variables */ -extern H5TS_once_t H5TS_first_init_g; -extern H5TS_key_t H5TS_errstk_key_g; -extern H5TS_key_t H5TS_funcstk_key_g; -extern H5TS_key_t H5TS_apictx_key_g; - -#if defined c_plusplus || defined __cplusplus -extern "C" { -#endif /* c_plusplus || __cplusplus */ - -H5_DLL void H5TS_pthread_first_thread_init(void); -H5_DLL herr_t H5TS_mutex_lock(H5TS_mutex_t *mutex); -H5_DLL herr_t H5TS_mutex_unlock(H5TS_mutex_t *mutex); -H5_DLL herr_t H5TS_cancel_count_inc(void); -H5_DLL herr_t H5TS_cancel_count_dec(void); +/* Library-scope global variables */ +extern H5TS_once_t H5TS_first_init_g; /* Library initialization */ +extern H5TS_key_t H5TS_errstk_key_g; /* Error stacks */ +#ifdef H5_HAVE_CODESTACK +extern H5TS_key_t H5TS_funcstk_key_g; /* Function stacks */ +#endif /* H5_HAVE_CODESTACK */ +extern H5TS_key_t H5TS_apictx_key_g; /* API contexts */ + +/* Library-scope routines */ +/* (Only used within H5private.h macros) */ +H5_DLL herr_t H5TS_mutex_lock(H5TS_mutex_t *mutex); +H5_DLL herr_t H5TS_mutex_unlock(H5TS_mutex_t *mutex); +H5_DLL herr_t H5TS_cancel_count_inc(void); +H5_DLL herr_t H5TS_cancel_count_dec(void); + +/* Testing routines */ H5_DLL H5TS_thread_t H5TS_create_thread(void *(*func)(void *), H5TS_attr_t *attr, void *udata); -#if defined c_plusplus || defined __cplusplus -} -#endif /* c_plusplus || __cplusplus */ - #else /* H5_HAVE_THREADSAFE */ #define H5TS_thread_id() ((uint64_t)0) diff --git a/src/H5Tarray.c b/src/H5Tarray.c index 5afe74c..0371437 100644 --- a/src/H5Tarray.c +++ b/src/H5Tarray.c @@ -255,13 +255,13 @@ H5T__get_array_ndims(const H5T_t *dt) *------------------------------------------------------------------------- */ int -H5Tget_array_dims2(hid_t type_id, hsize_t dims[]) +H5Tget_array_dims2(hid_t type_id, hsize_t dims[] /*out*/) { H5T_t *dt; /* pointer to array data type */ int ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE2("Is", "i*h", type_id, dims); + H5TRACE2("Is", "ix", type_id, dims); /* Check args */ if (NULL == (dt = (H5T_t *)H5I_object_verify(type_id, H5I_DATATYPE))) @@ -383,13 +383,13 @@ done: *------------------------------------------------------------------------- */ int -H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int H5_ATTR_UNUSED perm[]) +H5Tget_array_dims1(hid_t type_id, hsize_t dims[] /*out*/, int H5_ATTR_UNUSED perm[] /*out*/) { H5T_t *dt; /* Array datatype to query */ int ret_value; /* return value */ FUNC_ENTER_API(FAIL) - H5TRACE3("Is", "i*h*Is", type_id, dims, perm); + H5TRACE3("Is", "ixx", type_id, dims, perm); /* Check args */ if (NULL == (dt = (H5T_t *)H5I_object_verify(type_id, H5I_DATATYPE))) diff --git a/src/H5Tdbg.c b/src/H5Tdbg.c index 5d0c5cd..758430b 100644 --- a/src/H5Tdbg.c +++ b/src/H5Tdbg.c @@ -120,9 +120,9 @@ H5T__print_stats(H5T_path_t H5_ATTR_UNUSED *path, int H5_ATTR_UNUSED *nprint /*i HDfprintf(H5DEBUG(T), " %-16s %10" PRIdHSIZE " %10u %8s %8s %8s %10s\n", path->name, path->stats.nelmts, path->stats.ncalls, timestrs.user, timestrs.system, timestrs.elapsed, bandwidth); - free(timestrs.user); - free(timestrs.system); - free(timestrs.elapsed); + HDfree(timestrs.user); + HDfree(timestrs.system); + HDfree(timestrs.elapsed); } #endif diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index b508dfd..fd545c2 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -29,4 +29,80 @@ #define H5_MY_PKG_ERR H5E_DATATYPE #define H5_MY_PKG_INIT YES +/** + * \defgroup H5T H5T + * \brief Datatype Interface + * \todo Describe concisely what the functions in this module are about. + * + * \defgroup ARRAY Array Datatypes + * \ingroup H5T + * \defgroup ATOM Atomic Datatypes + * \ingroup H5T + * \defgroup COMPOUND Compound Datatypes + * \ingroup H5T + * \defgroup CONV Conversion Function + * \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 + * + * \defgroup PDT Predefined Datatypes + * \ingroup H5T + * \details What is a predefined HDF5 datatype? + * \todo Fill in the blanks! + * + * \defgroup PDTCPU By CPU + * \ingroup PDT + * \details CPU-specific datatypes + * \defgroup PDTALPHA DEC Alpha + * \ingroup PDTCPU + * \defgroup PDTX86 AMD & INTEL + * \ingroup PDTCPU + * \defgroup PDTMIPS SGI MIPS + * \ingroup PDTCPU + * + * \defgroup PDTIEEE IEEE + * \ingroup PDT + * \details The IEEE floating point types in big- and little-endian byte orders. + * + * \defgroup PDTSTD Standard Datatypes + * \ingroup PDT + * \details These are "standard" types. For instance, signed (2's complement) + * and unsigned integers of various sizes in big- and little-endian + * byte orders. + * + * \defgroup PDTUNIX UNIX-specific Datatypes + * \ingroup PDT + * \details Types which are particular to Unix. + * \todo Fill in the blanks! + * + * \defgroup PDTNAT Native Datatypes + * \ingroup PDT + * \details These are the datatypes detected during library \Emph{compilation} + * by \c H5detect(). Their names differ from other HDF5 datatype names + * as follows: + * \li Instead of a class name, precision and byte order as the last + * component, they have a C-like type name. + * \li If the type begins with \c U then it is the unsigned version of + * the integer type; other integer types are signed. + * \li The datatype \c LLONG corresponds C's \Code{long long} and + * \c LDOUBLE is \Code{long double}. These types might be the same + * as \c LONG and \c DOUBLE, respectively. + * \defgroup PDTC9x C9x Integer Datatypes + * \ingroup PDTNAT + * \details C9x integer types + * \todo Fill in the blanks! + * + * \defgroup PDTS Strings + * \ingroup PDT + * + */ + #endif /* _H5Tmodule_H */ diff --git a/src/H5Tpkg.h b/src/H5Tpkg.h index 0261428..4f3d89d 100644 --- a/src/H5Tpkg.h +++ b/src/H5Tpkg.h @@ -338,8 +338,7 @@ typedef struct H5T_shared_t { H5T_class_t type; /*which class of type is this? */ size_t size; /*total size of an instance of this type */ unsigned version; /* Version of object header message to encode this object with */ - hbool_t - force_conv; /* Set if this type always needs to be converted and H5T__conv_noop cannot be called */ + hbool_t force_conv; /* Set if this type always needs to be converted and H5T__conv_noop cannot be called */ struct H5T_t * parent; /*parent type for derived datatypes */ H5VL_object_t *owned_vol_obj; /* Vol object owned by this type (free on close) */ union { diff --git a/src/H5Tprivate.h b/src/H5Tprivate.h index 4675871..b3dc064 100644 --- a/src/H5Tprivate.h +++ b/src/H5Tprivate.h @@ -24,7 +24,7 @@ typedef struct H5T_t H5T_t; #include "H5Tpublic.h" /* Other public headers needed by this file */ -#include "H5MMpublic.h" /* Memory management */ +#include "H5MMpublic.h" /* Memory management */ /* Private headers needed by this file */ #include "H5private.h" /* Generic Functions */ diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h index 73a00b6..68a1d79 100644 --- a/src/H5Tpublic.h +++ b/src/H5Tpublic.h @@ -23,194 +23,245 @@ #define HOFFSET(S, M) (offsetof(S, M)) -/* These are the various classes of datatypes */ -/* If this goes over 16 types (0-15), the file format will need to change) */ +/** + * These are the various classes of datatypes + * internal If this goes over 16 types (0-15), the file format will need to + * change. + */ +//! [H5T_class_t_snip] typedef enum H5T_class_t { - H5T_NO_CLASS = -1, /*error */ - H5T_INTEGER = 0, /*integer types */ - H5T_FLOAT = 1, /*floating-point types */ - H5T_TIME = 2, /*date and time types */ - H5T_STRING = 3, /*character string types */ - H5T_BITFIELD = 4, /*bit field types */ - H5T_OPAQUE = 5, /*opaque types */ - H5T_COMPOUND = 6, /*compound types */ - H5T_REFERENCE = 7, /*reference types */ - H5T_ENUM = 8, /*enumeration types */ - H5T_VLEN = 9, /*Variable-Length types */ - H5T_ARRAY = 10, /*Array types */ - - H5T_NCLASSES /*this must be last */ + H5T_NO_CLASS = -1, /**< error */ + H5T_INTEGER = 0, /**< integer types */ + H5T_FLOAT = 1, /**< floating-point types */ + H5T_TIME = 2, /**< date and time types */ + H5T_STRING = 3, /**< character string types */ + H5T_BITFIELD = 4, /**< bit field types */ + H5T_OPAQUE = 5, /**< opaque types */ + H5T_COMPOUND = 6, /**< compound types */ + H5T_REFERENCE = 7, /**< reference types */ + H5T_ENUM = 8, /**< enumeration types */ + H5T_VLEN = 9, /**< variable-Length types */ + H5T_ARRAY = 10, /**< array types */ + + H5T_NCLASSES /**< sentinel: this must be last */ } H5T_class_t; +//! [H5T_class_t_snip] -/* Byte orders */ +/** + * Byte orders + */ +//! [H5T_order_t_snip] typedef enum H5T_order_t { - H5T_ORDER_ERROR = -1, /*error */ - H5T_ORDER_LE = 0, /*little endian */ - H5T_ORDER_BE = 1, /*bit endian */ - H5T_ORDER_VAX = 2, /*VAX mixed endian */ - H5T_ORDER_MIXED = 3, /*Compound type with mixed member orders */ - H5T_ORDER_NONE = 4 /*no particular order (strings, bits,..) */ + H5T_ORDER_ERROR = -1, /**< error */ + H5T_ORDER_LE = 0, /**< little endian */ + H5T_ORDER_BE = 1, /**< bit endian */ + H5T_ORDER_VAX = 2, /**< VAX mixed endian */ + H5T_ORDER_MIXED = 3, /**< Compound type with mixed member orders */ + H5T_ORDER_NONE = 4 /**< no particular order (strings, bits,..) */ /*H5T_ORDER_NONE must be last */ } H5T_order_t; +//! [H5T_order_t_snip] -/* Types of integer sign schemes */ +/** + * Types of integer sign schemes + */ +//! [H5T_sign_t_snip] typedef enum H5T_sign_t { - H5T_SGN_ERROR = -1, /*error */ - H5T_SGN_NONE = 0, /*this is an unsigned type */ - H5T_SGN_2 = 1, /*two's complement */ + H5T_SGN_ERROR = -1, /**< error */ + H5T_SGN_NONE = 0, /**< this is an unsigned type */ + H5T_SGN_2 = 1, /**< two's complement */ - H5T_NSGN = 2 /*this must be last! */ + H5T_NSGN = 2 /** sentinel: this must be last! */ } H5T_sign_t; +//! [H5T_sign_t_snip] -/* Floating-point normalization schemes */ +/** + * Floating-point normalization schemes + */ +//! [H5T_norm_t_snip] typedef enum H5T_norm_t { - H5T_NORM_ERROR = -1, /*error */ - H5T_NORM_IMPLIED = 0, /*msb of mantissa isn't stored, always 1 */ - H5T_NORM_MSBSET = 1, /*msb of mantissa is always 1 */ - H5T_NORM_NONE = 2 /*not normalized */ + H5T_NORM_ERROR = -1, /**< error */ + H5T_NORM_IMPLIED = 0, /**< msb of mantissa isn't stored, always 1 */ + H5T_NORM_MSBSET = 1, /**< msb of mantissa is always 1 */ + H5T_NORM_NONE = 2 /**< not normalized */ /*H5T_NORM_NONE must be last */ } H5T_norm_t; +//! [H5T_norm_t_snip] -/* - * Character set to use for text strings. Do not change these values since - * they appear in HDF5 files! +/** + * Character set to use for text strings. + * \internal Do not change these values since they appear in HDF5 files! */ typedef enum H5T_cset_t { - H5T_CSET_ERROR = -1, /*error */ - H5T_CSET_ASCII = 0, /*US ASCII */ - H5T_CSET_UTF8 = 1, /*UTF-8 Unicode encoding */ - H5T_CSET_RESERVED_2 = 2, /*reserved for later use */ - H5T_CSET_RESERVED_3 = 3, /*reserved for later use */ - H5T_CSET_RESERVED_4 = 4, /*reserved for later use */ - H5T_CSET_RESERVED_5 = 5, /*reserved for later use */ - H5T_CSET_RESERVED_6 = 6, /*reserved for later use */ - H5T_CSET_RESERVED_7 = 7, /*reserved for later use */ - H5T_CSET_RESERVED_8 = 8, /*reserved for later use */ - H5T_CSET_RESERVED_9 = 9, /*reserved for later use */ - H5T_CSET_RESERVED_10 = 10, /*reserved for later use */ - H5T_CSET_RESERVED_11 = 11, /*reserved for later use */ - H5T_CSET_RESERVED_12 = 12, /*reserved for later use */ - H5T_CSET_RESERVED_13 = 13, /*reserved for later use */ - H5T_CSET_RESERVED_14 = 14, /*reserved for later use */ - H5T_CSET_RESERVED_15 = 15 /*reserved for later use */ + H5T_CSET_ERROR = -1, /**< error */ + H5T_CSET_ASCII = 0, /**< US ASCII */ + H5T_CSET_UTF8 = 1, /**< UTF-8 Unicode encoding */ + H5T_CSET_RESERVED_2 = 2, /**< reserved for later use */ + H5T_CSET_RESERVED_3 = 3, /**< reserved for later use */ + H5T_CSET_RESERVED_4 = 4, /**< reserved for later use */ + H5T_CSET_RESERVED_5 = 5, /**< reserved for later use */ + H5T_CSET_RESERVED_6 = 6, /**< reserved for later use */ + H5T_CSET_RESERVED_7 = 7, /**< reserved for later use */ + H5T_CSET_RESERVED_8 = 8, /**< reserved for later use */ + H5T_CSET_RESERVED_9 = 9, /**< reserved for later use */ + H5T_CSET_RESERVED_10 = 10, /**< reserved for later use */ + H5T_CSET_RESERVED_11 = 11, /**< reserved for later use */ + H5T_CSET_RESERVED_12 = 12, /**< reserved for later use */ + H5T_CSET_RESERVED_13 = 13, /**< reserved for later use */ + H5T_CSET_RESERVED_14 = 14, /**< reserved for later use */ + H5T_CSET_RESERVED_15 = 15 /**< reserved for later use */ } H5T_cset_t; -#define H5T_NCSET H5T_CSET_RESERVED_2 /*Number of character sets actually defined */ +#define H5T_NCSET H5T_CSET_RESERVED_2 /*Number of character sets actually defined */ -/* - * Type of padding to use in character strings. Do not change these values - * since they appear in HDF5 files! +/** + * Type of padding to use in character strings. + * \internal Do not change these values since they appear in HDF5 files! */ typedef enum H5T_str_t { - H5T_STR_ERROR = -1, /*error */ - H5T_STR_NULLTERM = 0, /*null terminate like in C */ - H5T_STR_NULLPAD = 1, /*pad with nulls */ - H5T_STR_SPACEPAD = 2, /*pad with spaces like in Fortran */ - H5T_STR_RESERVED_3 = 3, /*reserved for later use */ - H5T_STR_RESERVED_4 = 4, /*reserved for later use */ - H5T_STR_RESERVED_5 = 5, /*reserved for later use */ - H5T_STR_RESERVED_6 = 6, /*reserved for later use */ - H5T_STR_RESERVED_7 = 7, /*reserved for later use */ - H5T_STR_RESERVED_8 = 8, /*reserved for later use */ - H5T_STR_RESERVED_9 = 9, /*reserved for later use */ - H5T_STR_RESERVED_10 = 10, /*reserved for later use */ - H5T_STR_RESERVED_11 = 11, /*reserved for later use */ - H5T_STR_RESERVED_12 = 12, /*reserved for later use */ - H5T_STR_RESERVED_13 = 13, /*reserved for later use */ - H5T_STR_RESERVED_14 = 14, /*reserved for later use */ - H5T_STR_RESERVED_15 = 15 /*reserved for later use */ + H5T_STR_ERROR = -1, /**< error */ + H5T_STR_NULLTERM = 0, /**< null terminate like in C */ + H5T_STR_NULLPAD = 1, /**< pad with nulls */ + H5T_STR_SPACEPAD = 2, /**< pad with spaces like in Fortran */ + H5T_STR_RESERVED_3 = 3, /**< reserved for later use */ + H5T_STR_RESERVED_4 = 4, /**< reserved for later use */ + H5T_STR_RESERVED_5 = 5, /**< reserved for later use */ + H5T_STR_RESERVED_6 = 6, /**< reserved for later use */ + H5T_STR_RESERVED_7 = 7, /**< reserved for later use */ + H5T_STR_RESERVED_8 = 8, /**< reserved for later use */ + H5T_STR_RESERVED_9 = 9, /**< reserved for later use */ + H5T_STR_RESERVED_10 = 10, /**< reserved for later use */ + H5T_STR_RESERVED_11 = 11, /**< reserved for later use */ + H5T_STR_RESERVED_12 = 12, /**< reserved for later use */ + H5T_STR_RESERVED_13 = 13, /**< reserved for later use */ + H5T_STR_RESERVED_14 = 14, /**< reserved for later use */ + H5T_STR_RESERVED_15 = 15 /**< reserved for later use */ } H5T_str_t; -#define H5T_NSTR H5T_STR_RESERVED_3 /*num H5T_str_t types actually defined */ +#define H5T_NSTR H5T_STR_RESERVED_3 /*num H5T_str_t types actually defined */ -/* Type of padding to use in other atomic types */ +/** + * Type of padding to use in other atomic types + */ +//! [H5T_pad_t_snip] typedef enum H5T_pad_t { - H5T_PAD_ERROR = -1, /*error */ - H5T_PAD_ZERO = 0, /*always set to zero */ - H5T_PAD_ONE = 1, /*always set to one */ - H5T_PAD_BACKGROUND = 2, /*set to background value */ + H5T_PAD_ERROR = -1, /**< error */ + H5T_PAD_ZERO = 0, /**< always set to zero */ + H5T_PAD_ONE = 1, /**< always set to one */ + H5T_PAD_BACKGROUND = 2, /**< set to background value */ - H5T_NPAD = 3 /*THIS MUST BE LAST */ + H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */ } H5T_pad_t; +//! [H5T_pad_t_snip] -/* Commands sent to conversion functions */ +/** + * Commands sent to conversion functions + */ typedef enum H5T_cmd_t { - H5T_CONV_INIT = 0, /*query and/or initialize private data */ - H5T_CONV_CONV = 1, /*convert data from source to dest datatype */ - H5T_CONV_FREE = 2 /*function is being removed from path */ + H5T_CONV_INIT = 0, /**< query and/or initialize private data */ + H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */ + H5T_CONV_FREE = 2 /**< function is being removed from path */ } H5T_cmd_t; -/* How is the `bkg' buffer used by the conversion function? */ +/** + * How is the `bkg' buffer used by the conversion function? + */ typedef enum H5T_bkg_t { - H5T_BKG_NO = 0, /*background buffer is not needed, send NULL */ - H5T_BKG_TEMP = 1, /*bkg buffer used as temp storage only */ - H5T_BKG_YES = 2 /*init bkg buf with data before conversion */ + H5T_BKG_NO = 0, /**< background buffer is not needed, send NULL */ + H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only */ + H5T_BKG_YES = 2 /**< init bkg buf with data before conversion */ } H5T_bkg_t; -/* Type conversion client data */ +/** + * Type conversion client data + */ +//! [H5T_cdata_t_snip] typedef struct H5T_cdata_t { - H5T_cmd_t command; /*what should the conversion function do? */ - H5T_bkg_t need_bkg; /*is the background buffer needed? */ - hbool_t recalc; /*recalculate private data */ - void * priv; /*private data */ + H5T_cmd_t command;/**< what should the conversion function do? */ + H5T_bkg_t need_bkg;/**< is the background buffer needed? */ + hbool_t recalc; /**< recalculate private data */ + void *priv; /**< private data */ } H5T_cdata_t; +//! [H5T_cdata_t_snip] -/* Conversion function persistence */ +/** + * Conversion function persistence + */ typedef enum H5T_pers_t { - H5T_PERS_DONTCARE = -1, /*wild card */ - H5T_PERS_HARD = 0, /*hard conversion function */ - H5T_PERS_SOFT = 1 /*soft conversion function */ + H5T_PERS_DONTCARE = -1, /**< wild card */ + H5T_PERS_HARD = 0, /**< hard conversion function */ + H5T_PERS_SOFT = 1 /**< soft conversion function */ } H5T_pers_t; -/* The order to retrieve atomic native datatype */ +/** + * The order to retrieve atomic native datatype + */ +//! [H5T_direction_t_snip] typedef enum H5T_direction_t { - H5T_DIR_DEFAULT = 0, /*default direction is inscendent */ - H5T_DIR_ASCEND = 1, /*in inscendent order */ - H5T_DIR_DESCEND = 2 /*in descendent order */ + H5T_DIR_DEFAULT = 0, /**< default direction is inscendent */ + H5T_DIR_ASCEND = 1, /**< in inscendent order */ + H5T_DIR_DESCEND = 2 /**< in descendent order */ } H5T_direction_t; +//! [H5T_direction_t_snip] -/* The exception type passed into the conversion callback function */ +/** + * The exception type passed into the conversion callback function + */ typedef enum H5T_conv_except_t { - H5T_CONV_EXCEPT_RANGE_HI = 0, /*source value is greater than destination's range */ - H5T_CONV_EXCEPT_RANGE_LOW = 1, /*source value is less than destination's range */ - H5T_CONV_EXCEPT_PRECISION = 2, /*source value loses precision in destination */ - H5T_CONV_EXCEPT_TRUNCATE = 3, /*source value is truncated in destination */ - H5T_CONV_EXCEPT_PINF = 4, /*source value is positive infinity(floating number) */ - H5T_CONV_EXCEPT_NINF = 5, /*source value is negative infinity(floating number) */ - H5T_CONV_EXCEPT_NAN = 6 /*source value is NaN(floating number) */ + H5T_CONV_EXCEPT_RANGE_HI = 0, /**< source value is greater than destination's range */ + H5T_CONV_EXCEPT_RANGE_LOW = 1, /**< source value is less than destination's range */ + H5T_CONV_EXCEPT_PRECISION = 2, /**< source value loses precision in destination */ + H5T_CONV_EXCEPT_TRUNCATE = 3, /**< source value is truncated in destination */ + H5T_CONV_EXCEPT_PINF = 4, /**< source value is positive infinity(floating number) */ + H5T_CONV_EXCEPT_NINF = 5, /**< source value is negative infinity(floating number) */ + H5T_CONV_EXCEPT_NAN = 6 /**< source value is NaN(floating number) */ } H5T_conv_except_t; -/* The return value from conversion callback function H5T_conv_except_func_t */ +/** + * The return value from conversion callback function H5T_conv_except_func_t() + */ typedef enum H5T_conv_ret_t { - H5T_CONV_ABORT = -1, /*abort conversion */ - H5T_CONV_UNHANDLED = 0, /*callback function failed to handle the exception */ - H5T_CONV_HANDLED = 1 /*callback function handled the exception successfully */ + H5T_CONV_ABORT = -1, /**< abort conversion */ + H5T_CONV_UNHANDLED = 0, /**< callback function failed to handle the exception */ + H5T_CONV_HANDLED = 1 /**< callback function handled the exception successfully */ } H5T_conv_ret_t; -/* Variable Length Datatype struct in memory */ -/* (This is only used for VL sequences, not VL strings, which are stored in char *'s) */ +/** + * Variable Length Datatype struct in memory (This is only used for VL + * sequences, not VL strings, which are stored in char *'s) + */ typedef struct { - size_t len; /* Length of VL data (in base type units) */ - void * p; /* Pointer to VL data */ + size_t len; /**< Length of VL data (in base type units) */ + void * p; /**< Pointer to VL data */ } hvl_t; /* Variable Length String information */ -#define H5T_VARIABLE \ - ((size_t)( \ - -1)) /* Indicate that a string is variable length (null-terminated in C, instead of fixed length) */ +/** + * Indicate that a string is variable length (null-terminated in C, instead of + * fixed length) + */ +#define H5T_VARIABLE ((size_t)(-1)) /* Opaque information */ -#define H5T_OPAQUE_TAG_MAX 256 /* Maximum length of an opaque tag */ - /* This could be raised without too much difficulty */ +/** + * Maximum length of an opaque tag + * \internal This could be raised without too much difficulty + */ +#define H5T_OPAQUE_TAG_MAX 256 #ifdef __cplusplus extern "C" { #endif -/* All datatype conversion functions are... */ +/** + * All datatype conversion functions are... + */ +//! [H5T_conv_t_snip] typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist); +//! [H5T_conv_t_snip] -/* Exception handler. If an exception like overflow happenes during conversion, - * this function is called if it's registered through H5Pset_type_conv_cb. +/** + * Exception handler. If an exception like overflow happenes during conversion, + * this function is called if it's registered through H5Pset_type_conv_cb(). */ typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data); @@ -226,9 +277,25 @@ typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, /* * The IEEE floating point types in various byte orders. */ +/** + * \ingroup PDTIEEE + * 32-bit big-endian IEEE floating-point numbers + */ #define H5T_IEEE_F32BE (H5OPEN H5T_IEEE_F32BE_g) +/** + * \ingroup PDTIEEE + * 32-bit little-endian IEEE floating-point numbers + */ #define H5T_IEEE_F32LE (H5OPEN H5T_IEEE_F32LE_g) +/** + * \ingroup PDTIEEE + * 64-bit big-endian IEEE floating-point numbers + */ #define H5T_IEEE_F64BE (H5OPEN H5T_IEEE_F64BE_g) +/** + * \ingroup PDTIEEE + * 64-bit little-endian IEEE floating-point numbers + */ #define H5T_IEEE_F64LE (H5OPEN H5T_IEEE_F64LE_g) H5_DLLVAR hid_t H5T_IEEE_F32BE_g; H5_DLLVAR hid_t H5T_IEEE_F32LE_g; @@ -239,33 +306,141 @@ H5_DLLVAR hid_t H5T_IEEE_F64LE_g; * These are "standard" types. For instance, signed (2's complement) and * unsigned integers of various sizes and byte orders. */ -#define H5T_STD_I8BE (H5OPEN H5T_STD_I8BE_g) -#define H5T_STD_I8LE (H5OPEN H5T_STD_I8LE_g) -#define H5T_STD_I16BE (H5OPEN H5T_STD_I16BE_g) -#define H5T_STD_I16LE (H5OPEN H5T_STD_I16LE_g) -#define H5T_STD_I32BE (H5OPEN H5T_STD_I32BE_g) -#define H5T_STD_I32LE (H5OPEN H5T_STD_I32LE_g) -#define H5T_STD_I64BE (H5OPEN H5T_STD_I64BE_g) -#define H5T_STD_I64LE (H5OPEN H5T_STD_I64LE_g) -#define H5T_STD_U8BE (H5OPEN H5T_STD_U8BE_g) -#define H5T_STD_U8LE (H5OPEN H5T_STD_U8LE_g) -#define H5T_STD_U16BE (H5OPEN H5T_STD_U16BE_g) -#define H5T_STD_U16LE (H5OPEN H5T_STD_U16LE_g) -#define H5T_STD_U32BE (H5OPEN H5T_STD_U32BE_g) -#define H5T_STD_U32LE (H5OPEN H5T_STD_U32LE_g) -#define H5T_STD_U64BE (H5OPEN H5T_STD_U64BE_g) -#define H5T_STD_U64LE (H5OPEN H5T_STD_U64LE_g) -#define H5T_STD_B8BE (H5OPEN H5T_STD_B8BE_g) -#define H5T_STD_B8LE (H5OPEN H5T_STD_B8LE_g) -#define H5T_STD_B16BE (H5OPEN H5T_STD_B16BE_g) -#define H5T_STD_B16LE (H5OPEN H5T_STD_B16LE_g) -#define H5T_STD_B32BE (H5OPEN H5T_STD_B32BE_g) -#define H5T_STD_B32LE (H5OPEN H5T_STD_B32LE_g) -#define H5T_STD_B64BE (H5OPEN H5T_STD_B64BE_g) -#define H5T_STD_B64LE (H5OPEN H5T_STD_B64LE_g) -#define H5T_STD_REF_OBJ (H5OPEN H5T_STD_REF_OBJ_g) +/** + * \ingroup PDTSTD + * 8-bit big-endian signed integers + */ +#define H5T_STD_I8BE (H5OPEN H5T_STD_I8BE_g) +/** + * \ingroup PDTSTD + * 8-bit little-endian signed integers + */ +#define H5T_STD_I8LE (H5OPEN H5T_STD_I8LE_g) +/** + * \ingroup PDTSTD + * 16-bit big-endian signed integers + */ +#define H5T_STD_I16BE (H5OPEN H5T_STD_I16BE_g) +/** + * \ingroup PDTSTD + * 16-bit little-endian signed integers + */ +#define H5T_STD_I16LE (H5OPEN H5T_STD_I16LE_g) +/** + * \ingroup PDTSTD + * 32-bit big-endian signed integers + */ +#define H5T_STD_I32BE (H5OPEN H5T_STD_I32BE_g) +/** + * \ingroup PDTSTD + * 32-bit little-endian signed integers + */ +#define H5T_STD_I32LE (H5OPEN H5T_STD_I32LE_g) +/** + * \ingroup PDTSTD + * 64-bit big-endian signed integers + */ +#define H5T_STD_I64BE (H5OPEN H5T_STD_I64BE_g) +/** + * \ingroup PDTSTD + * 64-bit little-endian signed integers + */ +#define H5T_STD_I64LE (H5OPEN H5T_STD_I64LE_g) +/** + * \ingroup PDTSTD + * 8-bit big-endian unsigned integers + */ +#define H5T_STD_U8BE (H5OPEN H5T_STD_U8BE_g) +/** + * \ingroup PDTSTD + * 8-bit little-endian unsigned integers + */ +#define H5T_STD_U8LE (H5OPEN H5T_STD_U8LE_g) +/** + * \ingroup PDTSTD + * 16-bit big-endian unsigned integers + */ +#define H5T_STD_U16BE (H5OPEN H5T_STD_U16BE_g) +/** + * \ingroup PDTSTD + * 16-bit little-endian unsigned integers + */ +#define H5T_STD_U16LE (H5OPEN H5T_STD_U16LE_g) +/** + * \ingroup PDTSTD + * 32-bit big-endian unsigned integers + */ +#define H5T_STD_U32BE (H5OPEN H5T_STD_U32BE_g) +/** + * \ingroup PDTSTD + * 32-bit little-endian unsigned integers + */ +#define H5T_STD_U32LE (H5OPEN H5T_STD_U32LE_g) +/** + * \ingroup PDTSTD + * 64-bit big-endian unsigned integers + */ +#define H5T_STD_U64BE (H5OPEN H5T_STD_U64BE_g) +/** + * \ingroup PDTSTD + * 64-bit little-endian unsigned integers + */ +#define H5T_STD_U64LE (H5OPEN H5T_STD_U64LE_g) +/** + * \ingroup PDTSTD + * 8-bit big-endian bitfield + */ +#define H5T_STD_B8BE (H5OPEN H5T_STD_B8BE_g) +/** + * \ingroup PDTSTD + * 8-bit little-endian bitfield + */ +#define H5T_STD_B8LE (H5OPEN H5T_STD_B8LE_g) +/** + * \ingroup PDTSTD + * 16-bit big-endian bitfield + */ +#define H5T_STD_B16BE (H5OPEN H5T_STD_B16BE_g) +/** + * \ingroup PDTSTD + * 16-bit little-endian bitfield + */ +#define H5T_STD_B16LE (H5OPEN H5T_STD_B16LE_g) +/** + * \ingroup PDTSTD + * 32-bit big-endian bitfield + */ +#define H5T_STD_B32BE (H5OPEN H5T_STD_B32BE_g) +/** + * \ingroup PDTSTD + * 32-bit little-endian bitfield + */ +#define H5T_STD_B32LE (H5OPEN H5T_STD_B32LE_g) +/** + * \ingroup PDTSTD + * 64-bit big-endian bitfield + */ +#define H5T_STD_B64BE (H5OPEN H5T_STD_B64BE_g) +/** + * \ingroup PDTSTD + * 64-bit little-endian bitfield + */ +#define H5T_STD_B64LE (H5OPEN H5T_STD_B64LE_g) +/** + * \ingroup PDTSTD + * Object reference + */ +#define H5T_STD_REF_OBJ (H5OPEN H5T_STD_REF_OBJ_g) +/** + * \ingroup PDTSTD + * Dataset region reference + */ #define H5T_STD_REF_DSETREG (H5OPEN H5T_STD_REF_DSETREG_g) -#define H5T_STD_REF (H5OPEN H5T_STD_REF_g) +/** + * \ingroup PDTSTD + * Generic reference + */ +#define H5T_STD_REF (H5OPEN H5T_STD_REF_g) H5_DLLVAR hid_t H5T_STD_I8BE_g; H5_DLLVAR hid_t H5T_STD_I8LE_g; H5_DLLVAR hid_t H5T_STD_I16BE_g; @@ -297,9 +472,21 @@ H5_DLLVAR hid_t H5T_STD_REF_g; /* * Types which are particular to Unix. */ +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D32BE (H5OPEN H5T_UNIX_D32BE_g) +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D32LE (H5OPEN H5T_UNIX_D32LE_g) +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D64BE (H5OPEN H5T_UNIX_D64BE_g) +/** + * \ingroup PDTUNIX + */ #define H5T_UNIX_D64LE (H5OPEN H5T_UNIX_D64LE_g) H5_DLLVAR hid_t H5T_UNIX_D32BE_g; H5_DLLVAR hid_t H5T_UNIX_D32LE_g; @@ -310,12 +497,20 @@ H5_DLLVAR hid_t H5T_UNIX_D64LE_g; * Types particular to the C language. String types use `bytes' instead * of `bits' as their size. */ +/** + * \ingroup PDTS + * String datatype in C (size defined in bytes rather than in bits) + */ #define H5T_C_S1 (H5OPEN H5T_C_S1_g) H5_DLLVAR hid_t H5T_C_S1_g; /* * Types particular to Fortran. */ +/** + * \ingroup PDTS + * String datatype in Fortran (as defined for the HDF5 C library) + */ #define H5T_FORTRAN_S1 (H5OPEN H5T_FORTRAN_S1_g) H5_DLLVAR hid_t H5T_FORTRAN_S1_g; @@ -323,63 +518,239 @@ H5_DLLVAR hid_t H5T_FORTRAN_S1_g; * These types are for Intel CPU's. They are little endian with IEEE * floating point. */ -#define H5T_INTEL_I8 H5T_STD_I8LE +/** + * \ingroup PDTX86 + * 8-bit little-endian signed (2's complement) integers for Intel CPUs + */ +#define H5T_INTEL_I8 H5T_STD_I8LE +/** + * \ingroup PDTX86 + * 16-bit little-endian signed (2's complement) integers for Intel CPUs + */ #define H5T_INTEL_I16 H5T_STD_I16LE +/** + * \ingroup PDTX86 + * 32-bit little-endian signed (2's complement) integers for Intel CPUs + */ #define H5T_INTEL_I32 H5T_STD_I32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian signed (2's complement) integers for Intel CPUs + */ #define H5T_INTEL_I64 H5T_STD_I64LE -#define H5T_INTEL_U8 H5T_STD_U8LE +/** + * \ingroup PDTX86 + * 8-bit little-endian unsigned integers for Intel CPUs + */ +#define H5T_INTEL_U8 H5T_STD_U8LE +/** + * \ingroup PDTX86 + * 16-bit little-endian unsigned integers for Intel CPUs + */ #define H5T_INTEL_U16 H5T_STD_U16LE +/** + * \ingroup PDTX86 + * 32-bit little-endian unsigned integers for Intel CPUs + */ #define H5T_INTEL_U32 H5T_STD_U32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian unsigned integers for Intel CPUs + */ #define H5T_INTEL_U64 H5T_STD_U64LE -#define H5T_INTEL_B8 H5T_STD_B8LE +/** + * \ingroup PDTX86 + * 8-bit little-endian bitfield for Intel CPUs + */ +#define H5T_INTEL_B8 H5T_STD_B8LE +/** + * \ingroup PDTX86 + * 16-bit little-endian bitfield for Intel CPUs + */ #define H5T_INTEL_B16 H5T_STD_B16LE +/** + * \ingroup PDTX86 + * 32-bit little-endian bitfield for Intel CPUs + */ #define H5T_INTEL_B32 H5T_STD_B32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian bitfield for Intel CPUs + */ #define H5T_INTEL_B64 H5T_STD_B64LE +/** + * \ingroup PDTX86 + * 32-bit little-endian IEEE floating-point numbers for Intel CPUs + */ #define H5T_INTEL_F32 H5T_IEEE_F32LE +/** + * \ingroup PDTX86 + * 64-bit little-endian IEEE floating-point numbers for Intel CPUs + */ #define H5T_INTEL_F64 H5T_IEEE_F64LE /* * These types are for DEC Alpha CPU's. They are little endian with IEEE * floating point. */ -#define H5T_ALPHA_I8 H5T_STD_I8LE +/** + * \ingroup PDTALPHA + * 8-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ +#define H5T_ALPHA_I8 H5T_STD_I8LE +/** + * \ingroup PDTALPHA + * 16-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ #define H5T_ALPHA_I16 H5T_STD_I16LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ #define H5T_ALPHA_I32 H5T_STD_I32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian signed (2's complement) integers for DEC Alpha CPUs + */ #define H5T_ALPHA_I64 H5T_STD_I64LE -#define H5T_ALPHA_U8 H5T_STD_U8LE +/** + * \ingroup PDTALPHA + * 8-bit little-endian unsigned integers for DEC Alpha CPUs + */ +#define H5T_ALPHA_U8 H5T_STD_U8LE +/** + * \ingroup PDTALPHA + * 16-bit little-endian unsigned integers for DEC Alpha CPUs + */ #define H5T_ALPHA_U16 H5T_STD_U16LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian unsigned integers for DEC Alpha CPUs + */ #define H5T_ALPHA_U32 H5T_STD_U32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian unsigned integers for DEC Alpha CPUs + */ #define H5T_ALPHA_U64 H5T_STD_U64LE -#define H5T_ALPHA_B8 H5T_STD_B8LE +/** + * \ingroup PDTALPHA + * 8-bit little-endian bitfield for DEC Alpha CPUs + */ +#define H5T_ALPHA_B8 H5T_STD_B8LE +/** + * \ingroup PDTALPHA + * 16-bit little-endian bitfield for DEC Alpha CPUs + */ #define H5T_ALPHA_B16 H5T_STD_B16LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian bitfield for DEC Alpha CPUs + */ #define H5T_ALPHA_B32 H5T_STD_B32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian bitfield for DEC Alpha CPUs + */ #define H5T_ALPHA_B64 H5T_STD_B64LE +/** + * \ingroup PDTALPHA + * 32-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs + */ #define H5T_ALPHA_F32 H5T_IEEE_F32LE +/** + * \ingroup PDTALPHA + * 64-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs + */ #define H5T_ALPHA_F64 H5T_IEEE_F64LE /* * These types are for MIPS cpu's commonly used in SGI systems. They are big * endian with IEEE floating point. */ -#define H5T_MIPS_I8 H5T_STD_I8BE +/** + * \ingroup PDTMIPS + * 8-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ +#define H5T_MIPS_I8 H5T_STD_I8BE +/** + * \ingroup PDTMIPS + * 16-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ #define H5T_MIPS_I16 H5T_STD_I16BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ #define H5T_MIPS_I32 H5T_STD_I32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian signed (2's complement) integers for SGI MIPS CPUs + */ #define H5T_MIPS_I64 H5T_STD_I64BE -#define H5T_MIPS_U8 H5T_STD_U8BE +/** + * \ingroup PDTMIPS + * 8-bit big-endian unsigned integers for SGI MIPS CPUs + */ +#define H5T_MIPS_U8 H5T_STD_U8BE +/** + * \ingroup PDTMIPS + * 16-bit big-endian unsigned integers for SGI MIPS CPUs + */ #define H5T_MIPS_U16 H5T_STD_U16BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian unsigned integers for SGI MIPS CPUs + */ #define H5T_MIPS_U32 H5T_STD_U32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian unsigned integers for SGI MIPS CPUs + */ #define H5T_MIPS_U64 H5T_STD_U64BE -#define H5T_MIPS_B8 H5T_STD_B8BE +/** + * \ingroup PDTMIPS + * 8-bit big-endian bitfield for SGI MIPS CPUs + */ +#define H5T_MIPS_B8 H5T_STD_B8BE +/** + * \ingroup PDTMIPS + * 16-bit big-endian bitfield for SGI MIPS CPUs + */ #define H5T_MIPS_B16 H5T_STD_B16BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian bitfield for SGI MIPS CPUs + */ #define H5T_MIPS_B32 H5T_STD_B32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian bitfield for SGI MIPS CPUs + */ #define H5T_MIPS_B64 H5T_STD_B64BE +/** + * \ingroup PDTMIPS + * 32-bit big-endian IEEE floating-point numbers for MIPS CPUs + */ #define H5T_MIPS_F32 H5T_IEEE_F32BE +/** + * \ingroup PDTMIPS + * 64-bit big-endian IEEE floating-point numbers for MIPS CPUs + */ #define H5T_MIPS_F64 H5T_IEEE_F64BE /* * The VAX floating point types (i.e. in VAX byte order) */ +/** + * \ingroup PDTALPHA + * 32-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs + */ #define H5T_VAX_F32 (H5OPEN H5T_VAX_F32_g) +/** + * \ingroup PDTALPHA + * 64-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs + */ #define H5T_VAX_F64 (H5OPEN H5T_VAX_F64_g) H5_DLLVAR hid_t H5T_VAX_F32_g; H5_DLLVAR hid_t H5T_VAX_F64_g; @@ -393,32 +764,128 @@ H5_DLLVAR hid_t H5T_VAX_F64_g; * to C's `long long' and LDOUBLE is `long double' (these types might be the * same as `LONG' and `DOUBLE' respectively). */ -#define H5T_NATIVE_CHAR (CHAR_MIN ? H5T_NATIVE_SCHAR : H5T_NATIVE_UCHAR) -#define H5T_NATIVE_SCHAR (H5OPEN H5T_NATIVE_SCHAR_g) -#define H5T_NATIVE_UCHAR (H5OPEN H5T_NATIVE_UCHAR_g) -#define H5T_NATIVE_SHORT (H5OPEN H5T_NATIVE_SHORT_g) +/** + * \ingroup PDTNAT + * C-style \c char + */ +#define H5T_NATIVE_CHAR (CHAR_MIN ? H5T_NATIVE_SCHAR : H5T_NATIVE_UCHAR) +/** + * \ingroup PDTNAT + * C-style \Code{signed char} + */ +#define H5T_NATIVE_SCHAR (H5OPEN H5T_NATIVE_SCHAR_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned char} + */ +#define H5T_NATIVE_UCHAR (H5OPEN H5T_NATIVE_UCHAR_g) +/** + * \ingroup PDTNAT + * C-style \Code{short} + */ +#define H5T_NATIVE_SHORT (H5OPEN H5T_NATIVE_SHORT_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned short} + */ #define H5T_NATIVE_USHORT (H5OPEN H5T_NATIVE_USHORT_g) -#define H5T_NATIVE_INT (H5OPEN H5T_NATIVE_INT_g) -#define H5T_NATIVE_UINT (H5OPEN H5T_NATIVE_UINT_g) -#define H5T_NATIVE_LONG (H5OPEN H5T_NATIVE_LONG_g) -#define H5T_NATIVE_ULONG (H5OPEN H5T_NATIVE_ULONG_g) -#define H5T_NATIVE_LLONG (H5OPEN H5T_NATIVE_LLONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{int} + */ +#define H5T_NATIVE_INT (H5OPEN H5T_NATIVE_INT_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned int} + */ +#define H5T_NATIVE_UINT (H5OPEN H5T_NATIVE_UINT_g) +/** + * \ingroup PDTNAT + * C-style \Code{long} + */ +#define H5T_NATIVE_LONG (H5OPEN H5T_NATIVE_LONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned long} + */ +#define H5T_NATIVE_ULONG (H5OPEN H5T_NATIVE_ULONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{long long} + */ +#define H5T_NATIVE_LLONG (H5OPEN H5T_NATIVE_LLONG_g) +/** + * \ingroup PDTNAT + * C-style \Code{unsigned long long} + */ #define H5T_NATIVE_ULLONG (H5OPEN H5T_NATIVE_ULLONG_g) -#define H5T_NATIVE_FLOAT (H5OPEN H5T_NATIVE_FLOAT_g) +/** + * \ingroup PDTNAT + * C-style \Code{float} + */ +#define H5T_NATIVE_FLOAT (H5OPEN H5T_NATIVE_FLOAT_g) +/** + * \ingroup PDTNAT + * C-style \Code{double} + */ #define H5T_NATIVE_DOUBLE (H5OPEN H5T_NATIVE_DOUBLE_g) #if H5_SIZEOF_LONG_DOUBLE != 0 +/** + * \ingroup PDTNAT + * C-style \Code{long double} + */ #define H5T_NATIVE_LDOUBLE (H5OPEN H5T_NATIVE_LDOUBLE_g) #endif -#define H5T_NATIVE_B8 (H5OPEN H5T_NATIVE_B8_g) -#define H5T_NATIVE_B16 (H5OPEN H5T_NATIVE_B16_g) -#define H5T_NATIVE_B32 (H5OPEN H5T_NATIVE_B32_g) -#define H5T_NATIVE_B64 (H5OPEN H5T_NATIVE_B64_g) +/** + * \ingroup PDTNAT + * HDF5 8-bit bitfield based on native types + */ +#define H5T_NATIVE_B8 (H5OPEN H5T_NATIVE_B8_g) +/** + * \ingroup PDTNAT + * HDF5 16-bit bitfield based on native types + */ +#define H5T_NATIVE_B16 (H5OPEN H5T_NATIVE_B16_g) +/** + * \ingroup PDTNAT + * HDF5 32-bit bitfield based on native types + */ +#define H5T_NATIVE_B32 (H5OPEN H5T_NATIVE_B32_g) +/** + * \ingroup PDTNAT + * HDF5 64-bit bitfield based on native types + */ +#define H5T_NATIVE_B64 (H5OPEN H5T_NATIVE_B64_g) +/** + * \ingroup PDTNAT + * HDF5 opaque unit based on native types + */ #define H5T_NATIVE_OPAQUE (H5OPEN H5T_NATIVE_OPAQUE_g) -#define H5T_NATIVE_HADDR (H5OPEN H5T_NATIVE_HADDR_g) -#define H5T_NATIVE_HSIZE (H5OPEN H5T_NATIVE_HSIZE_g) +/** + * \ingroup PDTNAT + * HDF5 address type based on native types + */ +#define H5T_NATIVE_HADDR (H5OPEN H5T_NATIVE_HADDR_g) +/** + * \ingroup PDTNAT + * HDF5 size type based on native types + */ +#define H5T_NATIVE_HSIZE (H5OPEN H5T_NATIVE_HSIZE_g) +/** + * \ingroup PDTNAT + * HDF5 signed size type based on native types + */ #define H5T_NATIVE_HSSIZE (H5OPEN H5T_NATIVE_HSSIZE_g) -#define H5T_NATIVE_HERR (H5OPEN H5T_NATIVE_HERR_g) -#define H5T_NATIVE_HBOOL (H5OPEN H5T_NATIVE_HBOOL_g) +/** + * \ingroup PDTNAT + * HDF5 error code type based on native types + */ +#define H5T_NATIVE_HERR (H5OPEN H5T_NATIVE_HERR_g) +/** + * \ingroup PDTNAT + * HDF5 Boolean type based on native types + */ +#define H5T_NATIVE_HBOOL (H5OPEN H5T_NATIVE_HBOOL_g) H5_DLLVAR hid_t H5T_NATIVE_SCHAR_g; H5_DLLVAR hid_t H5T_NATIVE_UCHAR_g; H5_DLLVAR hid_t H5T_NATIVE_SHORT_g; @@ -446,12 +913,30 @@ H5_DLLVAR hid_t H5T_NATIVE_HERR_g; H5_DLLVAR hid_t H5T_NATIVE_HBOOL_g; /* C9x integer types */ -#define H5T_NATIVE_INT8 (H5OPEN H5T_NATIVE_INT8_g) -#define H5T_NATIVE_UINT8 (H5OPEN H5T_NATIVE_UINT8_g) -#define H5T_NATIVE_INT_LEAST8 (H5OPEN H5T_NATIVE_INT_LEAST8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT8 (H5OPEN H5T_NATIVE_INT8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT8 (H5OPEN H5T_NATIVE_UINT8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST8 (H5OPEN H5T_NATIVE_INT_LEAST8_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST8 (H5OPEN H5T_NATIVE_UINT_LEAST8_g) -#define H5T_NATIVE_INT_FAST8 (H5OPEN H5T_NATIVE_INT_FAST8_g) -#define H5T_NATIVE_UINT_FAST8 (H5OPEN H5T_NATIVE_UINT_FAST8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST8 (H5OPEN H5T_NATIVE_INT_FAST8_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST8 (H5OPEN H5T_NATIVE_UINT_FAST8_g) H5_DLLVAR hid_t H5T_NATIVE_INT8_g; H5_DLLVAR hid_t H5T_NATIVE_UINT8_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST8_g; @@ -459,12 +944,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST8_g; H5_DLLVAR hid_t H5T_NATIVE_INT_FAST8_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST8_g; -#define H5T_NATIVE_INT16 (H5OPEN H5T_NATIVE_INT16_g) -#define H5T_NATIVE_UINT16 (H5OPEN H5T_NATIVE_UINT16_g) -#define H5T_NATIVE_INT_LEAST16 (H5OPEN H5T_NATIVE_INT_LEAST16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT16 (H5OPEN H5T_NATIVE_INT16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT16 (H5OPEN H5T_NATIVE_UINT16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST16 (H5OPEN H5T_NATIVE_INT_LEAST16_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST16 (H5OPEN H5T_NATIVE_UINT_LEAST16_g) -#define H5T_NATIVE_INT_FAST16 (H5OPEN H5T_NATIVE_INT_FAST16_g) -#define H5T_NATIVE_UINT_FAST16 (H5OPEN H5T_NATIVE_UINT_FAST16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST16 (H5OPEN H5T_NATIVE_INT_FAST16_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST16 (H5OPEN H5T_NATIVE_UINT_FAST16_g) H5_DLLVAR hid_t H5T_NATIVE_INT16_g; H5_DLLVAR hid_t H5T_NATIVE_UINT16_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST16_g; @@ -472,12 +975,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST16_g; H5_DLLVAR hid_t H5T_NATIVE_INT_FAST16_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST16_g; -#define H5T_NATIVE_INT32 (H5OPEN H5T_NATIVE_INT32_g) -#define H5T_NATIVE_UINT32 (H5OPEN H5T_NATIVE_UINT32_g) -#define H5T_NATIVE_INT_LEAST32 (H5OPEN H5T_NATIVE_INT_LEAST32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT32 (H5OPEN H5T_NATIVE_INT32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT32 (H5OPEN H5T_NATIVE_UINT32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST32 (H5OPEN H5T_NATIVE_INT_LEAST32_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST32 (H5OPEN H5T_NATIVE_UINT_LEAST32_g) -#define H5T_NATIVE_INT_FAST32 (H5OPEN H5T_NATIVE_INT_FAST32_g) -#define H5T_NATIVE_UINT_FAST32 (H5OPEN H5T_NATIVE_UINT_FAST32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST32 (H5OPEN H5T_NATIVE_INT_FAST32_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST32 (H5OPEN H5T_NATIVE_UINT_FAST32_g) H5_DLLVAR hid_t H5T_NATIVE_INT32_g; H5_DLLVAR hid_t H5T_NATIVE_UINT32_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST32_g; @@ -485,12 +1006,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST32_g; H5_DLLVAR hid_t H5T_NATIVE_INT_FAST32_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST32_g; -#define H5T_NATIVE_INT64 (H5OPEN H5T_NATIVE_INT64_g) -#define H5T_NATIVE_UINT64 (H5OPEN H5T_NATIVE_UINT64_g) -#define H5T_NATIVE_INT_LEAST64 (H5OPEN H5T_NATIVE_INT_LEAST64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT64 (H5OPEN H5T_NATIVE_INT64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT64 (H5OPEN H5T_NATIVE_UINT64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_LEAST64 (H5OPEN H5T_NATIVE_INT_LEAST64_g) +/** + * \ingroup PDTC9x + */ #define H5T_NATIVE_UINT_LEAST64 (H5OPEN H5T_NATIVE_UINT_LEAST64_g) -#define H5T_NATIVE_INT_FAST64 (H5OPEN H5T_NATIVE_INT_FAST64_g) -#define H5T_NATIVE_UINT_FAST64 (H5OPEN H5T_NATIVE_UINT_FAST64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_INT_FAST64 (H5OPEN H5T_NATIVE_INT_FAST64_g) +/** + * \ingroup PDTC9x + */ +#define H5T_NATIVE_UINT_FAST64 (H5OPEN H5T_NATIVE_UINT_FAST64_g) H5_DLLVAR hid_t H5T_NATIVE_INT64_g; H5_DLLVAR hid_t H5T_NATIVE_UINT64_g; H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST64_g; @@ -499,93 +1038,1838 @@ H5_DLLVAR hid_t H5T_NATIVE_INT_FAST64_g; H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g; /* Operations defined on all datatypes */ -H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); -H5_DLL hid_t H5Tcopy(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Creates a new datatype. + * + * \param[in] type Class of datatype to create + * \param[in] size Size, in bytes, of the datatype being created + * + * \return \hid_t{datatype} + * + * \details H5Tcreate() creates a new datatype of the specified class with the + * specified number of bytes. This function is used only with the + * following datatype classes: + * - #H5T_COMPOUND + * - #H5T_OPAQUE + * - #H5T_ENUM + * - #H5T_STRING + * + * Other datatypes, including integer and floating-point datatypes, + * are typically created by using H5Tcopy() to copy and modify a + * predefined datatype. + * + * When creating a variable-length string datatype, \p size must + * be #H5T_VARIABLE. + * + * When creating a fixed-length string datatype, \p size will + * be the length of the string in bytes. The length of the + * string in characters will depend on i the encoding used; see + * H5Pset_char_encoding(). + * + * ENUMs created with this function have a signed native integer + * base datatype. Use H5Tenum_create() if a different integer base + * datatype is required. + * + * The datatype identifier returned from this function should be + * released with H5Tclose or resource leaks will result. + * + * \since 1.2.0 + * + * \see H5Tclose() + * + * \todo Original has a reference to “Creating variable-length string + * datatypes”. + * \todo Create an example for H5Tcreate. + * + */ +H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); +/** + * \ingroup H5T + * + * \brief Copies an existing datatype. + * + * \type_id + * + * \return \hid_t{datatype} + * + * \details H5Tcopy() makes a copy of an existing datatype. The returned type + * is always transient and unlocked. + * + * The \p type_id argument can be either a datatype identifier, + * a predefined datatype (defined in H5Tpublic.h), or a dataset + * identifier. If \p type_id is a dataset identifier, this function + * returns a transient, modifiable datatype which is a copy of the + * dataset's datatype. + * + * The returned datatype identifier should be released with H5Tclose() + * to prevent resource leak. + * + * \todo Create an example for H5Tcopy(). + * + */ +H5_DLL hid_t H5Tcopy(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Releases a datatype + * + * \type_id + * + * \return \herr_t + * + * \details H5Tclose() releases the datatype \p dtype_id. Further access + * through this datatype identifier is illegal. Failure to release + * a datatype with this call will result in resource leaks. + * + */ H5_DLL herr_t H5Tclose(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Determines whether two datatype identifiers refer to the same datatype + * + * \type_id{type1_id} + * \type_id{type2_id} + * + * \return \htri_t + * + * \details H5Tequal() determines whether two datatype identifiers refer to + * the same datatype. + * + * \since 1.6 or earlier + * + */ H5_DLL htri_t H5Tequal(hid_t type1_id, hid_t type2_id); +/** + * \ingroup H5T + * + * \brief Locks a datatype + * + * \type_id + * + * \return \herr_t + * + * \details H5Tlock() locks the datatype specified by the dtype_id identifier, + * making it read-only and non-destructible. This is normally done by + * the library for predefined datatypes so the application does not + * inadvertently change or delete a predefined type. Once a datatype + * is locked it can never be unlocked. + * + */ H5_DLL herr_t H5Tlock(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Commits a transient datatype, linking it into the file and creating + * a new committed datatype + * + * \fg_loc_id + * \param[in] name Name given to committed datatype + * \type_id Identifier of datatype to be committed and, upon function’s + * return, identifier for the committed datatype + * \lcpl_id + * \tcpl_id + * \tapl_id + * + * \return \herr_t + * + * \details H5Tcommit2() saves a transient datatype as an immutable committed + * datatype in a file. The datatype specified by \p dtype_id is + * committed to the file with the name name at the location specified + * by \p loc_id and with the datatype creation and access property + * lists \p tcpl_id and \p tapl_id, respectively. + * + * \p loc_id may be a file identifier, or a group identifier within + * that file. \p name may be either an absolute path in the file or + * a relative path from \p loc_id naming the newly-commited datatype. + * + * The link creation property list, \p lcpl_id, governs creation of + * the link(s) by which the new committed datatype is accessed and + * the creation of any intermediate groups that may be missing. + * + * Once commited, this datatype may be used to define the datatype + * of any other dataset or attribute in the file. + * + * This function will not accept a datatype that cannot actually hold + * information. This currently includes compound datatypes with no + * fields and enumerated datatypes with no members. + * + * Committed datatypes are sometimes referred to as named datatypes. + * + * \version 1.8.7 Function modified in this release to reject datatypes that + * will not accomodate actual data, such as a compound datatype + * with no fields or an enumerated datatype with no members. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id); -H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5T + * + * \brief Opens a committed (named) datatype + * + * \fgdta_loc_id + * \param[in] name Name of the datatype to open + * \tapl_id + * + * \return \hid_t{datatype} + * + * \details H5Topen2() opens a committed datatype at the location specified + * by \p loc_id and returns an identifier for the datatype. \p + * loc_id is either a file or group identifier. The identifier should + * eventually be closed by calling H5Tclose() to release resources. + * + * The committed datatype is opened with the datatype access property + * list tapl_id. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); +/** + * \ingroup H5T + * + * \brief Commits a transient datatype to a file, creating a new named + * datatype, but does not link it into the file structure + * + * \fg_loc_id + * \type_id + * \tcpl_id + * \tapl_id + * + * \return \herr_t + * + * \details H5Tcommit_anon() commits a transient datatype (not immutable) + * to a file, turning it into a named datatype with the specified + * creation and property lists. With default property lists, + * #H5P_DEFAULT, H5Tcommit_anon() provides similar functionality to + * that of H5Tcommit(), with the differences described below. + * + * #H5P_DEFAULT can be passed in for the datatype creation property + * list identifier, \p tcpl_id. The datatype access property list + * identifier, \p tapl_id, is provided for future functionality and + * is not used at this time. This parameter should always be passed + * as the value #H5P_DEFAULT. + * + * Note that H5Tcommit_anon() does not link this newly-committed + * datatype into the file. After the H5Tcommit_anon() call, the + * datatype identifier \p type_id must be linked into the HDF5 file + * structure with H5Olink() or it will be deleted from the file when + * the file is closed. + * + * The differences between this function and H5Tcommit() are as follows: + * \li H5Tcommit_anon() explicitly includes property lists, + * which provides for greater control of the creation process + * and of the properties of the new named datatype. H5Tcommit() + * always uses default properties. + * \li H5Tcommit_anon() neither provides the new named datatype’s + * name nor links it into the HDF5 file structure; those actions + * must be performed separately through a call to H5Olink(), + * which offers greater control over linking. + * + * This function will not accept a datatype that cannot actually + * hold data. This currently includes compound datatypes with no + * fields and enumerated datatypes with no members. + * + * \version 1.8.7 Function modified in this release to reject datatypes that + * will not accomodate actual data, such as a compound datatype + * with no fields or an enumerated datatype with no members. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tcommit_anon(hid_t loc_id, hid_t type_id, hid_t tcpl_id, hid_t tapl_id); -H5_DLL hid_t H5Tget_create_plist(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Returns a copy of a datatype's creation property list + * + * \type_id + * + * \return \hid_t{datatype creation property list} + * + * \details H5Tget_create_plist() returns a property list identifier + * for the datatype creation property list associated with the datatype + * specified by \p type_id. + * + * The creation property list identifier should be released with + * H5Pclose() to prevent memory leaks. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Tget_create_plist(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Determines whether a datatype is a committed type or a transient type + * + * \type_id + * + * \return \htri_t + * + * \details H5Tcommitted() queries a type to determine whether the type + * specified by the \p dtype_id identifier is a committed (formerly + * known as a \Emph{named}) type or a transient type. If this function returns + * a positive value, then the type is committed (that is, it has been + * committed, perhaps by some other application). Datasets which + * return committed datatypes with H5Dget_type() are able to share + * the datatype with other datasets in the same file. + * + * \version 1.8.0 Fortran API was added + * + * \since 1.6 or earlier + * + */ H5_DLL htri_t H5Tcommitted(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Encodes a datatype object description into a binary buffer + * + * \param[in] obj_id Identifier of the object to be encoded + * \param[in,out] buf Buffer for the object to be encoded into. + * \param[in,out] nalloc IN: The size of the allocated buffer + * OUT: The size of the buffer needed + * + * \return \herr_t + * + * \details H5Tencode() Given datatype identifier, H5Tencode() converts a + * datatype description into binary form in a buffer. Using this + * binary form in the buffer, a datatype object can be reconstructed + * using H5Tdecode() to return a new object handle (\ref hid_t) for + * this datatype. + * + * If the provided buffer is NULL, only the size of buffer needed is + * returned through \p nalloc. + * + * A preliminary H5Tencode() call can be made to find out the size + * of the buffer needed. This value is returned as \p nalloc. That + * value can then be assigned to \p nalloc for a second H5Tencode() + * call, which will retrieve the actual encoded object. + * + * If the library finds that \p nalloc is not big enough for the + * object, it simply returns the size of the buffer needed through + * \p nalloc without encoding the provided buffer. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tencode(hid_t obj_id, void *buf, size_t *nalloc); -H5_DLL hid_t H5Tdecode(const void *buf); +/** + * \ingroup H5T + * + * \brief Decodes a binary object description of datatype and return a new + * object handle + * + * \param[in] buf Buffer for the datatype object to be decoded + * + * \return \hid_t{datatype} + * + * \details H5Tdecode() Given an object description of datatype in binary in a + * buffer, H5Tdecode() reconstructs the HDF5 datatype object and + * returns a new object handle for it. The binary description of + * the object is encoded by H5Tencode(). User is responsible for + * passing in the right buffer. + * + * The datatype identifier returned by this function can be released + * with H5Tclose() when the identifier is no longer needed so that + * resource leaks will not develop. + * + */ +H5_DLL hid_t H5Tdecode(const void *buf); +/** + * \ingroup H5T + * + * \brief Flushes all buffers associated with a committed datatype to disk + * + * \type_id + * + * \return \herr_t + * + * \details H5Tflush() causes all buffers associated with a committed datatype + * \p type_id to be immediately flushed to disk without removing the + * data from the cache. + * + * HDF5 does not possess full control over buffering. H5Tflush() + * flushes the internal HDF5 buffers and then asks the operating + * system (the OS) to flush the system buffers for the open + * files. After that, the OS is responsible for ensuring that the + * data is actually flushed to disk. + * + * \return \herr_t + * + * \since 1.10.0 C function introduced with this release. + * + * \see H5Dflush() + * H5Drefresh() + * H5Tflush() + * H5Grefresh() + * H5Oflush() + * H5Orefresh() + * H5Tflush() + * H5Trefresh() + * H5Fstart_swmr_write() + * H5Pget_append_flush() + * H5Pget_object_flush_cb() + * H5Pset_append_flush() + * H5Pset_object_flush_cb() + * + */ H5_DLL herr_t H5Tflush(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Refreshes all buffers associated with a committed datatype + * + * \type_id + * + * \return \herr_t + * + * \details H5Trefresh() causes all buffers associated with a committed + * datatype to be cleared and immediately re-loaded with updated + * contents from disk. + * + * This function essentially closes the datatype, evicts all + * metadata associated with it from the cache, and then re-opens the + * datatype. The reopened datatype is automatically re-registered + * with the same identifier. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Trefresh(hid_t type_id); /* Operations defined on compound datatypes */ +/** + * \ingroup COMPOUND + * + * \brief Adds a new member to a compound datatype. + * + * \type_id{parent_id} + * \param[in] name Name of the field to insert + * \param[in] offset Offset in memory structure of the field to insert + * \param[in] member_id Datatype identifier of the field to insert + * + * \return \herr_t + * + * \details H5Tinsert() adds another member to the compound datatype, specified + * \p type_id. + * + * The new member has a \p name which must be unique within the + * compound datatype. The \p offset argument defines the start of the + * member in an instance of the compound datatype, and \p member_id + * is the datatype identifier of the new member. + * + * \note Members of a compound datatype do not have to be atomic + * datatypes; a compound datatype can have a member which is a + * compound datatype. + * + * \since 1.2.0 + * + * \todo Create example for H5Tinsert + * + */ H5_DLL herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id); +/** + * \ingroup COMPOUND + * + * \brief Recursively removes padding from within a compound datatype + * + * \type_id + * + * \return \herr_t + * + * \details H5Tpack() recursively removes padding from within a compound + * datatype to make it more efficient (space-wise) to store that data. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tpack(hid_t type_id); /* Operations defined on enumeration datatypes */ -H5_DLL hid_t H5Tenum_create(hid_t base_id); +/** + * \ingroup ENUM + * + * \brief Creates a new enumeration datatype + * + * \param[in] base_id Datatype identifier for the base datatype. Must be an + * integer datatype + * + * \return \hid_t{enumeration datatype} + * + * \details H5Tenum_create() creates a new enumeration datatype based on the + * specified base datatype, dtype_id, which must be an integer datatype. + * + * If a particular architecture datatype is required, a little endian + * or big endian datatype for example, use a native datatype as the + * base datatype and use H5Tconvert() on values as they are read + * from or written to a dataset. + * + * \since 1.2.0 + * + */ +H5_DLL hid_t H5Tenum_create(hid_t base_id); +/** + * \ingroup ENUM + * + * \brief Inserts a new enumeration datatype member + * + * \type_id{type} + * \param[in] name Name of the new member + * \param[in] value Pointer to the value of the new member + * + * \return \herr_t + * + * \details H5Tenum_insert() inserts a new enumeration datatype member into an + * enumeration datatype. + * + * \p type_id is the datatype identifier for the enumeration datatype, + * \p name is the name of the new member, and \p value points to the + * value of the new member. + * + * \p name and \p value must both be unique within \p dtype_id. + * + * \p value points to data which must be of the integer base datatype + * used when the enumeration datatype was created. If a particular + * architecture datatype is required, a little endian or big endian + * datatype for example, use a native datatype as the base datatype + * and use H5Tconvert() on values as they are read from or written + * to a dataset. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tenum_insert(hid_t type, const char *name, const void *value); +/** + * \ingroup ENUM + * + * \brief Returns the symbol name corresponding to a specified member of an + * enumeration datatype + * + * \type_id{type} + * \param[in] value Value of the enumeration datatype + * \param[out] name Buffer for output of the symbol name + * \param[in] size Anticipated size of the symbol name, in bytes + * + * \return Returns a non-negative value if successful. Otherwise returns a + * negative value + * + * \details H5Tenum_nameof() finds the symbol name that corresponds to the + * specified \p value of the enumeration datatype \p type. + * + * At most \p size characters of the symbol \p name are copied into + * the \p name buffer. If the entire symbol name and null terminator + * do not fit in the name buffer, then as many characters as possible + * are copied (not null terminated) and the function fails. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tenum_nameof(hid_t type, const void *value, char *name /*out*/, size_t size); +/** + * \ingroup ENUM + * + * \brief Returns the value corresponding to a specified member of an + * enumeration datatype + * + * \type_id{type} + * \param[in] name Symbol name of the enumeration datatype + * \param[out] value Buffer for the value of the enumeration datatype + * + * \return \herr_t + * + * \details H5Tenum_valueof() finds the value that corresponds to the + * specified name of the enumeration datatype \p dtype_id. + * + * Values returned in \p value will be of the enumerated type’s + * base type, that is, the datatype used by H5Tenum_create() when + * the enumerated type was created. + * + * The \p value buffer must be at least large enough to hold a value + * of that base type. If the size is unknown, you can determine it + * with H5Tget_size(). + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tenum_valueof(hid_t type, const char *name, void *value /*out*/); /* Operations defined on variable-length datatypes */ +/** + * \ingroup VLEN + * + * \brief Creates a new variable-length array datatype + * + * \type_id{base_id}, the element type of the datatype to create + * + * \return \hid_t{variable-length datatype} + * + * \details H5Tvlen_create() creates a new one-dimensional array datatype of + * variable-length (VL) with the base datatype \p base_id. + * + * This one-dimensional array often represents a data sequence of the + * base datatype, such as characters for character sequences or vertex + * coordinates for polygon lists. The base type specified for the VL + * datatype can be any HDF5 datatype, including another VL datatype, a + * compound datatype, or an atomic datatype. + * + * When necessary, use H5Tget_super() to determine the base type of + * the VL datatype. + * + * The datatype identifier returned from this function should be + * released with H5Tclose() or resource leaks will result. Under + * certain circumstances, H5Dvlen_reclaim() must also be used. + * + * \attention H5Tvlen_create() cannot be used to create a variable-length + * string datatype. H5Tvlen_create() called with a string or + * character base type creates a variable-length sequence of strings + * (a variable-length, 1-dimensional array), with each element of + * the array being of the string or character base type.\n + * To create a variable-length string datatype, see "Creating + * variable-length string datatypes." + * + * \todo Fix the reference. + * + */ H5_DLL hid_t H5Tvlen_create(hid_t base_id); /* Operations defined on array datatypes */ +/** + * \ingroup ARRAY + * + * \brief Creates an array datatype object + * + * \param[in] base_id Datatype identifier for the array base datatype + * \param[in] ndims Rank of the array + * \param[in] dim Size of each array dimension + * + * \return \hid_t{array datatype} + * + * \details H5Tarray_create2() creates a new array datatype object.\n\n + * \p base_id is the datatype of every element of the array, i.e., + * of the number at each position in the array. + * + * \p ndims is the number of dimensions and the size of each dimension + * is specified in the array \p dim. The value of \p rank is + * currently limited to #H5S_MAX_RANK and must be greater than 0 + * (zero). All dimension sizes specified in \p dim must be greater + * than 0 (zero). + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Tarray_create2(hid_t base_id, unsigned ndims, const hsize_t dim[/* ndims */]); -H5_DLL int H5Tget_array_ndims(hid_t type_id); -H5_DLL int H5Tget_array_dims2(hid_t type_id, hsize_t dims[]); +/** + * \ingroup ARRAY + * + * \brief Returns the rank of an array datatype + * + * \type_id + * + * \return Returns the rank of the array if successful; otherwise returns a + * negative value. + * + * \details H5Tget_array_ndims() returns the rank, i.e., the number of + * dimensions, of an array datatype object. + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_array_ndims(hid_t type_id); +/** + * \ingroup ARRAY + * + * \brief Retrieves sizes of array dimensions + * + * \type_id + * \param[out] dims Sizes of array dimensions + * + * \return Returns the non-negative number of dimensions of the array type + * if successful; otherwise returns a negative value. + * + * \details H5Tget_array_dims2() returns the sizes of the dimensions of the + * specified array datatype object in the array \p dims. + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_array_dims2(hid_t type_id, hsize_t dims[]); /* Operations defined on opaque datatypes */ +/** + * \ingroup OPAQUE + * + * \brief Tags an opaque datatype + * + * \type_id{type} of an opaque datatype + * \param[in] tag Descriptive ASCII string with which the opaque datatype is + * to be tagged + * + * \return \herr_t + * + * \details H5Tset_tag() tags an opaque datatype \p type with a descriptive + * ASCII identifier, \p tag. + * + * \p tag is intended to provide a concise description; the maximum + * size is hard-coded in the HDF5 library as 256 bytes + * (#H5T_OPAQUE_TAG_MAX). + * + * \version 1.6.5 The #H5T_OPAQUE_TAG_MAX macro constant, specifying the + * maximum size of an opaque datatype tag, was added in + * H5Tpublic.h. + * + */ H5_DLL herr_t H5Tset_tag(hid_t type, const char *tag); -H5_DLL char * H5Tget_tag(hid_t type); +/** + * \ingroup OPAQUE + * + * \brief Gets the tag associated with an opaque datatype + * + * \type_id{type} of an opaque datatype + * + * \return Returns a pointer to an allocated string if successful; otherwise + * returns NULL. + * + * \details H5Tget_tag() returns the tag associated with the opaque datatype + * \p type. + * + * \attention The tag is returned via a pointer to an allocated string, which + * the caller must free. + * + */ +H5_DLL char *H5Tget_tag(hid_t type); /* Querying property values */ -H5_DLL hid_t H5Tget_super(hid_t type); +/** + * \ingroup H5T + * + * \brief Returns the base datatype from which a datatype is derived + * + * \type_id{type} + * + * \return \hid_t{datatype} + * + * \details H5Tget_super() returns the base datatype from which the datatype + * \p type_id is derived. In the case of an enumeration type, the + * return value is an integer type. + * + * The datatype identifier returned by this function must be released + * with H5Tclose() when the identifier is no longer needed so that + * resource leaks will not develop. + * + */ +H5_DLL hid_t H5Tget_super(hid_t type); +/** + * \ingroup H5T + * + * \brief Returns a datatype class + * + * \type_id + * + * \return Returns the datatype class if successful; otherwise #H5T_NO_CLASS. + * + * \details H5Tget_class() returns the class of the datatype \p type_id. + * Valid class identifiers, as defined in H5Tpublic.h, are: + * \snippet this H5T_class_t_snip + * + * \note The library returns #H5T_STRING for both fixed-length and + * variable-length strings. + * + * \note Unsupported datatype: The time datatype class, #H5T_TIME, + * is not supported. If #H5T_TIME is used, the resulting data will + * be readable and modifiable only on the originating computing + * platform; it will not be portable to other platforms. + * + */ H5_DLL H5T_class_t H5Tget_class(hid_t type_id); -H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls); -H5_DLL size_t H5Tget_size(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Determines whether a datatype contains any datatypes of the given + * datatype class + * + * \type_id + * \param[in] cls Datatype class + * + * \return \htri_t + * + * \details H5Tdetect_class() determines whether the datatype specified in + * \p type_id contains any datatypes of the datatype class specified + * in \p dtype_class. + * + * This function is useful primarily in recursively examining all the + * fields and/or base types of compound, array, and variable-length + * datatypes. + * + * Valid class identifiers, as defined in H5Tpublic.h, are: + * \snippet this H5T_class_t_snip + * + * \since 1.6.0 + * + */ +H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls); +/** + * \ingroup H5T + * + * \brief Returns the size of a datatype + * + * \type_id + * + * \return Returns the size of the datatype in bytes if successful; otherwise, + * returns 0. + * + * \details H5Tget_size() returns the size of a datatype in bytes. + * \li For atomic datatypes, array datatypes, compound datatypes, and + * other datatypes of a constant size, the returned value is the + * size of the actual datatype in bytes. + * \li For variable-length string datatypes the returned value is + * the size of the pointer to the actual string, or \c sizeof(\c + * char \c *). This function does not return the size of actual + * variable-length string data. + * \li For variable-length sequence datatypes (see H5Tvlen_create()), + * the returned value is the size of the \p hvl_t struct, or \c + * sizeof(\p hvl_t). The \p hvl_t struct contains a pointer to the + * actual data and a size value. This function does not return the + * size of actual variable-length sequence data. + * + * \since 1.2.0 + * + * \see H5Tset_size() + * + * \todo Original has a reference to “Creating variable-length string datatypes”. + * \todo Create an example for H5Tget_size(). + * + */ +H5_DLL size_t H5Tget_size(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Returns the byte order of an atomic datatype + * + * \type_id + * + * \return Returns a byte order constant if successful; otherwise returns + * #H5T_ORDER_ERROR (-1) + * + * \details H5Tget_order() returns the byte order of an atomic datatype. + * Possible return values are: + * \snippet this H5T_order_t_snip + * Members of a compound datatype need not have the same byte + * order. If members of a compound datatype have more than one of + * little endian, big endian, or VAX byte order, H5Tget_order() will + * return #H5T_ORDER_MIXED for the compound datatype. A byte order of + * #H5T_ORDER_NONE will, however, be ignored; for example, if one or + * more members of a compound datatype have byte order #H5T_ORDER_NONE + * but all other members have byte order #H5T_ORDER_LE, H5Tget_order() + * will return #H5T_ORDER_LE for the compound datatype. + * + * \since 1.2.0 + * + */ H5_DLL H5T_order_t H5Tget_order(hid_t type_id); -H5_DLL size_t H5Tget_precision(hid_t type_id); -H5_DLL int H5Tget_offset(hid_t type_id); -H5_DLL herr_t H5Tget_pad(hid_t type_id, H5T_pad_t *lsb /*out*/, H5T_pad_t *msb /*out*/); -H5_DLL H5T_sign_t H5Tget_sign(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Returns the precision of an atomic datatype + * + * \type_id + * + * \return Returns the number of significant bits if successful; otherwise 0 + * + * \details H5Tget_precision() returns the precision of an atomic datatype + * (for example, integer or float) or a datatype whose base (parent) + * type is an atomic type (for example, array, enum and variable + * length). The precision is the number of significant bits which, + * unless padding is present, is 8 times larger than the value + * returned by H5Tget_size(). + * + * \since 1.2.0 + * + */ +H5_DLL size_t H5Tget_precision(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the bit offset of the first significant bit + * + * \type_id + * + * \return Returns an offset value if successful; otherwise returns a + * negative value. + * + * \details H5Tget_offset() retrieves the bit offset of the first significant + * bit. The significant bits of an atomic datum can be offset from the + * beginning of the memory for that datum by an amount of padding. The + * 'offset' property specifies the number of bits of padding that + * appear to the "right of" the value. That is, if we have a 32-bit + * datum with 16-bits of precision having the value 0x1122 then it + * will be laid out in memory as (from small byte address toward + * larger byte addresses): + * \code{.unparsed} + * 0: [ pad] [0x11] [0x22] [ pad] + * 1: [ pad] [0x22] [0x11] [ pad] + * 2: [0x11] [ pad] [ pad] [0x22] + * 3: [0x22] [ pad] [ pad] [0x11] + * \endcode + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_offset(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the padding type of the least and most-significant bit padding + * + * \type_id + * \param[out] lsb Buffer for the least-significant bit padding type + * \param[out] msb Buffer for the most-significant bit padding type + * + * \return \herr_t + * + * \details H5Tget_pad() retrieves the padding type of the least and + * most-significant bit padding. Valid padding types are: + * \snippet this H5T_pad_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Tget_pad(hid_t type_id, H5T_pad_t *lsb /*out*/, H5T_pad_t *msb /*out*/); +/** + * \ingroup ATOM + * + * \brief Retrieves the sign type for an integer type + * + * \type_id + * + * \return Returns a valid sign type if successful; otherwise #H5T_SGN_ERROR (-1) + * + * \details H5Tget_sign() retrieves the sign type for an integer type. + * Valid types are: + * \snippet this H5T_sign_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL H5T_sign_t H5Tget_sign(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves floating point datatype bit field information + * + * \type_id + * \param[out] spos Pointer to location to return floating-point sign bit + * \param[out] epos Pointer to location to return exponent bit-position + * \param[out] esize Pointer to location to return size of exponent in bits + * \param[out] mpos Pointer to location to return mantissa bit-position + * \param[out] msize Pointer to location to return size of mantissa in bits + * + * \return \herr_t + * + * \details H5Tget_fields() retrieves information about the locations of + * the various bit fields of a floating point datatype. The field + * positions are bit positions in the significant region of the + * datatype. Bits are numbered with the least significant bit number + * zero. Any (or even all) of the arguments can be null pointers. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tget_fields(hid_t type_id, size_t *spos /*out*/, size_t *epos /*out*/, size_t *esize /*out*/, size_t *mpos /*out*/, size_t *msize /*out*/); +/** + * \ingroup ATOM + * + * \brief Retrieves the exponent bias of a floating-point type + * + * \type_id + * + * \return Returns the bias if successful and 0, otherwise. + * + * \details H5Tget_ebias() retrieves the exponent bias of a floating-point type. + * + * \since 1.2.0 + * + */ H5_DLL size_t H5Tget_ebias(hid_t type_id); -H5_DLL H5T_norm_t H5Tget_norm(hid_t type_id); -H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id); -H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); -H5_DLL int H5Tget_nmembers(hid_t type_id); -H5_DLL char * H5Tget_member_name(hid_t type_id, unsigned membno); -H5_DLL int H5Tget_member_index(hid_t type_id, const char *name); -H5_DLL size_t H5Tget_member_offset(hid_t type_id, unsigned membno); +/** + * -------------------------------------------------------------------------- + * \ingroup ATOM + * + * \brief Retrieves mantissa normalization of a floating-point datatype + * + * \type_id + * + * \return Returns a valid normalization type if successful; otherwise + * returns #H5T_NORM_ERROR (-1) + * + * \details H5Tget_norm() retrieves the mantissa normalization of a + * floating-point datatype. Valid normalization types are: + * \snippet this H5T_norm_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL H5T_norm_t H5Tget_norm(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the internal padding type for unused bits in floating-point + * datatypes + * + * \type_id + * + * \return Returns a valid padding type if successful; otherwise returns + * #H5T_PAD_ERROR (-1). + * + * \details H5Tget_inpad() retrieves the internal padding type for unused + * bits in floating-point datatypes. Valid padding types are: + * \snippet this H5T_pad_t_snip + * + * \since 1.2.0 + * + */ +H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Retrieves the type of padding used for a string datatype + * + * \type_id + * + * \return Returns a valid string of the padding if successful; otherwise + * returns #H5T_STR_ERROR (-1) + * + * \details H5Tget_strpad() retrieves the type of padding used for a string + * datatype. + * + * The string padding type is set with H5Tset_strpad(). Possible + * values returned are: + * \str_pad_type + * + * \since 1.2.0 + * + */ +H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); +/** + * \ingroup COMPOUND + * + * \brief Retrieves the number of elements in a compound or enumeration datatype + * + * \type_id + * + * \return Returns the number of elements if successful; otherwise returns a + * negative value. + * + * \details H5Tget_nmembers() retrieves the number of fields in a compound + * datatype or the number of members of an enumeration datatype. + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_nmembers(hid_t type_id); +/** + * \ingroup COMPOUND + * + * \brief Retrieves the name of a compound or enumeration datatype member + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns a valid pointer to a string allocated with malloc() if + * successful; otherwise returns NULL. + * + * \details H5Tget_member_name() retrieves the name of a field of a compound + * datatype or an element of an enumeration datatype. + * + * The index of the target field or element is specified in \p + * member_no. Compound datatype fields and enumeration datatype + * elements are stored in no particular order with index values of + * 0 through N-1, where N is the value returned by H5Tget_nmembers(). + * + * The HDF5 library allocates a buffer to receive the name of + * the field. The caller must subsequently free the buffer with + * H5free_memory(). + * + * \since 1.2.0 + * + */ +H5_DLL char *H5Tget_member_name(hid_t type_id, unsigned membno); +/** + * \ingroup COMPOUND + * + * \brief Retrieves the index of a compound or enumeration datatype member + * + * \type_id + * \param[in] name Name of the field or member + * + * \return \herr_t + * + * \details H5Tget_member_index() retrieves the index of a field of a compound + * datatype or an element of an enumeration datatype. + * + * The name of the target field or element is specified by \p name. + * + * Fields are stored in no particular order with index values of 0 + * through N-1, where N is the value returned by H5Tget_nmembers() . + * + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_member_index(hid_t type_id, const char *name); +/** + * \ingroup COMPOUND + * + * \brief Retrieves the offset of a field of a compound datatype + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns the byte offset of the field if successful; otherwise + * returns 0 (zero). + * + * \details H5Tget_member_offset() retrieves the byte offset of the beginning + * of a field within a compound datatype with respect to the beginning + * of the compound datatype datum. + * + * Note that zero is a valid offset and that this function will fail + * only if a call to H5Tget_member_class() fails with the same arguments. + * + * \version 1.6.4 \p member_no parameter type changed to unsigned. + * + * \since 1.2.0 + * + */ +H5_DLL size_t H5Tget_member_offset(hid_t type_id, unsigned membno); +/** + * \ingroup COMPOUND + * + * \brief Returns datatype class of compound datatype member + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns the datatype class, a non-negative value, if successful; + * otherwise returns a negative value. + * + * \details Given a compound datatype, \p dtype_id, H5Tget_member_class() + * returns the datatype class of the member specified by \p member_no. + * + * Valid class identifiers, as defined in H5Tpublic.h, are: + * \snippet this H5T_class_t_snip + * + * \since 1.2.0 + * + */ H5_DLL H5T_class_t H5Tget_member_class(hid_t type_id, unsigned membno); -H5_DLL hid_t H5Tget_member_type(hid_t type_id, unsigned membno); -H5_DLL herr_t H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/); -H5_DLL H5T_cset_t H5Tget_cset(hid_t type_id); -H5_DLL htri_t H5Tis_variable_str(hid_t type_id); -H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); +/** + * \ingroup COMPOUND + * + * \brief Returns the datatype of the specified member + * + * \type_id + * \param[in] membno Zero-based index of the field or element + * + * \return Returns the identifier of a copy of the datatype of the field if + * successful; otherwise returns a negative value. + * + * \details H5Tget_member_type() returns the datatype of the specified member. + * The caller should invoke H5Tclose() to release resources associated + * with the type. + * + * \version 1.6.4 \p membno parameter type changed to unsigned. + * + * \since 1.2.0 + * + */ +H5_DLL hid_t H5Tget_member_type(hid_t type_id, unsigned membno); +/** + * \ingroup ENUM + * + * \brief Returns the value of an enumeration datatype member + * + * \type_id + * \param[in] membno Number of the enumeration datatype member + * \param[out] value Buffer for the value of the enumeration datatype member + * + * \return \herr_t + * + * \details H5Tget_member_value() returns the value of the enumeration datatype + * member \p member_no. + * + * The member value is returned in a user-supplied buffer pointed to + * by \p value. Values returned in \p value will be of the enumerated + * type’s base type, that is, the datatype used by H5Tenum_create() + * when the enumerated type was created. + * + * The value buffer must be at least large enough to hold a value + * of that base type. If the size is unknown, you can determine it + * with H5Tget_size(). + * + * \since 1.2.0 + * + */ +H5_DLL herr_t H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/); +/** + * \ingroup ATOM + * + * \brief Retrieves the character set type of a string datatype + * + * \type_id + * + * \return Returns a valid character set type if successful; otherwise + * #H5T_CSET_ERROR (-1). + * + * \details H5Tget_cset() retrieves the character set type of a string datatype. + * Valid character set types are: + * \csets + * + * \since 1.2.0 + * + */ +H5_DLL H5T_cset_t H5Tget_cset(hid_t type_id); +/** + * \ingroup ATOM + * + * \brief Determines whether datatype is a variable-length string + * + * \type_id + * + * \return Returns: + * \li a positive value if the specified datatype is a variable-length + * string + * \li 0 if the specified datatype is not a variable-length string + * \li a negative value when the function fails + * + * \details H5Tis_variable_str() determines whether the datatype identified + * by \p dtype_id is a variable-length string. + * + * This function can be used to distinguish between fixed and + * variable-length string datatypes. + * + * \since 1.6.0 + * + */ +H5_DLL htri_t H5Tis_variable_str(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Returns the native datatype identifier of a specified datatype + * + * \type_id + * \param[in] direction Direction of search + * + * \return \hid_t{native datatype} + * + * \details H5Tget_native_type() returns the equivalent native datatype + * identifier for the datatype specified by \p type_id. + * + * H5Tget_native_type() is designed primarily to facilitate use of + * the H5Dread() function, for which users otherwise must undertake a + * multi-step process to determine the native datatype of a dataset + * prior to reading it into memory. This function can be used for + * the following purposes: + * + * \li To determine the native datatype of an atomic datatype + * \li To determine the base datatype of an array, enumerated, or + * variable-length datatype + * \li To determine the native atomic datatypes of the individual + * components of a compound datatype + * + * For example, if \p type_id is a compound datatype, the returned + * datatype identifier will be for a similar compound datatype with + * each element converted to the corresponding native datatype; + * nested compound datatypes will be unwound. If \p type_id is an + * array, the returned datatype identifier will be for the native + * datatype of a single array element. + * + * H5Tget_native_type() selects the first matching native datatype + * from the following list: + * + * \li #H5T_NATIVE_CHAR + * \li #H5T_NATIVE_SHORT + * \li #H5T_NATIVE_INT + * \li #H5T_NATIVE_LONG + * \li #H5T_NATIVE_LLONG + * + * \li #H5T_NATIVE_UCHAR + * \li #H5T_NATIVE_USHORT + * \li #H5T_NATIVE_UINT + * \li #H5T_NATIVE_ULONG + * \li #H5T_NATIVE_ULLONG + * + * \li #H5T_NATIVE_FLOAT + * \li #H5T_NATIVE_DOUBLE + * \li #H5T_NATIVE_LDOUBLE + * + * \li #H5T_NATIVE_B8 + * \li #H5T_NATIVE_B16 + * \li #H5T_NATIVE_B32 + * \li #H5T_NATIVE_B64 + * + * The direction parameter indicates the order in which the library + * searches for a native datatype match. Valid values for direction + * are as follows: + * \snippet this H5T_direction_t_snip + * + * H5Tget_native_type() is designed primarily for use with integer, + * floating point, and bitfield datatypes. String, time, opaque, and + * reference datatypes are returned as a copy of dtype_id. See above + * for compound, array, enumerated, and variable-length datatypes. + * + * The identifier returned by H5Tget_native_type() should eventually + * be closed by calling H5Tclose() to release resources. + * + * \note Please note that a datatype is actually an object + * identifier or handle returned from opening the datatype. It + * is not persistent and its value can be different from one HDF5 + * session to the next. + * + * \note H5Tequal() can be used to compare datatypes. + * + * \note HDF5 High Level APIs that may also be of interest are: H5LTdtype_to_text() + * creates a text description of a datatype. H5LTtext_to_dtype() creates an + * HDF5 datatype given a text description. + * + * \since 1.6.0 + * + */ +H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); /* Setting property values */ +/** + * \ingroup H5T + * + * \brief Sets size for a datatype. + * + * \type_id + * \param[in] size New datatype size is bytes or #H5T_VARIABLE + * + * \return \herr_t + * + * \details H5Tset_size() sets the total size, \p size, in bytes, for a + * datatype. + * + * \p size must have a positive value, unless it is passed in as + * #H5T_VARIABLE and the datatype is a string datatype. + * + * \li Numeric datatypes: If the datatype is atomic and the size + * is decreased so that significant bits of the datatype extend + * beyond the edge of the new size, then the offset property of the + * datatype is decreased toward zero. If the offset becomes zero + * and the significant bits of the datatype still hang over the edge + * of the new size, then the number of significant bits is decreased. + * + * \li String or character datatypes: The size set for a string + * datatype should include space for the null-terminator character, + * otherwise it will not be stored on (or retrieved from) + * disk. Adjusting the size of a string automatically sets the + * precision to \p 8*size. + * + * \li Variable-length string datatypes: If \p dtype_id is a + * variable-length string, size must normally be set to #H5T_VARIABLE. + * + * \li Compound datatypes: This function may be used to increase or + * decrease the size of a compound datatype, but the function will + * fail if the new size is too small to accommodate all member fields. + * + * \li Ineligible datatypes: This function cannot be used with + * enumerated datatypes (#H5T_ENUM), array datatypes (#H5T_ARRAY), + * variable-length array datatypes (#H5T_VLEN), or reference datatypes + * (#H5T_REFERENCE). + * + * \since 1.2.0 + * + * \see H5Tget_size() + * + *\todo Create an example for H5Tset_size(). + *\todo Original has a reference to “Creating variable-length string datatypes”. + * + */ H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size); +/** + * \ingroup ATOM + * + * \brief Sets the byte order of a datatype + * + * \type_id + * \param[in] order Byte order constant + * + * \return \herr_t + * + * \details H5Tset_order() sets the byte order of a datatype.\n + * Byte order can currently be set to any of the following: + * \snippet this H5T_order_t_snip + * #H5T_ORDER_MIXED (3) is a valid value for order only when + * returned by the function H5Tget_order(); it cannot be set with + * H5Tset_order(). + * + * #H5T_ORDER_NONE (4) is a valid value for order, but it has no + * effect. It is valid only for fixed-length strings and object and + * region references and specifies “no particular order.” + * + * The byte order of a derived datatype is initially the same as + * that of the parent type, but can be changed with H5Tset_order(). + * + * This function cannot be used with a datatype after it has been + * committed. + * + * \note Special considerations: + * \li ENUM datatypes: Byte order must be set before any member on + * an ENUM is defined. + * \li Compound datatypes: Byte order is set individually on each member + * of a compound datatype; members of a compound datatype need not + * have the same byte order. + * \li Opaque datatypes: Byte order can be set but has no effect. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_order(hid_t type_id, H5T_order_t order); +/** + * \ingroup ATOM + * + * \brief Sets the precision of an atomic datatype + * + * \type_id + * \param[in] prec Number of bits of precision for datatype + * + * \return \herr_t + * + * \details H5Tset_precision() sets the precision of an atomic datatype. The + * precision is the number of significant bits which, unless + * padding is present, is 8 times larger than the value returned + * by H5Tget_size(). + * + * If the precision is increased then the offset is decreased and + * then the size is increased to insure that significant bits do not + * "hang over" the edge of the datatype. + * + * Changing the precision of an #H5T_STRING automatically changes + * the size as well. The precision must be a multiple of 8. + * + * When decreasing the precision of a floating point type, set the + * locations and sizes of the sign, mantissa, and exponent fields + * first. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_precision(hid_t type_id, size_t prec); +/** + * \ingroup ATOM + * + * \brief Sets the bit offset of the first significant bit + * + * \type_id + * \param[in] offset Offset of first significant bit + * + * \return \herr_t + * + * \details H5Tset_offset() sets the bit offset of the first significant + * bit. The significant bits of an atomic datum can be offset from + * the beginning of the memory for that datum by an amount of + * padding. The offset property specifies the number of bits of + * padding that appear “to the right of” the value. That is, + * if we have a 32-bit datum with 16-bits of precision having the + * value 0x1122, then it will be laid out in memory as (from small + * byte address toward larger byte addresses): + * \code{.unparsed} + * 0: [ pad] [0x11] [0x22] [ pad] + * 1: [ pad] [0x22] [0x11] [ pad] + * 2: [0x11] [ pad] [ pad] [0x22] + * 3: [0x22] [ pad] [ pad] [0x11] + * \endcode + * If the offset is incremented then the total size is incremented + * also if necessary to prevent significant bits of the value from + * hanging over the edge of the datatype. + * + * The offset of an #H5T_STRING cannot be set to anything but zero. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_offset(hid_t type_id, size_t offset); +/** + * \ingroup ATOM + * + * \brief Sets the least and most-significant bits padding types + * + * \type_id + * \param[in] lsb Padding type for least-significant bits + * \param[in] msb Padding type for most-significant bits + * + * \return \herr_t + * + * \details H5Tset_pad() sets the least and most-significant bits padding types. + * Available values are: + * \padding_type + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_pad(hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb); +/** + * \ingroup ATOM + * + * \brief Sets the sign property for an integer type + * + * \type_id + * \param[in] sign Sign type + * + * \return \herr_t + * + * \details H5Tset_sign() sets the sign property for an integer type: + * \sign_prop + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_sign(hid_t type_id, H5T_sign_t sign); +/** + * \ingroup ATOM + * + * \brief Sets locations and sizes of floating point bit fields + * + * \type_id + * \param[in] spos Sign position, i.e., the bit offset of the floating-point + * sign bit + * \param[in] epos Exponent bit position + * \param[in] esize Size of exponent in bits + * \param[in] mpos Mantissa bit position + * \param[in] msize Size of mantissa in bits + * + * \return \herr_t + * + * \details H5Tset_fields() sets the locations and sizes of the various + * floating-point bit fields. The field positions are bit positions + * in the significant region of the datatype. Bits are numbered with + * the least significant bit number zero. + * + * Fields are not allowed to extend beyond the number of bits of + * precision, nor are they allowed to overlap with one another. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_fields(hid_t type_id, size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize); +/** + * \ingroup ATOM + * + * \brief Sets the exponent bias of a floating-point type + * + * \type_id + * \param[in] ebias Exponent bias value + * + * \return \herr_t + * + * \details H5Tset_ebias() sets the exponent bias of a floating-point type. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_ebias(hid_t type_id, size_t ebias); +/** + * \ingroup ATOM + * + * \brief Sets the mantissa normalization of a floating-point datatype + * + * \type_id + * \param[in] norm Mantissa normalization type + * + * \return \herr_t + * + * \details H5Tset_norm() sets the mantissa normalization of a floating-point + * datatype. Valid normalization types are: + * \snippet this H5T_norm_t_snip + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_norm(hid_t type_id, H5T_norm_t norm); +/** + * \ingroup ATOM + * + * \brief Fills unused internal floating-point bits + * + * \type_id + * \param[in] pad Padding type + * + * \return \herr_t + * + * \details H5Tset_inpad() If any internal bits of a floating point-type are + * unused (that is, those significant bits which are not part of the + * sign, exponent, or mantissa), then H5Tset_inpad() will be filled + * according to the value of the padding value property inpad. Valid + * padding types are: + * \snippet this H5T_pad_t_snip + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_inpad(hid_t type_id, H5T_pad_t pad); +/** + * \ingroup ATOM + * + * \brief Sets character set to be used in a string or character datatype + * + * \type_id + * \param[in] cset Character set type + * + * \return \herr_t + * + * \details H5Tset_cset() sets the character set to be used in a dataset with + * a string or character datatype. + * + * Valid values for cset include the following: + * \csets + * For example, if the character set for the datatype \p type_id is set + * to #H5T_CSET_UTF8, string or character data of datatype dtype_id + * will be encoded using the UTF-8 Unicode character set. + * + * ASCII and UTF-8 Unicode are the only currently supported character + * encodings. Extended ASCII encodings (for example, ISO 8859) are + * not supported. This encoding policy is not enforced by the HDF5 + * library. Using encodings other than ASCII and UTF-8 can lead to + * compatibility and usability problems. + * + * Note that H5Tset_cset() sets the character set for a character or + * string datatype while H5Pset_char_encoding() sets the character + * set used for an HDF5 link or attribute name. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset); +/** + * \ingroup ATOM + * + * \brief Defines the type of padding used for character strings + * + * \type_id + * \param[in] strpad String padding type + * + * \return \herr_t + * + * \details H5Tset_strpad() defines the type of padding used for a string + * datatype. + * + * The method used to store character strings differs with the + * programming language. C usually null terminates strings while + * Fortran left-justifies and space-pads strings. + * + * Valid values of \p strpad are as follows: + * \str_pad_type + * When converting from a longer string to a shorter string, the + * behavior is as follows. If the shorter string is #H5T_STR_NULLPAD + * or #H5T_STR_SPACEPAD, then the string is simply truncated. If + * the short string is #H5T_STR_NULLTERM, it is truncated and a null + * terminator is appended. + * + * When converting from a shorter string to a longer string, the + * longer string is padded on the end by appending nulls or spaces. + * + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad); /* Type conversion database */ +/** + * \ingroup CONV + * + * \brief Registers a datatype conversion function + * + * \param[in] pers Conversion function type + * \param[in] name Name displayed in diagnostic output + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] func Function to convert between source and destination datatypes + * + * \return \herr_t + * + * \details H5Tregister() registers a hard or soft conversion function for a + * datatype conversion path. The parameter \p pers indicates whether a + * conversion function is hard (#H5T_PERS_HARD) or soft + * (#H5T_PERS_SOFT). User-defined functions employing compiler casting + * are designated as \Emph{hard}; other user-defined conversion + * functions registered with the HDF5 library (with H5Tregister() ) + * are designated as \Emph{soft}. The HDF5 library also has its own + * hard and soft conversion functions. + * + * A conversion path can have only one hard function. When type is + * #H5T_PERS_HARD, \p func replaces any previous hard function. + * + * When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the + * end of the master soft list and replaces the soft function in all + * applicable existing conversion paths. Soft functions are used when + * determining which conversion function is appropriate for this path. + * + * The \p name is used only for debugging and should be a short + * identifier for the function. + * + * The path is specified by the source and destination datatypes \p + * src_id and \p dst_id. For soft conversion functions, only the class + * of these types is important. + * + * The type of the conversion function pointer is declared as: + * \snippet this H5T_conv_t_snip + * + * The \ref H5T_cdata_t \c struct is declared as: + * \snippet this H5T_cdata_t_snip + * + * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function: + * the \c nelmts parameter type changed to size_t. + * + */ H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); +/** + * \ingroup CONV + * + * \brief Removes a conversion function + * + * \param[in] pers Conversion function type + * \param[in] name Name displayed in diagnostic output + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] func Function to convert between source and destination datatypes + * + * \return \herr_t + * + * \details H5Tunregister() removes a conversion function matching criteria + * such as soft or hard conversion, source and destination types, and + * the conversion function. + * + * If a user is trying to remove a conversion function he registered, + * all parameters can be used. If he is trying to remove a library’s + * default conversion function, there is no guarantee the \p name and + * \p func parameters will match the user’s chosen values. Passing in + * some values may cause this function to fail. A good practice is to + * pass in NULL as their values. + * + * All parameters are optional. The missing parameters will be used to + * generalize the search criteria. + * + * The conversion function pointer type declaration is described in + * H5Tregister(). + * + * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function: + * the \c nelmts parameter type changed to size_t. + * + */ H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); +/** + * \ingroup CONV + * + * \brief Finds a conversion function + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[out] pcdata Pointer to type conversion data + * + * \return Returns a pointer to a suitable conversion function if successful. + * Otherwise returns NULL. + * + * \details H5Tfind() finds a conversion function that can handle a conversion + * from type \p src_id to type \p dst_id. The \p pcdata argument is a + * pointer to a pointer to type conversion data which was created and + * initialized by the soft type conversion function of this path when + * the conversion function was installed on the path. + * + */ H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata); -H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); -H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background, - hid_t plist_id); -H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf); +/** + * \ingroup CONV + * + * \brief Check whether the library’s default conversion is hard conversion + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * + * \return \htri_t + * + * \details H5Tcompiler_conv() determines whether the library’s conversion + * function from type \p src_id to type \p dst_id is a compiler (hard) + * conversion or not. A compiler conversion uses compiler’s casting; a + * library (soft) conversion uses the library’s own conversion + * function. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); +/** + * -------------------------------------------------------------------------- + * \ingroup CONV + * + * \brief Converts data from one specified datatype to another + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] nelmts Size of array \p buf + * \param[in,out] buf Array containing pre- and post-conversion values + * \param[in] background Optional background buffer + * \dxpl_id{plist_id} + * + * \return \herr_t + * + * \details H5Tconvert() converts \p nelmts elements from a source datatype, + * specified by \p src_id, to a destination datatype, \p dst_id. The + * source elements are packed in \p buf and on return the destination + * elements will be packed in \p buf. That is, the conversion is + * performed in place. + * + * The optional background buffer is for use with compound datatypes. + * It is an array of \p nelmts values for the destination datatype + * which can then be merged with the converted values to recreate the + * compound datatype. For instance, background might be an array of + * structs with the \c a and \c b fields already initialized and the + * conversion of buf supplies the \c c and \c d field values. + * + * The parameter \p plist_id contains the dataset transfer property list + * identifier which is passed to the conversion functions. As of + * Release 1.2, this parameter is only used to pass along the + * variable-length datatype custom allocation information. + * + * \note H5Tconvert() will not resize the buffer \p buf; it must be large + * enough to hold the larger of the input and output data. + * + * \version 1.6.3 \p nelmts parameter type changed to size_t. + * \version 1.4.0 \p nelmts parameter type changed to \ref hsize_t. + * + */ +H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background, + hid_t plist_id); +/** + * \ingroup VLEN + * + * \brief Reclaims the variable length (VL) datatype memory buffers + * + * \type_id + * \space_id + * \dxpl_id{plist_id} used to create the buffer + * \param[in] buf Pointer to the buffer to be reclaimed + * + * \return \herr_t + * + * \details H5Treclaim() reclaims memory buffers created to store VL datatypes. + * It only frees the variable length data in the selection defined in + * the dataspace specified by \p space_id. The dataset transfer + * property list \p plist_id is required to find the correct + * allocation and/or free methods for the variable-length data in the + * buffer. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf); /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -598,11 +2882,140 @@ H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void /* Typedefs */ /* Function prototypes */ +/** + * \ingroup H5T + * + * \brief Commits a transient datatype to a file, creating a new named datatype + * + * \fg_loc_id + * \param[in] name Name given to committed datatype + * \param[in] type_id Identifier of datatype to be committed + * + * \return \herr_t + * + * \deprecated This function has been renamed from H5Tcommit() and is + * deprecated in favor of the macro #H5Tcommit or the function + * H5Tcommit2(). + * + * \details H5Tcommit1() commits the transient datatype (not immutable) to + * a file, turning it into a named datatype. + * + * The datatype \p dtype_id is committed as a named datatype at the + * location \p loc_id, which is either a file or group identifier, + * with the name \p name. + * + * \p name can be a relative path based at \p loc_id or an absolute + * path from the root of the file. Use of this function requires + * that any intermediate groups specified in the path already exist. + * + * As is the case for any object in a group, the length of the name + * of a named datatype is not limited. + * + * See H5Tcommit_anon() for a discussion of the differences between + * H5Tcommit() and H5Tcommit_anon(). + * + * This function will not accept a datatype that cannot actually + * hold data. This currently includes compound datatypes with no + * fields and enumerated datatypes with no members. + * + * \version 1.8.7 Function modified in this release to reject datatypes that + * will not accommodate actual data, such as a compound datatype with + * no fields or an enumerated datatype with no members. + * \version 1.8.0 C function H5Tcommit() renamed to H5Tcommit1() and deprecated + * in this release. + * \since 1.2.0 + * + */ H5_DLL herr_t H5Tcommit1(hid_t loc_id, const char *name, hid_t type_id); -H5_DLL hid_t H5Topen1(hid_t loc_id, const char *name); -H5_DLL hid_t H5Tarray_create1(hid_t base_id, int ndims, const hsize_t dim[/* ndims */], - const int perm[/* ndims */]); -H5_DLL int H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]); +/** + * \ingroup H5T + * + * \brief Opens a named datatype + * + * \fg_loc_id + * \param[in] name A datatype name, defined within the specified file or group + * + * \return \herr_t + * + * \deprecated This function has been renamed from H5Topen() and is + * deprecated in favor of the macro #H5Topen or the function + * H5Topen2(). + * + * \details H5Topen1() opens a named datatype at the location specified by + * \p loc_id and returns an identifier for the datatype. \p loc_id + * can be either a file or group identifier. The identifier should + * eventually be closed by calling H5Tclose() to release resources. + * + * \version 1.8.0 Function H5Topen() renamed to H5Topen1() and deprecated in + * this release. + * + * \since 1.2.0 + * + */ +H5_DLL hid_t H5Topen1(hid_t loc_id, const char *name); +/** + * \ingroup ARRAY + * + * \brief Creates an array datatype object + * + * \param[in] base_id Datatype identifier for the array base datatype + * \param[in] ndims Rank of the array + * \param[in] dim Size of each array dimension + * \param[in] perm Dimension permutation (Currently not implemented.) + * + * \return \hid_t{array datatype} + * + * \deprecated This function has been renamed from H5Tarray_create() and is + * deprecated in favor of the macro #H5Tarray_create or the function + * H5Tarray_create2(). + * + * \details H5Tarray_create1() creates a new array datatype object.\n\n + * \p base_id is the datatype of every element of the array, i.e., + * of the number at each position in the array. + * + * \p rank is the number of dimensions and the size of each dimension + * is specified in the array dims. The value of rank is currently + * limited to #H5S_MAX_RANK and must be greater than 0 (zero). All + * dimension sizes specified in dims must be greater than 0 (zero). + * + * The array \p perm is designed to contain the dimension permutation, + * i.e. C versus FORTRAN array order. (The parameter perm is + * currently unused and is not yet implemented.) + * + * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1() + * and deprecated in this release. + * \since 1.4.0 + * + */ +H5_DLL hid_t H5Tarray_create1(hid_t base_id, int ndims, const hsize_t dim[/* ndims */], + const int perm[/* ndims */]); +/** + * \ingroup ARRAY + * + * \brief Retrieves sizes of array dimensions + * + * \type_id + * \param[out] dims Sizes of array dimensions + * \param[out] perm Dimension permutations (This parameter is not used.) + * + * \return Returns the non-negative number of dimensions of the array type + * if successful; otherwise, returns a negative value. + * + * \deprecated This function has been renamed from H5Tget_array_dims() and is + * deprecated in favor of the macro #H5Tget_array_dims or the + * function H5Tget_array_dims2(). + * + * \details H5Tget_array_dims1() returns the sizes of the dimensions and + * the dimension permutations of the specified array datatype object. + * + * The sizes of the dimensions are returned in the array \p dims. + * + * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1() + * and deprecated in this release. + * \since 1.2.0 + * + */ +H5_DLL int H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Tref.c b/src/H5Tref.c index 7092a71..c71724f 100644 --- a/src/H5Tref.c +++ b/src/H5Tref.c @@ -513,7 +513,7 @@ H5T__ref_mem_read(H5VL_object_t H5_ATTR_UNUSED *src_file, const void *src_buf, s /* Memory-to-memory conversion to support vlen conversion */ if (NULL == dst_file) { - HDmemcpy(dst_buf, src_buf, dst_size); + H5MM_memcpy(dst_buf, src_buf, dst_size); HGOTO_DONE(ret_value); } @@ -602,7 +602,7 @@ H5T__ref_mem_write(H5VL_object_t *src_file, const void *src_buf, size_t src_size /* Memory-to-memory conversion to support vlen conversion */ if (NULL == src_file) { - HDmemcpy(dst_buf, src_buf, src_size); + H5MM_memcpy(dst_buf, src_buf, src_size); HGOTO_DONE(ret_value); } @@ -650,6 +650,7 @@ H5T__ref_mem_write(H5VL_object_t *src_file, const void *src_buf, size_t src_size /* Pass the correct encoding version for the selection depending on the * file libver bounds, this is later retrieved in H5S hyper decode */ H5CX_set_libver_bounds(src_f); + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case H5R_OBJECT2: case H5R_ATTR: diff --git a/src/H5Tvlen.c b/src/H5Tvlen.c index 0fdd113..2d373d1 100644 --- a/src/H5Tvlen.c +++ b/src/H5Tvlen.c @@ -626,7 +626,7 @@ H5T__vlen_mem_str_getptr(void *_vl) #ifdef H5_NO_ALIGNMENT_RESTRICTIONS char *s = *(char **)_vl; /* Pointer to the user's string information */ #else - char * s = NULL; /* Pointer to the user's string information */ + char *s = NULL; /* Pointer to the user's string information */ #endif FUNC_ENTER_STATIC_NOERR @@ -717,7 +717,7 @@ H5T__vlen_mem_str_read(H5VL_object_t H5_ATTR_UNUSED *file, void *_vl, void *buf, #ifdef H5_NO_ALIGNMENT_RESTRICTIONS char *s = *(char **)_vl; /* Pointer to the user's string information */ #else - char *s; /* Pointer to the user's string information */ + char *s; /* Pointer to the user's string information */ #endif FUNC_ENTER_STATIC_NOERR diff --git a/src/H5UCprivate.h b/src/H5UCprivate.h index 2d6f40f..2687318 100644 --- a/src/H5UCprivate.h +++ b/src/H5UCprivate.h @@ -59,4 +59,4 @@ typedef struct H5UC_t { H5_DLL H5UC_t *H5UC_create(void *s, H5UC_free_func_t free_func); H5_DLL herr_t H5UC_decr(H5UC_t *rc); -#endif /* _H5RSprivate_H */ +#endif /* _H5UCprivate_H */ @@ -85,7 +85,7 @@ H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id) hid_t ret_value = H5I_INVALID_HID; /* Return value */ FUNC_ENTER_API(H5I_INVALID_HID) - H5TRACE2("i", "*xi", cls, vipl_id); + H5TRACE2("i", "*#i", cls, vipl_id); /* Check arguments */ if (!cls) @@ -757,13 +757,13 @@ done: *--------------------------------------------------------------------------- */ herr_t -H5VLretrieve_lib_state(void **state) +H5VLretrieve_lib_state(void **state /*out*/) { herr_t ret_value = SUCCEED; /* Return value */ /* Must use this, to avoid modifying the API context stack in FUNC_ENTER */ FUNC_ENTER_API_NOINIT - H5TRACE1("e", "**x", state); + H5TRACE1("e", "x", state); /* Check args */ if (NULL == state) diff --git a/src/H5VLcallback.c b/src/H5VLcallback.c index 6abbf8d..460a170 100644 --- a/src/H5VLcallback.c +++ b/src/H5VLcallback.c @@ -29,7 +29,7 @@ #include "H5private.h" /* Generic Functions */ #include "H5Eprivate.h" /* Error handling */ -#include "H5Fprivate.h" /* File access */ +#include "H5Fprivate.h" /* File access */ #include "H5Iprivate.h" /* IDs */ #include "H5MMprivate.h" /* Memory management */ #include "H5Pprivate.h" /* Property lists */ @@ -263,13 +263,13 @@ done: *--------------------------------------------------------------------------- */ herr_t -H5VLget_cap_flags(hid_t connector_id, unsigned *cap_flags) +H5VLget_cap_flags(hid_t connector_id, unsigned *cap_flags /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE2("e", "i*Iu", connector_id, cap_flags); + H5TRACE2("e", "ix", connector_id, cap_flags); /* Check args */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -294,13 +294,13 @@ done: *--------------------------------------------------------------------------- */ herr_t -H5VLget_value(hid_t connector_id, H5VL_class_value_t *value) +H5VLget_value(hid_t connector_id, H5VL_class_value_t *value /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE2("e", "i*VC", connector_id, value); + H5TRACE2("e", "ix", connector_id, value); /* Check args */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -599,12 +599,12 @@ done: *--------------------------------------------------------------------------- */ herr_t -H5VLconnector_str_to_info(const char *str, hid_t connector_id, void **info) +H5VLconnector_str_to_info(const char *str, hid_t connector_id, void **info /*out*/) { herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE3("e", "*si**x", str, connector_id, info); + H5TRACE3("e", "*six", str, connector_id, info); /* Call internal routine */ if (H5VL__connector_str_to_info(str, connector_id, info) < 0) @@ -698,13 +698,13 @@ done: *--------------------------------------------------------------------------- */ herr_t -H5VLget_wrap_ctx(void *obj, hid_t connector_id, void **wrap_ctx) +H5VLget_wrap_ctx(void *obj, hid_t connector_id, void **wrap_ctx /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE3("e", "*xi**x", obj, connector_id, wrap_ctx); + H5TRACE3("e", "*xix", obj, connector_id, wrap_ctx); /* Check args and get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -994,14 +994,15 @@ done: */ void * H5VLattr_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, - hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t dxpl_id, void **req) + hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t dxpl_id, + void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE10("*x", "*x*xi*siiiii**x", obj, loc_params, connector_id, name, type_id, space_id, acpl_id, - aapl_id, dxpl_id, req); + H5TRACE10("*x", "*x*#i*siiiiix", obj, loc_params, connector_id, name, type_id, space_id, acpl_id, aapl_id, + dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -1097,13 +1098,13 @@ done: */ void * H5VLattr_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, - hid_t aapl_id, hid_t dxpl_id, void **req) + hid_t aapl_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("*x", "*x*xi*sii**x", obj, loc_params, connector_id, name, aapl_id, dxpl_id, req); + H5TRACE7("*x", "*x*#i*siix", obj, loc_params, connector_id, name, aapl_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -1194,13 +1195,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLattr_read(void *obj, hid_t connector_id, hid_t mem_type_id, void *buf, hid_t dxpl_id, void **req) +H5VLattr_read(void *obj, hid_t connector_id, hid_t mem_type_id, void *buf, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xii*xi**x", obj, connector_id, mem_type_id, buf, dxpl_id, req); + H5TRACE6("e", "*xii*xix", obj, connector_id, mem_type_id, buf, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -1292,13 +1293,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLattr_write(void *obj, hid_t connector_id, hid_t mem_type_id, const void *buf, hid_t dxpl_id, void **req) +H5VLattr_write(void *obj, hid_t connector_id, hid_t mem_type_id, const void *buf, hid_t dxpl_id, + void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xii*xi**x", obj, connector_id, mem_type_id, buf, dxpl_id, req); + H5TRACE6("e", "*xii*xix", obj, connector_id, mem_type_id, buf, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -1398,14 +1400,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLattr_get(void *obj, hid_t connector_id, H5VL_attr_get_t get_type, hid_t dxpl_id, void **req, +H5VLattr_get(void *obj, hid_t connector_id, H5VL_attr_get_t get_type, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVai**xx", obj, connector_id, get_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVaixx", obj, connector_id, get_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -1508,13 +1510,13 @@ done: */ herr_t H5VLattr_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_attr_specific_t specific_type, hid_t dxpl_id, void **req, va_list arguments) + H5VL_attr_specific_t specific_type, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("e", "*x*xiVbi**xx", obj, loc_params, connector_id, specific_type, dxpl_id, req, arguments); + H5TRACE7("e", "*x*#iVbixx", obj, loc_params, connector_id, specific_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -1616,14 +1618,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLattr_optional(void *obj, hid_t connector_id, H5VL_attr_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments) +H5VLattr_optional(void *obj, hid_t connector_id, H5VL_attr_optional_t opt_type, hid_t dxpl_id, + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVsi**xx", obj, connector_id, opt_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVsixx", obj, connector_id, opt_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -1707,13 +1709,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLattr_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req) +H5VLattr_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xii**x", obj, connector_id, dxpl_id, req); + H5TRACE4("e", "*xiix", obj, connector_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -1813,13 +1815,13 @@ done: void * H5VLdataset_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t lcpl_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id, hid_t dxpl_id, - void **req) + void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE11("*x", "*x*xi*siiiiii**x", obj, loc_params, connector_id, name, lcpl_id, type_id, space_id, + H5TRACE11("*x", "*x*#i*siiiiiix", obj, loc_params, connector_id, name, lcpl_id, type_id, space_id, dcpl_id, dapl_id, dxpl_id, req); /* Check args and get class pointer */ @@ -1916,13 +1918,13 @@ done: */ void * H5VLdataset_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, - hid_t dapl_id, hid_t dxpl_id, void **req) + hid_t dapl_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("*x", "*x*xi*sii**x", obj, loc_params, connector_id, name, dapl_id, dxpl_id, req); + H5TRACE7("*x", "*x*#i*siix", obj, loc_params, connector_id, name, dapl_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -2017,13 +2019,13 @@ done: */ herr_t H5VLdataset_read(void *obj, hid_t connector_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, - hid_t dxpl_id, void *buf, void **req) + hid_t dxpl_id, void *buf, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE8("e", "*xiiiii*x**x", obj, connector_id, mem_type_id, mem_space_id, file_space_id, dxpl_id, buf, + H5TRACE8("e", "*xiiiii*xx", obj, connector_id, mem_type_id, mem_space_id, file_space_id, dxpl_id, buf, req); /* Check args and get class pointer */ @@ -2119,13 +2121,13 @@ done: */ herr_t H5VLdataset_write(void *obj, hid_t connector_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, - hid_t dxpl_id, const void *buf, void **req) + hid_t dxpl_id, const void *buf, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE8("e", "*xiiiii*x**x", obj, connector_id, mem_type_id, mem_space_id, file_space_id, dxpl_id, buf, + H5TRACE8("e", "*xiiiii*xx", obj, connector_id, mem_type_id, mem_space_id, file_space_id, dxpl_id, buf, req); /* Check args and get class pointer */ @@ -2226,14 +2228,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLdataset_get(void *obj, hid_t connector_id, H5VL_dataset_get_t get_type, hid_t dxpl_id, void **req, +H5VLdataset_get(void *obj, hid_t connector_id, H5VL_dataset_get_t get_type, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVci**xx", obj, connector_id, get_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVcixx", obj, connector_id, get_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -2336,13 +2338,13 @@ done: */ herr_t H5VLdataset_specific(void *obj, hid_t connector_id, H5VL_dataset_specific_t specific_type, hid_t dxpl_id, - void **req, va_list arguments) + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVdi**xx", obj, connector_id, specific_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVdixx", obj, connector_id, specific_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -2444,13 +2446,13 @@ done: */ herr_t H5VLdataset_optional(void *obj, hid_t connector_id, H5VL_dataset_optional_t opt_type, hid_t dxpl_id, - void **req, va_list arguments) + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVti**xx", obj, connector_id, opt_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVtixx", obj, connector_id, opt_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -2551,13 +2553,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLdataset_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req) +H5VLdataset_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xii**x", obj, connector_id, dxpl_id, req); + H5TRACE4("e", "*xiix", obj, connector_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -2654,14 +2656,15 @@ done: */ void * H5VLdatatype_commit(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, - hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, hid_t dxpl_id, void **req) + hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, hid_t dxpl_id, + void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE10("*x", "*x*xi*siiiii**x", obj, loc_params, connector_id, name, type_id, lcpl_id, tcpl_id, - tapl_id, dxpl_id, req); + H5TRACE10("*x", "*x*#i*siiiiix", obj, loc_params, connector_id, name, type_id, lcpl_id, tcpl_id, tapl_id, + dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -2757,13 +2760,13 @@ done: */ void * H5VLdatatype_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, - hid_t tapl_id, hid_t dxpl_id, void **req) + hid_t tapl_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("*x", "*x*xi*sii**x", obj, loc_params, connector_id, name, tapl_id, dxpl_id, req); + H5TRACE7("*x", "*x*#i*siix", obj, loc_params, connector_id, name, tapl_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -2863,14 +2866,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLdatatype_get(void *obj, hid_t connector_id, H5VL_datatype_get_t get_type, hid_t dxpl_id, void **req, - va_list arguments) +H5VLdatatype_get(void *obj, hid_t connector_id, H5VL_datatype_get_t get_type, hid_t dxpl_id, + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVei**xx", obj, connector_id, get_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVeixx", obj, connector_id, get_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -2977,13 +2980,13 @@ done: */ herr_t H5VLdatatype_specific(void *obj, hid_t connector_id, H5VL_datatype_specific_t specific_type, hid_t dxpl_id, - void **req, va_list arguments) + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVfi**xx", obj, connector_id, specific_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVfixx", obj, connector_id, specific_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -3086,13 +3089,13 @@ done: */ herr_t H5VLdatatype_optional(void *obj, hid_t connector_id, H5VL_datatype_optional_t opt_type, hid_t dxpl_id, - void **req, va_list arguments) + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVui**xx", obj, connector_id, opt_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVuixx", obj, connector_id, opt_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -3183,13 +3186,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLdatatype_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req) +H5VLdatatype_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xii**x", obj, connector_id, dxpl_id, req); + H5TRACE4("e", "*xiix", obj, connector_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -3283,7 +3286,8 @@ done: *------------------------------------------------------------------------- */ void * -H5VLfile_create(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id, void **req) +H5VLfile_create(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id, + void **req /*out*/) { H5P_genplist_t * plist; /* Property list pointer */ H5VL_connector_prop_t connector_prop; /* Property for VOL connector ID & info */ @@ -3291,7 +3295,7 @@ H5VLfile_create(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("*x", "*sIuiii**x", name, flags, fcpl_id, fapl_id, dxpl_id, req); + H5TRACE6("*x", "*sIuiiix", name, flags, fcpl_id, fapl_id, dxpl_id, req); /* Get the VOL info from the fapl */ if (NULL == (plist = (H5P_genplist_t *)H5I_object(fapl_id))) @@ -3386,7 +3390,7 @@ done: *------------------------------------------------------------------------- */ void * -H5VLfile_open(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req) +H5VLfile_open(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req /*out*/) { H5P_genplist_t * plist; /* Property list pointer */ H5VL_connector_prop_t connector_prop; /* Property for VOL connector ID & info */ @@ -3394,7 +3398,7 @@ H5VLfile_open(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, vo void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE5("*x", "*sIuii**x", name, flags, fapl_id, dxpl_id, req); + H5TRACE5("*x", "*sIuiix", name, flags, fapl_id, dxpl_id, req); /* Get the VOL info from the fapl */ if (NULL == (plist = (H5P_genplist_t *)H5I_object(fapl_id))) @@ -3498,14 +3502,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLfile_get(void *obj, hid_t connector_id, H5VL_file_get_t get_type, hid_t dxpl_id, void **req, +H5VLfile_get(void *obj, hid_t connector_id, H5VL_file_get_t get_type, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVgi**xx", obj, connector_id, get_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVgixx", obj, connector_id, get_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -3643,13 +3647,13 @@ done: */ herr_t H5VLfile_specific(void *obj, hid_t connector_id, H5VL_file_specific_t specific_type, hid_t dxpl_id, - void **req, va_list arguments) + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVhi**xx", obj, connector_id, specific_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVhixx", obj, connector_id, specific_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -3748,14 +3752,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLfile_optional(void *obj, hid_t connector_id, H5VL_file_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments) +H5VLfile_optional(void *obj, hid_t connector_id, H5VL_file_optional_t opt_type, hid_t dxpl_id, + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVvi**xx", obj, connector_id, opt_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVvixx", obj, connector_id, opt_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -3850,13 +3854,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLfile_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req) +H5VLfile_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xii**x", obj, connector_id, dxpl_id, req); + H5TRACE4("e", "*xiix", obj, connector_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -3952,13 +3956,13 @@ done: */ void * H5VLgroup_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, - hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id, void **req) + hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE9("*x", "*x*xi*siiii**x", obj, loc_params, connector_id, name, lcpl_id, gcpl_id, gapl_id, dxpl_id, + H5TRACE9("*x", "*x*#i*siiiix", obj, loc_params, connector_id, name, lcpl_id, gcpl_id, gapl_id, dxpl_id, req); /* Check args and get class pointer */ @@ -4055,13 +4059,13 @@ done: */ void * H5VLgroup_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, - hid_t gapl_id, hid_t dxpl_id, void **req) + hid_t gapl_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("*x", "*x*xi*sii**x", obj, loc_params, connector_id, name, gapl_id, dxpl_id, req); + H5TRACE7("*x", "*x*#i*siix", obj, loc_params, connector_id, name, gapl_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -4161,14 +4165,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLgroup_get(void *obj, hid_t connector_id, H5VL_group_get_t get_type, hid_t dxpl_id, void **req, +H5VLgroup_get(void *obj, hid_t connector_id, H5VL_group_get_t get_type, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVii**xx", obj, connector_id, get_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiViixx", obj, connector_id, get_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -4271,13 +4275,13 @@ done: */ herr_t H5VLgroup_specific(void *obj, hid_t connector_id, H5VL_group_specific_t specific_type, hid_t dxpl_id, - void **req, va_list arguments) + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVji**xx", obj, connector_id, specific_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVjixx", obj, connector_id, specific_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -4379,14 +4383,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLgroup_optional(void *obj, hid_t connector_id, H5VL_group_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments) +H5VLgroup_optional(void *obj, hid_t connector_id, H5VL_group_optional_t opt_type, hid_t dxpl_id, + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVwi**xx", obj, connector_id, opt_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVwixx", obj, connector_id, opt_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -4481,13 +4485,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLgroup_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req) +H5VLgroup_close(void *obj, hid_t connector_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xii**x", obj, connector_id, dxpl_id, req); + H5TRACE4("e", "*xiix", obj, connector_id, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -4613,15 +4617,15 @@ done: */ herr_t H5VLlink_create(H5VL_link_create_type_t create_type, void *obj, const H5VL_loc_params_t *loc_params, - hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req, + hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE9("e", "Vk*x*xiiii**xx", create_type, obj, loc_params, connector_id, lcpl_id, lapl_id, dxpl_id, - req, arguments); + H5TRACE9("e", "Vk*x*#iiiixx", create_type, obj, loc_params, connector_id, lcpl_id, lapl_id, dxpl_id, req, + arguments); /* Get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -4721,14 +4725,14 @@ done: herr_t H5VLlink_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, - hid_t dxpl_id, void **req) + hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE9("e", "*x*x*x*xiiii**x", src_obj, loc_params1, dst_obj, loc_params2, connector_id, lcpl_id, - lapl_id, dxpl_id, req); + H5TRACE9("e", "*x*#*x*#iiiix", src_obj, loc_params1, dst_obj, loc_params2, connector_id, lcpl_id, lapl_id, + dxpl_id, req); /* Get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -4828,14 +4832,14 @@ done: herr_t H5VLlink_move(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, - hid_t dxpl_id, void **req) + hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE9("e", "*x*x*x*xiiii**x", src_obj, loc_params1, dst_obj, loc_params2, connector_id, lcpl_id, - lapl_id, dxpl_id, req); + H5TRACE9("e", "*x*#*x*#iiiix", src_obj, loc_params1, dst_obj, loc_params2, connector_id, lcpl_id, lapl_id, + dxpl_id, req); /* Get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -4936,13 +4940,13 @@ done: */ herr_t H5VLlink_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, H5VL_link_get_t get_type, - hid_t dxpl_id, void **req, va_list arguments) + hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("e", "*x*xiVli**xx", obj, loc_params, connector_id, get_type, dxpl_id, req, arguments); + H5TRACE7("e", "*x*#iVlixx", obj, loc_params, connector_id, get_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -5045,13 +5049,13 @@ done: */ herr_t H5VLlink_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_link_specific_t specific_type, hid_t dxpl_id, void **req, va_list arguments) + H5VL_link_specific_t specific_type, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("e", "*x*xiVmi**xx", obj, loc_params, connector_id, specific_type, dxpl_id, req, arguments); + H5TRACE7("e", "*x*#iVmixx", obj, loc_params, connector_id, specific_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -5152,14 +5156,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLlink_optional(void *obj, hid_t connector_id, H5VL_link_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments) +H5VLlink_optional(void *obj, hid_t connector_id, H5VL_link_optional_t opt_type, hid_t dxpl_id, + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVxi**xx", obj, connector_id, opt_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVxixx", obj, connector_id, opt_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -5254,13 +5258,13 @@ done: */ void * H5VLobject_open(void *obj, const H5VL_loc_params_t *params, hid_t connector_id, H5I_type_t *opened_type, - hid_t dxpl_id, void **req) + hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ void * ret_value = NULL; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("*x", "*x*xi*Iti**x", obj, params, connector_id, opened_type, dxpl_id, req); + H5TRACE6("*x", "*x*#i*Itix", obj, params, connector_id, opened_type, dxpl_id, req); /* Check args and get class pointer */ if (NULL == obj) @@ -5364,14 +5368,14 @@ done: herr_t H5VLobject_copy(void *src_obj, const H5VL_loc_params_t *src_loc_params, const char *src_name, void *dst_obj, const H5VL_loc_params_t *dst_loc_params, const char *dst_name, hid_t connector_id, - hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id, void **req) + hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id, void **req /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE11("e", "*x*x*s*x*x*siiii**x", src_obj, src_loc_params, src_name, dst_obj, dst_loc_params, - dst_name, connector_id, ocpypl_id, lcpl_id, dxpl_id, req); + H5TRACE11("e", "*x*#*s*x*#*siiiix", src_obj, src_loc_params, src_name, dst_obj, dst_loc_params, dst_name, + connector_id, ocpypl_id, lcpl_id, dxpl_id, req); /* Check args and get class pointers */ if (NULL == src_obj || NULL == dst_obj) @@ -5475,13 +5479,13 @@ done: */ herr_t H5VLobject_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, H5VL_object_get_t get_type, - hid_t dxpl_id, void **req, va_list arguments) + hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("e", "*x*xiVni**xx", obj, loc_params, connector_id, get_type, dxpl_id, req, arguments); + H5TRACE7("e", "*x*#iVnixx", obj, loc_params, connector_id, get_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -5584,13 +5588,14 @@ done: */ herr_t H5VLobject_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_object_specific_t specific_type, hid_t dxpl_id, void **req, va_list arguments) + H5VL_object_specific_t specific_type, hid_t dxpl_id, void **req /*out*/, + va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE7("e", "*x*xiVoi**xx", obj, loc_params, connector_id, specific_type, dxpl_id, req, arguments); + H5TRACE7("e", "*x*#iVoixx", obj, loc_params, connector_id, specific_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -5695,14 +5700,14 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLobject_optional(void *obj, hid_t connector_id, H5VL_object_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments) +H5VLobject_optional(void *obj, hid_t connector_id, H5VL_object_optional_t opt_type, hid_t dxpl_id, + void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiVyi**xx", obj, connector_id, opt_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiVyixx", obj, connector_id, opt_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) @@ -5805,13 +5810,13 @@ done: */ herr_t H5VLintrospect_get_conn_cls(void *obj, hid_t connector_id, H5VL_get_conn_lvl_t lvl, - const H5VL_class_t **conn_cls) + const H5VL_class_t **conn_cls /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xiVL**x", obj, connector_id, lvl, conn_cls); + H5TRACE4("e", "*xiVLx", obj, connector_id, lvl, conn_cls); /* Check args */ if (NULL == obj) @@ -5912,13 +5917,13 @@ done: */ herr_t H5VLintrospect_opt_query(void *obj, hid_t connector_id, H5VL_subclass_t subcls, int opt_type, - hbool_t *supported) + hbool_t *supported /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE5("e", "*xiVSIs*b", obj, connector_id, subcls, opt_type, supported); + H5TRACE5("e", "*xiVSIsx", obj, connector_id, subcls, opt_type, supported); /* Get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -6024,13 +6029,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLrequest_wait(void *req, hid_t connector_id, uint64_t timeout, H5ES_status_t *status) +H5VLrequest_wait(void *req, hid_t connector_id, uint64_t timeout, H5ES_status_t *status /*out*/) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xiUL*Es", req, connector_id, timeout, status); + H5TRACE4("e", "*xiULx", req, connector_id, timeout, status); /* Get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -6141,7 +6146,7 @@ H5VLrequest_notify(void *req, hid_t connector_id, H5VL_request_notify_t cb, void herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE4("e", "*xix*x", req, connector_id, cb, ctx); + H5TRACE4("e", "*xiVN*x", req, connector_id, cb, ctx); /* Get class pointer */ if (NULL == (cls = (H5VL_class_t *)H5I_object_verify(connector_id, H5I_VOL))) @@ -6783,13 +6788,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLblob_get(void *obj, hid_t connector_id, const void *blob_id, void *buf, size_t size, void *ctx) +H5VLblob_get(void *obj, hid_t connector_id, const void *blob_id, void *buf /*out*/, size_t size, void *ctx) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xi*x*xz*x", obj, connector_id, blob_id, buf, size, ctx); + H5TRACE6("e", "*xi*xxz*x", obj, connector_id, blob_id, buf, size, ctx); /* Get class pointer */ if (NULL == obj) @@ -7495,13 +7500,13 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VLoptional(void *obj, hid_t connector_id, int op_type, hid_t dxpl_id, void **req, va_list arguments) +H5VLoptional(void *obj, hid_t connector_id, int op_type, hid_t dxpl_id, void **req /*out*/, va_list arguments) { H5VL_class_t *cls; /* VOL connector's class struct */ herr_t ret_value = SUCCEED; /* Return value */ FUNC_ENTER_API_NOINIT - H5TRACE6("e", "*xiIsi**xx", obj, connector_id, op_type, dxpl_id, req, arguments); + H5TRACE6("e", "*xiIsixx", obj, connector_id, op_type, dxpl_id, req, arguments); /* Check args and get class pointer */ if (NULL == obj) diff --git a/src/H5VLconnector.h b/src/H5VLconnector.h index 63ac910..2abdca3 100644 --- a/src/H5VLconnector.h +++ b/src/H5VLconnector.h @@ -438,39 +438,44 @@ typedef struct H5VL_token_class_t { herr_t (*from_str)(void *obj, H5I_type_t obj_type, const char *token_str, H5O_token_t *token); } H5VL_token_class_t; -/* Class information for each VOL connector */ +/** + * \ingroup H5VLDEV + * Class information for each VOL connector + */ +//! [H5VL_class_t_snip] typedef struct H5VL_class_t { /* Overall connector fields & callbacks */ - unsigned int version; /* VOL connector class struct version # */ - H5VL_class_value_t value; /* Value to identify connector */ - const char * name; /* Connector name (MUST be unique!) */ - unsigned cap_flags; /* Capability flags for connector */ - herr_t (*initialize)(hid_t vipl_id); /* Connector initialization callback */ - herr_t (*terminate)(void); /* Connector termination callback */ + unsigned int version; /**< VOL connector class struct version # */ + H5VL_class_value_t value; /**< Value to identify connector */ + const char * name; /**< Connector name (MUST be unique!) */ + unsigned cap_flags; /**< Capability flags for connector */ + herr_t (*initialize)(hid_t vipl_id); /**< Connector initialization callback */ + herr_t (*terminate)(void); /**< Connector termination callback */ /* VOL framework */ - H5VL_info_class_t info_cls; /* VOL info fields & callbacks */ - H5VL_wrap_class_t wrap_cls; /* VOL object wrap / retrieval callbacks */ + H5VL_info_class_t info_cls; /**< VOL info fields & callbacks */ + H5VL_wrap_class_t wrap_cls; /**< VOL object wrap / retrieval callbacks */ /* Data Model */ - H5VL_attr_class_t attr_cls; /* Attribute (H5A*) class callbacks */ - H5VL_dataset_class_t dataset_cls; /* Dataset (H5D*) class callbacks */ - H5VL_datatype_class_t datatype_cls; /* Datatype (H5T*) class callbacks */ - H5VL_file_class_t file_cls; /* File (H5F*) class callbacks */ - H5VL_group_class_t group_cls; /* Group (H5G*) class callbacks */ - H5VL_link_class_t link_cls; /* Link (H5L*) class callbacks */ - H5VL_object_class_t object_cls; /* Object (H5O*) class callbacks */ + H5VL_attr_class_t attr_cls; /**< Attribute (H5A*) class callbacks */ + H5VL_dataset_class_t dataset_cls; /**< Dataset (H5D*) class callbacks */ + H5VL_datatype_class_t datatype_cls; /**< Datatype (H5T*) class callbacks */ + H5VL_file_class_t file_cls; /**< File (H5F*) class callbacks */ + H5VL_group_class_t group_cls; /**< Group (H5G*) class callbacks */ + H5VL_link_class_t link_cls; /**< Link (H5L*) class callbacks */ + H5VL_object_class_t object_cls; /**< Object (H5O*) class callbacks */ /* Infrastructure / Services */ - H5VL_introspect_class_t introspect_cls; /* Container/connector introspection class callbacks */ - H5VL_request_class_t request_cls; /* Asynchronous request class callbacks */ - H5VL_blob_class_t blob_cls; /* 'Blob' class callbacks */ - H5VL_token_class_t token_cls; /* VOL connector object token class callbacks */ + H5VL_introspect_class_t introspect_cls; /**< Container/connector introspection class callbacks */ + H5VL_request_class_t request_cls; /**< Asynchronous request class callbacks */ + H5VL_blob_class_t blob_cls; /**< 'Blob' class callbacks */ + H5VL_token_class_t token_cls; /**< VOL connector object token class callbacks */ /* Catch-all */ herr_t (*optional)(void *obj, int op_type, hid_t dxpl_id, void **req, - va_list arguments); /* Optional callback */ + va_list arguments); /**< Optional callback */ } H5VL_class_t; +//! [H5VL_class_t_snip] /********************/ /* Public Variables */ @@ -485,10 +490,54 @@ extern "C" { #endif /* Helper routines for VOL connector authors */ +/** + * \ingroup H5VLDEV + * \brief Registers a new VOL connector + * + * \param[in] cls A pointer to the plugin structure to register + * \vipl_id + * \return \hid_t{VOL connector} + * + * \details H5VLregister_connector() registers a new VOL connector as a member + * of the virtual object layer class. This VOL connector identifier is + * good until the library is closed or the connector is unregistered. + * + * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL + * initialization property list of class #H5P_VOL_INITIALIZE created + * with H5Pcreate(). When created, this property list contains no + * library properties. If a VOL connector author decides that + * initialization-specific data are needed, they can be added to the + * empty list and retrieved by the connector in the VOL connector's + * initialize callback. Use of the VOL initialization property list is + * uncommon, as most VOL-specific properties are added to the file + * access property list via the connector's API calls which set the + * VOL connector for the file open/create. For more information, see + * the VOL documentation. + * + * H5VL_class_t is defined in H5VLconnector.h in the source code. It + * contains class information for each VOL connector: + * \snippet this H5VL_class_t_snip + * + * \todo Fix the reference to VOL documentation. + * + * \since 1.12.0 + */ H5_DLL hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id); +/** + * \ingroup H5VLDEV + */ H5_DLL void *H5VLobject(hid_t obj_id); +/** + * \ingroup H5VLDEV + */ H5_DLL hid_t H5VLget_file_type(void *file_obj, hid_t connector_id, hid_t dtype_id); +/** + * \ingroup H5VLDEV + */ H5_DLL hid_t H5VLpeek_connector_id_by_name(const char *name); +/** + * \ingroup H5VLDEV + */ H5_DLL hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value); #ifdef __cplusplus diff --git a/src/H5VLint.c b/src/H5VLint.c index cc5b8b7..32aa8fb 100644 --- a/src/H5VLint.c +++ b/src/H5VLint.c @@ -2325,11 +2325,10 @@ H5VL_wrap_register(H5I_type_t type, void *obj, hbool_t app_ref) /* If the datatype is already VOL-managed, the datatype's vol_obj * field will get clobbered later, so disallow this. */ - if (type == H5I_DATATYPE) { + if (type == H5I_DATATYPE) if (vol_wrap_ctx->connector->id == H5VL_NATIVE) if (TRUE == H5T_already_vol_managed((const H5T_t *)obj)) HGOTO_ERROR(H5E_VOL, H5E_BADTYPE, H5I_INVALID_HID, "can't wrap an uncommitted datatype") - } /* Wrap the object with VOL connector info */ if (NULL == (new_obj = H5VL__wrap_obj(obj, type))) diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h index 1ff9137..91d61c9 100644 --- a/src/H5VLmodule.h +++ b/src/H5VLmodule.h @@ -27,4 +27,19 @@ #define H5_MY_PKG_ERR H5E_VOL #define H5_MY_PKG_INIT YES +/** + * \defgroup H5VL H5VL + * \brief Virtual Object Layer Interface + * \todo Describe concisely what the functions in this module are about. + * + * \defgroup H5VLDEF Definitions + * \ingroup H5VL + * \defgroup H5VLDEV VOL Developer + * \ingroup H5VL + * \defgroup H5VLNAT Native VOL + * \ingroup H5VL + * \defgroup H5VLPT Pass-through VOL + * \ingroup H5VL + */ + #endif /* _H5VLmodule_H */ diff --git a/src/H5VLnative.h b/src/H5VLnative.h index b703c4f..b81f9c1 100644 --- a/src/H5VLnative.h +++ b/src/H5VLnative.h @@ -123,7 +123,13 @@ extern "C" { #endif /* Token <--> address converters */ +/** + * \ingroup H5VLNAT + */ H5_DLL herr_t H5VLnative_addr_to_token(hid_t loc_id, haddr_t addr, H5O_token_t *token); +/** + * \ingroup H5VLNAT + */ H5_DLL herr_t H5VLnative_token_to_addr(hid_t loc_id, H5O_token_t token, haddr_t *addr); /* Not really public but must be included here */ diff --git a/src/H5VLnative_object.c b/src/H5VLnative_object.c index ac717b0..81ff5ea 100644 --- a/src/H5VLnative_object.c +++ b/src/H5VLnative_object.c @@ -338,7 +338,7 @@ H5VL__native_object_specific(void *obj, const H5VL_loc_params_t *loc_params, /* Lookup object */ case H5VL_OBJECT_LOOKUP: { - H5O_token_t *token = va_arg(arguments, H5O_token_t *); + H5O_token_t *token = HDva_arg(arguments, H5O_token_t *); HDassert(token); diff --git a/src/H5VLpassthru.c b/src/H5VLpassthru.c index eacb01e..4e967d9 100644 --- a/src/H5VLpassthru.c +++ b/src/H5VLpassthru.c @@ -2905,8 +2905,11 @@ H5VL_pass_through_request_specific(void *obj, H5VL_request_specific_t specific_t /* Finish use of copied vararg list */ va_end(tmp_arguments); } /* end if */ - else - assert(0 && "Unknown 'specific' operation"); + else { + H5VL_pass_through_t *o = (H5VL_pass_through_t *)obj; + + ret_value = H5VLrequest_specific(o->under_object, o->under_vol_id, specific_type, arguments); + } /* end else */ return ret_value; } /* end H5VL_pass_through_request_specific() */ diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h index 919a4b8..9c9d60a 100644 --- a/src/H5VLpublic.h +++ b/src/H5VLpublic.h @@ -28,39 +28,64 @@ /* VOL connector identifier values * These are H5VL_class_value_t values, NOT hid_t values! */ -#define H5_VOL_INVALID (-1) /* Invalid ID for VOL connector ID */ -#define H5_VOL_NATIVE 0 /* Native HDF5 file format VOL connector */ -#define H5_VOL_RESERVED 256 /* VOL connector IDs below this value are reserved for library use */ -#define H5_VOL_MAX 65535 /* Maximum VOL connector ID */ +/** + * \ingroup H5VLDEF + * Invalid ID for VOL connector ID + */ +#define H5_VOL_INVALID (-1) +/** + * \ingroup H5VLDEF + * Native HDF5 file format VOL connector + */ +#define H5_VOL_NATIVE 0 +/** + * \ingroup H5VLDEF + * VOL connector IDs below this value are reserved for library use + */ +#define H5_VOL_RESERVED 256 +/** + * \ingroup H5VLDEF + * Maximum VOL connector ID + */ +#define H5_VOL_MAX 65535 /*******************/ /* Public Typedefs */ /*******************/ -/* - * VOL connector identifiers. Values 0 through 255 are for connectors defined - * by the HDF5 library. Values 256 through 511 are available for testing new - * connectors. Subsequent values should be obtained from the HDF5 development - * team at help@hdfgroup.org. +/** + * \ingroup H5VLDEF + * + * \brief VOL connector identifiers. + * + * \details Values 0 through 255 are for connectors defined by the HDF5 + * library. Values 256 through 511 are available for testing new + * connectors. Subsequent values should be obtained from the HDF5 + * development team at mailto:help@hdfgroup.org. */ +//! [H5VL_class_value_t_snip] typedef int H5VL_class_value_t; +//! [H5VL_class_value_t_snip] -/* Enum type for each VOL subclass */ -/* (Used for various queries, etc) */ +/** + * \ingroup H5VLDEF + * \details Enum type for each VOL subclass + * (Used for various queries, etc) + */ typedef enum H5VL_subclass_t { - H5VL_SUBCLS_NONE, /* Operations outside of a subclass */ - H5VL_SUBCLS_INFO, /* 'Info' subclass */ - H5VL_SUBCLS_WRAP, /* 'Wrap' subclass */ - H5VL_SUBCLS_ATTR, /* 'Attribute' subclass */ - H5VL_SUBCLS_DATASET, /* 'Dataset' subclass */ - H5VL_SUBCLS_DATATYPE, /* 'Named datatype' subclass */ - H5VL_SUBCLS_FILE, /* 'File' subclass */ - H5VL_SUBCLS_GROUP, /* 'Group' subclass */ - H5VL_SUBCLS_LINK, /* 'Link' subclass */ - H5VL_SUBCLS_OBJECT, /* 'Object' subclass */ - H5VL_SUBCLS_REQUEST, /* 'Request' subclass */ - H5VL_SUBCLS_BLOB, /* 'Blob' subclass */ - H5VL_SUBCLS_TOKEN /* 'Token' subclass */ + H5VL_SUBCLS_NONE, /**< Operations outside of a subclass */ + H5VL_SUBCLS_INFO, /**< 'Info' subclass */ + H5VL_SUBCLS_WRAP, /**< 'Wrap' subclass */ + H5VL_SUBCLS_ATTR, /**< 'Attribute' subclass */ + H5VL_SUBCLS_DATASET, /**< 'Dataset' subclass */ + H5VL_SUBCLS_DATATYPE, /**< 'Named datatype' subclass */ + H5VL_SUBCLS_FILE, /**< 'File' subclass */ + H5VL_SUBCLS_GROUP, /**< 'Group' subclass */ + H5VL_SUBCLS_LINK, /**< 'Link' subclass */ + H5VL_SUBCLS_OBJECT, /**< 'Object' subclass */ + H5VL_SUBCLS_REQUEST, /**< 'Request' subclass */ + H5VL_SUBCLS_BLOB, /**< 'Blob' subclass */ + H5VL_SUBCLS_TOKEN /**< 'Token' subclass */ } H5VL_subclass_t; /********************/ @@ -75,17 +100,231 @@ typedef enum H5VL_subclass_t { extern "C" { #endif -H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id); -H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id); -H5_DLL htri_t H5VLis_connector_registered_by_name(const char *name); -H5_DLL htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value); -H5_DLL hid_t H5VLget_connector_id(hid_t obj_id); -H5_DLL hid_t H5VLget_connector_id_by_name(const char *name); -H5_DLL hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value); +/** + * \ingroup H5VL + * \brief Registers a new VOL connector by name + * + * \param[in] connector_name Connector name + * \vipl_id + * \return \hid_t{VOL connector} + * + * \details H5VLregister_connector_by_name() registers a new VOL connector with + * the name \p connector_name as a member of the virtual object layer + * class. This VOL connector identifier is good until the library is + * closed or the connector is unregistered. + * + * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL + * initialization property list of class #H5P_VOL_INITIALIZE created + * with H5Pcreate(). When created, this property list contains no + * library properties. If a VOL connector author decides that + * initialization-specific data are needed, they can be added to the + * empty list and retrieved by the connector in the VOL connector's + * initialize callback. Use of the VOL initialization property list is + * uncommon, as most VOL-specific properties are added to the file + * access property list via the connector's API calls which set the + * VOL connector for the file open/create. For more information, see + * the VOL documentation. + * + * \todo Fix the reference to VOL documentation. + * + * \since 1.12.0 + */ +H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id); +/** + * \ingroup H5VL + * \brief Registers a new VOL connector by value + * + * \param[in] connector_value Connector value + * \vipl_id + * \return \hid_t{VOL connector} + * + * \details H5VLregister_connector_by_value() registers a new VOL connector + * with value connector_value as a member of the virtual object layer + * class. This VOL connector identifier is good until the library is + * closed or the connector is unregistered. + * + * \p connector_value has a type of H5VL_class_value_t, which is + * defined in H5VLpublic.h as follows: + * \snippet this H5VL_class_value_t_snip + * + * Valid VOL connector identifiers can have values from 0 through 255 + * for connectors defined by the HDF5 library. Values 256 through 511 + * are available for testing new connectors. Subsequent values should + * be obtained by contacting the The HDF Help Desk. + * + * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL + * initialization property list of class #H5P_VOL_INITIALIZE created + * with H5Pcreate(). When created, this property list contains no + * library properties. If a VOL connector author decides that + * initialization-specific data are needed, they can be added to the + * empty list and retrieved by the connector in the VOL connector's + * initialize callback. Use of the VOL initialization property list is + * uncommon, as most VOL-specific properties are added to the file + * access property list via the connector's API calls which set the + * VOL connector for the file open/create. For more information, see + * the VOL documentation. + * + * \todo Fix the reference to VOL documentation. + * + * \since 1.12.0 + */ +H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id); +/** + * \ingroup H5VL + * \brief Tests whether a VOL class has been registered under a certain name + * + * \param[in] name Alleged name of connector + * \return \htri_t + * + * \details H5VLis_connector_registered_by_name() tests whether a VOL class has + * been registered or not, according to the supplied connector name + * \p name. + * + * \since 1.12.0 + */ +H5_DLL htri_t H5VLis_connector_registered_by_name(const char *name); +/** + * \ingroup H5VL + * \brief Tests whether a VOL class has been registered for a given value + * + * \param[in] connector_value Connector value + * \return \htri_t + * + * \details H5VLis_connector_registered_by_value() tests whether a VOL class + * has been registered, according to the supplied connector value \p + * connector_value. + * + * \p connector_value has a type of H5VL_class_value_t, which is + * defined in H5VLpublic.h as follows: + * \snippet this H5VL_class_value_t_snip + * + * Valid VOL connector identifiers can have values from 0 through 255 + * for connectors defined by the HDF5 library. Values 256 through 511 + * are available for testing new connectors. Subsequent values should + * be obtained by contacting the The HDF Help Desk. + * + * \since 1.12.0 + */ +H5_DLL htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value); +/** + * \ingroup H5VL + * \brief Retrieves the VOL connector identifier for a given object identifier + * + * \obj_id + * \return \hid_t{VOL connector} + * + * \details H5VLget_connector_id() retrieves the registered VOL connector + * identifier for the specified object identifier \p obj_id. The VOL + * connector identifier must be closed with H5VLclose() when no longer + * in use. + * + * \since 1.12.0 + */ +H5_DLL hid_t H5VLget_connector_id(hid_t obj_id); +/** + * \ingroup H5VL + * \brief Retrieves the identifier for a registered VOL connector name + * + * \param[in] name Connector name + * \return \hid_t{VOL connector} + * + * \details H5VLget_connector_id_by_name() retrieves the identifier for a + * registered VOL connector with the name \p name. The identifier must + * be closed with H5VLclose() when no longer in use. + * + * \since 1.12.0 + */ +H5_DLL hid_t H5VLget_connector_id_by_name(const char *name); +/** + * \ingroup H5VL + * \brief Retrieves the identifier for a registered VOL connector value + * + * \param[in] connector_value Connector value + * \return \hid_t{VOL connector} + * + * \details H5VLget_connector_id_by_value() retrieves the identifier for a + * registered VOL connector with the value \p connector_value. The + * identifier will need to be closed by H5VLclose(). + * + * \p connector_value has a type of H5VL_class_value_t, which is + * defined in H5VLpublic.h as follows: + * \snippet this H5VL_class_value_t_snip + * + * Valid VOL connector identifiers can have values from 0 through 255 + * for connectors defined by the HDF5 library. Values 256 through 511 + * are available for testing new connectors. Subsequent values should + * be obtained by contacting the The HDF Help Desk. + * + * \since 1.12.0 + */ +H5_DLL hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value); +/** + * \ingroup H5VL + * \brief Retrieves a connector name for a VOL + * + * \obj_id{id} or file identifier + * \param[out] name Connector name + * \param[in] size Maximum length of the name to retrieve + * \return Returns the length of the connector name on success, and a negative value on failure. + * + * \details H5VLget_connector_name() retrieves up to \p size elements of the + * VOL name \p name associated with the object or file identifier \p + * id. + * + * Passing in a NULL pointer for size will return the size of the + * connector name. This can be used to determine the size of the + * buffer to allocate for the name. + * + * \since 1.12.0 + */ H5_DLL ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size); -H5_DLL herr_t H5VLclose(hid_t connector_id); -H5_DLL herr_t H5VLunregister_connector(hid_t connector_id); -H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported); +/** + * \ingroup H5VL + * \brief Closes a VOL connector identifier + * + * \param[in] connector_id Connector identifier + * \return \herr_t + * + * \details H5VLclose() closes a VOL connector identifier. This does not affect + * the file access property lists which have been defined to use this + * VOL connector or files which are already opened under this + * connector. + * + * \since 1.12.0 + */ +H5_DLL herr_t H5VLclose(hid_t connector_id); +/** + * \ingroup H5VL + * \brief Removes a VOL connector identifier from the library + * + * \param[in] connector_id Connector identifier + * \return \herr_t + * + * \details H5VLunregister_connector() removes a VOL connector identifier from + * the library. This does not affect the file access property lists + * which have been defined to use the VOL connector or any files which + * are already opened with this connector. + * + * \attention H5VLunregister_connector() will fail if attempting to unregister + * the native VOL connector. + * + * \since 1.12.0 + */ +H5_DLL herr_t H5VLunregister_connector(hid_t connector_id); +/** + * \ingroup H5VL + * \brief Determine if a VOL connector supports a particular + * optional callback operation. + * + * \obj_id + * \param[in] subcls VOL subclass + * \param[in] opt_type Option type + * \param[out] supported Flag + * \return \herr_t + * + * \since 1.12.0 + */ +H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported); #ifdef __cplusplus } @@ -447,13 +447,8 @@ H5VM_hyper_fill(unsigned n, const hsize_t *_size, const hsize_t *total_size, con *------------------------------------------------------------------------- */ herr_t -H5VM_hyper_copy(unsigned n, const hsize_t *_size, - - /*destination*/ - const hsize_t *dst_size, const hsize_t *dst_offset, void *_dst, - - /*source*/ - const hsize_t *src_size, const hsize_t *src_offset, const void *_src) +H5VM_hyper_copy(unsigned n, const hsize_t *_size, const hsize_t *dst_size, const hsize_t *dst_offset, + void *_dst, const hsize_t *src_size, const hsize_t *src_offset, const void *_src) { const uint8_t *src = (const uint8_t *)_src; /*cast for ptr arithmtc */ uint8_t * dst = (uint8_t *)_dst; /*cast for ptr arithmtc */ @@ -491,7 +486,7 @@ H5VM_hyper_copy(unsigned n, const hsize_t *_size, #ifdef NO_INLINED_CODE dst_start = H5VM_hyper_stride(n, size, dst_size, dst_offset, dst_stride); src_start = H5VM_hyper_stride(n, size, src_size, src_offset, src_stride); -#else /* NO_INLINED_CODE */ +#else /* NO_INLINED_CODE */ /* in-line version of two calls to H5VM_hyper_stride() */ { hsize_t dst_acc; /*accumulator */ @@ -795,13 +790,9 @@ H5VM_stride_copy_s(unsigned n, hsize_t elmt_size, const hsize_t *size, const hss *------------------------------------------------------------------------- */ static void -H5VM__stride_copy2(hsize_t nelmts, hsize_t elmt_size, - - /* destination */ - unsigned dst_n, const hsize_t *dst_size, const hsize_t *dst_stride, void *_dst, - - /* source */ - unsigned src_n, const hsize_t *src_size, const hsize_t *src_stride, const void *_src) +H5VM__stride_copy2(hsize_t nelmts, hsize_t elmt_size, unsigned dst_n, const hsize_t *dst_size, + const hsize_t *dst_stride, void *_dst, unsigned src_n, const hsize_t *src_size, + const hsize_t *src_stride, const void *_src) { uint8_t * dst = (uint8_t *)_dst; const uint8_t *src = (const uint8_t *)_src; @@ -47,7 +47,7 @@ typedef struct H5Z_object_t { #ifdef H5_HAVE_PARALLEL hbool_t sanity_checked; /* Whether the sanity check for collectively calling H5Zunregister has been done */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ } H5Z_object_t; /* Enumerated type for dataset creation prelude callbacks */ @@ -175,13 +175,13 @@ H5Z_term_package(void) H5Z_stat_table_g[i].stats[dir].errors, timestrs.user, timestrs.system, timestrs.elapsed, bandwidth); next: - free(timestrs.user); - free(timestrs.system); - free(timestrs.elapsed); + HDfree(timestrs.user); + HDfree(timestrs.system); + HDfree(timestrs.elapsed); } /* end for */ } /* end for */ } /* end if */ -#endif /* H5Z_DEBUG */ +#endif /* H5Z_DEBUG */ /* Free the table of filters */ if (H5Z_table_g) { @@ -255,11 +255,11 @@ H5Zregister(const void *cls) /* Set cls_real to point to the translated structure */ cls_real = &cls_new; -#else /* H5_NO_DEPRECATED_SYMBOLS */ +#else /* H5_NO_DEPRECATED_SYMBOLS */ /* Deprecated symbols not allowed, throw an error */ HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid H5Z_class_t version number"); #endif /* H5_NO_DEPRECATED_SYMBOLS */ - } /* end if */ + } /* end if */ if (cls_real->id < 0 || cls_real->id > H5Z_FILTER_MAX) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "invalid filter identification number") @@ -327,7 +327,7 @@ H5Z_register(const H5Z_class2_t *cls) #ifdef H5Z_DEBUG HDmemset(H5Z_stat_table_g + i, 0, sizeof(H5Z_stats_t)); #endif /* H5Z_DEBUG */ - } /* end if */ + } /* end if */ /* Filter already registered */ else { /* Replace old contents */ @@ -582,12 +582,12 @@ done: *------------------------------------------------------------------------- */ static int -H5Z__flush_file_cb(void *obj_ptr, hid_t H5_ATTR_UNUSED obj_id, void *key H5_ATTR_PARALLEL_USED) +H5Z__flush_file_cb(void *obj_ptr, hid_t H5_ATTR_UNUSED obj_id, void H5_ATTR_PARALLEL_USED *key) { H5F_t *f = (H5F_t *)obj_ptr; /* File object for operations */ #ifdef H5_HAVE_PARALLEL H5Z_object_t *object = (H5Z_object_t *)key; -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ int ret_value = FALSE; /* Return value */ FUNC_ENTER_STATIC @@ -632,7 +632,7 @@ H5Z__flush_file_cb(void *obj_ptr, hid_t H5_ATTR_UNUSED obj_id, void *key H5_ATTR if (H5P_USER_TRUE == coll_md_read) H5CX_set_coll_metadata_read(TRUE); } /* end if */ -#endif /* H5_HAVE_PARALLEL */ +#endif /* H5_HAVE_PARALLEL */ /* Call the flush routine for mounted file hierarchies */ if (H5F_flush_mounts((H5F_t *)obj_ptr) < 0) @@ -1665,12 +1665,12 @@ done: *------------------------------------------------------------------------- */ herr_t -H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags) +H5Zget_filter_info(H5Z_filter_t filter, unsigned *filter_config_flags /*out*/) { herr_t ret_value = SUCCEED; FUNC_ENTER_API(FAIL) - H5TRACE2("e", "Zf*Iu", filter, filter_config_flags); + H5TRACE2("e", "Zfx", filter, filter_config_flags); /* Get the filter info */ if (H5Z_get_filter_info(filter, filter_config_flags) < 0) diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index d83f338..3be2629 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -29,4 +29,71 @@ #define H5_MY_PKG_ERR H5E_PLINE #define H5_MY_PKG_INIT YES +/** + * \defgroup H5Z H5Z + * + * + * \brief Filter and Compression Interface + * + * \details The functions in this module let you configure filters that process + * data during I/O operation. + * + * HDF5 supports a filter pipeline that provides the capability for + * standard and customized raw data processing during I/O operations. + * HDF5 is distributed with a small set of standard filters such as + * compression (gzip, SZIP, and a shuffling algorithm) and error + * checking (Fletcher32 checksum). For further flexibility, the + * library allows a user application to extend the pipeline through + * the creation and registration of customized filters. + * + * The flexibility of the filter pipeline implementation enables the + * definition of additional filters by a user application. A filter + * \li is associated with a dataset when the dataset is created, + * \li can be used only with chunked data (i.e., datasets stored in + * the #H5D_CHUNKED storage layout), and + * \li is applied independently to each chunk of the dataset. + * + * The HDF5 library does not support filters for contiguous datasets + * because of the difficulty of implementing random access for partial + * I/O. Compact dataset filters are not supported because it would not + * produce significant results. + * + * Filter identifiers for the filters distributed with the HDF5 + * Library are as follows: + * <table> + * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or + * deflation, filter</td></tr> + * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset + * compression filter</td></tr> + * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm + * filter</td></tr> + * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum, + * or error checking, filter</td></tr> + * </table> + * Custom filters that have been registered with the library will have + * additional unique identifiers. + * + * See \Emph{HDF5 Dynamically Loaded Filters} for more information on + * how an HDF5 application can apply a filter that is not registered + * with the HDF5 library. + * + * \todo Fix the reference. + * + * \defgroup H5ZPRE Predefined Filters + * \ingroup H5Z + * \defgroup FLETCHER32 Checksum Filter + * \ingroup H5ZPRE + * \defgroup SCALEOFFSET Scale-Offset Filter + * \ingroup H5ZPRE + * \defgroup SHUFFLE Shuffle Filter + * \ingroup H5ZPRE + * \defgroup SZIP Szip Filter + * \ingroup H5ZPRE + * + */ + #endif /* _H5Zmodule_H */ diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index 97da13c..56047ae 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -21,111 +21,229 @@ /* Public headers needed by this file */ #include "H5public.h" -/* - * Filter identifiers. Values 0 through 255 are for filters defined by the - * HDF5 library. Values 256 through 511 are available for testing new - * filters. Subsequent values should be obtained from the HDF5 development - * team at help@hdfgroup.org. These values will never change because they - * appear in the HDF5 files. +/** + * \brief Filter identifiers + * + * \details Values 0 through 255 are for filters defined by the HDF5 library. + * Values 256 through 511 are available for testing new filters. + * Subsequent values should be obtained from the HDF5 development team + * at mailto:help@hdfgroup.org. These values will never change because + * they appear in the HDF5 files. */ typedef int H5Z_filter_t; /* Filter IDs */ -#define H5Z_FILTER_ERROR (-1) /*no filter */ -#define H5Z_FILTER_NONE 0 /*reserved indefinitely */ -#define H5Z_FILTER_DEFLATE 1 /*deflation like gzip */ -#define H5Z_FILTER_SHUFFLE 2 /*shuffle the data */ -#define H5Z_FILTER_FLETCHER32 3 /*fletcher32 checksum of EDC */ -#define H5Z_FILTER_SZIP 4 /*szip compression */ -#define H5Z_FILTER_NBIT 5 /*nbit compression */ -#define H5Z_FILTER_SCALEOFFSET 6 /*scale+offset compression */ -#define H5Z_FILTER_RESERVED 256 /*filter ids below this value are reserved for library use */ - -#define H5Z_FILTER_MAX 65535 /*maximum filter id */ +/** + * no filter + */ +#define H5Z_FILTER_ERROR (-1) +/** + * reserved indefinitely + */ +#define H5Z_FILTER_NONE 0 +/** + * deflation like gzip + */ +#define H5Z_FILTER_DEFLATE 1 +/** + * shuffle the data + */ +#define H5Z_FILTER_SHUFFLE 2 +/** + * fletcher32 checksum of EDC + */ +#define H5Z_FILTER_FLETCHER32 3 +/** + * szip compression + */ +#define H5Z_FILTER_SZIP 4 +/** + * nbit compression + */ +#define H5Z_FILTER_NBIT 5 +/** + * scale+offset compression + */ +#define H5Z_FILTER_SCALEOFFSET 6 +/** + * filter ids below this value are reserved for library use + */ +#define H5Z_FILTER_RESERVED 256 +/** + * maximum filter id + */ +#define H5Z_FILTER_MAX 65535 /* General macros */ -#define H5Z_FILTER_ALL 0 /* Symbol to remove all filters in H5Premove_filter */ -#define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */ - /* (should probably be allowed to be an - * unlimited amount, but currently each - * filter uses a bit in a 32-bit field, - * so the format would have to be - * changed to accommodate that) - */ +/** + * Symbol to remove all filters in H5Premove_filter() + */ +#define H5Z_FILTER_ALL 0 +/** + * Maximum number of filters allowed in a pipeline + * + * \internal (should probably be allowed to be an unlimited amount, but + * currently each filter uses a bit in a 32-bit field, so the format + * would have to be changed to accommodate that) + */ +#define H5Z_MAX_NFILTERS 32 /* Flags for filter definition (stored) */ -#define H5Z_FLAG_DEFMASK 0x00ff /*definition flag mask */ -#define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory */ -#define H5Z_FLAG_OPTIONAL 0x0001 /*filter is optional */ +/** + * definition flag mask + */ +#define H5Z_FLAG_DEFMASK 0x00ff +/** + * filter is mandatory + */ +#define H5Z_FLAG_MANDATORY 0x0000 +/** + * filter is optional + */ +#define H5Z_FLAG_OPTIONAL 0x0001 /* Additional flags for filter invocation (not stored) */ -#define H5Z_FLAG_INVMASK 0xff00 /*invocation flag mask */ -#define H5Z_FLAG_REVERSE 0x0100 /*reverse direction; read */ -#define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read */ +/** + * invocation flag mask + */ +#define H5Z_FLAG_INVMASK 0xff00 +/** + * reverse direction; read + */ +#define H5Z_FLAG_REVERSE 0x0100 +/** + * skip EDC filters for read + */ +#define H5Z_FLAG_SKIP_EDC 0x0200 /* Special parameters for szip compression */ /* [These are aliases for the similar definitions in szlib.h, which we can't * include directly due to the duplication of various symbols with the zlib.h * header file] */ +/** + * \ingroup SZIP */ #define H5_SZIP_ALLOW_K13_OPTION_MASK 1 -#define H5_SZIP_CHIP_OPTION_MASK 2 -#define H5_SZIP_EC_OPTION_MASK 4 -#define H5_SZIP_NN_OPTION_MASK 32 -#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 +/** + * \ingroup SZIP */ +#define H5_SZIP_CHIP_OPTION_MASK 2 +/** + * \ingroup SZIP */ +#define H5_SZIP_EC_OPTION_MASK 4 +/** + * \ingroup SZIP */ +#define H5_SZIP_NN_OPTION_MASK 32 +/** + * \ingroup SZIP */ +#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 /* Macros for the shuffle filter */ -#define H5Z_SHUFFLE_USER_NPARMS 0 /* Number of parameters that users can set */ -#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */ +/** + * \ingroup SHUFFLE + * Number of parameters that users can set for the shuffle filter + */ +#define H5Z_SHUFFLE_USER_NPARMS 0 +/** + * \ingroup SHUFFLE + * Total number of parameters for the shuffle filter + */ +#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Macros for the szip filter */ -#define H5Z_SZIP_USER_NPARMS 2 /* Number of parameters that users can set */ -#define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */ -#define H5Z_SZIP_PARM_MASK 0 /* "User" parameter for option mask */ -#define H5Z_SZIP_PARM_PPB 1 /* "User" parameter for pixels-per-block */ -#define H5Z_SZIP_PARM_BPP 2 /* "Local" parameter for bits-per-pixel */ -#define H5Z_SZIP_PARM_PPS 3 /* "Local" parameter for pixels-per-scanline */ +/** + * \ingroup SZIP + * Number of parameters that users can set for SZIP + */ +#define H5Z_SZIP_USER_NPARMS 2 +/** + * \ingroup SZIP + * Total number of parameters for SZIP filter + */ +#define H5Z_SZIP_TOTAL_NPARMS 4 +/** + * \ingroup SZIP + * "User" parameter for option mask + */ +#define H5Z_SZIP_PARM_MASK 0 +/** + * \ingroup SZIP + * "User" parameter for pixels-per-block + */ +#define H5Z_SZIP_PARM_PPB 1 +/** + * \ingroup SZIP + * "Local" parameter for bits-per-pixel + */ +#define H5Z_SZIP_PARM_BPP 2 +/** + * \ingroup SZIP + * "Local" parameter for pixels-per-scanline + */ +#define H5Z_SZIP_PARM_PPS 3 /* Macros for the nbit filter */ +/** + * \ingroup NBIT + * Number of parameters that users can set for the N-bit filter + */ #define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */ /* Macros for the scale offset filter */ -#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */ +/** + * \ingroup SCALEOFFSET + * Number of parameters that users can set for the scale-offset filter + */ +#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Special parameters for ScaleOffset filter*/ +/** + * \ingroup SCALEOFFSET */ #define H5Z_SO_INT_MINBITS_DEFAULT 0 +/** + * \ingroup SCALEOFFSET */ typedef enum H5Z_SO_scale_type_t { H5Z_SO_FLOAT_DSCALE = 0, H5Z_SO_FLOAT_ESCALE = 1, H5Z_SO_INT = 2 } H5Z_SO_scale_type_t; -/* Current version of the H5Z_class_t struct */ +/** + * Current version of the H5Z_class_t struct + */ #define H5Z_CLASS_T_VERS (1) -/* Values to decide if EDC is enabled for reading data */ +/** + * \ingroup FLETCHER32 + * Values to decide if EDC is enabled for reading data + */ typedef enum H5Z_EDC_t { - H5Z_ERROR_EDC = -1, /* error value */ - H5Z_DISABLE_EDC = 0, - H5Z_ENABLE_EDC = 1, - H5Z_NO_EDC = 2 /* must be the last */ + H5Z_ERROR_EDC = -1, /**< error value */ + H5Z_DISABLE_EDC = 0, + H5Z_ENABLE_EDC = 1, + H5Z_NO_EDC = 2 /**< sentinel */ } H5Z_EDC_t; /* Bit flags for H5Zget_filter_info */ #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001) #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002) -/* Return values for filter callback function */ +/** + * Return values for filter callback function + */ typedef enum H5Z_cb_return_t { - H5Z_CB_ERROR = -1, - H5Z_CB_FAIL = 0, /* I/O should fail if filter fails. */ - H5Z_CB_CONT = 1, /* I/O continues if filter fails. */ - H5Z_CB_NO = 2 + H5Z_CB_ERROR = -1, + H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */ + H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */ + H5Z_CB_NO = 2 } H5Z_cb_return_t; -/* Filter callback function definition */ +/** + * Filter callback function definition + */ typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data); -/* Structure for filter callback property */ +/** + * Structure for filter callback property + */ typedef struct H5Z_cb_t { H5Z_filter_func_t func; void * op_data; @@ -135,87 +253,376 @@ typedef struct H5Z_cb_t { extern "C" { #endif -/* - * Before a dataset gets created, the "can_apply" callbacks for any filters used - * in the dataset creation property list are called - * with the dataset's dataset creation property list, the dataset's datatype and - * a dataspace describing a chunk (for chunked dataset storage). +/** + * \details Before a dataset gets created, the \c can_apply callbacks for any + * filters used in the dataset creation property list are called with + * the dataset's dataset creation property list, the dataset's + * datatype and a dataspace describing a chunk (for chunked dataset + * storage). * - * The "can_apply" callback must determine if the combination of the dataset - * creation property list setting, the datatype and the dataspace represent a - * valid combination to apply this filter to. For example, some cases of - * invalid combinations may involve the filter not operating correctly on - * certain datatypes (or certain datatype sizes), or certain sizes of the chunk - * dataspace. + * The \c can_apply callback must determine if the combination of the + * dataset creation property list setting, the datatype and the + * dataspace represent a valid combination to apply this filter to. + * For example, some cases of invalid combinations may involve the + * filter not operating correctly on certain datatypes (or certain + * datatype sizes), or certain sizes of the chunk dataspace. * - * The "can_apply" callback can be the NULL pointer, in which case, the library - * will assume that it can apply to any combination of dataset creation - * property list values, datatypes and dataspaces. + * The \c can_apply callback can be the NULL pointer, in which case, + * the library will assume that it can apply to any combination of + * dataset creation property list values, datatypes and dataspaces. * - * The "can_apply" callback returns positive a valid combination, zero for an - * invalid combination and negative for an error. + * The \c can_apply callback returns positive a valid combination, + * zero for an invalid combination and negative for an error. */ +//! [H5Z_can_apply_func_t_snip] typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); - -/* - * After the "can_apply" callbacks are checked for new datasets, the "set_local" - * callbacks for any filters used in the dataset creation property list are - * called. These callbacks receive the dataset's private copy of the dataset - * creation property list passed in to H5Dcreate (i.e. not the actual property - * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate - * (which is not copied and should not be modified) and a dataspace describing - * the chunk (for chunked dataset storage) (which should also not be modified). +//! [H5Z_can_apply_func_t_snip] +/** + * \details After the "can_apply" callbacks are checked for new datasets, the + * \c set_local callbacks for any filters used in the dataset creation + * property list are called. These callbacks receive the dataset's + * private copy of the dataset creation property list passed in to + * H5Dcreate() (i.e. not the actual property list passed in to + * H5Dcreate()) and the datatype ID passed in to H5Dcreate() (which is + * not copied and should not be modified) and a dataspace describing + * the chunk (for chunked dataset storage) (which should also not be + * modified). * - * The "set_local" callback must set any parameters that are specific to this - * dataset, based on the combination of the dataset creation property list - * values, the datatype and the dataspace. For example, some filters perform - * different actions based on different datatypes (or datatype sizes) or - * different number of dimensions or dataspace sizes. + * The \c set_local callback must set any parameters that are specific + * to this dataset, based on the combination of the dataset creation + * property list values, the datatype and the dataspace. For example, + * some filters perform different actions based on different datatypes + * (or datatype sizes) or different number of dimensions or dataspace + * sizes. * - * The "set_local" callback can be the NULL pointer, in which case, the library - * will assume that there are no dataset-specific settings for this filter. + * The \c set_local callback can be the NULL pointer, in which case, + * the library will assume that there are no dataset-specific settings + * for this filter. * - * The "set_local" callback must return non-negative on success and negative - * for an error. + * The \c set_local callback must return non-negative on success and + * negative for an error. */ +//! [H5Z_set_local_func_t_snip] typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); - -/* - * A filter gets definition flags and invocation flags (defined above), the - * client data array and size defined when the filter was added to the - * pipeline, the size in bytes of the data on which to operate, and pointers - * to a buffer and its allocated size. +//! [H5Z_set_local_func_t_snip] +/** + * \details A filter gets definition flags and invocation flags (defined + * above), the client data array and size defined when the filter was + * added to the pipeline, the size in bytes of the data on which to + * operate, and pointers to a buffer and its allocated size. * - * The filter should store the result in the supplied buffer if possible, - * otherwise it can allocate a new buffer, freeing the original. The - * allocated size of the new buffer should be returned through the BUF_SIZE - * pointer and the new buffer through the BUF pointer. + * The filter should store the result in the supplied buffer if + * possible, otherwise it can allocate a new buffer, freeing the + * original. The allocated size of the new buffer should be returned + * through the \p buf_size pointer and the new buffer through the \p + * buf pointer. * - * The return value from the filter is the number of bytes in the output - * buffer. If an error occurs then the function should return zero and leave - * all pointer arguments unchanged. + * The return value from the filter is the number of bytes in the + * output buffer. If an error occurs then the function should return + * zero and leave all pointer arguments unchanged. */ +//! [H5Z_func_t_snip] typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, void **buf); - -/* +//! [H5Z_func_t_snip] +/** * The filter table maps filter identification numbers to structs that * contain a pointers to the filter function and timing statistics. */ +//! [H5Z_class2_t_snip] typedef struct H5Z_class2_t { - int version; /* Version number of the H5Z_class_t struct */ - H5Z_filter_t id; /* Filter ID number */ - unsigned encoder_present; /* Does this filter have an encoder? */ - unsigned decoder_present; /* Does this filter have a decoder? */ - const char * name; /* Comment for debugging */ - H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ - H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ - H5Z_func_t filter; /* The actual filter function */ + int version; /**< Version number of the H5Z_class_t struct */ + H5Z_filter_t id; /**< Filter ID number */ + unsigned encoder_present; /**< Does this filter have an encoder? */ + unsigned decoder_present; /**< Does this filter have a decoder? */ + const char * name; /**< Comment for debugging */ + H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ + H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */ + H5Z_func_t filter; /**< The actual filter function */ } H5Z_class2_t; +//! [H5Z_class2_t_snip] +/** + * \ingroup H5Z + * + * \brief Registers a new filter with the HDF5 library + * + * \param[in] cls A pointer to a buffer for the struct containing the + * filter-definition + * + * \return \herr_t + * + * \details H5Zregister() registers a new filter with the HDF5 library. + * + * \details Making a new filter available to an application is a two-step + * process. The first step is to write the three filter callback + * functions described below: \c can_apply, \c set_local, and \c + * filter. This call to H5Zregister(), registering the filter with the + * library, is the second step. The can_apply and set_local fields can + * be set to NULL if they are not required for the filter being + * registered. + * + * H5Zregister() accepts a single parameter, a pointer to a buffer for + * the \p cls data structure. That data structure must conform to one + * of the following definitions: + * \snippet this H5Z_class1_t_snip + * or + * \snippet this H5Z_class2_t_snip + * + * \c version is a library-defined value reporting the version number + * of the #H5Z_class_t struct. This currently must be set to + * #H5Z_CLASS_T_VERS. + * + * \c id is the identifier for the new filter. This is a user-defined + * value between #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX. These + * values are defined in the HDF5 source file H5Zpublic.h, but the + * symbols #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX should always be + * used instead of the literal values. + * + * \c encoder_present is a library-defined value indicating whether + * the filter’s encoding capability is available to the application. + * + * \c decoder_present is a library-defined value indicating whether + * the filter’s encoding capability is available to the application. + * + * \c name is a descriptive comment used for debugging, may contain a + * descriptive name for the filter, and may be the null pointer. + * + * \c can_apply, described in detail below, is a user-defined callback + * function which determines whether the combination of the dataset + * creation property list values, the datatype, and the dataspace + * represent a valid combination to apply this filter to. + * + * \c set_local, described in detail below, is a user-defined callback + * function which sets any parameters that are specific to this + * dataset, based on the combination of the dataset creation property + * list values, the datatype, and the dataspace. + * + * \c filter, described in detail below, is a user-defined callback + * function which performs the action of the filter. + * + * The statistics associated with a filter are not reset by this + * function; they accumulate over the life of the library. + * + * #H5Z_class_t is a macro which maps to either H5Z_class1_t or + * H5Z_class2_t, depending on the needs of the application. To affect + * only this macro, H5Z_class_t_vers may be defined to either 1 or 2. + * Otherwise, it will behave in the same manner as other API + * compatibility macros. See API Compatibility Macros in HDF5 for more + * information. H5Z_class1_t matches the #H5Z_class_t structure that is + * used in the 1.6.x versions of the HDF5 library. + * + * H5Zregister() will automatically detect which structure type has + * been passed in, regardless of the mapping of the #H5Z_class_t macro. + * However, the application must make sure that the fields are filled + * in according to the correct structure definition if the macro is + * used to declare the structure. + * + * \Bold{The callback functions:}\n Before H5Zregister() can link a + * filter into an application, three callback functions must be + * defined as described in the HDF5 library header file H5Zpublic.h. + * + * When a filter is applied to the fractal heap for a group (e.g., + * when compressing group metadata) and if the can apply and set local + * callback functions have been defined for that filter, HDF5 passes + * the value -1 for all parameters for those callback functions. This + * is done to ensure that the filter will not be applied to groups if + * it relies on these parameters, as they are not applicable to group + * fractal heaps; to operate on group fractal heaps, a filter must be + * capable of operating on an opaque block of binary data. + * + * The \Emph{can apply} callback function must return a positive value + * for a valid combination, zero for an invalid combination, and a + * negative value for an error. + * \snippet this H5Z_can_apply_func_t_snip + * + * Before a dataset is created, the \Emph{can apply} callbacks for any + * filters used in the dataset creation property list are called with + * the dataset's dataset creation property list, \c dcpl_id, the + * dataset's datatype, \p type_id, and a dataspace describing a chunk, + * \p space_id, (for chunked dataset storage). + * + * This callback must determine whether the combination of the dataset + * creation property list settings, the datatype, and the dataspace + * represent a valid combination to which to apply this filter. For + * example, an invalid combination may involve the filter not + * operating correctly on certain datatypes, on certain datatype + * sizes, or on certain sizes of the chunk dataspace. If this filter + * is enabled through H5Pset_filter() as optional and the can apply + * function returns 0, the library will skip the filter in the filter + * pipeline. + * + * This callback can be the NULL pointer, in which case the library + * will assume that the filter can be applied to a dataset with any + * combination of dataset creation property list values, datatypes, + * and dataspaces. + * + * The \Emph{set local} callback function is defined as follows: + * \snippet this H5Z_set_local_func_t_snip + * + * After the can apply callbacks are checked for a new dataset, the + * \Emph{set local} callback functions for any filters used in the + * dataset creation property list are called. These callbacks receive + * \c dcpl_id, the dataset's private copy of the dataset creation + * property list passed in to H5Dcreate() (i.e. not the actual + * property list passed in to H5Dcreate()); \c type_id, the datatype + * identifier passed in to H5Dcreate(), which is not copied and should + * not be modified; and \c space_id, a dataspace describing the chunk + * (for chunked dataset storage), which should also not be modified. + * + * The set local callback must set any filter parameters that are + * specific to this dataset, based on the combination of the dataset + * creation property list values, the datatype, and the dataspace. For + * example, some filters perform different actions based on different + * datatypes, datatype sizes, numbers of dimensions, or dataspace + * sizes. + * + * The \Emph{set local} callback may be the NULL pointer, in which + * case, the library will assume that there are no dataset-specific + * settings for this filter. + * + * The \Emph{set local} callback function must return a non-negative + * value on success and a negative value for an error. + * + * The \Emph{filter operation} callback function, defining the + * filter's operation on the data, is defined as follows: + * \snippet this H5Z_func_t_snip + * + * The parameters \c flags, \c cd_nelmts, and \c cd_values are the + * same as for the function H5Pset_filter(). The one exception is that + * an additional flag, #H5Z_FLAG_REVERSE, is set when the filter is + * called as part of the input pipeline. + * + * The parameter \c buf points to the input buffer which has a size of + * \c buf_size bytes, \c nbytes of which are valid data. + * + * The filter should perform the transformation in place if possible. + * If the transformation cannot be done in place, then the filter + * should allocate a new buffer with malloc() and assign it to \c buf, + * assigning the allocated size of that buffer to \c buf_size. The old + * buffer should be freed by calling free(). + * + * If successful, the \Emph{filter operation} callback function + * returns the number of valid bytes of data contained in \c buf. In + * the case of failure, the return value is 0 (zero) and all pointer + * arguments are left unchanged. + * + * \version 1.8.6 Return type for the \Emph{can apply} callback function, + * \ref H5Z_can_apply_func_t, changed to \ref htri_t. + * \version 1.8.5 Semantics of the \Emph{can apply} and \Emph{set local} + * callback functions changed to accommodate the use of filters + * with group fractal heaps. + * \version 1.8.3 #H5Z_class_t renamed to H5Z_class2_t, H5Z_class1_t structure + * introduced for backwards compatibility with release 1.6.x, + * and #H5Z_class_t macro introduced in this release. Function + * modified to accept either structure type. + * \version 1.8.0 The fields \c version, \c encoder_present, and + * \c decoder_present were added to the #H5Z_class_t \c struct + * in this release. + * \version 1.6.0 This function was substantially revised in Release 1.6.0 with + * a new #H5Z_class_t struct and new set local and can apply + * callback functions. + * + */ H5_DLL herr_t H5Zregister(const void *cls); +/** + * \ingroup H5Z + * + * \brief Unregisters a filter. + * + * \param[in] id Identifier of the filter to be unregistered. + * \return \herr_t + * + * \details H5Zunregister() unregisters the filter specified in \p id. + * + * \details This function first iterates through all opened datasets and + * groups. If an open object that uses this filter is found, the + * function will fail with a message indicating that an object using + * the filter is still open. All open files are then flushed to make + * sure that all cached data that may use this filter are written out. + * + * If the application is a parallel program, all processes that + * participate in collective data write should call this function to + * ensure that all data is flushed. + * + * After a call to H5Zunregister(), the filter specified in filter + * will no longer be available to the application. + * + * \version 1.8.12 Function modified to check for open objects using the + * filter. + * \since 1.6.0 + */ H5_DLL herr_t H5Zunregister(H5Z_filter_t id); +/** + * \ingroup H5Z + * + * \brief Determines whether a filter is available + * + * \param[in] id Filter identifier + * \return \htri_t + * + * \details H5Zfilter_avail() determines whether the filter specified in \p id + * is available to the application. + * + * \since 1.6.0 + */ H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); +/** + * \ingroup H5Z + * + * \brief Retrieves information about a filter + * + * \param[in] filter Filter identifier + * \param[out] filter_config_flags A bit field encoding the returned filter + * information + * \return \herr_t + * + * \details H5Zget_filter_info() retrieves information about a filter. At + * present, this means that the function retrieves a filter's + * configuration flags, indicating whether the filter is configured to + * decode data, to encode data, neither, or both. + * + * If \p filter_config_flags is not set to NULL prior to the function + * call, the returned parameter contains a bit field specifying the + * available filter configuration. The configuration flag values can + * then be determined through a series of bitwise AND operations, as + * described below. + * + * Valid filter configuration flags include the following: + * <table> + * <tr><td>#H5Z_FILTER_CONFIG_ENCODE_ENABLED</td> + * <td>Encoding is enabled for this filter</td></tr> + * <tr><td>#H5Z_FILTER_CONFIG_DECODE_ENABLED</td> + * <td>Decoding is enabled for this filter</td></tr> + * </table> + * + * A bitwise AND of the returned \p filter_config_flags and a valid + * filter configuration flag will reveal whether the related + * configuration option is available. For example, if the value of + * \code + * H5Z_FILTER_CONFIG_ENCODE_ENABLED & filter_config_flags + * \endcode + * is true, i.e., greater than 0 (zero), the queried filter + * is configured to encode data; if the value is \c FALSE, i.e., equal to + * 0 (zero), the filter is not so configured. + * + * If a filter is not encode-enabled, the corresponding \c H5Pset_* + * function will return an error if the filter is added to a dataset + * creation property list (which is required if the filter is to be + * used to encode that dataset). For example, if the + * #H5Z_FILTER_CONFIG_ENCODE_ENABLED flag is not returned for the SZIP + * filter, #H5Z_FILTER_SZIP, a call to H5Pset_szip() will fail. + * + * If a filter is not decode-enabled, the application will not be able + * to read an existing file encoded with that filter. + * + * This function should be called, and the returned \p + * filter_config_flags analyzed, before calling any other function, + * such as H5Pset_szip() , that might require a particular filter + * configuration. + * + * \since 1.6.3 + */ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags); /* Symbols defined for compatibility with previous versions of the HDF5 API. @@ -224,17 +631,19 @@ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_confi */ #ifndef H5_NO_DEPRECATED_SYMBOLS -/* +/** * The filter table maps filter identification numbers to structs that * contain a pointers to the filter function and timing statistics. */ +//! [H5Z_class1_t_snip] typedef struct H5Z_class1_t { - H5Z_filter_t id; /* Filter ID number */ - const char * name; /* Comment for debugging */ - H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ - H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ - H5Z_func_t filter; /* The actual filter function */ + H5Z_filter_t id; /**< Filter ID number */ + const char * name; /**< Comment for debugging */ + H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ + H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */ + H5Z_func_t filter; /**< The actual filter function */ } H5Z_class1_t; +//! [H5Z_class1_t_snip] #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Zshuffle.c b/src/H5Zshuffle.c index bd28f84..354d4df 100644 --- a/src/H5Zshuffle.c +++ b/src/H5Zshuffle.c @@ -123,7 +123,7 @@ H5Z__filter_shuffle(unsigned flags, size_t cd_nelmts, const unsigned cd_values[] size_t i; /* Local index variables */ #ifdef NO_DUFFS_DEVICE size_t j; /* Local index variable */ -#endif /* NO_DUFFS_DEVICE */ +#endif /* NO_DUFFS_DEVICE */ size_t leftover; /* Extra bytes at end of buffer */ size_t ret_value = 0; /* Return value */ @@ -165,7 +165,7 @@ H5Z__filter_shuffle(unsigned flags, size_t cd_nelmts, const unsigned cd_values[] j--; } /* end for */ -#else /* NO_DUFFS_DEVICE */ +#else /* NO_DUFFS_DEVICE */ { size_t duffs_index; /* Counting index for Duff's device */ @@ -177,31 +177,38 @@ H5Z__filter_shuffle(unsigned flags, size_t cd_nelmts, const unsigned cd_values[] case 0: do { DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 7: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 6: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 5: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 4: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 3: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 2: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 1: DUFF_GUTS } while (--duffs_index > 0); } /* end switch */ } -#endif /* NO_DUFFS_DEVICE */ +#endif /* NO_DUFFS_DEVICE */ #undef DUFF_GUTS } /* end for */ @@ -229,7 +236,7 @@ H5Z__filter_shuffle(unsigned flags, size_t cd_nelmts, const unsigned cd_values[] j--; } /* end for */ -#else /* NO_DUFFS_DEVICE */ +#else /* NO_DUFFS_DEVICE */ { size_t duffs_index; /* Counting index for Duff's device */ @@ -241,31 +248,38 @@ H5Z__filter_shuffle(unsigned flags, size_t cd_nelmts, const unsigned cd_values[] case 0: do { DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 7: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 6: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 5: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 4: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 3: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 2: DUFF_GUTS + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 1: DUFF_GUTS } while (--duffs_index > 0); } /* end switch */ } -#endif /* NO_DUFFS_DEVICE */ +#endif /* NO_DUFFS_DEVICE */ #undef DUFF_GUTS } /* end for */ diff --git a/src/H5Ztrans.c b/src/H5Ztrans.c index a61a52d..cde1862 100644 --- a/src/H5Ztrans.c +++ b/src/H5Ztrans.c @@ -1033,7 +1033,7 @@ H5Z_xform_eval(H5Z_data_xform_t *data_xform_prop, void *array, size_t array_size #if CHAR_MIN >= 0 else if (array_type == H5T_NATIVE_SCHAR) H5Z_XFORM_DO_OP5(signed char, array_size) -#else /* CHAR_MIN >= 0 */ +#else /* CHAR_MIN >= 0 */ else if (array_type == H5T_NATIVE_UCHAR) H5Z_XFORM_DO_OP5(unsigned char, array_size) #endif /* CHAR_MIN >= 0 */ diff --git a/src/H5checksum.c b/src/H5checksum.c index 7ae588e..82964d9 100644 --- a/src/H5checksum.c +++ b/src/H5checksum.c @@ -25,6 +25,7 @@ /****************/ /* Module Setup */ /****************/ +#include "H5module.h" /* This source code file is part of the H5 module */ /***********/ /* Headers */ @@ -379,7 +380,7 @@ uint32_t H5_checksum_lookup3(const void *key, size_t length, uint32_t initval) { const uint8_t *k = (const uint8_t *)key; - uint32_t a, b, c; /* internal state */ + uint32_t a, b, c = 0; /* internal state */ FUNC_ENTER_NOAPI_NOINIT_NOERR @@ -414,36 +415,47 @@ H5_checksum_lookup3(const void *key, size_t length, uint32_t initval) { case 12: c += ((uint32_t)k[11]) << 24; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 11: c += ((uint32_t)k[10]) << 16; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 10: c += ((uint32_t)k[9]) << 8; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 9: c += k[8]; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 8: b += ((uint32_t)k[7]) << 24; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 7: b += ((uint32_t)k[6]) << 16; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 6: b += ((uint32_t)k[5]) << 8; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 5: b += k[4]; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 4: a += ((uint32_t)k[3]) << 24; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 3: a += ((uint32_t)k[2]) << 16; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 2: a += ((uint32_t)k[1]) << 8; + /* FALLTHROUGH */ H5_ATTR_FALLTHROUGH case 1: a += k[0]; diff --git a/src/H5dbg.c b/src/H5dbg.c index 1b64d2c..5d38efc 100644 --- a/src/H5dbg.c +++ b/src/H5dbg.c @@ -25,6 +25,7 @@ /****************/ /* Module Setup */ /****************/ +#include "H5module.h" /* This source code file is part of the H5 module */ /***********/ /* Headers */ diff --git a/src/H5detect.c b/src/H5detect.c index 973cd97..e383d9b 100644 --- a/src/H5detect.c +++ b/src/H5detect.c @@ -1140,7 +1140,7 @@ print_header(void) #ifdef H5_HAVE_GETPWUID struct passwd *pwd = NULL; #else - int pwd = 1; + int pwd = 1; #endif static const char *month_name[] = {"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"}; diff --git a/src/H5err.txt b/src/H5err.txt index 24ac2ac..05476e5 100644 --- a/src/H5err.txt +++ b/src/H5err.txt @@ -46,6 +46,7 @@ MAJOR, H5E_ARGS, Invalid arguments to routine MAJOR, H5E_RESOURCE, Resource unavailable MAJOR, H5E_INTERNAL, Internal error (too specific to document in detail) +MAJOR, H5E_LIB, General library infrastructure MAJOR, H5E_FILE, File accessibility MAJOR, H5E_IO, Low-level I/O MAJOR, H5E_FUNC, Function entry/exit diff --git a/src/H5make_libsettings.c b/src/H5make_libsettings.c index 617d1f5..2afa531 100644 --- a/src/H5make_libsettings.c +++ b/src/H5make_libsettings.c @@ -144,7 +144,7 @@ print_header(void) #ifdef H5_HAVE_GETPWUID struct passwd *pwd = NULL; #else - int pwd = 1; + int pwd = 1; #endif static const char *month_name[] = {"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"}; diff --git a/src/H5module.h b/src/H5module.h new file mode 100644 index 0000000..2b7d858 --- /dev/null +++ b/src/H5module.h @@ -0,0 +1,34 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * Purpose: This file contains declarations which define macros for the + * H5 package. Including this header means that the source file + * is part of the H5 package. + */ +#ifndef _H5module_H +#define _H5module_H + +/* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error + * reporting macros. + */ +#define H5_MODULE +#define H5_MY_PKG H5 +#define H5_MY_PKG_ERR H5E_LIB +#define H5_MY_PKG_INIT YES + +/**\defgroup H5 H5 + * \brief General Library Functions + * \todo Describe concisely what the functions in this module are about. + */ + +#endif /* _H5module_H */ diff --git a/src/H5mpi.c b/src/H5mpi.c index c1f9132..613a4bf 100644 --- a/src/H5mpi.c +++ b/src/H5mpi.c @@ -25,7 +25,7 @@ /****************/ /* Local Macros */ /****************/ -#define TWO_GIG_LIMIT (1 << 31) +#define TWO_GIG_LIMIT INT32_MAX #ifndef H5_MAX_MPI_COUNT #define H5_MAX_MPI_COUNT (1 << 30) #endif @@ -33,7 +33,7 @@ /*******************/ /* Local Variables */ /*******************/ -static hsize_t bigio_count = H5_MAX_MPI_COUNT; +static hsize_t bigio_count_g = H5_MAX_MPI_COUNT; /*------------------------------------------------------------------------- * Function: H5_mpi_set_bigio_count @@ -42,7 +42,7 @@ static hsize_t bigio_count = H5_MAX_MPI_COUNT; * when we utilize derived datatypes. This is of * particular interest for allowing nightly testing * - * Return: The current/previous value of bigio_count. + * Return: The current/previous value of bigio_count_g. * * Programmer: Richard Warren, March 10, 2017 * @@ -51,10 +51,10 @@ static hsize_t bigio_count = H5_MAX_MPI_COUNT; hsize_t H5_mpi_set_bigio_count(hsize_t new_count) { - hsize_t orig_count = bigio_count; + hsize_t orig_count = bigio_count_g; if ((new_count > 0) && (new_count < (hsize_t)TWO_GIG_LIMIT)) { - bigio_count = new_count; + bigio_count_g = new_count; } return orig_count; } /* end H5_mpi_set_bigio_count() */ @@ -63,9 +63,9 @@ H5_mpi_set_bigio_count(hsize_t new_count) * Function: H5_mpi_get_bigio_count * * Purpose: Allow other HDF5 library functions to access - * the current value for bigio_count. + * the current value for bigio_count_g. * - * Return: The current/previous value of bigio_count. + * Return: The current/previous value of bigio_count_g. * * Programmer: Richard Warren, October 7, 2019 * @@ -74,7 +74,7 @@ H5_mpi_set_bigio_count(hsize_t new_count) hsize_t H5_mpi_get_bigio_count(void) { - return bigio_count; + return bigio_count_g; } /*------------------------------------------------------------------------- @@ -471,8 +471,8 @@ H5_mpio_create_large_type(hsize_t num_elements, MPI_Aint stride_bytes, MPI_Datat FUNC_ENTER_NOAPI(FAIL) /* Calculate how many Big MPI datatypes are needed to represent the buffer */ - num_big_types = (int)(num_elements / bigio_count); - leftover = (hsize_t)num_elements - (hsize_t)num_big_types * bigio_count; + num_big_types = (int)(num_elements / bigio_count_g); + leftover = (hsize_t)num_elements - (hsize_t)num_big_types * bigio_count_g; H5_CHECKED_ASSIGN(remaining_bytes, int, leftover, hsize_t); /* Create a contiguous datatype of size equal to the largest @@ -481,11 +481,11 @@ H5_mpio_create_large_type(hsize_t num_elements, MPI_Aint stride_bytes, MPI_Datat * use type_hvector to create the type with the displacement provided */ if (0 == stride_bytes) { - if (MPI_SUCCESS != (mpi_code = MPI_Type_contiguous((int)bigio_count, old_type, &inner_type))) + if (MPI_SUCCESS != (mpi_code = MPI_Type_contiguous((int)bigio_count_g, old_type, &inner_type))) HMPI_GOTO_ERROR(FAIL, "MPI_Type_contiguous failed", mpi_code) } /* end if */ else if (MPI_SUCCESS != - (mpi_code = MPI_Type_create_hvector((int)bigio_count, 1, stride_bytes, old_type, &inner_type))) + (mpi_code = MPI_Type_create_hvector((int)bigio_count_g, 1, stride_bytes, old_type, &inner_type))) HMPI_GOTO_ERROR(FAIL, "MPI_Type_create_hvector failed", mpi_code) /* Create a contiguous datatype of the buffer (minus the remaining < 2GB part) @@ -510,7 +510,7 @@ H5_mpio_create_large_type(hsize_t num_elements, MPI_Aint stride_bytes, MPI_Datat HMPI_GOTO_ERROR(FAIL, "MPI_Type_contiguous failed", mpi_code) } /* end if */ else if (MPI_SUCCESS != (mpi_code = MPI_Type_create_hvector( - (int)(num_elements - (hsize_t)num_big_types * bigio_count), 1, + (int)(num_elements - (hsize_t)num_big_types * bigio_count_g), 1, stride_bytes, old_type, &leftover_type))) HMPI_GOTO_ERROR(FAIL, "MPI_Type_create_hvector failed", mpi_code) @@ -529,7 +529,7 @@ H5_mpio_create_large_type(hsize_t num_elements, MPI_Aint stride_bytes, MPI_Datat block_len[0] = 1; block_len[1] = 1; disp[0] = 0; - disp[1] = (old_extent + stride_bytes) * num_big_types * (MPI_Aint)bigio_count; + disp[1] = (old_extent + stride_bytes) * num_big_types * (MPI_Aint)bigio_count_g; if (MPI_SUCCESS != (mpi_code = MPI_Type_create_struct(2, block_len, disp, type, new_type))) HMPI_GOTO_ERROR(FAIL, "MPI_Type_create_struct failed", mpi_code) diff --git a/src/H5private.h b/src/H5private.h index ca005f6..2d90766 100644 --- a/src/H5private.h +++ b/src/H5private.h @@ -298,6 +298,10 @@ * Note that Solaris Studio supports attribute, but does not support the * attributes we use. * + * When using H5_ATTR_FALLTHROUGH, you should also include a comment that + * says FALLTHROUGH to reduce warnings on compilers that don't use + * attributes but do respect fall-through comments. + * * H5_ATTR_CONST is redefined in tools/h5repack/dynlib_rpk.c to quiet * gcc warnings (it has to use the public API and can't include this * file). Be sure to update that file if the #ifdefs change here. @@ -476,11 +480,11 @@ typedef unsigned char uint8_t; #if H5_SIZEOF_INT16_T >= 2 #elif H5_SIZEOF_SHORT >= 2 -typedef short int16_t; +typedef short int16_t; #undef H5_SIZEOF_INT16_T #define H5_SIZEOF_INT16_T H5_SIZEOF_SHORT #elif H5_SIZEOF_INT >= 2 -typedef int int16_t; +typedef int int16_t; #undef H5_SIZEOF_INT16_T #define H5_SIZEOF_INT16_T H5_SIZEOF_INT #else @@ -502,11 +506,11 @@ typedef unsigned uint16_t; #if H5_SIZEOF_INT32_T >= 4 #elif H5_SIZEOF_SHORT >= 4 -typedef short int32_t; +typedef short int32_t; #undef H5_SIZEOF_INT32_T #define H5_SIZEOF_INT32_T H5_SIZEOF_SHORT #elif H5_SIZEOF_INT >= 4 -typedef int int32_t; +typedef int int32_t; #undef H5_SIZEOF_INT32_T #define H5_SIZEOF_INT32_T H5_SIZEOF_INT #elif H5_SIZEOF_LONG >= 4 @@ -678,7 +682,7 @@ typedef struct { #endif /* HDabs */ #ifndef HDaccept #define HDaccept(A, B, C) accept((A), (B), (C)) /* mirror VFD */ -#endif /* HDaccept */ +#endif /* HDaccept */ #ifndef HDaccess #define HDaccess(F, M) access(F, M) #endif /* HDaccess */ @@ -705,7 +709,7 @@ typedef struct { #endif /* HDasin */ #ifndef HDasprintf #define HDasprintf asprintf /*varargs*/ -#endif /* HDasprintf */ +#endif /* HDasprintf */ #ifndef HDassert #define HDassert(X) assert(X) #endif /* HDassert */ @@ -732,7 +736,7 @@ typedef struct { #endif /* HDatol */ #ifndef HDbind #define HDbind(A, B, C) bind((A), (B), (C)) /* mirror VFD */ -#endif /* HDbind */ +#endif /* HDbind */ #ifndef HDbsearch #define HDbsearch(K, B, N, Z, F) bsearch(K, B, N, Z, F) #endif /* HDbsearch */ @@ -780,7 +784,7 @@ typedef struct { #endif /* HDclosedir */ #ifndef HDconnect #define HDconnect(A, B, C) connect((A), (B), (C)) /* mirror VFD */ -#endif /* HDconnect */ +#endif /* HDconnect */ #ifndef HDcos #define HDcos(X) cos(X) #endif /* HDcos */ @@ -1029,7 +1033,7 @@ typedef off_t h5_stat_size_t; #endif /* HDgetgroups */ #ifndef HDgethostbyaddr #define HDgethostbyaddr(A, B, C) gethostbyaddr((A), (B), (C)) /* mirror VFD */ -#endif /* HDgethostbyaddr */ +#endif /* HDgethostbyaddr */ #ifndef HDgethostname #define HDgethostname(N, L) gethostname(N, L) #endif /* HDgethostname */ @@ -1071,55 +1075,55 @@ typedef off_t h5_stat_size_t; #endif /* HDgmtime */ #ifndef HDhtonl #define HDhtonl(X) htonl((X)) /* mirror VFD */ -#endif /* HDhtonl */ +#endif /* HDhtonl */ #ifndef HDhtons #define HDhtons(X) htons((X)) /* mirror VFD */ -#endif /* HDhtons */ +#endif /* HDhtons */ #ifndef HDinet_addr #define HDinet_addr(C) inet_addr((C)) /* mirror VFD */ -#endif /* HDinet_addr */ +#endif /* HDinet_addr */ #ifndef HDinet_ntoa #define HDinet_ntoa(C) inet_ntoa((C)) /* mirror VFD */ -#endif /* HDinet_ntoa */ +#endif /* HDinet_ntoa */ #ifndef HDisalnum #define HDisalnum(C) isalnum((int)(C)) /*cast for solaris warning*/ -#endif /* HDisalnum */ +#endif /* HDisalnum */ #ifndef HDisalpha #define HDisalpha(C) isalpha((int)(C)) /*cast for solaris warning*/ -#endif /* HDisalpha */ +#endif /* HDisalpha */ #ifndef HDisatty #define HDisatty(F) isatty(F) #endif /* HDisatty */ #ifndef HDiscntrl #define HDiscntrl(C) iscntrl((int)(C)) /*cast for solaris warning*/ -#endif /* HDiscntrl */ +#endif /* HDiscntrl */ #ifndef HDisdigit #define HDisdigit(C) isdigit((int)(C)) /*cast for solaris warning*/ -#endif /* HDisdigit */ +#endif /* HDisdigit */ #ifndef HDisgraph #define HDisgraph(C) isgraph((int)(C)) /*cast for solaris warning*/ -#endif /* HDisgraph */ +#endif /* HDisgraph */ #ifndef HDislower #define HDislower(C) islower((int)(C)) /*cast for solaris warning*/ -#endif /* HDislower */ +#endif /* HDislower */ #ifndef HDisnan #define HDisnan(X) isnan(X) #endif /* HDisnan */ #ifndef HDisprint #define HDisprint(C) isprint((int)(C)) /*cast for solaris warning*/ -#endif /* HDisprint */ +#endif /* HDisprint */ #ifndef HDispunct #define HDispunct(C) ispunct((int)(C)) /*cast for solaris warning*/ -#endif /* HDispunct */ +#endif /* HDispunct */ #ifndef HDisspace #define HDisspace(C) isspace((int)(C)) /*cast for solaris warning*/ -#endif /* HDisspace */ +#endif /* HDisspace */ #ifndef HDisupper #define HDisupper(C) isupper((int)(C)) /*cast for solaris warning*/ -#endif /* HDisupper */ +#endif /* HDisupper */ #ifndef HDisxdigit #define HDisxdigit(C) isxdigit((int)(C)) /*cast for solaris warning*/ -#endif /* HDisxdigit */ +#endif /* HDisxdigit */ #ifndef HDkill #define HDkill(P, S) kill(P, S) #endif /* HDkill */ @@ -1137,7 +1141,7 @@ typedef off_t h5_stat_size_t; #endif /* HDlink */ #ifndef HDlisten #define HDlisten(A, B) listen((A), (B)) /* mirror VFD */ -#endif /* HDlisten */ +#endif /* HDlisten */ #ifndef HDllround #define HDllround(V) llround(V) #endif /* HDround */ @@ -1221,10 +1225,10 @@ typedef off_t h5_stat_size_t; #endif /* HDnanosleep */ #ifndef HDntohl #define HDntohl(A) ntohl((A)) /* mirror VFD */ -#endif /* HDntohl */ +#endif /* HDntohl */ #ifndef HDntohs #define HDntohs(A) ntohs((A)) /* mirror VFD */ -#endif /* HDntohs */ +#endif /* HDntohs */ #ifndef HDopen #define HDopen(F, ...) open(F, __VA_ARGS__) #endif /* HDopen */ @@ -1255,6 +1259,57 @@ typedef off_t h5_stat_size_t; #ifndef HDprintf #define HDprintf printf #endif /* HDprintf */ +#ifndef HDpthread_attr_destroy +#define HDpthread_attr_destroy(A) pthread_attr_destroy(A) +#endif /* HDpthread_attr_destroy */ +#ifndef HDpthread_attr_init +#define HDpthread_attr_init(A) pthread_attr_init(A) +#endif /* HDpthread_attr_init */ +#ifndef HDpthread_attr_setscope +#define HDpthread_attr_setscope(A, S) pthread_attr_setscope(A, S) +#endif /* HDpthread_attr_setscope */ +#ifndef HDpthread_cond_init +#define HDpthread_cond_init(C, A) pthread_cond_init(C, A) +#endif /* HDpthread_cond_init */ +#ifndef HDpthread_cond_signal +#define HDpthread_cond_signal(C) pthread_cond_signal(C) +#endif /* HDpthread_cond_signal */ +#ifndef HDpthread_cond_wait +#define HDpthread_cond_wait(C, M) pthread_cond_wait(C, M) +#endif /* HDpthread_cond_wait */ +#ifndef HDpthread_create +#define HDpthread_create(R, A, F, U) pthread_create(R, A, F, U) +#endif /* HDpthread_create */ +#ifndef HDpthread_equal +#define HDpthread_equal(T1, T2) pthread_equal(T1, T2) +#endif /* HDpthread_equal */ +#ifndef HDpthread_getspecific +#define HDpthread_getspecific(K) pthread_getspecific(K) +#endif /* HDpthread_getspecific */ +#ifndef HDpthread_join +#define HDpthread_join(T, V) pthread_join(T, V) +#endif /* HDpthread_join */ +#ifndef HDpthread_key_create +#define HDpthread_key_create(K, D) pthread_key_create(K, D) +#endif /* HDpthread_key_create */ +#ifndef HDpthread_mutex_init +#define HDpthread_mutex_init(M, A) pthread_mutex_init(M, A) +#endif /* HDpthread_mutex_init */ +#ifndef HDpthread_mutex_lock +#define HDpthread_mutex_lock(M) pthread_mutex_lock(M) +#endif /* HDpthread_mutex_lock */ +#ifndef HDpthread_mutex_unlock +#define HDpthread_mutex_unlock(M) pthread_mutex_unlock(M) +#endif /* HDpthread_mutex_unlock */ +#ifndef HDpthread_self +#define HDpthread_self() pthread_self() +#endif /* HDpthread_self */ +#ifndef HDpthread_setcancelstate +#define HDpthread_setcancelstate(N, O) pthread_setcancelstate(N, O) +#endif /* HDpthread_setcancelstate */ +#ifndef HDpthread_setspecific +#define HDpthread_setspecific(K, V) pthread_setspecific(K, V) +#endif /* HDpthread_setspecific */ #ifndef HDputc #define HDputc(C, F) putc(C, F) #endif /* HDputc*/ @@ -1296,7 +1351,7 @@ H5_DLL void HDsrand(unsigned int seed); #ifndef HDsrandom #define HDsrandom(S) srandom(S) #endif /* HDsrandom */ -#else /* H5_HAVE_RANDOM */ +#else /* H5_HAVE_RANDOM */ #ifndef HDrand #define HDrand() rand() #endif /* HDrand */ @@ -1374,7 +1429,7 @@ H5_DLL void HDsrand(unsigned int seed); #endif /* HDsetsid */ #ifndef HDsetsockopt #define HDsetsockopt(A, B, C, D, E) setsockopt((A), (B), (C), (D), (E)) /* mirror VFD */ -#endif /* HDsetsockopt */ +#endif /* HDsetsockopt */ #ifndef HDsetuid #define HDsetuid(U) setuid(U) #endif /* HDsetuid */ @@ -1383,7 +1438,7 @@ H5_DLL void HDsrand(unsigned int seed); #endif /* HDsetvbuf */ #ifndef HDshutdown #define HDshutdown(A, B) shutdown((A), (B)) /* mirror VFD */ -#endif /* HDshutdown */ +#endif /* HDshutdown */ #ifndef HDsigaction #define HDsigaction(S, A, O) sigaction((S), (A), (O)) #endif /* HDsigaction */ @@ -1431,13 +1486,13 @@ H5_DLL void HDsrand(unsigned int seed); #endif /* HDsleep */ #ifndef HDsnprintf #define HDsnprintf snprintf /*varargs*/ -#endif /* HDsnprintf */ +#endif /* HDsnprintf */ #ifndef HDsocket #define HDsocket(A, B, C) socket((A), (B), (C)) /* mirror VFD */ -#endif /* HDsocket */ +#endif /* HDsocket */ #ifndef HDsprintf #define HDsprintf sprintf /*varargs*/ -#endif /* HDsprintf */ +#endif /* HDsprintf */ #ifndef HDsqrt #define HDsqrt(X) sqrt(X) #endif /* HDsqrt */ @@ -1651,7 +1706,7 @@ H5_DLL int64_t HDstrtoll(const char *s, const char **rest, int base); * define these in terms of macros. */ #if !defined strdup && !defined H5_HAVE_STRDUP -extern char * strdup(const char *s); +extern char *strdup(const char *s); #endif #ifndef HDstrdup @@ -1937,9 +1992,33 @@ extern char H5libhdf5_settings[]; /* embedded library information */ #define H5TRACE11(R, T, A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10) /*void*/ #define H5TRACE12(R, T, A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11) /*void*/ #define H5TRACE_RETURN(V) /*void*/ -#endif /* H5_DEBUG_API */ +#endif /* H5_DEBUG_API */ +/* Argument tracing macros (defined all the time) */ +#define H5ARG_TRACE0(C, T) C, T +#define H5ARG_TRACE1(C, T, A0) C, T, #A0, A0 +#define H5ARG_TRACE2(C, T, A0, A1) C, T, #A0, A0, #A1, A1 +#define H5ARG_TRACE3(C, T, A0, A1, A2) C, T, #A0, A0, #A1, A1, #A2, A2 +#define H5ARG_TRACE4(C, T, A0, A1, A2, A3) C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3 +#define H5ARG_TRACE5(C, T, A0, A1, A2, A3, A4) C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4 +#define H5ARG_TRACE6(C, T, A0, A1, A2, A3, A4, A5) C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4, #A5, A5 +#define H5ARG_TRACE7(C, T, A0, A1, A2, A3, A4, A5, A6) \ + C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4, #A5, A5, #A6, A6 +#define H5ARG_TRACE8(C, T, A0, A1, A2, A3, A4, A5, A6, A7) \ + C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4, #A5, A5, #A6, A6, #A7, A7 +#define H5ARG_TRACE9(C, T, A0, A1, A2, A3, A4, A5, A6, A7, A8) \ + C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4, #A5, A5, #A6, A6, #A7, A7, #A8, A8 +#define H5ARG_TRACE10(C, T, A0, A1, A2, A3, A4, A5, A6, A7, A8, A9) \ + C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4, #A5, A5, #A6, A6, #A7, A7, #A8, A8, #A9, A9 +#define H5ARG_TRACE11(C, T, A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10) \ + C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4, #A5, A5, #A6, A6, #A7, A7, #A8, A8, #A9, A9, #A10, A10 +#define H5ARG_TRACE12(C, T, A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11) \ + C, T, #A0, A0, #A1, A1, #A2, A2, #A3, A3, #A4, A4, #A5, A5, #A6, A6, #A7, A7, #A8, A8, #A9, A9, #A10, \ + A10, #A11, A11 + +struct H5RS_str_t; H5_DLL double H5_trace(const double *calltime, const char *func, const char *type, ...); +H5_DLL herr_t H5_trace_args(struct H5RS_str_t *rs, const char *type, va_list ap); /*------------------------------------------------------------------------- * Purpose: Register function entry for library initialization and code @@ -2067,10 +2146,10 @@ extern hbool_t H5_libterm_g; /* Is the library being shutdown? */ #define H5_PUSH_FUNC H5CS_push(FUNC); #define H5_POP_FUNC H5CS_pop(); -#else /* H5_HAVE_CODESTACK */ +#else /* H5_HAVE_CODESTACK */ #define H5_PUSH_FUNC /* void */ #define H5_POP_FUNC /* void */ -#endif /* H5_HAVE_CODESTACK */ +#endif /* H5_HAVE_CODESTACK */ #ifdef H5_HAVE_MPE extern hbool_t H5_MPEinit_g; /* Has the MPE Library been initialized? */ @@ -2123,7 +2202,7 @@ H5_DLL herr_t H5CX_pop(void); func_check = TRUE; \ } /* end if */ \ } /* end scope */ -#else /* NDEBUG */ +#else /* NDEBUG */ #define FUNC_ENTER_CHECK_NAME(asrt) #endif /* NDEBUG */ @@ -2156,7 +2235,6 @@ H5_DLL herr_t H5CX_pop(void); #define FUNC_ENTER_API_INIT(err) \ /* Initialize the library */ \ if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) { \ - H5_INIT_GLOBAL = TRUE; \ if (H5_init_library() < 0) \ HGOTO_ERROR(H5E_FUNC, H5E_CANTINIT, err, "library initialization failed") \ } /* end if */ \ @@ -2248,6 +2326,23 @@ H5_DLL herr_t H5CX_pop(void); FUNC_ENTER_API_INIT(err); \ { +/* + * Use this macro for API functions that shouldn't perform _any_ initialization + * of the library or an interface, or push themselves on the function + * stack, or perform tracing, etc. This macro _only_ sanity checks the + * API name itself. Examples are: H5TSmutex_acquire, + * + */ +#define FUNC_ENTER_API_NAMECHECK_ONLY \ + { \ + { \ + { \ + { \ + { \ + { \ + FUNC_ENTER_COMMON_NOERR(H5_IS_API(FUNC)); \ + { + /* Note: this macro only works when there's _no_ interface initialization routine for the module */ #define FUNC_ENTER_NOAPI_INIT(err) \ /* Initialize the package, if appropriate */ \ @@ -2327,6 +2422,17 @@ H5_DLL herr_t H5CX_pop(void); FUNC_ENTER_COMMON_NOERR(!H5_IS_API(FUNC)); \ if (H5_PKG_INIT_VAR || !H5_TERM_GLOBAL) { +/* + * Use this macro for non-API functions that shouldn't perform _any_ initialization + * of the library or an interface, or push themselves on the function + * stack, or perform tracing, etc. This macro _only_ sanity checks the + * API name itself. Examples are private routines in the H5TS package. + * + */ +#define FUNC_ENTER_NOAPI_NAMECHECK_ONLY \ + { \ + FUNC_ENTER_COMMON_NOERR(!H5_IS_API(FUNC)); + /* Use the following two macros as replacements for the FUNC_ENTER_NOAPI * and FUNC_ENTER_NOAPI_NOINIT macros when the function needs to set * up a metadata tag. */ @@ -2394,6 +2500,17 @@ H5_DLL herr_t H5CX_pop(void); FUNC_ENTER_COMMON_NOERR(H5_IS_PKG(FUNC)); \ if (H5_PKG_INIT_VAR || !H5_TERM_GLOBAL) { +/* + * Use this macro for non-API functions that shouldn't perform _any_ initialization + * of the library or an interface, or push themselves on the function + * stack, or perform tracing, etc. This macro _only_ sanity checks the + * API name itself. Examples are static routines in the H5TS package. + * + */ +#define FUNC_ENTER_STATIC_NAMECHECK_ONLY \ + { \ + FUNC_ENTER_COMMON_NOERR(H5_IS_PKG(FUNC)); + /* Use the following macro as replacement for the FUNC_ENTER_STATIC * macro when the function needs to set up a metadata tag. */ #define FUNC_ENTER_STATIC_TAG(tag) \ @@ -2471,6 +2588,18 @@ H5_DLL herr_t H5CX_pop(void); } \ } /*end scope from beginning of FUNC_ENTER*/ +/* Use this macro to match the FUNC_ENTER_API_NAMECHECK_ONLY macro */ +#define FUNC_LEAVE_API_NAMECHECK_ONLY(ret_value) \ + ; \ + } /*end scope from end of FUNC_ENTER*/ \ + return (ret_value); \ + } \ + } \ + } \ + } \ + } \ + } /*end scope from beginning of FUNC_ENTER*/ + #define FUNC_LEAVE_NOAPI(ret_value) \ ; \ } /*end scope from end of FUNC_ENTER*/ \ @@ -2496,6 +2625,14 @@ H5_DLL herr_t H5CX_pop(void); return (ret_value); \ } /*end scope from beginning of FUNC_ENTER*/ +/* Use these macros to match the FUNC_ENTER_NOAPI_NAMECHECK_ONLY macro */ +#define FUNC_LEAVE_NOAPI_NAMECHECK_ONLY(ret_value) \ + return (ret_value); \ + } /*end scope from beginning of FUNC_ENTER*/ +#define FUNC_LEAVE_NOAPI_VOID_NAMECHECK_ONLY \ + return; \ + } /*end scope from beginning of FUNC_ENTER*/ + /* Use this macro when exiting a function that set up a metadata tag */ #define FUNC_LEAVE_NOAPI_TAG(ret_value) \ ; \ @@ -2599,7 +2736,6 @@ extern hbool_t H5_api_entered_g; /* Has library already been entered through API \ /* Initialize the library or bust */ \ if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) { \ - H5_INIT_GLOBAL = TRUE; \ if (H5_init_library() < 0) { \ /* (Can't use H5E_THROW here) */ \ H5E_PRINTF(H5E_CANTINIT, "interface initialization failed"); \ diff --git a/src/H5public.h b/src/H5public.h index 5b9a5fe..20a7dc1 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -176,15 +176,15 @@ typedef long long ssize_t; */ #if H5_SIZEOF_INT64_T >= 8 #elif H5_SIZEOF_INT >= 8 -typedef int int64_t; +typedef int int64_t; #undef H5_SIZEOF_INT64_T #define H5_SIZEOF_INT64_T H5_SIZEOF_INT #elif H5_SIZEOF_LONG >= 8 -typedef long int64_t; +typedef long int64_t; #undef H5_SIZEOF_INT64_T #define H5_SIZEOF_INT64_T H5_SIZEOF_LONG #elif H5_SIZEOF_LONG_LONG >= 8 -typedef long long int64_t; +typedef long long int64_t; #undef H5_SIZEOF_INT64_T #define H5_SIZEOF_INT64_T H5_SIZEOF_LONG_LONG #else @@ -199,12 +199,12 @@ typedef long long int64_t; #define UINT64_MAX ((uint64_t)-1) #endif #elif H5_SIZEOF_INT >= 8 -typedef unsigned uint64_t; +typedef unsigned uint64_t; #define UINT64_MAX UINT_MAX #undef H5_SIZEOF_UINT64_T #define H5_SIZEOF_UINT64_T H5_SIZEOF_INT #elif H5_SIZEOF_LONG >= 8 -typedef unsigned long uint64_t; +typedef unsigned long uint64_t; #define UINT64_MAX ULONG_MAX #undef H5_SIZEOF_UINT64_T #define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG @@ -289,30 +289,36 @@ typedef unsigned long long haddr_t; */ #if H5_SIZEOF_UINT32_T >= 4 #elif H5_SIZEOF_SHORT >= 4 -typedef short uint32_t; +typedef short uint32_t; #undef H5_SIZEOF_UINT32_T #define H5_SIZEOF_UINT32_T H5_SIZEOF_SHORT #elif H5_SIZEOF_INT >= 4 -typedef unsigned int uint32_t; +typedef unsigned int uint32_t; #undef H5_SIZEOF_UINT32_T #define H5_SIZEOF_UINT32_T H5_SIZEOF_INT #elif H5_SIZEOF_LONG >= 4 -typedef unsigned long uint32_t; +typedef unsigned long uint32_t; #undef H5_SIZEOF_UINT32_T #define H5_SIZEOF_UINT32_T H5_SIZEOF_LONG #else #error "nothing appropriate for uint32_t" #endif -/* Common iteration orders */ +//! [H5_iter_order_t_snip] + +/** + * Common iteration orders + */ typedef enum { - H5_ITER_UNKNOWN = -1, /* Unknown order */ - H5_ITER_INC, /* Increasing order */ - H5_ITER_DEC, /* Decreasing order */ - H5_ITER_NATIVE, /* No particular order, whatever is fastest */ - H5_ITER_N /* Number of iteration orders */ + H5_ITER_UNKNOWN = -1, /**< Unknown order */ + H5_ITER_INC, /**< Increasing order */ + H5_ITER_DEC, /**< Decreasing order */ + H5_ITER_NATIVE, /**< No particular order, whatever is fastest */ + H5_ITER_N /**< Number of iteration orders */ } H5_iter_order_t; +//! [H5_iter_order_t_snip] + /* Iteration callback values */ /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) @@ -321,66 +327,473 @@ typedef enum { #define H5_ITER_CONT (0) #define H5_ITER_STOP (1) -/* +//! [H5_index_t_snip] + +/** * The types of indices on links in groups/attributes on objects. * Primarily used for "<do> <foo> by index" routines and for iterating over * links in groups/attributes on objects. */ typedef enum H5_index_t { - H5_INDEX_UNKNOWN = -1, /* Unknown index type */ - H5_INDEX_NAME, /* Index on names */ - H5_INDEX_CRT_ORDER, /* Index on creation order */ - H5_INDEX_N /* Number of indices defined */ + H5_INDEX_UNKNOWN = -1, /**< Unknown index type */ + H5_INDEX_NAME, /**< Index on names */ + H5_INDEX_CRT_ORDER, /**< Index on creation order */ + H5_INDEX_N /**< Number of indices defined */ } H5_index_t; -/* +//! [H5_index_t_snip] + +/** * Storage info struct used by H5O_info_t and H5F_info_t */ +//! [H5_ih_info_t_snip] typedef struct H5_ih_info_t { - hsize_t index_size; /* btree and/or list */ + hsize_t index_size; /**< btree and/or list */ hsize_t heap_size; } H5_ih_info_t; +//! [H5_ih_info_t_snip] -/* Tokens are unique and permanent identifiers that are - * used to reference HDF5 objects in a container. */ +/** + * The maximum size allowed for tokens + * \details Tokens are unique and permanent identifiers that are + * used to reference HDF5 objects in a container. This allows + * for 128-bit tokens + */ +#define H5O_MAX_TOKEN_SIZE (16) -/* The maximum size allowed for tokens */ -#define H5O_MAX_TOKEN_SIZE (16) /* Allows for 128-bit tokens */ +//! [H5O_token_t_snip] +/** + * \internal (Hoisted here, since it's used by both the + * H5Lpublic.h and H5Opublic.h headers) */ /* Type for object tokens */ -/* (Hoisted here, since it's used by both the H5Lpublic.h and H5Opublic.h headers) */ typedef struct H5O_token_t { uint8_t __data[H5O_MAX_TOKEN_SIZE]; } H5O_token_t; -/* +//! [H5O_token_t_snip] + +/** * Allocation statistics info struct */ typedef struct H5_alloc_stats_t { - unsigned long long total_alloc_bytes; /* Running count of total # of bytes allocated */ - size_t curr_alloc_bytes; /* Current # of bytes allocated */ - size_t peak_alloc_bytes; /* Peak # of bytes allocated */ - size_t max_block_size; /* Largest block allocated */ - size_t total_alloc_blocks_count; /* Running count of total # of blocks allocated */ - size_t curr_alloc_blocks_count; /* Current # of blocks allocated */ - size_t peak_alloc_blocks_count; /* Peak # of blocks allocated */ + unsigned long long total_alloc_bytes; /**< Running count of total # of bytes allocated */ + size_t curr_alloc_bytes; /**< Current # of bytes allocated */ + size_t peak_alloc_bytes; /**< Peak # of bytes allocated */ + size_t max_block_size; /**< Largest block allocated */ + size_t total_alloc_blocks_count; /**< Running count of total # of blocks allocated */ + size_t curr_alloc_blocks_count; /**< Current # of blocks allocated */ + size_t peak_alloc_blocks_count; /**< Peak # of blocks allocated */ } H5_alloc_stats_t; /* Functions in H5.c */ +/** + * \ingroup H5 + * \brief Initializes the HDF5 library + * \return \herr_t + * + * \details H5open() initializes the HDF5 library. + * + * \details When the HDF5 library is used in a C application, the library is + * automatically initialized when the first HDf5 function call is + * issued. If one finds that an HDF5 library function is failing + * inexplicably, H5open() can be called first. It is safe to call + * H5open() before an application issues any other function calls to + * the HDF5 library as there are no damaging side effects in calling + * it more than once. + */ H5_DLL herr_t H5open(void); +/** + * \ingroup H5 + * \brief Flushes all data to disk, closes all open objects, and releases memory + * \return \herr_t + * + * \details H5close() flushes all data to disk, closes all open HDF5 objects, + * and cleans up all memory used by the HDF5 library. This function is + * generally called when the application calls exit(), but may be + * called earlier in the event of an emergency shutdown or out of a + * desire to free all resources used by the HDF5 library. + */ H5_DLL herr_t H5close(void); +/** + * \ingroup H5 + * \brief Instructs library not to install atexit() cleanup routine + * \return \herr_t + * + * \details H5dont_atexit() indicates to the library that an atexit() cleanup + * routine should not be installed. The major purpose for using this + * function is in situations where the library is dynamically linked + * into an application and is un-linked from the application before + * exit() gets called. In those situations, a routine installed with + * atexit() would jump to a routine which was no longer in memory, + * causing errors. + * + * \attention In order to be effective, this routine \Emph{must} be called + * before any other HDF5 function calls, and must be called each + * time the library is loaded/linked into the application (the first + * time and after it's been un-loaded). + */ H5_DLL herr_t H5dont_atexit(void); +/** + * \ingroup H5 + * \brief Garbage collects on all free-lists of all types + * \return \herr_t + * + * \details H5garbage_collect() walks through all garbage collection routines + * of the library, freeing any unused memory. + * + * It is not required that H5garbage_collect() be called at any + * particular time; it is only necessary in certain situations where + * the application has performed actions that cause the library to + * allocate many objects. The application should call + * H5garbage_collect() if it eventually releases those objects and + * wants to reduce the memory used by the library from the peak usage + * required. + * + * \note The library automatically garbage collects all the free lists when the + * application ends. + */ H5_DLL herr_t H5garbage_collect(void); +/** + * \ingroup H5 + * \brief Sets free-list size limits + * + * \param[in] reg_global_lim The cumulative limit, in bytes, on memory used for + * all regular free lists (Default: 1MB) + * \param[in] reg_list_lim The limit, in bytes, on memory used for each regular + * free list (Default: 64KB) + * \param[in] arr_global_lim The cumulative limit, in bytes, on memory used for + * all array free lists (Default: 4MB) + * \param[in] arr_list_lim The limit, in bytes, on memory used for each array + * free list (Default: 256KB) + * \param[in] blk_global_lim The cumulative limit, in bytes, on memory used for + * all block free lists and, separately, for all + * factory free lists (Default: 16MB) + * \param[in] blk_list_lim The limit, in bytes, on memory used for each block + * or factory free list (Default: 1MB) + * \return \herr_t + * + * \details H5set_free_list_limits() sets size limits on all types of free + * lists. The HDF5 library uses free lists internally to manage + * memory. The types of free lists used are as follows: + * \li Regular free lists manage memory for single internal data + * structures. + * \li Array free lists manage memory for arrays of internal + * data structures. + * \li Block free lists manage memory for arbitrarily-sized blocks + * of bytes. + * \li Factory free lists manage memory for fixed-size blocks of + * bytes. + * + * The parameters specify global and per-list limits; for example, \p + * reg_global_limit and \p reg_list_limit limit the accumulated size + * of all regular free lists and the size of each individual regular + * free list, respectively. Therefore, if an application sets a 1Mb + * limit on each of the global lists, up to 4Mb of total storage might + * be allocated, 1Mb for each of the regular, array, block, and + * factory type lists. + * + * The settings specified for block free lists are duplicated for + * factory free lists. Therefore, increasing the global limit on block + * free lists by x bytes will increase the potential free list memory + * usage by 2x bytes. + * + * Using a value of -1 for a limit means that no limit is set for the + * specified type of free list. + * + * \version 1.8.3 Function changed in this release to set factory free list + * memory limits. + * + * \since 1.6.0 + */ H5_DLL herr_t H5set_free_list_limits(int reg_global_lim, int reg_list_lim, int arr_global_lim, int arr_list_lim, int blk_global_lim, int blk_list_lim); +/** + * \ingroup H5 + * \brief Gets the current size of the free lists used to manage memory + * + * \param[out] reg_size The current size of all "regular" free list memory used + * \param[out] arr_size The current size of all "array" free list memory used + * \param[out] blk_size The current size of all "block" free list memory used + * \param[out] fac_size The current size of all "factory" free list memory used + * \return \herr_t + * + * \details H5get_free_list_sizes() obtains the current size of the different + * kinds of free lists that the library uses to manage memory. The + * free list sizes can be set with H5set_free_list_limits() and + * garbage collected with H5garbage_collect(). These lists are global + * for the entire library. + * + * \since 1.12.1 + */ H5_DLL herr_t H5get_free_list_sizes(size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size); +/** + * \ingroup H5 + * \brief Gets the memory allocation statistics for the library + * + * \param[out] stats Memory allocation statistics + * \return \herr_t + * + * \details H5get_alloc_stats() gets the memory allocation statistics for the + * library, if the \c --enable-memory-alloc-sanity-check option was + * given when building the library. Applications can check whether + * this option was enabled detecting if the + * \c H5_MEMORY_ALLOC_SANITY_CHECK macro is defined. This option is + * enabled by default for debug builds of the library and disabled by + * default for non-debug builds. If the option is not enabled, all the + * values returned with be 0. These statistics are global for the + * entire library, but do not include allocations from chunked dataset + * I/O filters or non-native VOL connectors. + * + * \since 1.12.1 + */ H5_DLL herr_t H5get_alloc_stats(H5_alloc_stats_t *stats); +/** + * \ingroup H5 + * \brief Returns the HDF library release number + * + * \param[out] majnum The major version number of the library + * \param[out] minnum The minor version number of the library + * \param[out] relnum The release version number of the library + * \return \herr_t + * + * \details H5get_libversion() retrieves the major, minor, and release numbers + * of the version of the HDF5 library which is linked to the + * application. + * + */ H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *relnum); +/** + * \ingroup H5 + * \brief Verifies that HDF5 library versions are consistent + * + * \param[in] majnum HDF5 library major version number + * \param[in] minnum HDF5 library minor version number + * \param[in] relnum HDF5 library release number + * \return \herr_t + * + * \details H5check_version() verifies that the version of the HDF5 library + * with which an application was compiled, as indicated by the passed + * parameters, matches the version of the HDF5 library against which + * the application is currently linked. + * + * \p majnum is the major version number of the HDF library with which + * the application was compiled, \p minnum is the minor version + * number, and \p relnum is the release number. Consider the following + * example: + * + * An official HDF5 release is labelled as follows: + * HDF5 Release \Code{\<majnum\>.\<minnum\>.\<relnum\>}\n + * For example, in HDF5 Release 1.8.5: + * \li 1 is the major version number, \p majnum. + * \li 8 is the minor version number, \p minnum. + * \li 5 is the release number, \p relnum. + * + * As stated above, H5check_version() first verifies that the version + * of the HDF5 library with which an application was compiled matches + * the version of the HDF5 library against which the application is + * currently linked. If this check fails, H5check_version() causes the + * application to abort (by means of a standard C abort() call) and + * prints information that is usually useful for debugging. This + * precaution is is taken to avoid the risks of data corruption or + * segmentation faults. + * + * The most common cause of this failure is that an application was + * compiled with one version of HDF5 and is dynamically linked with a + * different version different version. + * + * If the above test passes, H5check_version() proceeds to verify the + * consistency of additional library version information. This is + * designed to catch source code inconsistencies that do not normally + * cause failures; if this check reveals an inconsistency, an + * informational warning is printed but the application is allowed to + * run. + * + */ H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum); +/** + * \ingroup H5 + * \brief Determines whether the HDF5 library was built with the thread-safety + * feature enabled + * + * \param[out] is_ts Boolean value indicating whether the library was built + * with thread-safety enabled + * \return \herr_t + * + * \details The HDF5 library, although not internally multi-threaded, can be + * built with a thread-safety feature enabled that protects internal + * data structures with a mutex. In certain circumstances, it may be + * useful to determine, at run-time, whether the linked HDF5 library + * was built with the thread-safety feature enabled. + */ H5_DLL herr_t H5is_library_threadsafe(hbool_t *is_ts); +/** + * \ingroup H5 + * \brief Frees memory allocated by the HDF5 library + * + * \param[in] mem Buffer to be freed. Can be NULL + * \return \herr_t + * + * \details H5free_memory() frees memory that has been allocated by the caller + * with H5allocate_memory() or by the HDF5 library on behalf of the + * caller. + * + * H5Tget_member_name() provides an example of memory allocation on + * behalf of the caller: The function returns a buffer containing the + * name of a compound datatype member. It is the caller’s + * responsibility to eventually free that buffer with H5free_memory(). + * + * \attention It is especially important to use this function to free memory + * allocated by the library on Windows. The C standard library is + * implemented in dynamic link libraries (DLLs) known as the C + * run-time (CRT). Each version of Visual Studio comes with two CRT + * DLLs (debug and release) and allocating and freeing across DLL + * boundaries can cause resource leaks and subtle bugs due to heap + * corruption.\n + * Only use this function to free memory allocated by the HDF5 + * Library. It will generally not be safe to use this function to + * free memory allocated by any other means.\n + * Even when using this function, it is still best to ensure that + * all components of a C application are built with the same version + * of Visual Studio and build (debug or release) and thus linked + * against the same CRT. + * + * \see H5allocate_memory(), H5resize_memory() + * + * \since 1.8.13 + * + */ H5_DLL herr_t H5free_memory(void *mem); -H5_DLL void * H5allocate_memory(size_t size, hbool_t clear); -H5_DLL void * H5resize_memory(void *mem, size_t size); +/** + * \ingroup H5 + * \brief Frees memory allocated by the HDF5 library + * + * \param[in] size The size in bytes of the buffer to be allocated + * \param[in] clear Flag whether the new buffer is to be initialized with 0 + * + * \return On success, returns pointer to newly allocated buffer or returns + * NULL if size is 0 (zero).\n + * Returns NULL on failure. + * + * \details H5allocate_memory() allocates a memory buffer of size bytes that + * will later be freed internally by the HDF5 library. + * + * The boolean \p clear parameter specifies whether the buffer should + * be initialized. If clear is \c TRUE, all bits in the buffer are to be + * set to 0 (zero); if clear is \c FALSE, the buffer will not be + * initialized. + * + * This function is intended to have the semantics of malloc() and + * calloc(). However, unlike malloc() and calloc() which allow for a + * "special" pointer to be returned instead of NULL, this function + * always returns NULL on failure or when size is set to 0 (zero). + * + * \note At this time, the only intended use for this function is to allocate + * memory that will be returned to the library as a data buffer from a + * third-party filter. + * + * \attention To avoid heap corruption, allocated memory should be freed using + * the same library that initially allocated it. In most cases, the + * HDF5 API uses resources that are allocated and freed either + * entirely by the user or entirely by the library, so this is not a + * problem. In rare cases, however, HDF5 API calls will free memory + * that the user allocated. This function allows the user to safely + * allocate this memory.\n + * It is particularly important to use this function to allocate + * memory in Microsoft Windows environments. In Windows, the C + * standard library is implemented in dynamic link libraries (DLLs) + * known as the C run-time (CRT). Each version of Visual Studio + * comes with multiple versions of the CRT DLLs (debug, release, et + * cetera) and allocating and freeing memory across DLL boundaries + * can cause resource leaks and subtle bugs due to heap corruption.\n + * Even when using this function, it is best where possible to + * ensure that all components of a C application are built with the + * same version of Visual Studio and configuration (Debug or + * Release), and thus linked against the same CRT.\n + * Use this function only to allocate memory inside third-party HDF5 + * filters. It will generally not be safe to use this function to + * allocate memory for any other purpose. + * + * \see H5free_memory(), H5resize_memory() + * + * \since 1.8.15 + * + */ +H5_DLL void *H5allocate_memory(size_t size, hbool_t clear); +/** + * \ingroup H5 + * \brief Resizes and, if required, re-allocates memory that will later be + * freed internally by the HDF5 library + * + * \param[in] mem Pointer to a buffer to be resized. May be NULL + * \param[in] size New size of the buffer, in bytes + + * + * \return On success, returns pointer to resized or reallocated buffer + * or returns NULL if size is 0 (zero).\n + * Returns NULL on failure. + * + * \details H5resize_memory() takes a pointer to an existing buffer and resizes + * the buffer to match the value in \p size. If necessary, the buffer + * is reallocated. If \p size is 0, the buffer is released. + * + * The input buffer must either be NULL or have been allocated by + * H5allocate_memory() since the input buffer may be freed by the + * library. + * + * For certain behaviors, the pointer \p mem may be passed in as NULL. + * + * This function is intended to have the semantics of realloc(): + * + * <table> + * <tr><td>\Code{H5resize_memory(buffer, size)}</td> + * <td>Resizes buffer. Returns pointer to resized buffer.</td></tr> + * <tr><td>\Code{H5resize_memory(NULL, size)}</td> + * <td>Allocates memory using HDF5 Library allocator. + * Returns pointer to new buffer</td></tr> + * <tr><td>\Code{H5resize_memory(buffer, 0)}</td> + * <td>Frees memory using HDF5 Library allocator. + * Returns NULL.</td></tr> + * <tr><td>\Code{H5resize_memory(NULL, 0)}</td> + * <td>Returns NULL (undefined in C standard).</td></tr> + * </table> + * + * Unlike realloc(), which allows for a "special pointer to be + * returned instead of NULL, this function always returns NULL on + * failure or when size is 0 (zero). + * + * \note At this time, the only intended use for this function is to resize or + * reallocate memory that will be returned to the library (and eventually + * to the user) as a data buffer from a third-party HDF5 filter. + * + * \attention To avoid heap corruption, allocated memory should be freed using + * the same library that initially allocated it. In most cases, the + * HDF5 API uses resources that are allocated and freed either + * entirely by the user or entirely by the library, so this is not a + * problem. In rare cases, however, HDF5 API calls will free memory + * that the user allocated. This function allows the user to safely + * allocate this memory.\n + * It is particularly important to use this function to resize + * memory on Microsoft Windows systems. In Windows, the C standard + * library is implemented in dynamic link libraries (DLLs) known as + * the C run-time (CRT). Each version of Visual Studio comes with + * multiple versions of the CRT DLLs (debug, release, et cetera) and + * allocating and freeing memory across DLL boundaries can cause + * resource leaks and subtle bugs due to heap corruption.\n + * Even when using this function, it is still best to ensure that + * all components of a C application are built with the same version + * of Visual Studio and the same configuration (Debug or Release), + * and thus linked against the same CRT.\n + * Only use this function to resize memory inside third-party HDF5 + * filters. It will generally not be safe to use this function to + * resize memory for any other purpose. + * + * \see H5allocate_memory(), H5free_memory() + * + * \since 1.8.15 + * + */ +H5_DLL void *H5resize_memory(void *mem, size_t size); #ifdef __cplusplus } diff --git a/src/H5system.c b/src/H5system.c index b2a2668..fdc6c22 100644 --- a/src/H5system.c +++ b/src/H5system.c @@ -25,6 +25,7 @@ /****************/ /* Module Setup */ /****************/ +#include "H5module.h" /* This source code file is part of the H5 module */ /***********/ /* Headers */ @@ -346,8 +347,8 @@ H5_make_time(struct tm *tm) * VS 2015 is removed, with _get_timezone replacing it. */ long timezone = 0; -#endif /* defined(H5_HAVE_VISUAL_STUDIO) && (_MSC_VER >= 1900) */ - time_t ret_value; /* Return value */ +#endif /* defined(H5_HAVE_VISUAL_STUDIO) && (_MSC_VER >= 1900) */ + time_t ret_value = 0; /* Return value */ FUNC_ENTER_NOAPI_NOINIT diff --git a/src/H5timer.c b/src/H5timer.c index 1df2d8d..b637a16 100644 --- a/src/H5timer.c +++ b/src/H5timer.c @@ -24,6 +24,7 @@ /****************/ /* Module Setup */ /****************/ +#include "H5module.h" /* This source code file is part of the H5 module */ /***********/ /* Headers */ @@ -163,7 +164,7 @@ H5_now(void) HDgettimeofday(&now_tv, NULL); now = now_tv.tv_sec; } -#else /* H5_HAVE_GETTIMEOFDAY */ +#else /* H5_HAVE_GETTIMEOFDAY */ now = HDtime(NULL); #endif /* H5_HAVE_GETTIMEOFDAY */ @@ -201,8 +202,8 @@ H5_now_usec(void) HDgettimeofday(&now_tv, NULL); now = (uint64_t)(now_tv.tv_sec * (1000 * 1000)) + (uint64_t)now_tv.tv_usec; } -#else /* H5_HAVE_GETTIMEOFDAY */ - now = (uint64_t)(HDtime(NULL) * (1000 * 1000)); +#else /* H5_HAVE_GETTIMEOFDAY */ + now = (uint64_t)(HDtime(NULL) * (1000 * 1000)); #endif /* H5_HAVE_GETTIMEOFDAY */ return (now); diff --git a/src/H5trace.c b/src/H5trace.c index 9f23d0a..4beecc3 100644 --- a/src/H5trace.c +++ b/src/H5trace.c @@ -25,7 +25,8 @@ /****************/ /* Module Setup */ /****************/ -#define H5I_FRIEND /*suppress error about including H5Ipkg */ +#include "H5module.h" /* This source code file is part of the H5 module */ +#define H5I_FRIEND /*suppress error about including H5Ipkg */ /***********/ /* Headers */ @@ -36,7 +37,9 @@ #include "H5FDprivate.h" /* File drivers */ #include "H5Rprivate.h" /* References */ #include "H5Ipkg.h" /* IDs */ +#include "H5Mpublic.h" /* Maps */ #include "H5MMprivate.h" /* Memory management */ +#include "H5RSprivate.h" /* Reference-counted strings */ #include "H5VLprivate.h" /* Virtual Object Layer */ #ifdef H5_HAVE_PARALLEL @@ -59,6 +62,9 @@ /********************/ /* Local Prototypes */ /********************/ +static herr_t H5_trace_args_bool(H5RS_str_t *rs, hbool_t val); +static herr_t H5_trace_args_cset(H5RS_str_t *rs, H5T_cset_t cset); +static herr_t H5_trace_args_close_degree(H5RS_str_t *rs, H5F_close_degree_t degree); /*********************/ /* Package Variables */ @@ -73,134 +79,170 @@ /*******************/ /*------------------------------------------------------------------------- - * Function: H5_trace + * Function: H5_trace_args_bool * - * Purpose: This function is called whenever an API function is called - * and tracing is turned on. If RETURNING is non-zero then - * the caller is about to return and RETURNING points to the - * time for the corresponding function call event. Otherwise - * we print the function name and the arguments. + * Purpose: This routine formats an hbool_t and adds the output to + * the refcounted string (RS) argument. * - * The TYPE argument is a string which gives the type of each of - * the following argument pairs. Each type is zero or more - * asterisks (one for each level of indirection, although some - * types have one level of indirection already implied) followed - * by either one letter (lower case) or two letters (first one - * uppercase). + * Return: SUCCEED / FAIL * - * The variable argument list consists of pairs of values. Each - * pair is a string which is the formal argument name in the - * calling function, followed by the argument value. The type - * of the argument value is given by the TYPE string. + * Programmer: Quincey Koziol + * Monday, September 21, 2020 * - * Note: The TYPE string is meant to be terse and is generated by a - * separate perl script. + *------------------------------------------------------------------------- + */ +static herr_t +H5_trace_args_bool(H5RS_str_t *rs, hbool_t val) +{ + /* FUNC_ENTER() should not be called */ + + if (TRUE == val) + H5RS_acat(rs, "TRUE"); + else if (!val) + H5RS_acat(rs, "FALSE"); + else + H5RS_asprintf_cat(rs, "TRUE(%u)", (unsigned)val); + + return SUCCEED; +} /* end H5_trace_args_bool() */ + +/*------------------------------------------------------------------------- + * Function: H5_trace_args_cset * - * WARNING: DO NOT CALL ANY HDF5 FUNCTION THAT CALLS FUNC_ENTER(). DOING - * SO MAY CAUSE H5_trace() TO BE INVOKED RECURSIVELY OR MAY - * CAUSE LIBRARY INITIALIZATIONS THAT ARE NOT DESIRED. + * Purpose: This routine formats an H5T_cset_t and adds the output to + * the refcounted string (RS) argument. * - * Return: Execution time for an API call + * Return: SUCCEED / FAIL * - * Programmer: Robb Matzke - * Tuesday, June 16, 1998 + * Programmer: Quincey Koziol + * Sunday, September 20, 2020 * *------------------------------------------------------------------------- */ -double -H5_trace(const double *returning, const char *func, const char *type, ...) +static herr_t +H5_trace_args_cset(H5RS_str_t *rs, H5T_cset_t cset) { - va_list ap; - char buf[64], *rest; - const char * argname; - int argno = 0, ptr, asize_idx; - hssize_t asize[16]; - hssize_t i; - void * vp = NULL; - FILE * out = H5_debug_g.trace; - static hbool_t is_first_invocation = TRUE; - H5_timer_t function_timer; - H5_timevals_t function_times; - static H5_timer_t running_timer; - H5_timevals_t running_times; - static int current_depth = 0; - static int last_call_depth = 0; + /* FUNC_ENTER() should not be called */ + switch (cset) { + case H5T_CSET_ERROR: + H5RS_acat(rs, "H5T_CSET_ERROR"); + break; + + case H5T_CSET_ASCII: + H5RS_acat(rs, "H5T_CSET_ASCII"); + break; + + case H5T_CSET_UTF8: + H5RS_acat(rs, "H5T_CSET_UTF8"); + break; + + case H5T_CSET_RESERVED_2: + case H5T_CSET_RESERVED_3: + case H5T_CSET_RESERVED_4: + case H5T_CSET_RESERVED_5: + case H5T_CSET_RESERVED_6: + case H5T_CSET_RESERVED_7: + case H5T_CSET_RESERVED_8: + case H5T_CSET_RESERVED_9: + case H5T_CSET_RESERVED_10: + case H5T_CSET_RESERVED_11: + case H5T_CSET_RESERVED_12: + case H5T_CSET_RESERVED_13: + case H5T_CSET_RESERVED_14: + case H5T_CSET_RESERVED_15: + H5RS_asprintf_cat(rs, "H5T_CSET_RESERVED_%ld", (long)cset); + break; + + default: + H5RS_asprintf_cat(rs, "%ld", (long)cset); + break; + } /* end switch */ + + return SUCCEED; +} /* end H5_trace_args_cset() */ + +/*------------------------------------------------------------------------- + * Function: H5_trace_args_close_degree + * + * Purpose: This routine formats an H5F_close_degree_t and adds the output to + * the refcounted string (RS) argument. + * + * Return: SUCCEED / FAIL + * + * Programmer: Quincey Koziol + * Monday, September 21, 2020 + * + *------------------------------------------------------------------------- + */ +static herr_t +H5_trace_args_close_degree(H5RS_str_t *rs, H5F_close_degree_t degree) +{ /* FUNC_ENTER() should not be called */ - if (!out) - return 0.0F; /*tracing is off*/ - HDva_start(ap, type); + switch (degree) { + case H5F_CLOSE_DEFAULT: + H5RS_acat(rs, "H5F_CLOSE_DEFAULT"); + break; - if (H5_debug_g.ttop) { - if (returning) { - if (current_depth > 1) { - --current_depth; - return 0.0F; - } /* end if */ - } /* end if */ - else { - if (current_depth > 0) { - /*do not update last_call_depth*/ - current_depth++; - return 0.0F; - } /* end if */ - } /* end else */ - } /* end if */ + case H5F_CLOSE_WEAK: + H5RS_acat(rs, "H5F_CLOSE_WEAK"); + break; - /* Get time for event if the trace times flag is set */ - if (is_first_invocation && H5_debug_g.ttimes) { - /* start the library-wide timer */ - is_first_invocation = FALSE; - H5_timer_init(&running_timer); - H5_timer_start(&running_timer); - } /* end if */ - if (H5_debug_g.ttimes) { - /* start the timer for this function */ - H5_timer_init(&function_timer); - H5_timer_start(&function_timer); - } /* end if */ + case H5F_CLOSE_SEMI: + H5RS_acat(rs, "H5F_CLOSE_SEMI"); + break; - /* Print the first part of the line. This is the indication of the - * nesting depth followed by the function name and either start of - * argument list or start of return value. If this call is for a - * function return and no other calls have been made to H5_trace() - * since the one for the function call, then we're continuing - * the same line. */ - if (returning) { - HDassert(current_depth > 0); - --current_depth; - if (current_depth < last_call_depth) { - /* We are at the beginning of a line */ - if (H5_debug_g.ttimes) { - char tmp[320]; + case H5F_CLOSE_STRONG: + H5RS_acat(rs, "H5F_CLOSE_STRONG"); + break; - H5_timer_get_times(function_timer, &function_times); - H5_timer_get_times(running_timer, &running_times); - HDsprintf(tmp, "%.6f", (function_times.elapsed - running_times.elapsed)); - HDfprintf(out, " %*s ", (int)HDstrlen(tmp), ""); - } /* end if */ - for (i = 0; i < current_depth; i++) - HDfputc('+', out); - HDfprintf(out, "%*s%s = ", 2 * current_depth, "", func); - } /* end if */ - else { - /* Continue current line with return value */ - HDfprintf(out, " = "); - } /* end else */ - } /* end if */ - else { - if (current_depth > last_call_depth) - HDfputs(" = <delayed>\n", out); - if (H5_debug_g.ttimes) { - H5_timer_get_times(function_timer, &function_times); - H5_timer_get_times(running_timer, &running_times); - HDfprintf(out, "@%.6f ", (function_times.elapsed - running_times.elapsed)); - } /* end if */ - for (i = 0; i < current_depth; i++) - HDfputc('+', out); - HDfprintf(out, "%*s%s(", 2 * current_depth, "", func); - } /* end else */ + default: + H5RS_asprintf_cat(rs, "%ld", (long)degree); + break; + } /* end switch */ + + return SUCCEED; +} /* end H5_trace_args_cset() */ + +/*------------------------------------------------------------------------- + * Function: H5_trace_args + * + * Purpose: This routine formats a set of function arguments, placing the + * resulting string in the refcounted string (RS) argument. + * + * The TYPE argument is a string which gives the type of each of + * the following argument pairs. Each type begins with zero or + * more asterisks (one for each level of indirection, although + * some types have one level of indirection already implied) + * followed by either one letter (lower case) or two letters + * (first one uppercase). + * + * The variable argument list consists of pairs of values. Each + * pair is a string which is the formal argument name in the + * calling function, followed by the argument value. The type + * of the argument value is given by the TYPE string. + * + * Note: The TYPE string is meant to be terse and is generated by a + * separate perl script. + * + * Return: SUCCEED / FAIL + * + * Programmer: Quincey Koziol + * Saturday, September 19, 2020 + * + *------------------------------------------------------------------------- + */ +herr_t +H5_trace_args(H5RS_str_t *rs, const char *type, va_list ap) +{ + const char *argname; + int argno = 0, ptr, asize_idx; + hssize_t asize[16]; + hssize_t i; + void * vp = NULL; + + /* FUNC_ENTER() should not be called */ /* Clear array sizes */ for (i = 0; i < (hssize_t)NELMTS(asize); i++) @@ -211,7 +253,11 @@ H5_trace(const double *returning, const char *func, const char *type, ...) /* Count levels of indirection */ for (ptr = 0; '*' == *type; type++) ptr++; + + /* Array parameter, possibly with another argument as the array size */ if ('[' == *type) { + char *rest; + if ('a' == type[1]) { asize_idx = (int)HDstrtol(type + 2, &rest, 10); HDassert(0 <= asize_idx && asize_idx < (int)NELMTS(asize)); @@ -229,1136 +275,1338 @@ H5_trace(const double *returning, const char *func, const char *type, ...) asize_idx = -1; /* - * The argument name. Leave off the `_id' part. If the argument - * name is the null pointer then don't print the argument or the - * following `='. This is used for return values. + * The argument name. If the argument name is the null pointer then + * don't print the argument or the following `=' (this is used for + * return values). */ argname = HDva_arg(ap, char *); - if (argname) { - unsigned n = (unsigned)MAX(0, (int)HDstrlen(argname) - 3); - - if (!HDstrcmp(argname + n, "_id")) { - HDstrncpy(buf, argname, (size_t)MIN((int)sizeof(buf) - 1, n)); - buf[MIN((int)sizeof(buf) - 1, n)] = '\0'; - argname = buf; - } /* end if */ - HDfprintf(out, "%s%s=", argno ? ", " : "", argname); - } /* end if */ + if (argname) + H5RS_asprintf_cat(rs, "%s%s=", argno ? ", " : "", argname); else argname = ""; - /* The value */ - if (ptr) + /* A pointer/array */ + if (ptr) { vp = HDva_arg(ap, void *); - switch (type[0]) { - case 'a': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + if (vp) { + switch (type[0]) { + case 'h': /* hsize_t */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + hsize_t *p = (hsize_t *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) { + if (H5S_UNLIMITED == p[i]) + H5RS_asprintf_cat(rs, "%sH5S_UNLIMITED", (i ? ", " : "")); + else + H5RS_asprintf_cat(rs, "%s%" PRIuHSIZE, (i ? ", " : ""), p[i]); + } /* end for */ + H5RS_acat(rs, "}"); + } /* end if */ + break; + + case 'H': + if ('s' == type[1]) { /* hssize_t */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + hssize_t *p = (hssize_t *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) + H5RS_asprintf_cat(rs, "%s%" PRIdHSIZE, (i ? ", " : ""), p[i]); + H5RS_acat(rs, "}"); + } /* end if */ + } /* end if */ + else + H5RS_asprintf_cat(rs, "%p", vp); + break; + + case 'I': + if ('s' == type[1]) { /* int / int32_t */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + int *p = (int *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) + H5RS_asprintf_cat(rs, "%s%d", (i ? ", " : ""), p[i]); + H5RS_acat(rs, "}"); + } /* end if */ + } /* end if */ + else if ('u' == type[1]) { /* unsigned / uint32_t */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + unsigned *p = (unsigned *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) + H5RS_asprintf_cat(rs, "%s%u", i ? ", " : "", p[i]); + H5RS_acat(rs, "}"); + } /* end if */ + } /* end else-if */ + else + H5RS_asprintf_cat(rs, "%p", vp); + break; + + case 's': /* char* */ + /* Strings have one level of indirection by default, pointers + * to strings have 2 or more. + */ + if (ptr > 1) + H5RS_asprintf_cat(rs, "%p", vp); + else + H5RS_asprintf_cat(rs, "\"%s\"", (const char *)vp); + break; + + case 'U': + if ('l' == type[1]) { /* unsigned long */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + unsigned long *p = (unsigned long *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) + H5RS_asprintf_cat(rs, "%s%lu", i ? ", " : "", p[i]); + H5RS_acat(rs, "}"); + } /* end if */ + } /* end if */ + else if ('L' == type[1]) { /* unsigned long long / uint64_t */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + unsigned long long *p = (unsigned long long *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) + H5RS_asprintf_cat(rs, "%s%llu", i ? ", " : "", p[i]); + H5RS_acat(rs, "}"); + } /* end if */ + } /* end else-if */ + else + H5RS_asprintf_cat(rs, "%p", vp); + break; + + case 'x': /* void */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + void **p = (void **)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) { + if (p[i]) + H5RS_asprintf_cat(rs, "%s%p", (i ? ", " : ""), p[i]); + else + H5RS_asprintf_cat(rs, "%sNULL", (i ? ", " : "")); + } /* end for */ + H5RS_acat(rs, "}"); + } /* end if */ + break; + + case 'z': /* size_t */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + size_t *p = (size_t *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) + H5RS_asprintf_cat(rs, "%s%zu", (i ? ", " : ""), p[i]); + H5RS_acat(rs, "}"); + } /* end if */ + break; + + case 'Z': + if ('s' == type[1]) { /* ssize_t */ + H5RS_asprintf_cat(rs, "%p", vp); + if (asize_idx >= 0 && asize[asize_idx] >= 0) { + ssize_t *p = (ssize_t *)vp; + + H5RS_acat(rs, " {"); + for (i = 0; i < asize[asize_idx]; i++) + H5RS_asprintf_cat(rs, "%s%zd", (i ? ", " : ""), p[i]); + H5RS_acat(rs, "}"); + } /* end if */ + } /* end if */ + else + H5RS_asprintf_cat(rs, "%p", vp); + break; + + default: + H5RS_asprintf_cat(rs, "%p", vp); + } /* end switch */ + } /* end if */ + else + H5RS_acat(rs, "NULL"); + } /* end if */ + /* A value */ + else { + switch (type[0]) { + case 'a': /* haddr_t */ + { haddr_t addr = HDva_arg(ap, haddr_t); - HDfprintf(out, "%" PRIuHADDR, addr); - } /* end else */ + if (H5F_addr_defined(addr)) + H5RS_asprintf_cat(rs, "%" PRIuHADDR, addr); + else + H5RS_acat(rs, "UNDEF"); + } /* end block */ break; - case 'b': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'A': + switch (type[1]) { + case 'i': /* H5A_info_t */ + { + H5A_info_t ainfo = HDva_arg(ap, H5A_info_t); + + H5RS_acat(rs, "{"); + H5_trace_args_bool(rs, ainfo.corder_valid); + H5RS_asprintf_cat(rs, ", %u, ", ainfo.corder); + H5_trace_args_cset(rs, ainfo.cset); + H5RS_asprintf_cat(rs, "%" PRIuHSIZE "}", ainfo.data_size); + } /* end block */ + break; + +#ifndef H5_NO_DEPRECATED_SYMBOLS + case 'o': /* H5A_operator1_t */ + { + H5A_operator1_t aop1 = (H5A_operator1_t)HDva_arg(ap, H5A_operator1_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)aop1); + } /* end block */ + break; +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + + case 'O': /* H5A_operator2_t */ + { + H5A_operator2_t aop2 = (H5A_operator2_t)HDva_arg(ap, H5A_operator2_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)aop2); + } /* end block */ + break; + + default: + H5RS_asprintf_cat(rs, "BADTYPE(A%c)", type[1]); + goto error; + } /* end switch */ + break; + + case 'b': /* hbool_t */ + { /* Can't pass hbool_t to HDva_arg() */ hbool_t bool_var = (hbool_t)HDva_arg(ap, int); - if (TRUE == bool_var) - HDfprintf(out, "TRUE"); - else if (!bool_var) - HDfprintf(out, "FALSE"); - else - HDfprintf(out, "TRUE(%u)", (unsigned)bool_var); - } + + H5_trace_args_bool(rs, bool_var); + } /* end block */ break; - case 'd': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'C': + switch (type[1]) { + case 'c': /* H5AC_cache_config_t */ + { + H5AC_cache_config_t cc = HDva_arg(ap, H5AC_cache_config_t); + + H5RS_asprintf_cat(rs, "{%d, ", cc.version); + H5_trace_args_bool(rs, cc.rpt_fcn_enabled); + H5RS_acat(rs, ", "); + H5_trace_args_bool(rs, cc.open_trace_file); + H5RS_acat(rs, ", "); + H5_trace_args_bool(rs, cc.close_trace_file); + H5RS_asprintf_cat(rs, ", '%s', ", cc.trace_file_name); + H5RS_acat(rs, ", "); + H5_trace_args_bool(rs, cc.evictions_enabled); + H5RS_acat(rs, ", "); + H5_trace_args_bool(rs, cc.set_initial_size); + H5RS_asprintf_cat(rs, ", %zu, ", cc.initial_size); + H5RS_asprintf_cat(rs, "%f, ", cc.min_clean_fraction); + H5RS_asprintf_cat(rs, "%zu, ", cc.max_size); + H5RS_asprintf_cat(rs, "%zu, ", cc.min_size); + H5RS_asprintf_cat(rs, "%ld, ", cc.epoch_length); + switch (cc.incr_mode) { + case H5C_incr__off: + H5RS_acat(rs, "H5C_incr__off"); + break; + + case H5C_incr__threshold: + H5RS_acat(rs, "H5C_incr__threshold"); + break; + + default: + H5RS_asprintf_cat(rs, "%ld", (long)cc.incr_mode); + break; + } /* end switch */ + H5RS_asprintf_cat(rs, ", %f, ", cc.lower_hr_threshold); + H5RS_asprintf_cat(rs, "%f, ", cc.increment); + H5_trace_args_bool(rs, cc.apply_max_increment); + H5RS_asprintf_cat(rs, ", %zu, ", cc.max_increment); + switch (cc.flash_incr_mode) { + case H5C_flash_incr__off: + H5RS_acat(rs, "H5C_flash_incr__off"); + break; + + case H5C_flash_incr__add_space: + H5RS_acat(rs, "H5C_flash_incr__add_space"); + break; + + default: + H5RS_asprintf_cat(rs, "%ld", (long)cc.flash_incr_mode); + break; + } /* end switch */ + H5RS_asprintf_cat(rs, ", %f, ", cc.flash_multiple); + H5RS_asprintf_cat(rs, "%f, ", cc.flash_threshold); + switch (cc.decr_mode) { + case H5C_decr__off: + H5RS_acat(rs, "H5C_decr__off"); + break; + + case H5C_decr__threshold: + H5RS_acat(rs, "H5C_decr__threshold"); + break; + + case H5C_decr__age_out: + H5RS_acat(rs, "H5C_decr__age_out"); + break; + + case H5C_decr__age_out_with_threshold: + H5RS_acat(rs, "H5C_decr__age_out_with_threshold"); + break; + + default: + H5RS_asprintf_cat(rs, "%ld", (long)cc.decr_mode); + break; + } /* end switch */ + H5RS_asprintf_cat(rs, ", %f, ", cc.upper_hr_threshold); + H5RS_asprintf_cat(rs, "%f, ", cc.decrement); + H5_trace_args_bool(rs, cc.apply_max_decrement); + H5RS_asprintf_cat(rs, ", %zu, ", cc.max_decrement); + H5RS_asprintf_cat(rs, "%d, ", cc.epochs_before_eviction); + H5_trace_args_bool(rs, cc.apply_empty_reserve); + H5RS_asprintf_cat(rs, ", %f, ", cc.empty_reserve); + H5RS_asprintf_cat(rs, "%zu, ", cc.dirty_bytes_threshold); + H5RS_asprintf_cat(rs, "%d}", cc.metadata_write_strategy); + } /* end block */ + break; + + case 'C': /* H5AC_cache_image_config_t */ + { + H5AC_cache_image_config_t cic = HDva_arg(ap, H5AC_cache_image_config_t); + + H5RS_asprintf_cat(rs, "{%d, ", cic.version); + H5_trace_args_bool(rs, cic.generate_image); + H5RS_acat(rs, ", "); + H5_trace_args_bool(rs, cic.save_resize_status); + H5RS_acat(rs, ", "); + H5RS_asprintf_cat(rs, "%d}", cic.entry_ageout); + } /* end block */ + break; + + default: + H5RS_asprintf_cat(rs, "BADTYPE(C%c)", type[1]); + goto error; + } /* end switch */ + break; + + case 'd': /* double */ + { double dbl = HDva_arg(ap, double); - HDfprintf(out, "%g", dbl); - } /* end else */ + H5RS_asprintf_cat(rs, "%g", dbl); + } /* end block */ break; - case 'D': - switch (type[1]) { - case 'a': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'D': + switch (type[1]) { + case 'a': /* H5D_alloc_time_t */ + { H5D_alloc_time_t alloc_time = (H5D_alloc_time_t)HDva_arg(ap, int); switch (alloc_time) { case H5D_ALLOC_TIME_ERROR: - HDfprintf(out, "H5D_ALLOC_TIME_ERROR"); + H5RS_acat(rs, "H5D_ALLOC_TIME_ERROR"); break; case H5D_ALLOC_TIME_DEFAULT: - HDfprintf(out, "H5D_ALLOC_TIME_DEFAULT"); + H5RS_acat(rs, "H5D_ALLOC_TIME_DEFAULT"); break; case H5D_ALLOC_TIME_EARLY: - HDfprintf(out, "H5D_ALLOC_TIME_EARLY"); + H5RS_acat(rs, "H5D_ALLOC_TIME_EARLY"); break; case H5D_ALLOC_TIME_LATE: - HDfprintf(out, "H5D_ALLOC_TIME_LATE"); + H5RS_acat(rs, "H5D_ALLOC_TIME_LATE"); break; case H5D_ALLOC_TIME_INCR: - HDfprintf(out, "H5D_ALLOC_TIME_INCR"); + H5RS_acat(rs, "H5D_ALLOC_TIME_INCR"); break; default: - HDfprintf(out, "%ld", (long)alloc_time); + H5RS_asprintf_cat(rs, "%ld", (long)alloc_time); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'c': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'A': /* H5D_append_cb_t */ + { + H5D_append_cb_t dapp = (H5D_append_cb_t)HDva_arg(ap, H5D_append_cb_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)dapp); + } /* end block */ + break; + + case 'c': /* H5FD_mpio_collective_opt_t */ + { H5FD_mpio_collective_opt_t opt = (H5FD_mpio_collective_opt_t)HDva_arg(ap, int); switch (opt) { case H5FD_MPIO_COLLECTIVE_IO: - HDfprintf(out, "H5FD_MPIO_COLLECTIVE_IO"); + H5RS_acat(rs, "H5FD_MPIO_COLLECTIVE_IO"); break; case H5FD_MPIO_INDIVIDUAL_IO: - HDfprintf(out, "H5FD_MPIO_INDIVIDUAL_IO"); + H5RS_acat(rs, "H5FD_MPIO_INDIVIDUAL_IO"); break; default: - HDfprintf(out, "%ld", (long)opt); + H5RS_asprintf_cat(rs, "%ld", (long)opt); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'f': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'f': /* H5D_fill_time_t */ + { H5D_fill_time_t fill_time = (H5D_fill_time_t)HDva_arg(ap, int); switch (fill_time) { case H5D_FILL_TIME_ERROR: - HDfprintf(out, "H5D_FILL_TIME_ERROR"); + H5RS_acat(rs, "H5D_FILL_TIME_ERROR"); break; case H5D_FILL_TIME_ALLOC: - HDfprintf(out, "H5D_FILL_TIME_ALLOC"); + H5RS_acat(rs, "H5D_FILL_TIME_ALLOC"); break; case H5D_FILL_TIME_NEVER: - HDfprintf(out, "H5D_FILL_TIME_NEVER"); + H5RS_acat(rs, "H5D_FILL_TIME_NEVER"); break; case H5D_FILL_TIME_IFSET: - HDfprintf(out, "H5D_FILL_TIME_IFSET"); + H5RS_acat(rs, "H5D_FILL_TIME_IFSET"); break; default: - HDfprintf(out, "%ld", (long)fill_time); + H5RS_asprintf_cat(rs, "%ld", (long)fill_time); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'F': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'F': /* H5D_fill_value_t */ + { H5D_fill_value_t fill_value = (H5D_fill_value_t)HDva_arg(ap, int); switch (fill_value) { case H5D_FILL_VALUE_ERROR: - HDfprintf(out, "H5D_FILL_VALUE_ERROR"); + H5RS_acat(rs, "H5D_FILL_VALUE_ERROR"); break; case H5D_FILL_VALUE_UNDEFINED: - HDfprintf(out, "H5D_FILL_VALUE_UNDEFINED"); + H5RS_acat(rs, "H5D_FILL_VALUE_UNDEFINED"); break; case H5D_FILL_VALUE_DEFAULT: - HDfprintf(out, "H5D_FILL_VALUE_DEFAULT"); + H5RS_acat(rs, "H5D_FILL_VALUE_DEFAULT"); break; case H5D_FILL_VALUE_USER_DEFINED: - HDfprintf(out, "H5D_FILL_VALUE_USER_DEFINED"); + H5RS_acat(rs, "H5D_FILL_VALUE_USER_DEFINED"); break; default: - HDfprintf(out, "%ld", (long)fill_value); + H5RS_asprintf_cat(rs, "%ld", (long)fill_value); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'h': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'g': /* H5D_gather_func_t */ + { + H5D_gather_func_t gop = (H5D_gather_func_t)HDva_arg(ap, H5D_gather_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)gop); + } /* end block */ + break; + + case 'h': /* H5FD_mpio_chunk_opt_t */ + { H5FD_mpio_chunk_opt_t opt = (H5FD_mpio_chunk_opt_t)HDva_arg(ap, int); switch (opt) { case H5FD_MPIO_CHUNK_DEFAULT: - HDfprintf(out, "H5FD_MPIO_CHUNK_DEFAULT"); + H5RS_acat(rs, "H5FD_MPIO_CHUNK_DEFAULT"); break; case H5FD_MPIO_CHUNK_ONE_IO: - HDfprintf(out, "H5FD_MPIO_CHUNK_ONE_IO"); + H5RS_acat(rs, "H5FD_MPIO_CHUNK_ONE_IO"); break; case H5FD_MPIO_CHUNK_MULTI_IO: - HDfprintf(out, "H5FD_MPIO_CHUNK_MULTI_IO"); + H5RS_acat(rs, "H5FD_MPIO_CHUNK_MULTI_IO"); break; default: - HDfprintf(out, "%ld", (long)opt); + H5RS_asprintf_cat(rs, "%ld", (long)opt); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'i': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'i': /* H5D_mpio_actual_io_mode_t */ + { H5D_mpio_actual_io_mode_t actual_io_mode = (H5D_mpio_actual_io_mode_t)HDva_arg(ap, int); switch (actual_io_mode) { case H5D_MPIO_NO_COLLECTIVE: - HDfprintf(out, "H5D_MPIO_NO_COLLECTIVE"); + H5RS_acat(rs, "H5D_MPIO_NO_COLLECTIVE"); break; case H5D_MPIO_CHUNK_INDEPENDENT: - HDfprintf(out, "H5D_MPIO_CHUNK_INDEPENDENT"); + H5RS_acat(rs, "H5D_MPIO_CHUNK_INDEPENDENT"); break; case H5D_MPIO_CHUNK_COLLECTIVE: - HDfprintf(out, "H5D_MPIO_CHUNK_COLLECTIVE"); + H5RS_acat(rs, "H5D_MPIO_CHUNK_COLLECTIVE"); break; case H5D_MPIO_CHUNK_MIXED: - HDfprintf(out, "H5D_MPIO_CHUNK_MIXED"); + H5RS_acat(rs, "H5D_MPIO_CHUNK_MIXED"); break; case H5D_MPIO_CONTIGUOUS_COLLECTIVE: - HDfprintf(out, "H5D_MPIO_CONTIGUOUS_COLLECTIVE"); + H5RS_acat(rs, "H5D_MPIO_CONTIGUOUS_COLLECTIVE"); break; default: - HDfprintf(out, "%ld", (long)actual_io_mode); + H5RS_asprintf_cat(rs, "%ld", (long)actual_io_mode); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'k': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'I': /* H5FD_file_image_callbacks_t */ + { + H5FD_file_image_callbacks_t ficb = HDva_arg(ap, H5FD_file_image_callbacks_t); + + H5RS_asprintf_cat(rs, "{%p, ", (void *)(uintptr_t)ficb.image_malloc); + H5RS_asprintf_cat(rs, "%p, ", (void *)(uintptr_t)ficb.image_memcpy); + H5RS_asprintf_cat(rs, "%p, ", (void *)(uintptr_t)ficb.image_realloc); + H5RS_asprintf_cat(rs, "%p, ", (void *)(uintptr_t)ficb.image_free); + H5RS_asprintf_cat(rs, "%p, ", (void *)(uintptr_t)ficb.udata_copy); + H5RS_asprintf_cat(rs, "%p, ", (void *)(uintptr_t)ficb.udata_free); + H5RS_asprintf_cat(rs, "%p}", ficb.udata); + } /* end block */ + break; + + case 'k': /* H5D_chunk_index_t */ + { H5D_chunk_index_t idx = (H5D_chunk_index_t)HDva_arg(ap, int); switch (idx) { case H5D_CHUNK_IDX_BTREE: - HDfprintf(out, "H5D_CHUNK_IDX_BTREE"); + H5RS_acat(rs, "H5D_CHUNK_IDX_BTREE"); break; case H5D_CHUNK_IDX_NONE: - HDfprintf(out, "H5D_CHUNK_IDX_NONE"); + H5RS_acat(rs, "H5D_CHUNK_IDX_NONE"); break; case H5D_CHUNK_IDX_FARRAY: - HDfprintf(out, "H5D_CHUNK_IDX_FARRAY"); + H5RS_acat(rs, "H5D_CHUNK_IDX_FARRAY"); break; case H5D_CHUNK_IDX_EARRAY: - HDfprintf(out, "H5D_CHUNK_IDX_EARRAY"); + H5RS_acat(rs, "H5D_CHUNK_IDX_EARRAY"); break; case H5D_CHUNK_IDX_BT2: - HDfprintf(out, "H5D_CHUNK_IDX_BT2"); + H5RS_acat(rs, "H5D_CHUNK_IDX_BT2"); break; case H5D_CHUNK_IDX_SINGLE: - HDfprintf(out, "H5D_CHUNK_IDX_SINGLE"); + H5RS_acat(rs, "H5D_CHUNK_IDX_SINGLE"); break; case H5D_CHUNK_IDX_NTYPES: - HDfprintf(out, "ERROR: H5D_CHUNK_IDX_NTYPES (invalid value)"); + H5RS_acat(rs, "ERROR: H5D_CHUNK_IDX_NTYPES (invalid value)"); break; default: - HDfprintf(out, "UNKNOWN VALUE: %ld", (long)idx); + H5RS_asprintf_cat(rs, "UNKNOWN VALUE: %ld", (long)idx); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'l': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'l': /* H5D_layout_t */ + { H5D_layout_t layout = (H5D_layout_t)HDva_arg(ap, int); switch (layout) { case H5D_LAYOUT_ERROR: - HDfprintf(out, "H5D_LAYOUT_ERROR"); + H5RS_acat(rs, "H5D_LAYOUT_ERROR"); break; case H5D_COMPACT: - HDfprintf(out, "H5D_COMPACT"); + H5RS_acat(rs, "H5D_COMPACT"); break; case H5D_CONTIGUOUS: - HDfprintf(out, "H5D_CONTIGUOUS"); + H5RS_acat(rs, "H5D_CONTIGUOUS"); break; case H5D_CHUNKED: - HDfprintf(out, "H5D_CHUNKED"); + H5RS_acat(rs, "H5D_CHUNKED"); break; case H5D_VIRTUAL: - HDfprintf(out, "H5D_VIRTUAL"); + H5RS_acat(rs, "H5D_VIRTUAL"); break; case H5D_NLAYOUTS: - HDfprintf(out, "H5D_NLAYOUTS"); + H5RS_acat(rs, "H5D_NLAYOUTS"); break; default: - HDfprintf(out, "%ld", (long)layout); + H5RS_asprintf_cat(rs, "%ld", (long)layout); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'n': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'n': /* H5D_mpio_no_collective_cause_t */ + { H5D_mpio_no_collective_cause_t nocol_cause_mode = (H5D_mpio_no_collective_cause_t)HDva_arg(ap, int); hbool_t flag_already_displayed = FALSE; /* Check for all bit-flags which might be set */ if (nocol_cause_mode & H5D_MPIO_COLLECTIVE) { - HDfprintf(out, "H5D_MPIO_COLLECTIVE"); + H5RS_acat(rs, "H5D_MPIO_COLLECTIVE"); flag_already_displayed = TRUE; } /* end if */ if (nocol_cause_mode & H5D_MPIO_SET_INDEPENDENT) { - HDfprintf(out, "%sH5D_MPIO_SET_INDEPENDENT", - flag_already_displayed ? " | " : ""); + H5RS_asprintf_cat(rs, "%sH5D_MPIO_SET_INDEPENDENT", + flag_already_displayed ? " | " : ""); flag_already_displayed = TRUE; } /* end if */ if (nocol_cause_mode & H5D_MPIO_DATATYPE_CONVERSION) { - HDfprintf(out, "%sH5D_MPIO_DATATYPE_CONVERSION", - flag_already_displayed ? " | " : ""); + H5RS_asprintf_cat(rs, "%sH5D_MPIO_DATATYPE_CONVERSION", + flag_already_displayed ? " | " : ""); flag_already_displayed = TRUE; } /* end if */ if (nocol_cause_mode & H5D_MPIO_DATA_TRANSFORMS) { - HDfprintf(out, "%sH5D_MPIO_DATA_TRANSFORMS", - flag_already_displayed ? " | " : ""); + H5RS_asprintf_cat(rs, "%sH5D_MPIO_DATA_TRANSFORMS", + flag_already_displayed ? " | " : ""); flag_already_displayed = TRUE; } /* end if */ if (nocol_cause_mode & H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED) { - HDfprintf(out, "%sH5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED", - flag_already_displayed ? " | " : ""); + H5RS_asprintf_cat(rs, "%sH5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED", + flag_already_displayed ? " | " : ""); flag_already_displayed = TRUE; } /* end if */ if (nocol_cause_mode & H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES) { - HDfprintf(out, "%sH5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES", - flag_already_displayed ? " | " : ""); + H5RS_asprintf_cat(rs, "%sH5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES", + flag_already_displayed ? " | " : ""); flag_already_displayed = TRUE; } /* end if */ if (nocol_cause_mode & H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET) { - HDfprintf(out, "%sH5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET", - flag_already_displayed ? " | " : ""); + H5RS_asprintf_cat(rs, "%sH5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET", + flag_already_displayed ? " | " : ""); flag_already_displayed = TRUE; } /* end if */ /* Display '<none>' if there's no flags set */ if (!flag_already_displayed) - HDfprintf(out, "<none>"); - } /* end else */ + H5RS_acat(rs, "<none>"); + } /* end block */ break; - case 'o': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'o': /* H5D_mpio_actual_chunk_opt_mode_t */ + { H5D_mpio_actual_chunk_opt_mode_t chunk_opt_mode = (H5D_mpio_actual_chunk_opt_mode_t)HDva_arg(ap, int); switch (chunk_opt_mode) { case H5D_MPIO_NO_CHUNK_OPTIMIZATION: - HDfprintf(out, "H5D_MPIO_NO_CHUNK_OPTIMIZATION"); + H5RS_acat(rs, "H5D_MPIO_NO_CHUNK_OPTIMIZATION"); break; case H5D_MPIO_LINK_CHUNK: - HDfprintf(out, "H5D_MPIO_LINK_CHUNK"); + H5RS_acat(rs, "H5D_MPIO_LINK_CHUNK"); break; case H5D_MPIO_MULTI_CHUNK: - HDfprintf(out, "H5D_MPIO_MULTI_CHUNK"); + H5RS_acat(rs, "H5D_MPIO_MULTI_CHUNK"); break; default: - HDfprintf(out, "%ld", (long)chunk_opt_mode); + H5RS_asprintf_cat(rs, "%ld", (long)chunk_opt_mode); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'O': /* H5D_operator_t */ + { + H5D_operator_t dop = (H5D_operator_t)HDva_arg(ap, H5D_operator_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)dop); + } /* end block */ + break; + + case 's': /* H5D_space_status_t */ + { H5D_space_status_t space_status = (H5D_space_status_t)HDva_arg(ap, int); switch (space_status) { case H5D_SPACE_STATUS_NOT_ALLOCATED: - HDfprintf(out, "H5D_SPACE_STATUS_NOT_ALLOCATED"); + H5RS_acat(rs, "H5D_SPACE_STATUS_NOT_ALLOCATED"); break; case H5D_SPACE_STATUS_PART_ALLOCATED: - HDfprintf(out, "H5D_SPACE_STATUS_PART_ALLOCATED"); + H5RS_acat(rs, "H5D_SPACE_STATUS_PART_ALLOCATED"); break; case H5D_SPACE_STATUS_ALLOCATED: - HDfprintf(out, "H5D_SPACE_STATUS_ALLOCATED"); + H5RS_acat(rs, "H5D_SPACE_STATUS_ALLOCATED"); break; case H5D_SPACE_STATUS_ERROR: - HDfprintf(out, "H5D_SPACE_STATUS_ERROR"); + H5RS_acat(rs, "H5D_SPACE_STATUS_ERROR"); break; default: - HDfprintf(out, "%ld", (long)space_status); + H5RS_asprintf_cat(rs, "%ld", (long)space_status); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'S': /* H5D_scatter_func_t */ + { + H5D_scatter_func_t sop = (H5D_scatter_func_t)HDva_arg(ap, H5D_scatter_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)sop); + } /* end block */ + break; + + case 't': /* H5FD_mpio_xfer_t */ + { H5FD_mpio_xfer_t transfer = (H5FD_mpio_xfer_t)HDva_arg(ap, int); switch (transfer) { case H5FD_MPIO_INDEPENDENT: - HDfprintf(out, "H5FD_MPIO_INDEPENDENT"); + H5RS_acat(rs, "H5FD_MPIO_INDEPENDENT"); break; case H5FD_MPIO_COLLECTIVE: - HDfprintf(out, "H5FD_MPIO_COLLECTIVE"); + H5RS_acat(rs, "H5FD_MPIO_COLLECTIVE"); break; default: - HDfprintf(out, "%ld", (long)transfer); + H5RS_asprintf_cat(rs, "%ld", (long)transfer); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'v': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'v': /* H5D_vds_view_t */ + { H5D_vds_view_t view = (H5D_vds_view_t)HDva_arg(ap, int); switch (view) { case H5D_VDS_ERROR: - HDfprintf(out, "H5D_VDS_ERROR"); + H5RS_acat(rs, "H5D_VDS_ERROR"); break; case H5D_VDS_FIRST_MISSING: - HDfprintf(out, "H5D_VDS_FIRST_MISSING"); + H5RS_acat(rs, "H5D_VDS_FIRST_MISSING"); break; case H5D_VDS_LAST_AVAILABLE: - HDfprintf(out, "H5D_VDS_LAST_AVAILABLE"); + H5RS_acat(rs, "H5D_VDS_LAST_AVAILABLE"); break; default: - HDfprintf(out, "%ld", (long)view); + H5RS_asprintf_cat(rs, "%ld", (long)view); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(D%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(D%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'e': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'e': /* herr_t */ + { herr_t status = HDva_arg(ap, herr_t); if (status >= 0) - HDfprintf(out, "SUCCEED"); + H5RS_acat(rs, "SUCCEED"); else - HDfprintf(out, "FAIL"); - } /* end else */ + H5RS_acat(rs, "FAIL"); + } /* end block */ break; - case 'E': - switch (type[1]) { - case 'd': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'E': + switch (type[1]) { +#ifndef H5_NO_DEPRECATED_SYMBOLS + case 'a': /* H5E_auto1_t */ + { + H5E_auto1_t eauto1 = (H5E_auto1_t)HDva_arg(ap, H5E_auto1_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)eauto1); + } /* end block */ + break; +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + + case 'A': /* H5E_auto2_t */ + { + H5E_auto2_t eauto2 = (H5E_auto2_t)HDva_arg(ap, H5E_auto2_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)eauto2); + } /* end block */ + break; + + case 'd': /* H5E_direction_t */ + { H5E_direction_t direction = (H5E_direction_t)HDva_arg(ap, int); switch (direction) { case H5E_WALK_UPWARD: - HDfprintf(out, "H5E_WALK_UPWARD"); + H5RS_acat(rs, "H5E_WALK_UPWARD"); break; case H5E_WALK_DOWNWARD: - HDfprintf(out, "H5E_WALK_DOWNWARD"); + H5RS_acat(rs, "H5E_WALK_DOWNWARD"); break; default: - HDfprintf(out, "%ld", (long)direction); + H5RS_asprintf_cat(rs, "%ld", (long)direction); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'e': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'e': /* H5E_error_t */ + { H5E_error2_t *error = HDva_arg(ap, H5E_error2_t *); - HDfprintf(out, "0x%p", (void *)error); - } /* end else */ + H5RS_asprintf_cat(rs, "%p", (void *)error); + } /* end block */ break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 's': /* H5ES_status_t */ + { H5ES_status_t status = (H5ES_status_t)HDva_arg(ap, int); switch (status) { case H5ES_STATUS_IN_PROGRESS: - HDfprintf(out, "H5ES_STATUS_IN_PROGRESS"); + H5RS_acat(rs, "H5ES_STATUS_IN_PROGRESS"); break; + case H5ES_STATUS_SUCCEED: - HDfprintf(out, "H5ES_STATUS_SUCCEED"); + H5RS_acat(rs, "H5ES_STATUS_SUCCEED"); break; + case H5ES_STATUS_FAIL: - HDfprintf(out, "H5ES_STATUS_FAIL"); + H5RS_acat(rs, "H5ES_STATUS_FAIL"); break; + case H5ES_STATUS_CANCELED: - HDfprintf(out, "H5ES_STATUS_CANCELED"); + H5RS_acat(rs, "H5ES_STATUS_CANCELED"); break; default: - HDfprintf(out, "%ld", (long)status); + H5RS_asprintf_cat(rs, "%ld", (long)status); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 't': /* H5E_type_t */ + { H5E_type_t etype = (H5E_type_t)HDva_arg(ap, int); switch (etype) { case H5E_MAJOR: - HDfprintf(out, "H5E_MAJOR"); + H5RS_acat(rs, "H5E_MAJOR"); break; case H5E_MINOR: - HDfprintf(out, "H5E_MINOR"); + H5RS_acat(rs, "H5E_MINOR"); break; default: - HDfprintf(out, "%ld", (long)etype); + H5RS_asprintf_cat(rs, "%ld", (long)etype); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(E%c)", type[1]); - goto error; - } /* end switch */ - break; - - case 'F': - switch (type[1]) { - case 'd': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { - H5F_close_degree_t degree = (H5F_close_degree_t)HDva_arg(ap, int); - - switch (degree) { - case H5F_CLOSE_DEFAULT: - HDfprintf(out, "H5F_CLOSE_DEFAULT"); - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(E%c)", type[1]); + goto error; + } /* end switch */ + break; - case H5F_CLOSE_WEAK: - HDfprintf(out, "H5F_CLOSE_WEAK"); - break; + case 'F': + switch (type[1]) { + case 'C': /* H5FD_class_t */ + { + H5FD_class_t cls = HDva_arg(ap, H5FD_class_t); - case H5F_CLOSE_SEMI: - HDfprintf(out, "H5F_CLOSE_SEMI"); - break; + H5RS_asprintf_cat(rs, "{'%s', " H5_PRINTF_HADDR_FMT ", ", cls.name, cls.maxaddr); + H5_trace_args_close_degree(rs, cls.fc_degree); + H5RS_acat(rs, ", ...}"); + } /* end block */ + break; - case H5F_CLOSE_STRONG: - HDfprintf(out, "H5F_CLOSE_STRONG"); - break; + case 'd': /* H5F_close_degree_t */ + { + H5F_close_degree_t degree = (H5F_close_degree_t)HDva_arg(ap, int); - default: - HDfprintf(out, "%ld", (long)degree); - break; - } /* end switch */ - } /* end else */ + H5_trace_args_close_degree(rs, degree); + } /* end block */ break; - case 'f': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'f': /* H5F_fspace_strategy_t */ + { H5F_fspace_strategy_t fs_strategy = (H5F_fspace_strategy_t)HDva_arg(ap, int); switch (fs_strategy) { case H5F_FSPACE_STRATEGY_FSM_AGGR: - HDfprintf(out, "H5F_FSPACE_STRATEGY_FSM_AGGR"); + H5RS_acat(rs, "H5F_FSPACE_STRATEGY_FSM_AGGR"); break; case H5F_FSPACE_STRATEGY_PAGE: - HDfprintf(out, "H5F_FSPACE_STRATEGY_PAGE"); + H5RS_acat(rs, "H5F_FSPACE_STRATEGY_PAGE"); break; case H5F_FSPACE_STRATEGY_AGGR: - HDfprintf(out, "H5F_FSPACE_STRATEGY_AGGR"); + H5RS_acat(rs, "H5F_FSPACE_STRATEGY_AGGR"); break; case H5F_FSPACE_STRATEGY_NONE: - HDfprintf(out, "H5F_FSPACE_STRATEGY_NONE"); + H5RS_acat(rs, "H5F_FSPACE_STRATEGY_NONE"); break; case H5F_FSPACE_STRATEGY_NTYPES: default: - HDfprintf(out, "%ld", (long)fs_strategy); + H5RS_asprintf_cat(rs, "%ld", (long)fs_strategy); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'm': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'F': /* H5F_flush_cb_t */ + { + H5F_flush_cb_t fflsh = (H5F_flush_cb_t)HDva_arg(ap, H5F_flush_cb_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)fflsh); + } /* end block */ + break; + + case 'I': /* H5F_info2_t */ + { + H5F_info2_t fi2 = HDva_arg(ap, H5F_info2_t); + + H5RS_asprintf_cat(rs, "{{%u, %" PRIuHSIZE ", %" PRIuHSIZE "}, ", + fi2.super.version, fi2.super.super_size, + fi2.super.super_ext_size); + H5RS_asprintf_cat(rs, "{%u, %" PRIuHSIZE ", %" PRIuHSIZE "}, ", fi2.free.version, + fi2.free.meta_size, fi2.free.tot_space); + H5RS_asprintf_cat(rs, "{%u, %" PRIuHSIZE ", {%" PRIuHSIZE ", %" PRIuHSIZE "}}}", + fi2.sohm.version, fi2.sohm.hdr_size, + fi2.sohm.msgs_info.index_size, fi2.sohm.msgs_info.heap_size); + } /* end block */ + break; + + case 'm': /* H5F_mem_t */ + { H5F_mem_t mem_type = (H5F_mem_t)HDva_arg(ap, int); switch (mem_type) { case H5FD_MEM_NOLIST: - HDfprintf(out, "H5FD_MEM_NOLIST"); + H5RS_acat(rs, "H5FD_MEM_NOLIST"); break; case H5FD_MEM_DEFAULT: - HDfprintf(out, "H5FD_MEM_DEFAULT"); + H5RS_acat(rs, "H5FD_MEM_DEFAULT"); break; case H5FD_MEM_SUPER: - HDfprintf(out, "H5FD_MEM_SUPER"); + H5RS_acat(rs, "H5FD_MEM_SUPER"); break; case H5FD_MEM_BTREE: - HDfprintf(out, "H5FD_MEM_BTREE"); + H5RS_acat(rs, "H5FD_MEM_BTREE"); break; case H5FD_MEM_DRAW: - HDfprintf(out, "H5FD_MEM_DRAW"); + H5RS_acat(rs, "H5FD_MEM_DRAW"); break; case H5FD_MEM_GHEAP: - HDfprintf(out, "H5FD_MEM_GHEAP"); + H5RS_acat(rs, "H5FD_MEM_GHEAP"); break; case H5FD_MEM_LHEAP: - HDfprintf(out, "H5FD_MEM_LHEAP"); + H5RS_acat(rs, "H5FD_MEM_LHEAP"); break; case H5FD_MEM_OHDR: - HDfprintf(out, "H5FD_MEM_OHDR"); + H5RS_acat(rs, "H5FD_MEM_OHDR"); break; case H5FD_MEM_NTYPES: default: - HDfprintf(out, "%ld", (long)mem_type); + H5RS_asprintf_cat(rs, "%ld", (long)mem_type); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 's': /* H5F_scope_t */ + { H5F_scope_t scope = (H5F_scope_t)HDva_arg(ap, int); switch (scope) { case H5F_SCOPE_LOCAL: - HDfprintf(out, "H5F_SCOPE_LOCAL"); + H5RS_acat(rs, "H5F_SCOPE_LOCAL"); break; case H5F_SCOPE_GLOBAL: - HDfprintf(out, "H5F_SCOPE_GLOBAL"); + H5RS_acat(rs, "H5F_SCOPE_GLOBAL"); break; default: - HDfprintf(out, "%ld", (long)scope); + H5RS_asprintf_cat(rs, "%ld", (long)scope); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ + case 't': /* H5F_file_space_type_t */ + { + H5F_file_space_type_t fspace_type = (H5F_file_space_type_t)HDva_arg(ap, int); + + switch (fspace_type) { + case H5F_FILE_SPACE_DEFAULT: + H5RS_acat(rs, "H5F_FILE_SPACE_DEFAULT"); + break; + + case H5F_FILE_SPACE_ALL_PERSIST: + H5RS_acat(rs, "H5F_FILE_SPACE_ALL_PERSIST"); + break; + + case H5F_FILE_SPACE_ALL: + H5RS_acat(rs, "H5F_FILE_SPACE_ALL"); + break; + + case H5F_FILE_SPACE_AGGR_VFD: + H5RS_acat(rs, "H5F_FILE_SPACE_AGGR_VFD"); + break; + + case H5F_FILE_SPACE_VFD: + H5RS_acat(rs, "H5F_FILE_SPACE_VFD"); + break; + + case H5F_FILE_SPACE_NTYPES: + default: + H5RS_asprintf_cat(rs, "%ld", (long)fspace_type); + break; + } /* end switch */ + } /* end block */ break; - case 'v': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'v': /* H5F_libver_t */ + { H5F_libver_t libver_vers = (H5F_libver_t)HDva_arg(ap, int); switch (libver_vers) { case H5F_LIBVER_EARLIEST: - HDfprintf(out, "H5F_LIBVER_EARLIEST"); + H5RS_acat(rs, "H5F_LIBVER_EARLIEST"); break; case H5F_LIBVER_V18: - HDfprintf(out, "H5F_LIBVER_V18"); + H5RS_acat(rs, "H5F_LIBVER_V18"); break; case H5F_LIBVER_V110: - HDfprintf(out, "H5F_LIBVER_V110"); + H5RS_acat(rs, "H5F_LIBVER_V110"); break; case H5F_LIBVER_V112: - HDfprintf(out, "H5F_LIBVER_V112"); + H5RS_acat(rs, "H5F_LIBVER_V112"); break; case H5F_LIBVER_V114: HDcompile_assert(H5F_LIBVER_LATEST == H5F_LIBVER_V114); - HDfprintf(out, "H5F_LIBVER_LATEST"); + H5RS_acat(rs, "H5F_LIBVER_LATEST"); break; case H5F_LIBVER_ERROR: case H5F_LIBVER_NBOUNDS: default: - HDfprintf(out, "%ld", (long)libver_vers); + H5RS_asprintf_cat(rs, "%ld", (long)libver_vers); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(F%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(F%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'G': - switch (type[1]) { + case 'G': + switch (type[1]) { #ifndef H5_NO_DEPRECATED_SYMBOLS - case 'o': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'i': /* H5G_iterate_t */ + { + H5G_iterate_t git = (H5G_iterate_t)HDva_arg(ap, H5G_iterate_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)git); + } /* end block */ + break; + + case 'o': /* H5G_obj_t */ + { H5G_obj_t obj_type = (H5G_obj_t)HDva_arg(ap, int); switch (obj_type) { case H5G_UNKNOWN: - HDfprintf(out, "H5G_UNKNOWN"); + H5RS_acat(rs, "H5G_UNKNOWN"); break; case H5G_GROUP: - HDfprintf(out, "H5G_GROUP"); + H5RS_acat(rs, "H5G_GROUP"); break; case H5G_DATASET: - HDfprintf(out, "H5G_DATASET"); + H5RS_acat(rs, "H5G_DATASET"); break; case H5G_TYPE: - HDfprintf(out, "H5G_TYPE"); + H5RS_acat(rs, "H5G_TYPE"); break; case H5G_LINK: - HDfprintf(out, "H5G_LINK"); + H5RS_acat(rs, "H5G_LINK"); break; case H5G_UDLINK: - HDfprintf(out, "H5G_UDLINK"); + H5RS_acat(rs, "H5G_UDLINK"); break; case H5G_RESERVED_5: case H5G_RESERVED_6: case H5G_RESERVED_7: - HDfprintf(out, "H5G_RESERVED(%ld)", (long)obj_type); + H5RS_asprintf_cat(rs, "H5G_RESERVED(%ld)", (long)obj_type); break; default: - HDfprintf(out, "%ld", (long)obj_type); + H5RS_asprintf_cat(rs, "%ld", (long)obj_type); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 's': /* H5G_stat_t */ + { H5G_stat_t *statbuf = HDva_arg(ap, H5G_stat_t *); - HDfprintf(out, "0x%p", (void *)statbuf); - } + H5RS_asprintf_cat(rs, "%p", (void *)statbuf); + } /* end block */ break; #endif /* H5_NO_DEPRECATED_SYMBOLS */ - default: - HDfprintf(out, "BADTYPE(G%c)", type[1]); - goto error; - } - break; - - case 'h': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - hsize_t *p = (hsize_t *)vp; + default: + H5RS_asprintf_cat(rs, "BADTYPE(G%c)", type[1]); + goto error; + } /* end switch */ + break; - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) { - if (H5S_UNLIMITED == p[i]) - HDfprintf(out, "%sH5S_UNLIMITED", (i ? ", " : "")); - else - HDfprintf(out, "%s%" PRIuHSIZE, (i ? ", " : ""), p[i]); - } /* end for */ - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'h': /* hsize_t */ + { hsize_t hsize = HDva_arg(ap, hsize_t); if (H5S_UNLIMITED == hsize) - HDfprintf(out, "H5S_UNLIMITED"); + H5RS_acat(rs, "H5S_UNLIMITED"); else { - HDfprintf(out, "%" PRIuHSIZE, hsize); + H5RS_asprintf_cat(rs, "%" PRIuHSIZE, hsize); asize[argno] = (hssize_t)hsize; } /* end else */ - } /* end else */ + } /* end block */ break; - case 'H': - switch (type[1]) { - case 's': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - hssize_t *p = (hssize_t *)vp; - - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) - HDfprintf(out, "%s%" PRIdHSIZE, (i ? ", " : ""), p[i]); - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'H': + switch (type[1]) { + case 'a': /* H5_alloc_stats_t */ + { + H5_alloc_stats_t stats = HDva_arg(ap, H5_alloc_stats_t); + + H5RS_asprintf_cat(rs, "{%llu, %zu, %zu, %zu, %zu, %zu, %zu}", + stats.total_alloc_bytes, stats.curr_alloc_bytes, + stats.peak_alloc_bytes, stats.max_block_size, + stats.total_alloc_blocks_count, stats.curr_alloc_blocks_count, + stats.peak_alloc_blocks_count); + } /* end block */ + break; + + case 's': /* hssize_t */ + { hssize_t hssize = HDva_arg(ap, hssize_t); - HDfprintf(out, "%" PRIdHSIZE, hssize); + H5RS_asprintf_cat(rs, "%" PRIdHSIZE, hssize); asize[argno] = (hssize_t)hssize; - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(H%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(H%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'i': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'i': /* hid_t (and H5E_major_t / H5E_minor_t) */ + { hid_t obj = HDva_arg(ap, hid_t); if (H5P_DEFAULT == obj) - HDfprintf(out, "H5P_DEFAULT"); + H5RS_acat(rs, "H5P_DEFAULT"); else if (obj < 0) - HDfprintf(out, "FAIL"); + H5RS_acat(rs, "FAIL"); else { switch (H5I_TYPE(obj)) { /* Use internal H5I macro instead of function call */ case H5I_UNINIT: - HDfprintf(out, "%ld (uninit - error)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (uninit - error)", (unsigned long long)obj); break; case H5I_BADID: - HDfprintf(out, "%ld (error)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (badid - error)", (unsigned long long)obj); break; case H5I_FILE: - HDfprintf(out, "%ld (file)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (file)", (unsigned long long)obj); break; case H5I_GROUP: - HDfprintf(out, "%ld (group)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (group)", (unsigned long long)obj); break; case H5I_DATATYPE: if (obj == H5T_NATIVE_SCHAR_g) - HDfprintf(out, "H5T_NATIVE_SCHAR"); + H5RS_acat(rs, "H5T_NATIVE_SCHAR"); else if (obj == H5T_NATIVE_UCHAR_g) - HDfprintf(out, "H5T_NATIVE_UCHAR"); + H5RS_acat(rs, "H5T_NATIVE_UCHAR"); else if (obj == H5T_NATIVE_SHORT_g) - HDfprintf(out, "H5T_NATIVE_SHORT"); + H5RS_acat(rs, "H5T_NATIVE_SHORT"); else if (obj == H5T_NATIVE_USHORT_g) - HDfprintf(out, "H5T_NATIVE_USHORT"); + H5RS_acat(rs, "H5T_NATIVE_USHORT"); else if (obj == H5T_NATIVE_INT_g) - HDfprintf(out, "H5T_NATIVE_INT"); + H5RS_acat(rs, "H5T_NATIVE_INT"); else if (obj == H5T_NATIVE_UINT_g) - HDfprintf(out, "H5T_NATIVE_UINT"); + H5RS_acat(rs, "H5T_NATIVE_UINT"); else if (obj == H5T_NATIVE_LONG_g) - HDfprintf(out, "H5T_NATIVE_LONG"); + H5RS_acat(rs, "H5T_NATIVE_LONG"); else if (obj == H5T_NATIVE_ULONG_g) - HDfprintf(out, "H5T_NATIVE_ULONG"); + H5RS_acat(rs, "H5T_NATIVE_ULONG"); else if (obj == H5T_NATIVE_LLONG_g) - HDfprintf(out, "H5T_NATIVE_LLONG"); + H5RS_acat(rs, "H5T_NATIVE_LLONG"); else if (obj == H5T_NATIVE_ULLONG_g) - HDfprintf(out, "H5T_NATIVE_ULLONG"); + H5RS_acat(rs, "H5T_NATIVE_ULLONG"); else if (obj == H5T_NATIVE_FLOAT_g) - HDfprintf(out, "H5T_NATIVE_FLOAT"); + H5RS_acat(rs, "H5T_NATIVE_FLOAT"); else if (obj == H5T_NATIVE_DOUBLE_g) - HDfprintf(out, "H5T_NATIVE_DOUBLE"); + H5RS_acat(rs, "H5T_NATIVE_DOUBLE"); #if H5_SIZEOF_LONG_DOUBLE != 0 else if (obj == H5T_NATIVE_LDOUBLE_g) - HDfprintf(out, "H5T_NATIVE_LDOUBLE"); + H5RS_acat(rs, "H5T_NATIVE_LDOUBLE"); #endif else if (obj == H5T_IEEE_F32BE_g) - HDfprintf(out, "H5T_IEEE_F32BE"); + H5RS_acat(rs, "H5T_IEEE_F32BE"); else if (obj == H5T_IEEE_F32LE_g) - HDfprintf(out, "H5T_IEEE_F32LE"); + H5RS_acat(rs, "H5T_IEEE_F32LE"); else if (obj == H5T_IEEE_F64BE_g) - HDfprintf(out, "H5T_IEEE_F64BE"); + H5RS_acat(rs, "H5T_IEEE_F64BE"); else if (obj == H5T_IEEE_F64LE_g) - HDfprintf(out, "H5T_IEEE_F64LE"); + H5RS_acat(rs, "H5T_IEEE_F64LE"); else if (obj == H5T_STD_I8BE_g) - HDfprintf(out, "H5T_STD_I8BE"); + H5RS_acat(rs, "H5T_STD_I8BE"); else if (obj == H5T_STD_I8LE_g) - HDfprintf(out, "H5T_STD_I8LE"); + H5RS_acat(rs, "H5T_STD_I8LE"); else if (obj == H5T_STD_I16BE_g) - HDfprintf(out, "H5T_STD_I16BE"); + H5RS_acat(rs, "H5T_STD_I16BE"); else if (obj == H5T_STD_I16LE_g) - HDfprintf(out, "H5T_STD_I16LE"); + H5RS_acat(rs, "H5T_STD_I16LE"); else if (obj == H5T_STD_I32BE_g) - HDfprintf(out, "H5T_STD_I32BE"); + H5RS_acat(rs, "H5T_STD_I32BE"); else if (obj == H5T_STD_I32LE_g) - HDfprintf(out, "H5T_STD_I32LE"); + H5RS_acat(rs, "H5T_STD_I32LE"); else if (obj == H5T_STD_I64BE_g) - HDfprintf(out, "H5T_STD_I64BE"); + H5RS_acat(rs, "H5T_STD_I64BE"); else if (obj == H5T_STD_I64LE_g) - HDfprintf(out, "H5T_STD_I64LE"); + H5RS_acat(rs, "H5T_STD_I64LE"); else if (obj == H5T_STD_U8BE_g) - HDfprintf(out, "H5T_STD_U8BE"); + H5RS_acat(rs, "H5T_STD_U8BE"); else if (obj == H5T_STD_U8LE_g) - HDfprintf(out, "H5T_STD_U8LE"); + H5RS_acat(rs, "H5T_STD_U8LE"); else if (obj == H5T_STD_U16BE_g) - HDfprintf(out, "H5T_STD_U16BE"); + H5RS_acat(rs, "H5T_STD_U16BE"); else if (obj == H5T_STD_U16LE_g) - HDfprintf(out, "H5T_STD_U16LE"); + H5RS_acat(rs, "H5T_STD_U16LE"); else if (obj == H5T_STD_U32BE_g) - HDfprintf(out, "H5T_STD_U32BE"); + H5RS_acat(rs, "H5T_STD_U32BE"); else if (obj == H5T_STD_U32LE_g) - HDfprintf(out, "H5T_STD_U32LE"); + H5RS_acat(rs, "H5T_STD_U32LE"); else if (obj == H5T_STD_U64BE_g) - HDfprintf(out, "H5T_STD_U64BE"); + H5RS_acat(rs, "H5T_STD_U64BE"); else if (obj == H5T_STD_U64LE_g) - HDfprintf(out, "H5T_STD_U64LE"); + H5RS_acat(rs, "H5T_STD_U64LE"); else if (obj == H5T_STD_B8BE_g) - HDfprintf(out, "H5T_STD_B8BE"); + H5RS_acat(rs, "H5T_STD_B8BE"); else if (obj == H5T_STD_B8LE_g) - HDfprintf(out, "H5T_STD_B8LE"); + H5RS_acat(rs, "H5T_STD_B8LE"); else if (obj == H5T_STD_B16BE_g) - HDfprintf(out, "H5T_STD_B16BE"); + H5RS_acat(rs, "H5T_STD_B16BE"); else if (obj == H5T_STD_B16LE_g) - HDfprintf(out, "H5T_STD_B16LE"); + H5RS_acat(rs, "H5T_STD_B16LE"); else if (obj == H5T_STD_B32BE_g) - HDfprintf(out, "H5T_STD_B32BE"); + H5RS_acat(rs, "H5T_STD_B32BE"); else if (obj == H5T_STD_B32LE_g) - HDfprintf(out, "H5T_STD_B32LE"); + H5RS_acat(rs, "H5T_STD_B32LE"); else if (obj == H5T_STD_B64BE_g) - HDfprintf(out, "H5T_STD_B64BE"); + H5RS_acat(rs, "H5T_STD_B64BE"); else if (obj == H5T_STD_B64LE_g) - HDfprintf(out, "H5T_STD_B64LE"); + H5RS_acat(rs, "H5T_STD_B64LE"); else if (obj == H5T_C_S1_g) - HDfprintf(out, "H5T_C_S1"); + H5RS_acat(rs, "H5T_C_S1"); else if (obj == H5T_FORTRAN_S1_g) - HDfprintf(out, "H5T_FORTRAN_S1"); + H5RS_acat(rs, "H5T_FORTRAN_S1"); else - HDfprintf(out, "%ld (dtype)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (dtype)", (unsigned long long)obj); break; case H5I_DATASPACE: - HDfprintf(out, "%ld (dspace)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (dspace)", (unsigned long long)obj); /* Save the rank of simple dataspaces for arrays */ /* This may generate recursive call to the library... -QAK */ { @@ -1371,506 +1619,515 @@ H5_trace(const double *returning, const char *func, const char *type, ...) break; case H5I_DATASET: - HDfprintf(out, "%ld (dset)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (dset)", (unsigned long long)obj); break; case H5I_ATTR: - HDfprintf(out, "%ld (attr)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (attr)", (unsigned long long)obj); break; case H5I_MAP: - HDfprintf(out, "%ld (map)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (map)", (unsigned long long)obj); break; case H5I_VFL: - HDfprintf(out, "%ld (file driver)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (file driver)", (unsigned long long)obj); break; case H5I_VOL: - HDfprintf(out, "%ld (VOL plugin)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (VOL plugin)", (unsigned long long)obj); break; case H5I_GENPROP_CLS: - HDfprintf(out, "%ld (genprop class)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (genprop class)", (unsigned long long)obj); break; case H5I_GENPROP_LST: - HDfprintf(out, "%ld (genprop list)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (genprop list)", (unsigned long long)obj); break; case H5I_ERROR_CLASS: - HDfprintf(out, "%ld (err class)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (err class)", (unsigned long long)obj); break; case H5I_ERROR_MSG: - HDfprintf(out, "%ld (err msg)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (err msg)", (unsigned long long)obj); break; case H5I_ERROR_STACK: - HDfprintf(out, "%ld (err stack)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (err stack)", (unsigned long long)obj); break; case H5I_SPACE_SEL_ITER: - HDfprintf(out, "%ld (dataspace selection iterator)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (dataspace selection iterator)", + (unsigned long long)obj); break; case H5I_NTYPES: - HDfprintf(out, "%ld (ntypes - error)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (ntypes - error)", (unsigned long long)obj); break; default: - HDfprintf(out, "%ld (unknown class)", (long)obj); + H5RS_asprintf_cat(rs, "0x%0llx (unknown class)", (unsigned long long)obj); break; } /* end switch */ } /* end else */ - } /* end else */ + } /* end block */ break; - case 'I': - switch (type[1]) { - case 'i': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'I': + switch (type[1]) { + case 'f': /* H5I_free_t */ + { + H5I_free_t ifree = (H5I_free_t)HDva_arg(ap, H5I_free_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)ifree); + } /* end block */ + break; + + case 'i': /* H5_index_t */ + { H5_index_t idx_type = (H5_index_t)HDva_arg(ap, int); switch (idx_type) { case H5_INDEX_UNKNOWN: - HDfprintf(out, "H5_INDEX_UNKNOWN"); + H5RS_acat(rs, "H5_INDEX_UNKNOWN"); break; case H5_INDEX_NAME: - HDfprintf(out, "H5_INDEX_NAME"); + H5RS_acat(rs, "H5_INDEX_NAME"); break; case H5_INDEX_CRT_ORDER: - HDfprintf(out, "H5_INDEX_CRT_ORDER"); + H5RS_acat(rs, "H5_INDEX_CRT_ORDER"); break; case H5_INDEX_N: - HDfprintf(out, "H5_INDEX_N"); + H5RS_acat(rs, "H5_INDEX_N"); break; default: - HDfprintf(out, "%ld", (long)idx_type); + H5RS_asprintf_cat(rs, "%ld", (long)idx_type); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'o': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'I': /* H5I_iterate_func_t */ + { + H5I_iterate_func_t iiter = (H5I_iterate_func_t)HDva_arg(ap, H5I_iterate_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)iiter); + } /* end block */ + break; + + case 'o': /* H5_iter_order_t */ + { H5_iter_order_t order = (H5_iter_order_t)HDva_arg(ap, int); switch (order) { case H5_ITER_UNKNOWN: - HDfprintf(out, "H5_ITER_UNKNOWN"); + H5RS_acat(rs, "H5_ITER_UNKNOWN"); break; case H5_ITER_INC: - HDfprintf(out, "H5_ITER_INC"); + H5RS_acat(rs, "H5_ITER_INC"); break; case H5_ITER_DEC: - HDfprintf(out, "H5_ITER_DEC"); + H5RS_acat(rs, "H5_ITER_DEC"); break; case H5_ITER_NATIVE: - HDfprintf(out, "H5_ITER_NATIVE"); + H5RS_acat(rs, "H5_ITER_NATIVE"); break; case H5_ITER_N: - HDfprintf(out, "H5_ITER_N"); + H5RS_acat(rs, "H5_ITER_N"); break; default: - HDfprintf(out, "%ld", (long)order); + H5RS_asprintf_cat(rs, "%ld", (long)order); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 's': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - int *p = (int *)vp; - - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) - HDfprintf(out, "%s%d", (i ? ", " : ""), p[i]); - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 's': /* int / int32_t */ + { int is = HDva_arg(ap, int); - HDfprintf(out, "%d", is); + H5RS_asprintf_cat(rs, "%d", is); asize[argno] = is; - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'S': /* H5I_search_func_t */ + { + H5I_search_func_t isearch = (H5I_search_func_t)HDva_arg(ap, H5I_search_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)isearch); + } /* end block */ + break; + + case 't': /* H5I_type_t */ + { H5I_type_t id_type = (H5I_type_t)HDva_arg(ap, int); switch (id_type) { case H5I_UNINIT: - HDfprintf(out, "H5I_UNINIT"); + H5RS_acat(rs, "H5I_UNINIT"); break; case H5I_BADID: - HDfprintf(out, "H5I_BADID"); + H5RS_acat(rs, "H5I_BADID"); break; case H5I_FILE: - HDfprintf(out, "H5I_FILE"); + H5RS_acat(rs, "H5I_FILE"); break; case H5I_GROUP: - HDfprintf(out, "H5I_GROUP"); + H5RS_acat(rs, "H5I_GROUP"); break; case H5I_DATATYPE: - HDfprintf(out, "H5I_DATATYPE"); + H5RS_acat(rs, "H5I_DATATYPE"); break; case H5I_DATASPACE: - HDfprintf(out, "H5I_DATASPACE"); + H5RS_acat(rs, "H5I_DATASPACE"); break; case H5I_DATASET: - HDfprintf(out, "H5I_DATASET"); + H5RS_acat(rs, "H5I_DATASET"); break; case H5I_ATTR: - HDfprintf(out, "H5I_ATTR"); + H5RS_acat(rs, "H5I_ATTR"); break; case H5I_MAP: - HDfprintf(out, "H5I_MAP"); + H5RS_acat(rs, "H5I_MAP"); break; case H5I_VFL: - HDfprintf(out, "H5I_VFL"); + H5RS_acat(rs, "H5I_VFL"); break; case H5I_VOL: - HDfprintf(out, "H5I_VOL"); + H5RS_acat(rs, "H5I_VOL"); break; case H5I_GENPROP_CLS: - HDfprintf(out, "H5I_GENPROP_CLS"); + H5RS_acat(rs, "H5I_GENPROP_CLS"); break; case H5I_GENPROP_LST: - HDfprintf(out, "H5I_GENPROP_LST"); + H5RS_acat(rs, "H5I_GENPROP_LST"); break; case H5I_ERROR_CLASS: - HDfprintf(out, "H5I_ERROR_CLASS"); + H5RS_acat(rs, "H5I_ERROR_CLASS"); break; case H5I_ERROR_MSG: - HDfprintf(out, "H5I_ERROR_MSG"); + H5RS_acat(rs, "H5I_ERROR_MSG"); break; case H5I_ERROR_STACK: - HDfprintf(out, "H5I_ERROR_STACK"); + H5RS_acat(rs, "H5I_ERROR_STACK"); break; case H5I_SPACE_SEL_ITER: - HDfprintf(out, "H5I_SPACE_SEL_ITER"); + H5RS_acat(rs, "H5I_SPACE_SEL_ITER"); break; case H5I_NTYPES: - HDfprintf(out, "H5I_NTYPES"); + H5RS_acat(rs, "H5I_NTYPES"); break; default: - HDfprintf(out, "%ld", (long)id_type); + H5RS_asprintf_cat(rs, "%ld", (long)id_type); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'u': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - unsigned *p = (unsigned *)vp; - - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) - HDfprintf(out, "%s%u", i ? ", " : "", p[i]); - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'u': /* unsigned / uint32_t */ + { unsigned iu = HDva_arg(ap, unsigned); - HDfprintf(out, "%u", iu); + H5RS_asprintf_cat(rs, "%u", iu); asize[argno] = iu; - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(I%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(I%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'k': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'k': /* H5O_token_t */ + { H5O_token_t token = HDva_arg(ap, H5O_token_t); int j; for (j = 0; j < H5O_MAX_TOKEN_SIZE; j++) - HDfprintf(out, "%02x", token.__data[j]); - } /* end else */ + H5RS_asprintf_cat(rs, "%02x", token.__data[j]); + } /* end block */ break; - case 'L': - switch (type[1]) { - case 'l': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'L': + switch (type[1]) { +#ifndef H5_NO_DEPRECATED_SYMBOLS + case 'i': /* H5L_iterate1_t */ + { + H5L_iterate1_t liter = (H5L_iterate1_t)HDva_arg(ap, H5L_iterate1_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)liter); + } /* end block */ + break; +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + + case 'I': /* H5L_iterate2_t */ + { + H5L_iterate2_t liter = (H5L_iterate2_t)HDva_arg(ap, H5L_iterate2_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)liter); + } /* end block */ + break; + + case 'l': /* H5L_type_t (or H5G_link_t) */ + { H5L_type_t link_type = (H5L_type_t)HDva_arg(ap, int); switch (link_type) { case H5L_TYPE_ERROR: - HDfprintf(out, "H5L_TYPE_ERROR"); + H5RS_acat(rs, "H5L_TYPE_ERROR"); break; case H5L_TYPE_HARD: - HDfprintf(out, "H5L_TYPE_HARD"); + H5RS_acat(rs, "H5L_TYPE_HARD"); break; case H5L_TYPE_SOFT: - HDfprintf(out, "H5L_TYPE_SOFT"); + H5RS_acat(rs, "H5L_TYPE_SOFT"); break; case H5L_TYPE_EXTERNAL: - HDfprintf(out, "H5L_TYPE_EXTERNAL"); + H5RS_acat(rs, "H5L_TYPE_EXTERNAL"); break; case H5L_TYPE_MAX: - HDfprintf(out, "H5L_TYPE_MAX"); + H5RS_acat(rs, "H5L_TYPE_MAX"); break; default: - HDfprintf(out, "%ld", (long)link_type); + H5RS_asprintf_cat(rs, "%ld", (long)link_type); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(G%c)", type[1]); - goto error; - } /* end switch */ - break; + case 't': /* H5L_elink_traverse_t */ + { + H5L_elink_traverse_t elt = + (H5L_elink_traverse_t)HDva_arg(ap, H5L_elink_traverse_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)elt); + } /* end block */ + break; + + default: + H5RS_asprintf_cat(rs, "BADTYPE(G%c)", type[1]); + goto error; + } /* end switch */ + break; + + case 'M': + switch (type[1]) { + case 'a': /* H5MM_allocate_t */ + { + H5MM_allocate_t afunc = (H5MM_allocate_t)HDva_arg(ap, H5MM_allocate_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)afunc); + } /* end block */ + break; - case 'M': - switch (type[1]) { - case 'c': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ #ifdef H5_HAVE_PARALLEL - else { + case 'c': /* MPI_Comm */ + { MPI_Comm comm = HDva_arg(ap, MPI_Comm); - HDfprintf(out, "%ld", (long)comm); - } /* end else */ -#endif /* H5_HAVE_PARALLEL */ + H5RS_asprintf_cat(rs, "%ld", (long)comm); + } /* end block */ + break; +#endif /* H5_HAVE_PARALLEL */ + + case 'f': /* H5MM_free_t */ + { + H5MM_free_t ffunc = (H5MM_free_t)HDva_arg(ap, H5MM_free_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)ffunc); + } /* end block */ break; - case 'i': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ #ifdef H5_HAVE_PARALLEL - else { + case 'i': /* MPI_Info */ + { MPI_Info info = HDva_arg(ap, MPI_Info); - HDfprintf(out, "%ld", (long)info); - } /* end else */ -#endif /* H5_HAVE_PARALLEL */ + H5RS_asprintf_cat(rs, "%ld", (long)info); + } /* end block */ break; +#endif /* H5_HAVE_PARALLEL */ - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { +#ifdef H5_HAVE_MAP_API + case 'I': /* H5M_iterate_t */ + { + H5M_iterate_t miter = (H5M_iterate_t)HDva_arg(ap, H5M_iterate_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)miter); + } /* end block */ + break; +#endif /* H5_HAVE_MAP_API */ + + case 't': /* H5FD_mem_t */ + { H5FD_mem_t mt = (H5FD_mem_t)HDva_arg(ap, int); switch (mt) { case H5FD_MEM_NOLIST: - HDfprintf(out, "H5FD_MEM_NOLIST"); + H5RS_acat(rs, "H5FD_MEM_NOLIST"); break; case H5FD_MEM_DEFAULT: - HDfprintf(out, "H5FD_MEM_DEFAULT"); + H5RS_acat(rs, "H5FD_MEM_DEFAULT"); break; case H5FD_MEM_SUPER: - HDfprintf(out, "H5FD_MEM_SUPER"); + H5RS_acat(rs, "H5FD_MEM_SUPER"); break; case H5FD_MEM_BTREE: - HDfprintf(out, "H5FD_MEM_BTREE"); + H5RS_acat(rs, "H5FD_MEM_BTREE"); break; case H5FD_MEM_DRAW: - HDfprintf(out, "H5FD_MEM_DRAW"); + H5RS_acat(rs, "H5FD_MEM_DRAW"); break; case H5FD_MEM_GHEAP: - HDfprintf(out, "H5FD_MEM_GHEAP"); + H5RS_acat(rs, "H5FD_MEM_GHEAP"); break; case H5FD_MEM_LHEAP: - HDfprintf(out, "H5FD_MEM_LHEAP"); + H5RS_acat(rs, "H5FD_MEM_LHEAP"); break; case H5FD_MEM_OHDR: - HDfprintf(out, "H5FD_MEM_OHDR"); + H5RS_acat(rs, "H5FD_MEM_OHDR"); break; case H5FD_MEM_NTYPES: - HDfprintf(out, "H5FD_MEM_NTYPES"); + H5RS_acat(rs, "H5FD_MEM_NTYPES"); break; default: - HDfprintf(out, "%ld", (long)mt); + H5RS_asprintf_cat(rs, "%ld", (long)mt); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - goto error; - } /* end switch */ - break; + default: + goto error; + } /* end switch */ + break; - case 'o': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'o': /* off_t */ + { off_t offset = HDva_arg(ap, off_t); - HDfprintf(out, "%ld", (long)offset); - } /* end else */ + H5RS_asprintf_cat(rs, "%ld", (long)offset); + } /* end block */ break; - case 'O': - switch (type[1]) { - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'O': + switch (type[1]) { +#ifndef H5_NO_DEPRECATED_SYMBOLS + case 'i': /* H5O_iterate1_t */ + { + H5O_iterate1_t oiter = (H5O_iterate1_t)HDva_arg(ap, H5O_iterate1_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)oiter); + } /* end block */ + break; +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + + case 'I': /* H5O_iterate2_t */ + { + H5O_iterate2_t oiter2 = (H5O_iterate2_t)HDva_arg(ap, H5O_iterate2_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)oiter2); + } /* end block */ + break; + + case 's': /* H5O_mcdt_search_cb_t */ + { + H5O_mcdt_search_cb_t osrch = + (H5O_mcdt_search_cb_t)HDva_arg(ap, H5O_mcdt_search_cb_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)osrch); + } /* end block */ + break; + + case 't': /* H5O_type_t */ + { H5O_type_t objtype = (H5O_type_t)HDva_arg(ap, int); switch (objtype) { case H5O_TYPE_UNKNOWN: - HDfprintf(out, "H5O_TYPE_UNKNOWN"); + H5RS_acat(rs, "H5O_TYPE_UNKNOWN"); break; case H5O_TYPE_GROUP: - HDfprintf(out, "H5O_TYPE_GROUP"); + H5RS_acat(rs, "H5O_TYPE_GROUP"); break; case H5O_TYPE_DATASET: - HDfprintf(out, "H5O_TYPE_DATASET"); + H5RS_acat(rs, "H5O_TYPE_DATASET"); break; case H5O_TYPE_NAMED_DATATYPE: - HDfprintf(out, "H5O_TYPE_NAMED_DATATYPE"); + H5RS_acat(rs, "H5O_TYPE_NAMED_DATATYPE"); break; case H5O_TYPE_MAP: - HDfprintf(out, "H5O_TYPE_MAP"); + H5RS_acat(rs, "H5O_TYPE_MAP"); break; case H5O_TYPE_NTYPES: - HDfprintf(out, "H5O_TYPE_NTYPES"); + H5RS_acat(rs, "H5O_TYPE_NTYPES"); break; default: - HDfprintf(out, "BADTYPE(%ld)", (long)objtype); + H5RS_asprintf_cat(rs, "BADTYPE(%ld)", (long)objtype); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(S%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(S%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'p': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'p': /* H5P_class_t */ + { hid_t pclass_id = HDva_arg(ap, hid_t); char * class_name = NULL; H5P_genclass_t *pclass; @@ -1879,619 +2136,609 @@ H5_trace(const double *returning, const char *func, const char *type, ...) /* (This may generate recursive call to the library... -QAK) */ if (NULL != (pclass = (H5P_genclass_t *)H5I_object(pclass_id)) && NULL != (class_name = H5P_get_class_name(pclass))) { - HDfprintf(out, "%s", class_name); + H5RS_asprintf_cat(rs, "%s", class_name); H5MM_xfree(class_name); } /* end if */ else - HDfprintf(out, "%ld", (long)pclass_id); - } /* end else */ + H5RS_asprintf_cat(rs, "%ld", (long)pclass_id); + } /* end block */ break; - case 'R': - switch (type[1]) { + case 'P': + switch (type[1]) { + case 'c': /* H5P_cls_create_func_t */ + { + H5P_cls_create_func_t pcls_crt = + (H5P_cls_create_func_t)HDva_arg(ap, H5P_cls_create_func_t); - case 'o': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { - hobj_ref_t ref = HDva_arg(ap, hobj_ref_t); + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)pcls_crt); + } /* end block */ + break; + + case 'C': /* H5P_prp_create_func_t */ + { + H5P_prp_create_func_t prp_crt = + (H5P_prp_create_func_t)HDva_arg(ap, H5P_prp_create_func_t); - HDfprintf(out, "Reference Object=%" PRIuHADDR, ref); - } /* end else */ + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)prp_crt); + } /* end block */ break; - case 'd': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'D': /* H5P_prp_delete_func_t */ + { + H5P_prp_delete_func_t prp_del = + (H5P_prp_delete_func_t)HDva_arg(ap, H5P_prp_delete_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)prp_del); + } /* end block */ + break; + + case 'G': /* H5P_prp_get_func_t */ + { + H5P_prp_get_func_t prp_get = (H5P_prp_get_func_t)HDva_arg(ap, H5P_prp_get_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)prp_get); + } /* end block */ + break; + + case 'i': /* H5P_iterate_t */ + { + H5P_iterate_t piter = (H5P_iterate_t)HDva_arg(ap, H5P_iterate_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)piter); + } /* end block */ + break; + + case 'l': /* H5P_cls_close_func_t */ + { + H5P_cls_close_func_t pcls_cls = + (H5P_cls_close_func_t)HDva_arg(ap, H5P_cls_close_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)pcls_cls); + } /* end block */ + break; + + case 'L': /* H5P_prp_close_func_t */ + { + H5P_prp_close_func_t prp_cls = + (H5P_prp_close_func_t)HDva_arg(ap, H5P_prp_close_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)prp_cls); + } /* end block */ + break; + + case 'M': /* H5P_prp_compare_func_t */ + { + H5P_prp_compare_func_t prp_cmp = + (H5P_prp_compare_func_t)HDva_arg(ap, H5P_prp_compare_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)prp_cmp); + } /* end block */ + break; + + case 'o': /* H5P_cls_copy_func_t */ + { + H5P_cls_copy_func_t pcls_cpy = + (H5P_cls_copy_func_t)HDva_arg(ap, H5P_cls_copy_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)pcls_cpy); + } /* end block */ + break; + + case 'O': /* H5P_prp_copy_func_t */ + { + H5P_prp_copy_func_t prp_cpy = + (H5P_prp_copy_func_t)HDva_arg(ap, H5P_prp_copy_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)prp_cpy); + } /* end block */ + break; + + case 'S': /* H5P_prp_set_func_t */ + { + H5P_prp_set_func_t prp_set = (H5P_prp_set_func_t)HDva_arg(ap, H5P_prp_set_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)prp_set); + } /* end block */ + break; + + default: + H5RS_asprintf_cat(rs, "BADTYPE(P%c)", type[1]); + goto error; + } /* end switch */ + break; + + case 'R': + switch (type[1]) { + case 'd': /* hdset_reg_ref_t */ + { /* Note! region references are array types */ - HDfprintf(out, "Reference Region"); + H5RS_acat(rs, "Reference Region"); goto error; - } /* end else */ + } /* end block */ break; - case 'r': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'o': /* hobj_ref_t */ + { + hobj_ref_t ref = HDva_arg(ap, hobj_ref_t); + + H5RS_asprintf_cat(rs, "Reference Object=%" PRIuHADDR, ref); + } /* end block */ + break; + + case 'r': /* H5R_ref_t */ + { /* Note! reference types are opaque types */ - HDfprintf(out, "Reference Opaque"); + H5RS_acat(rs, "Reference Opaque"); goto error; - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 't': /* H5R_type_t */ + { H5R_type_t reftype = (H5R_type_t)HDva_arg(ap, int); switch (reftype) { case H5R_BADTYPE: - HDfprintf(out, "H5R_BADTYPE"); + H5RS_acat(rs, "H5R_BADTYPE"); break; case H5R_OBJECT1: - HDfprintf(out, "H5R_OBJECT1"); + H5RS_acat(rs, "H5R_OBJECT1"); break; case H5R_DATASET_REGION1: - HDfprintf(out, "H5R_DATASET_REGION1"); + H5RS_acat(rs, "H5R_DATASET_REGION1"); break; case H5R_OBJECT2: - HDfprintf(out, "H5R_OBJECT2"); + H5RS_acat(rs, "H5R_OBJECT2"); break; case H5R_DATASET_REGION2: - HDfprintf(out, "H5R_DATASET_REGION2"); + H5RS_acat(rs, "H5R_DATASET_REGION2"); break; case H5R_ATTR: - HDfprintf(out, "H5R_ATTR"); + H5RS_acat(rs, "H5R_ATTR"); break; case H5R_MAXTYPE: - HDfprintf(out, "H5R_MAXTYPE"); + H5RS_acat(rs, "H5R_MAXTYPE"); break; default: - HDfprintf(out, "BADTYPE(%ld)", (long)reftype); + H5RS_asprintf_cat(rs, "BADTYPE(%ld)", (long)reftype); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(S%c)", type[1]); - goto error; - } - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(S%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'S': - switch (type[1]) { - case 'c': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'S': + switch (type[1]) { + case 'c': /* H5S_class_t */ + { H5S_class_t cls = (H5S_class_t)HDva_arg(ap, int); switch (cls) { case H5S_NO_CLASS: - HDfprintf(out, "H5S_NO_CLASS"); + H5RS_acat(rs, "H5S_NO_CLASS"); break; case H5S_SCALAR: - HDfprintf(out, "H5S_SCALAR"); + H5RS_acat(rs, "H5S_SCALAR"); break; case H5S_SIMPLE: - HDfprintf(out, "H5S_SIMPLE"); + H5RS_acat(rs, "H5S_SIMPLE"); break; case H5S_NULL: - HDfprintf(out, "H5S_NULL"); + H5RS_acat(rs, "H5S_NULL"); break; default: - HDfprintf(out, "%ld", (long)cls); + H5RS_asprintf_cat(rs, "%ld", (long)cls); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 's': /* H5S_seloper_t */ + { H5S_seloper_t so = (H5S_seloper_t)HDva_arg(ap, int); switch (so) { case H5S_SELECT_NOOP: - HDfprintf(out, "H5S_NOOP"); + H5RS_acat(rs, "H5S_NOOP"); break; case H5S_SELECT_SET: - HDfprintf(out, "H5S_SELECT_SET"); + H5RS_acat(rs, "H5S_SELECT_SET"); break; case H5S_SELECT_OR: - HDfprintf(out, "H5S_SELECT_OR"); + H5RS_acat(rs, "H5S_SELECT_OR"); break; case H5S_SELECT_AND: - HDfprintf(out, "H5S_SELECT_AND"); + H5RS_acat(rs, "H5S_SELECT_AND"); break; case H5S_SELECT_XOR: - HDfprintf(out, "H5S_SELECT_XOR"); + H5RS_acat(rs, "H5S_SELECT_XOR"); break; case H5S_SELECT_NOTB: - HDfprintf(out, "H5S_SELECT_NOTB"); + H5RS_acat(rs, "H5S_SELECT_NOTB"); break; case H5S_SELECT_NOTA: - HDfprintf(out, "H5S_SELECT_NOTA"); + H5RS_acat(rs, "H5S_SELECT_NOTA"); break; case H5S_SELECT_APPEND: - HDfprintf(out, "H5S_SELECT_APPEND"); + H5RS_acat(rs, "H5S_SELECT_APPEND"); break; case H5S_SELECT_PREPEND: - HDfprintf(out, "H5S_SELECT_PREPEND"); + H5RS_acat(rs, "H5S_SELECT_PREPEND"); break; case H5S_SELECT_INVALID: - HDfprintf(out, "H5S_SELECT_INVALID"); + H5RS_acat(rs, "H5S_SELECT_INVALID"); break; default: - HDfprintf(out, "%ld", (long)so); + H5RS_asprintf_cat(rs, "%ld", (long)so); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 't': /* H5S_sel_type */ + { H5S_sel_type st = (H5S_sel_type)HDva_arg(ap, int); switch (st) { case H5S_SEL_ERROR: - HDfprintf(out, "H5S_SEL_ERROR"); + H5RS_acat(rs, "H5S_SEL_ERROR"); break; case H5S_SEL_NONE: - HDfprintf(out, "H5S_SEL_NONE"); + H5RS_acat(rs, "H5S_SEL_NONE"); break; case H5S_SEL_POINTS: - HDfprintf(out, "H5S_SEL_POINTS"); + H5RS_acat(rs, "H5S_SEL_POINTS"); break; case H5S_SEL_HYPERSLABS: - HDfprintf(out, "H5S_SEL_HYPERSLABS"); + H5RS_acat(rs, "H5S_SEL_HYPERSLABS"); break; case H5S_SEL_ALL: - HDfprintf(out, "H5S_SEL_ALL"); + H5RS_acat(rs, "H5S_SEL_ALL"); break; case H5S_SEL_N: - HDfprintf(out, "H5S_SEL_N"); + H5RS_acat(rs, "H5S_SEL_N"); break; default: - HDfprintf(out, "%ld", (long)st); + H5RS_asprintf_cat(rs, "%ld", (long)st); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(S%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(S%c)", type[1]); + goto error; + } /* end switch */ + break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { - const char *str = HDva_arg(ap, const char *); + case 't': /* htri_t */ + { + htri_t tri_var = HDva_arg(ap, htri_t); - HDfprintf(out, "\"%s\"", str); - } /* end else */ + if (tri_var > 0) + H5RS_acat(rs, "TRUE"); + else if (!tri_var) + H5RS_acat(rs, "FALSE"); + else + H5RS_asprintf_cat(rs, "FAIL(%d)", (int)tri_var); + } /* end block */ break; - case 'T': - switch (type[1]) { - case 'c': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'T': + switch (type[1]) { + case 'c': /* H5T_cset_t */ + { H5T_cset_t cset = (H5T_cset_t)HDva_arg(ap, int); - switch (cset) { - case H5T_CSET_ERROR: - HDfprintf(out, "H5T_CSET_ERROR"); - break; - - case H5T_CSET_ASCII: - HDfprintf(out, "H5T_CSET_ASCII"); - break; - - case H5T_CSET_UTF8: - HDfprintf(out, "H5T_CSET_UTF8"); - break; + H5_trace_args_cset(rs, cset); + } /* end block */ + break; - case H5T_CSET_RESERVED_2: - case H5T_CSET_RESERVED_3: - case H5T_CSET_RESERVED_4: - case H5T_CSET_RESERVED_5: - case H5T_CSET_RESERVED_6: - case H5T_CSET_RESERVED_7: - case H5T_CSET_RESERVED_8: - case H5T_CSET_RESERVED_9: - case H5T_CSET_RESERVED_10: - case H5T_CSET_RESERVED_11: - case H5T_CSET_RESERVED_12: - case H5T_CSET_RESERVED_13: - case H5T_CSET_RESERVED_14: - case H5T_CSET_RESERVED_15: - HDfprintf(out, "H5T_CSET_RESERVED_%ld", (long)cset); - break; + case 'C': /* H5T_conv_t */ + { + H5T_conv_t tconv = (H5T_conv_t)HDva_arg(ap, H5T_conv_t); - default: - HDfprintf(out, "%ld", (long)cset); - break; - } /* end switch */ - } /* end else */ + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)tconv); + } /* end block */ break; - case 'd': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'd': /* H5T_direction_t */ + { H5T_direction_t direct = (H5T_direction_t)HDva_arg(ap, int); switch (direct) { case H5T_DIR_DEFAULT: - HDfprintf(out, "H5T_DIR_DEFAULT"); + H5RS_acat(rs, "H5T_DIR_DEFAULT"); break; case H5T_DIR_ASCEND: - HDfprintf(out, "H5T_DIR_ASCEND"); + H5RS_acat(rs, "H5T_DIR_ASCEND"); break; case H5T_DIR_DESCEND: - HDfprintf(out, "H5T_DIR_DESCEND"); + H5RS_acat(rs, "H5T_DIR_DESCEND"); break; default: - HDfprintf(out, "%ld", (long)direct); + H5RS_asprintf_cat(rs, "%ld", (long)direct); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'e': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'e': /* H5T_pers_t */ + { H5T_pers_t pers = (H5T_pers_t)HDva_arg(ap, int); switch (pers) { case H5T_PERS_DONTCARE: - HDfprintf(out, "H5T_PERS_DONTCARE"); + H5RS_acat(rs, "H5T_PERS_DONTCARE"); break; case H5T_PERS_SOFT: - HDfprintf(out, "H5T_PERS_SOFT"); + H5RS_acat(rs, "H5T_PERS_SOFT"); break; case H5T_PERS_HARD: - HDfprintf(out, "H5T_PERS_HARD"); + H5RS_acat(rs, "H5T_PERS_HARD"); break; default: - HDfprintf(out, "%ld", (long)pers); + H5RS_asprintf_cat(rs, "%ld", (long)pers); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'n': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'E': /* H5T_conv_except_func_t */ + { + H5T_conv_except_func_t conv_ex = + (H5T_conv_except_func_t)HDva_arg(ap, H5T_conv_except_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)conv_ex); + } /* end block */ + break; + + case 'n': /* H5T_norm_t */ + { H5T_norm_t norm = (H5T_norm_t)HDva_arg(ap, int); switch (norm) { case H5T_NORM_ERROR: - HDfprintf(out, "H5T_NORM_ERROR"); + H5RS_acat(rs, "H5T_NORM_ERROR"); break; case H5T_NORM_IMPLIED: - HDfprintf(out, "H5T_NORM_IMPLIED"); + H5RS_acat(rs, "H5T_NORM_IMPLIED"); break; case H5T_NORM_MSBSET: - HDfprintf(out, "H5T_NORM_MSBSET"); + H5RS_acat(rs, "H5T_NORM_MSBSET"); break; case H5T_NORM_NONE: - HDfprintf(out, "H5T_NORM_NONE"); + H5RS_acat(rs, "H5T_NORM_NONE"); break; default: - HDfprintf(out, "%ld", (long)norm); + H5RS_asprintf_cat(rs, "%ld", (long)norm); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'o': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'o': /* H5T_order_t */ + { H5T_order_t order = (H5T_order_t)HDva_arg(ap, int); switch (order) { case H5T_ORDER_ERROR: - HDfprintf(out, "H5T_ORDER_ERROR"); + H5RS_acat(rs, "H5T_ORDER_ERROR"); break; case H5T_ORDER_LE: - HDfprintf(out, "H5T_ORDER_LE"); + H5RS_acat(rs, "H5T_ORDER_LE"); break; case H5T_ORDER_BE: - HDfprintf(out, "H5T_ORDER_BE"); + H5RS_acat(rs, "H5T_ORDER_BE"); break; case H5T_ORDER_VAX: - HDfprintf(out, "H5T_ORDER_VAX"); + H5RS_acat(rs, "H5T_ORDER_VAX"); break; case H5T_ORDER_MIXED: - HDfprintf(out, "H5T_ORDER_MIXED"); + H5RS_acat(rs, "H5T_ORDER_MIXED"); break; case H5T_ORDER_NONE: - HDfprintf(out, "H5T_ORDER_NONE"); + H5RS_acat(rs, "H5T_ORDER_NONE"); break; default: - HDfprintf(out, "%ld", (long)order); + H5RS_asprintf_cat(rs, "%ld", (long)order); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'p': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'p': /* H5T_pad_t */ + { H5T_pad_t pad = (H5T_pad_t)HDva_arg(ap, int); switch (pad) { case H5T_PAD_ERROR: - HDfprintf(out, "H5T_PAD_ERROR"); + H5RS_acat(rs, "H5T_PAD_ERROR"); break; case H5T_PAD_ZERO: - HDfprintf(out, "H5T_PAD_ZERO"); + H5RS_acat(rs, "H5T_PAD_ZERO"); break; case H5T_PAD_ONE: - HDfprintf(out, "H5T_PAD_ONE"); + H5RS_acat(rs, "H5T_PAD_ONE"); break; case H5T_PAD_BACKGROUND: - HDfprintf(out, "H5T_PAD_BACKGROUND"); + H5RS_acat(rs, "H5T_PAD_BACKGROUND"); break; case H5T_NPAD: - HDfprintf(out, "H5T_NPAD"); + H5RS_acat(rs, "H5T_NPAD"); break; default: - HDfprintf(out, "%ld", (long)pad); + H5RS_asprintf_cat(rs, "%ld", (long)pad); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 's': /* H5T_sign_t */ + { H5T_sign_t sign = (H5T_sign_t)HDva_arg(ap, int); switch (sign) { case H5T_SGN_ERROR: - HDfprintf(out, "H5T_SGN_ERROR"); + H5RS_acat(rs, "H5T_SGN_ERROR"); break; case H5T_SGN_NONE: - HDfprintf(out, "H5T_SGN_NONE"); + H5RS_acat(rs, "H5T_SGN_NONE"); break; case H5T_SGN_2: - HDfprintf(out, "H5T_SGN_2"); + H5RS_acat(rs, "H5T_SGN_2"); break; case H5T_NSGN: - HDfprintf(out, "H5T_NSGN"); + H5RS_acat(rs, "H5T_NSGN"); break; default: - HDfprintf(out, "%ld", (long)sign); + H5RS_asprintf_cat(rs, "%ld", (long)sign); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 't': /* H5T_class_t */ + { H5T_class_t type_class = (H5T_class_t)HDva_arg(ap, int); switch (type_class) { case H5T_NO_CLASS: - HDfprintf(out, "H5T_NO_CLASS"); + H5RS_acat(rs, "H5T_NO_CLASS"); break; case H5T_INTEGER: - HDfprintf(out, "H5T_INTEGER"); + H5RS_acat(rs, "H5T_INTEGER"); break; case H5T_FLOAT: - HDfprintf(out, "H5T_FLOAT"); + H5RS_acat(rs, "H5T_FLOAT"); break; case H5T_TIME: - HDfprintf(out, "H5T_TIME"); + H5RS_acat(rs, "H5T_TIME"); break; case H5T_STRING: - HDfprintf(out, "H5T_STRING"); + H5RS_acat(rs, "H5T_STRING"); break; case H5T_BITFIELD: - HDfprintf(out, "H5T_BITFIELD"); + H5RS_acat(rs, "H5T_BITFIELD"); break; case H5T_OPAQUE: - HDfprintf(out, "H5T_OPAQUE"); + H5RS_acat(rs, "H5T_OPAQUE"); break; case H5T_COMPOUND: - HDfprintf(out, "H5T_COMPOUND"); + H5RS_acat(rs, "H5T_COMPOUND"); break; case H5T_REFERENCE: - HDfprintf(out, "H5T_REFERENCE"); + H5RS_acat(rs, "H5T_REFERENCE"); break; case H5T_ENUM: - HDfprintf(out, "H5T_ENUM"); + H5RS_acat(rs, "H5T_ENUM"); break; case H5T_VLEN: - HDfprintf(out, "H5T_VLEN"); + H5RS_acat(rs, "H5T_VLEN"); break; case H5T_ARRAY: - HDfprintf(out, "H5T_ARRAY"); + H5RS_acat(rs, "H5T_ARRAY"); break; case H5T_NCLASSES: - HDfprintf(out, "H5T_NCLASSES"); + H5RS_acat(rs, "H5T_NCLASSES"); break; default: - HDfprintf(out, "%ld", (long)type_class); + H5RS_asprintf_cat(rs, "%ld", (long)type_class); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'z': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'z': /* H5T_str_t */ + { H5T_str_t str = (H5T_str_t)HDva_arg(ap, int); switch (str) { case H5T_STR_ERROR: - HDfprintf(out, "H5T_STR_ERROR"); + H5RS_acat(rs, "H5T_STR_ERROR"); break; case H5T_STR_NULLTERM: - HDfprintf(out, "H5T_STR_NULLTERM"); + H5RS_acat(rs, "H5T_STR_NULLTERM"); break; case H5T_STR_NULLPAD: - HDfprintf(out, "H5T_STR_NULLPAD"); + H5RS_acat(rs, "H5T_STR_NULLPAD"); break; case H5T_STR_SPACEPAD: - HDfprintf(out, "H5T_STR_SPACEPAD"); + H5RS_acat(rs, "H5T_STR_SPACEPAD"); break; case H5T_STR_RESERVED_3: @@ -2507,1219 +2754,1211 @@ H5_trace(const double *returning, const char *func, const char *type, ...) case H5T_STR_RESERVED_13: case H5T_STR_RESERVED_14: case H5T_STR_RESERVED_15: - HDfprintf(out, "H5T_STR_RESERVED(%ld)", (long)str); + H5RS_asprintf_cat(rs, "H5T_STR_RESERVED(%ld)", (long)str); break; default: - HDfprintf(out, "%ld", (long)str); + H5RS_asprintf_cat(rs, "%ld", (long)str); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(T%c)", type[1]); - goto error; - } /* end switch */ - break; - - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { - htri_t tri_var = HDva_arg(ap, htri_t); - - if (tri_var > 0) - HDfprintf(out, "TRUE"); - else if (!tri_var) - HDfprintf(out, "FALSE"); - else - HDfprintf(out, "FAIL(%d)", (int)tri_var); - } /* end else */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(T%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'U': - switch (type[1]) { - case 'l': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - unsigned long *p = (unsigned long *)vp; - - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) - HDfprintf(out, "%s%lu", i ? ", " : "", p[i]); - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'U': + switch (type[1]) { + case 'l': /* unsigned long */ + { unsigned long iul = HDva_arg(ap, unsigned long); - HDfprintf(out, "%lu", iul); + H5RS_asprintf_cat(rs, "%lu", iul); asize[argno] = (hssize_t)iul; - } /* end else */ - break; - - case 'L': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - unsigned long long *p = (unsigned long long *)vp; - - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) - HDfprintf(out, "%s%llu", i ? ", " : "", p[i]); - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + } /* end block */ + break; + + case 'L': /* unsigned long long / uint64_t */ + { unsigned long long iull = HDva_arg(ap, unsigned long long); - HDfprintf(out, "%llu", iull); + H5RS_asprintf_cat(rs, "%llu", iull); asize[argno] = (hssize_t)iull; - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(U%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(U%c)", type[1]); + goto error; + } /* end switch */ + break; - case 'V': - switch (type[1]) { - case 'a': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'V': + switch (type[1]) { + case 'a': /* H5VL_attr_get_t */ + { H5VL_attr_get_t get = (H5VL_attr_get_t)HDva_arg(ap, int); switch (get) { case H5VL_ATTR_GET_SPACE: - HDfprintf(out, "H5VL_ATTR_GET_SPACE"); + H5RS_acat(rs, "H5VL_ATTR_GET_SPACE"); break; + case H5VL_ATTR_GET_TYPE: - HDfprintf(out, "H5VL_ATTR_GET_TYPE"); + H5RS_acat(rs, "H5VL_ATTR_GET_TYPE"); break; + case H5VL_ATTR_GET_ACPL: - HDfprintf(out, "H5VL_ATTR_GET_ACPL"); + H5RS_acat(rs, "H5VL_ATTR_GET_ACPL"); break; + case H5VL_ATTR_GET_NAME: - HDfprintf(out, "H5VL_ATTR_GET_NAME"); + H5RS_acat(rs, "H5VL_ATTR_GET_NAME"); break; + case H5VL_ATTR_GET_STORAGE_SIZE: - HDfprintf(out, "H5VL_ATTR_GET_STORAGE_SIZE"); + H5RS_acat(rs, "H5VL_ATTR_GET_STORAGE_SIZE"); break; + case H5VL_ATTR_GET_INFO: - HDfprintf(out, "H5VL_ATTR_GET_INFO"); + H5RS_acat(rs, "H5VL_ATTR_GET_INFO"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'A': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'A': /* H5VL_blob_optional_t */ + { H5VL_blob_optional_t optional = (H5VL_blob_optional_t)HDva_arg(ap, int); - switch (optional) { - default: - HDfprintf(out, "%ld", (long)optional); - break; - } /* end switch */ - } /* end else */ + H5RS_asprintf_cat(rs, "%ld", (long)optional); + } /* end block */ break; - case 'b': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'b': /* H5VL_attr_specific_t */ + { H5VL_attr_specific_t specific = (H5VL_attr_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_ATTR_DELETE: - HDfprintf(out, "H5VL_ATTR_DELETE"); + H5RS_acat(rs, "H5VL_ATTR_DELETE"); break; + case H5VL_ATTR_EXISTS: - HDfprintf(out, "H5VL_ATTR_EXISTS"); + H5RS_acat(rs, "H5VL_ATTR_EXISTS"); break; + case H5VL_ATTR_ITER: - HDfprintf(out, "H5VL_ATTR_ITER"); + H5RS_acat(rs, "H5VL_ATTR_ITER"); break; + case H5VL_ATTR_RENAME: - HDfprintf(out, "H5VL_ATTR_RENAME"); + H5RS_acat(rs, "H5VL_ATTR_RENAME"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'B': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'B': /* H5VL_blob_specific_t */ + { H5VL_blob_specific_t specific = (H5VL_blob_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_BLOB_DELETE: - HDfprintf(out, "H5VL_BLOB_DELETE"); + H5RS_acat(rs, "H5VL_BLOB_DELETE"); break; + case H5VL_BLOB_GETSIZE: - HDfprintf(out, "H5VL_BLOB_GETSIZE"); + H5RS_acat(rs, "H5VL_BLOB_GETSIZE"); break; + case H5VL_BLOB_ISNULL: - HDfprintf(out, "H5VL_BLOB_ISNULL"); + H5RS_acat(rs, "H5VL_BLOB_ISNULL"); break; + case H5VL_BLOB_SETNULL: - HDfprintf(out, "H5VL_BLOB_SETNULL"); + H5RS_acat(rs, "H5VL_BLOB_SETNULL"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ - break; - - case 'C': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { - H5VL_class_value_t class_val = - (H5VL_class_value_t)HDva_arg(ap, H5VL_class_value_t); - - if (H5_VOL_NATIVE == class_val) - HDfprintf(out, "H5_VOL_NATIVE"); - else - HDfprintf(out, "%ld", (long)class_val); - } /* end else */ + } /* end block */ break; - case 'c': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'c': /* H5VL_dataset_get_t */ + { H5VL_dataset_get_t get = (H5VL_dataset_get_t)HDva_arg(ap, int); switch (get) { case H5VL_DATASET_GET_SPACE: - HDfprintf(out, "H5VL_DATASET_GET_SPACE"); + H5RS_acat(rs, "H5VL_DATASET_GET_SPACE"); break; + case H5VL_DATASET_GET_SPACE_STATUS: - HDfprintf(out, "H5VL_DATASET_GET_SPACE_STATUS"); + H5RS_acat(rs, "H5VL_DATASET_GET_SPACE_STATUS"); break; + case H5VL_DATASET_GET_TYPE: - HDfprintf(out, "H5VL_DATASET_GET_TYPE"); + H5RS_acat(rs, "H5VL_DATASET_GET_TYPE"); break; + case H5VL_DATASET_GET_DCPL: - HDfprintf(out, "H5VL_DATASET_GET_DCPL"); + H5RS_acat(rs, "H5VL_DATASET_GET_DCPL"); break; + case H5VL_DATASET_GET_DAPL: - HDfprintf(out, "H5VL_DATASET_GET_DAPL"); + H5RS_acat(rs, "H5VL_DATASET_GET_DAPL"); break; + case H5VL_DATASET_GET_STORAGE_SIZE: - HDfprintf(out, "H5VL_DATASET_GET_STORAGE_SIZE"); + H5RS_acat(rs, "H5VL_DATASET_GET_STORAGE_SIZE"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'd': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); + case 'C': /* H5VL_class_value_t */ + { + H5VL_class_value_t class_val = + (H5VL_class_value_t)HDva_arg(ap, H5VL_class_value_t); + + if (H5_VOL_NATIVE == class_val) + H5RS_acat(rs, "H5_VOL_NATIVE"); else - HDfprintf(out, "NULL"); - } /* end if */ - else { + H5RS_asprintf_cat(rs, "%ld", (long)class_val); + } /* end block */ + break; + + case 'd': /* H5VL_dataset_specific_t */ + { H5VL_dataset_specific_t specific = (H5VL_dataset_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_DATASET_SET_EXTENT: - HDfprintf(out, "H5VL_DATASET_SET_EXTENT"); + H5RS_acat(rs, "H5VL_DATASET_SET_EXTENT"); break; + case H5VL_DATASET_FLUSH: - HDfprintf(out, "H5VL_DATASET_FLUSH"); + H5RS_acat(rs, "H5VL_DATASET_FLUSH"); break; + case H5VL_DATASET_REFRESH: - HDfprintf(out, "H5VL_DATASET_REFRESH"); + H5RS_acat(rs, "H5VL_DATASET_REFRESH"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'e': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'e': /* H5VL_datatype_get_t */ + { H5VL_datatype_get_t get = (H5VL_datatype_get_t)HDva_arg(ap, int); switch (get) { case H5VL_DATATYPE_GET_BINARY: - HDfprintf(out, "H5VL_DATATYPE_GET_BINARY"); + H5RS_acat(rs, "H5VL_DATATYPE_GET_BINARY"); break; + case H5VL_DATATYPE_GET_TCPL: - HDfprintf(out, "H5VL_DATATYPE_GET_TCPL"); + H5RS_acat(rs, "H5VL_DATATYPE_GET_TCPL"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'f': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'f': /* H5VL_datatype_specific_t */ + { H5VL_datatype_specific_t specific = (H5VL_datatype_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_DATATYPE_FLUSH: - HDfprintf(out, "H5VL_DATATYPE_FLUSH"); + H5RS_acat(rs, "H5VL_DATATYPE_FLUSH"); break; + case H5VL_DATATYPE_REFRESH: - HDfprintf(out, "H5VL_DATATYPE_REFRESH"); + H5RS_acat(rs, "H5VL_DATATYPE_REFRESH"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'g': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'g': /* H5VL_file_get_t */ + { H5VL_file_get_t get = (H5VL_file_get_t)HDva_arg(ap, int); switch (get) { case H5VL_FILE_GET_CONT_INFO: - HDfprintf(out, "H5VL_FILE_GET_CONT_INFO"); + H5RS_acat(rs, "H5VL_FILE_GET_CONT_INFO"); break; + case H5VL_FILE_GET_FAPL: - HDfprintf(out, "H5VL_FILE_GET_FAPL"); + H5RS_acat(rs, "H5VL_FILE_GET_FAPL"); break; + case H5VL_FILE_GET_FCPL: - HDfprintf(out, "H5VL_FILE_GET_FCPL"); + H5RS_acat(rs, "H5VL_FILE_GET_FCPL"); break; + case H5VL_FILE_GET_FILENO: - HDfprintf(out, "H5VL_FILE_GET_FILENO"); + H5RS_acat(rs, "H5VL_FILE_GET_FILENO"); break; + case H5VL_FILE_GET_INTENT: - HDfprintf(out, "H5VL_FILE_GET_INTENT"); + H5RS_acat(rs, "H5VL_FILE_GET_INTENT"); break; + case H5VL_FILE_GET_NAME: - HDfprintf(out, "H5VL_FILE_GET_NAME"); + H5RS_acat(rs, "H5VL_FILE_GET_NAME"); break; + case H5VL_FILE_GET_OBJ_COUNT: - HDfprintf(out, "H5VL_FILE_GET_OBJ_COUNT"); + H5RS_acat(rs, "H5VL_FILE_GET_OBJ_COUNT"); break; + case H5VL_FILE_GET_OBJ_IDS: - HDfprintf(out, "H5VL_FILE_GET_OBJ_IDS"); + H5RS_acat(rs, "H5VL_FILE_GET_OBJ_IDS"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'h': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'h': /* H5VL_file_specific_t */ + { H5VL_file_specific_t specific = (H5VL_file_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_FILE_FLUSH: - HDfprintf(out, "H5VL_FILE_FLUSH"); + H5RS_acat(rs, "H5VL_FILE_FLUSH"); break; + case H5VL_FILE_REOPEN: - HDfprintf(out, "H5VL_FILE_REOPEN"); + H5RS_acat(rs, "H5VL_FILE_REOPEN"); break; + case H5VL_FILE_MOUNT: - HDfprintf(out, "H5VL_FILE_MOUNT"); + H5RS_acat(rs, "H5VL_FILE_MOUNT"); break; + case H5VL_FILE_UNMOUNT: - HDfprintf(out, "H5VL_FILE_UNMOUNT"); + H5RS_acat(rs, "H5VL_FILE_UNMOUNT"); break; + case H5VL_FILE_IS_ACCESSIBLE: - HDfprintf(out, "H5VL_FILE_IS_ACCESSIBLE"); + H5RS_acat(rs, "H5VL_FILE_IS_ACCESSIBLE"); break; + case H5VL_FILE_DELETE: - HDfprintf(out, "H5VL_FILE_DELETE"); + H5RS_acat(rs, "H5VL_FILE_DELETE"); break; + case H5VL_FILE_IS_EQUAL: - HDfprintf(out, "H5VL_FILE_IS_EQUAL"); + H5RS_acat(rs, "H5VL_FILE_IS_EQUAL"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'i': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'i': /* H5VL_group_get_t */ + { H5VL_group_get_t get = (H5VL_group_get_t)HDva_arg(ap, int); switch (get) { case H5VL_GROUP_GET_GCPL: - HDfprintf(out, "H5VL_GROUP_GET_GCPL"); + H5RS_acat(rs, "H5VL_GROUP_GET_GCPL"); break; + case H5VL_GROUP_GET_INFO: - HDfprintf(out, "H5VL_GROUP_GET_INFO"); + H5RS_acat(rs, "H5VL_GROUP_GET_INFO"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'j': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'j': /* H5VL_group_specific_t */ + { H5VL_group_specific_t specific = (H5VL_group_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_GROUP_FLUSH: - HDfprintf(out, "H5VL_GROUP_FLUSH"); + H5RS_acat(rs, "H5VL_GROUP_FLUSH"); break; + case H5VL_GROUP_REFRESH: - HDfprintf(out, "H5VL_GROUP_REFRESH"); + H5RS_acat(rs, "H5VL_GROUP_REFRESH"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'k': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'k': /* H5VL_link_create_type_t */ + { H5VL_link_create_type_t create = (H5VL_link_create_type_t)HDva_arg(ap, int); switch (create) { case H5VL_LINK_CREATE_HARD: - HDfprintf(out, "H5VL_LINK_CREATE_HARD"); + H5RS_acat(rs, "H5VL_LINK_CREATE_HARD"); break; + case H5VL_LINK_CREATE_SOFT: - HDfprintf(out, "H5VL_LINK_CREATE_SOFT"); + H5RS_acat(rs, "H5VL_LINK_CREATE_SOFT"); break; + case H5VL_LINK_CREATE_UD: - HDfprintf(out, "H5VL_LINK_CREATE_UD"); + H5RS_acat(rs, "H5VL_LINK_CREATE_UD"); break; + default: - HDfprintf(out, "%ld", (long)create); + H5RS_asprintf_cat(rs, "%ld", (long)create); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'l': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'l': /* H5VL_link_get_t */ + { H5VL_link_get_t get = (H5VL_link_get_t)HDva_arg(ap, int); switch (get) { case H5VL_LINK_GET_INFO: - HDfprintf(out, "H5VL_LINK_GET_INFO"); + H5RS_acat(rs, "H5VL_LINK_GET_INFO"); break; + case H5VL_LINK_GET_NAME: - HDfprintf(out, "H5VL_LINK_GET_NAME"); + H5RS_acat(rs, "H5VL_LINK_GET_NAME"); break; + case H5VL_LINK_GET_VAL: - HDfprintf(out, "H5VL_LINK_GET_VAL"); + H5RS_acat(rs, "H5VL_LINK_GET_VAL"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'L': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'L': /* H5VL_get_conn_lvl_t */ + { H5VL_get_conn_lvl_t get = (H5VL_get_conn_lvl_t)HDva_arg(ap, int); switch (get) { case H5VL_GET_CONN_LVL_CURR: - HDfprintf(out, "H5VL_GET_CONN_LVL_CURR"); + H5RS_acat(rs, "H5VL_GET_CONN_LVL_CURR"); break; + case H5VL_GET_CONN_LVL_TERM: - HDfprintf(out, "H5VL_GET_CONN_LVL_TERM"); + H5RS_acat(rs, "H5VL_GET_CONN_LVL_TERM"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'm': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'm': /* H5VL_link_specific_t */ + { H5VL_link_specific_t specific = (H5VL_link_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_LINK_DELETE: - HDfprintf(out, "H5VL_LINK_DELETE"); + H5RS_acat(rs, "H5VL_LINK_DELETE"); break; + case H5VL_LINK_EXISTS: - HDfprintf(out, "H5VL_LINK_EXISTS"); + H5RS_acat(rs, "H5VL_LINK_EXISTS"); break; + case H5VL_LINK_ITER: - HDfprintf(out, "H5VL_LINK_ITER"); + H5RS_acat(rs, "H5VL_LINK_ITER"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'n': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'n': /* H5VL_object_get_t */ + { H5VL_object_get_t get = (H5VL_object_get_t)HDva_arg(ap, int); switch (get) { case H5VL_OBJECT_GET_FILE: - HDfprintf(out, "H5VL_OBJECT_GET_FILE"); + H5RS_acat(rs, "H5VL_OBJECT_GET_FILE"); break; + case H5VL_OBJECT_GET_NAME: - HDfprintf(out, "H5VL_OBJECT_GET_NAME"); + H5RS_acat(rs, "H5VL_OBJECT_GET_NAME"); break; + case H5VL_OBJECT_GET_TYPE: - HDfprintf(out, "H5VL_OBJECT_GET_TYPE"); + H5RS_acat(rs, "H5VL_OBJECT_GET_TYPE"); break; + case H5VL_OBJECT_GET_INFO: - HDfprintf(out, "H5VL_OBJECT_GET_INFO"); + H5RS_acat(rs, "H5VL_OBJECT_GET_INFO"); break; + default: - HDfprintf(out, "%ld", (long)get); + H5RS_asprintf_cat(rs, "%ld", (long)get); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'o': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'N': /* H5VL_request_notify_t */ + { + H5VL_request_notify_t vlrnot = + (H5VL_request_notify_t)HDva_arg(ap, H5VL_request_notify_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)vlrnot); + } /* end block */ + break; + + case 'o': /* H5VL_object_specific_t */ + { H5VL_object_specific_t specific = (H5VL_object_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_OBJECT_CHANGE_REF_COUNT: - HDfprintf(out, "H5VL_OBJECT_CHANGE_REF_COUNT"); + H5RS_acat(rs, "H5VL_OBJECT_CHANGE_REF_COUNT"); break; + case H5VL_OBJECT_EXISTS: - HDfprintf(out, "H5VL_OBJECT_EXISTS"); + H5RS_acat(rs, "H5VL_OBJECT_EXISTS"); break; + case H5VL_OBJECT_LOOKUP: - HDfprintf(out, "H5VL_OBJECT_LOOKUP"); + H5RS_acat(rs, "H5VL_OBJECT_LOOKUP"); break; + case H5VL_OBJECT_VISIT: - HDfprintf(out, "H5VL_OBJECT_VISIT"); + H5RS_acat(rs, "H5VL_OBJECT_VISIT"); break; + case H5VL_OBJECT_FLUSH: - HDfprintf(out, "H5VL_OBJECT_FLUSH"); + H5RS_acat(rs, "H5VL_OBJECT_FLUSH"); break; + case H5VL_OBJECT_REFRESH: - HDfprintf(out, "H5VL_OBJECT_REFRESH"); + H5RS_acat(rs, "H5VL_OBJECT_REFRESH"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'r': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'r': /* H5VL_request_specific_t */ + { H5VL_request_specific_t specific = (H5VL_request_specific_t)HDva_arg(ap, int); switch (specific) { case H5VL_REQUEST_WAITANY: - HDfprintf(out, "H5VL_REQUEST_WAITANY"); + H5RS_acat(rs, "H5VL_REQUEST_WAITANY"); break; + case H5VL_REQUEST_WAITSOME: - HDfprintf(out, "H5VL_REQUEST_WAITSOME"); + H5RS_acat(rs, "H5VL_REQUEST_WAITSOME"); break; + case H5VL_REQUEST_WAITALL: - HDfprintf(out, "H5VL_REQUEST_WAITALL"); + H5RS_acat(rs, "H5VL_REQUEST_WAITALL"); break; + default: - HDfprintf(out, "%ld", (long)specific); + H5RS_asprintf_cat(rs, "%ld", (long)specific); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 's': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 's': /* H5VL_attr_optional_t */ + { H5VL_attr_optional_t optional = (H5VL_attr_optional_t)HDva_arg(ap, int); switch (optional) { #ifndef H5_NO_DEPRECATED_SYMBOLS case H5VL_NATIVE_ATTR_ITERATE_OLD: - HDfprintf(out, "H5VL_NATIVE_ATTR_ITERATE_OLD"); + H5RS_acat(rs, "H5VL_NATIVE_ATTR_ITERATE_OLD"); break; #endif /* H5_NO_DEPRECATED_SYMBOLS */ + default: - HDfprintf(out, "%ld", (long)optional); + H5RS_asprintf_cat(rs, "%ld", (long)optional); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'S': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'S': /* H5VL_subclass_t */ + { H5VL_subclass_t subclass = (H5VL_subclass_t)HDva_arg(ap, int); switch (subclass) { case H5VL_SUBCLS_NONE: - HDfprintf(out, "H5VL_SUBCLS_NONE"); + H5RS_acat(rs, "H5VL_SUBCLS_NONE"); break; + case H5VL_SUBCLS_INFO: - HDfprintf(out, "H5VL_SUBCLS_INFO"); + H5RS_acat(rs, "H5VL_SUBCLS_INFO"); break; + case H5VL_SUBCLS_WRAP: - HDfprintf(out, "H5VL_SUBCLS_WRAP"); + H5RS_acat(rs, "H5VL_SUBCLS_WRAP"); break; + case H5VL_SUBCLS_ATTR: - HDfprintf(out, "H5VL_SUBCLS_ATTR"); + H5RS_acat(rs, "H5VL_SUBCLS_ATTR"); break; + case H5VL_SUBCLS_DATASET: - HDfprintf(out, "H5VL_SUBCLS_DATASET"); + H5RS_acat(rs, "H5VL_SUBCLS_DATASET"); break; + case H5VL_SUBCLS_DATATYPE: - HDfprintf(out, "H5VL_SUBCLS_DATATYPE"); + H5RS_acat(rs, "H5VL_SUBCLS_DATATYPE"); break; + case H5VL_SUBCLS_FILE: - HDfprintf(out, "H5VL_SUBCLS_FILE"); + H5RS_acat(rs, "H5VL_SUBCLS_FILE"); break; + case H5VL_SUBCLS_GROUP: - HDfprintf(out, "H5VL_SUBCLS_GROUP"); + H5RS_acat(rs, "H5VL_SUBCLS_GROUP"); break; + case H5VL_SUBCLS_LINK: - HDfprintf(out, "H5VL_SUBCLS_LINK"); + H5RS_acat(rs, "H5VL_SUBCLS_LINK"); break; + case H5VL_SUBCLS_OBJECT: - HDfprintf(out, "H5VL_SUBCLS_OBJECT"); + H5RS_acat(rs, "H5VL_SUBCLS_OBJECT"); break; + case H5VL_SUBCLS_REQUEST: - HDfprintf(out, "H5VL_SUBCLS_REQUEST"); + H5RS_acat(rs, "H5VL_SUBCLS_REQUEST"); break; + case H5VL_SUBCLS_BLOB: - HDfprintf(out, "H5VL_SUBCLS_BLOB"); + H5RS_acat(rs, "H5VL_SUBCLS_BLOB"); break; + case H5VL_SUBCLS_TOKEN: - HDfprintf(out, "H5VL_SUBCLS_TOKEN"); + H5RS_acat(rs, "H5VL_SUBCLS_TOKEN"); break; + default: - HDfprintf(out, "%ld", (long)subclass); + H5RS_asprintf_cat(rs, "%ld", (long)subclass); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 't': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 't': /* H5VL_dataset_optional_t */ + { H5VL_dataset_optional_t optional = (H5VL_dataset_optional_t)HDva_arg(ap, int); switch (optional) { case H5VL_NATIVE_DATASET_FORMAT_CONVERT: - HDfprintf(out, "H5VL_NATIVE_DATASET_FORMAT_CONVERT"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_FORMAT_CONVERT"); break; + case H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE: - HDfprintf(out, "H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE"); break; + case H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE: - HDfprintf(out, "H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE"); break; + case H5VL_NATIVE_DATASET_GET_NUM_CHUNKS: - HDfprintf(out, "H5VL_NATIVE_DATASET_GET_NUM_CHUNKS"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_GET_NUM_CHUNKS"); break; + case H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX: - HDfprintf(out, "H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX"); break; + case H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD: - HDfprintf(out, "H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD"); break; + case H5VL_NATIVE_DATASET_CHUNK_READ: - HDfprintf(out, "H5VL_NATIVE_DATASET_CHUNK_READ"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_CHUNK_READ"); break; + case H5VL_NATIVE_DATASET_CHUNK_WRITE: - HDfprintf(out, "H5VL_NATIVE_DATASET_CHUNK_WRITE"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_CHUNK_WRITE"); break; + case H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE: - HDfprintf(out, "H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE"); break; + case H5VL_NATIVE_DATASET_GET_OFFSET: - HDfprintf(out, "H5VL_NATIVE_DATASET_GET_OFFSET"); + H5RS_acat(rs, "H5VL_NATIVE_DATASET_GET_OFFSET"); break; + default: - HDfprintf(out, "%ld", (long)optional); + H5RS_asprintf_cat(rs, "%ld", (long)optional); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'u': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'u': /* H5VL_datatype_optional_t */ + { H5VL_datatype_optional_t optional = (H5VL_datatype_optional_t)HDva_arg(ap, int); - switch (optional) { - default: - HDfprintf(out, "%ld", (long)optional); - break; - } /* end switch */ - } /* end else */ + H5RS_asprintf_cat(rs, "%ld", (long)optional); + } /* end block */ break; - case 'v': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'v': /* H5VL_file_optional_t */ + { H5VL_file_optional_t optional = (H5VL_file_optional_t)HDva_arg(ap, int); switch (optional) { case H5VL_NATIVE_FILE_CLEAR_ELINK_CACHE: - HDfprintf(out, "H5VL_NATIVE_FILE_CLEAR_ELINK_CACHE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_CLEAR_ELINK_CACHE"); break; + case H5VL_NATIVE_FILE_GET_FILE_IMAGE: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_FILE_IMAGE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_FILE_IMAGE"); break; + case H5VL_NATIVE_FILE_GET_FREE_SECTIONS: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_FREE_SECTIONS"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_FREE_SECTIONS"); break; + case H5VL_NATIVE_FILE_GET_FREE_SPACE: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_FREE_SPACE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_FREE_SPACE"); break; + case H5VL_NATIVE_FILE_GET_INFO: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_INFO"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_INFO"); break; + case H5VL_NATIVE_FILE_GET_MDC_CONF: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_MDC_CONF"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_MDC_CONF"); break; + case H5VL_NATIVE_FILE_GET_MDC_HR: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_MDC_HR"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_MDC_HR"); break; + case H5VL_NATIVE_FILE_GET_MDC_SIZE: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_MDC_SIZE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_MDC_SIZE"); break; + case H5VL_NATIVE_FILE_GET_SIZE: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_SIZE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_SIZE"); break; + case H5VL_NATIVE_FILE_GET_VFD_HANDLE: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_VFD_HANDLE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_VFD_HANDLE"); break; + case H5VL_NATIVE_FILE_RESET_MDC_HIT_RATE: - HDfprintf(out, "H5VL_NATIVE_FILE_RESET_MDC_HIT_RATE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_RESET_MDC_HIT_RATE"); break; + case H5VL_NATIVE_FILE_SET_MDC_CONFIG: - HDfprintf(out, "H5VL_NATIVE_FILE_SET_MDC_CONFIG"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_SET_MDC_CONFIG"); break; + case H5VL_NATIVE_FILE_GET_METADATA_READ_RETRY_INFO: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_METADATA_READ_RETRY_INFO"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_METADATA_READ_RETRY_INFO"); break; + case H5VL_NATIVE_FILE_START_SWMR_WRITE: - HDfprintf(out, "H5VL_NATIVE_FILE_START_SWMR_WRITE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_START_SWMR_WRITE"); break; + case H5VL_NATIVE_FILE_START_MDC_LOGGING: - HDfprintf(out, "H5VL_NATIVE_FILE_START_MDC_LOGGING"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_START_MDC_LOGGING"); break; + case H5VL_NATIVE_FILE_STOP_MDC_LOGGING: - HDfprintf(out, "H5VL_NATIVE_FILE_STOP_MDC_LOGGING"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_STOP_MDC_LOGGING"); break; + case H5VL_NATIVE_FILE_GET_MDC_LOGGING_STATUS: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_MDC_LOGGING_STATUS"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_MDC_LOGGING_STATUS"); break; + case H5VL_NATIVE_FILE_FORMAT_CONVERT: - HDfprintf(out, "H5VL_NATIVE_FILE_FORMAT_CONVERT"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_FORMAT_CONVERT"); break; + case H5VL_NATIVE_FILE_RESET_PAGE_BUFFERING_STATS: - HDfprintf(out, "H5VL_NATIVE_FILE_RESET_PAGE_BUFFERING_STATS"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_RESET_PAGE_BUFFERING_STATS"); break; + case H5VL_NATIVE_FILE_GET_PAGE_BUFFERING_STATS: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_PAGE_BUFFERING_STATS"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_PAGE_BUFFERING_STATS"); break; + case H5VL_NATIVE_FILE_GET_MDC_IMAGE_INFO: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_MDC_IMAGE_INFO"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_MDC_IMAGE_INFO"); break; + case H5VL_NATIVE_FILE_GET_EOA: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_EOA"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_EOA"); break; + case H5VL_NATIVE_FILE_INCR_FILESIZE: - HDfprintf(out, "H5VL_NATIVE_FILE_INCR_FILESIZE"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_INCR_FILESIZE"); break; + case H5VL_NATIVE_FILE_SET_LIBVER_BOUNDS: - HDfprintf(out, "H5VL_NATIVE_FILE_SET_LIBVER_BOUNDS"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_SET_LIBVER_BOUNDS"); break; + case H5VL_NATIVE_FILE_GET_MIN_DSET_OHDR_FLAG: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_MIN_DSET_OHDR_FLAG"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_MIN_DSET_OHDR_FLAG"); break; + case H5VL_NATIVE_FILE_SET_MIN_DSET_OHDR_FLAG: - HDfprintf(out, "H5VL_NATIVE_FILE_SET_MIN_DSET_OHDR_FLAG"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_SET_MIN_DSET_OHDR_FLAG"); break; + case H5VL_NATIVE_FILE_GET_MPI_ATOMICITY: - HDfprintf(out, "H5VL_NATIVE_FILE_GET_MPI_ATOMICITY"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_GET_MPI_ATOMICITY"); break; + case H5VL_NATIVE_FILE_SET_MPI_ATOMICITY: - HDfprintf(out, "H5VL_NATIVE_FILE_SET_MPI_ATOMICITY"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_SET_MPI_ATOMICITY"); break; + case H5VL_NATIVE_FILE_POST_OPEN: - HDfprintf(out, "H5VL_NATIVE_FILE_POST_OPEN"); + H5RS_acat(rs, "H5VL_NATIVE_FILE_POST_OPEN"); break; + default: - HDfprintf(out, "%ld", (long)optional); + H5RS_asprintf_cat(rs, "%ld", (long)optional); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'w': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'w': /* H5VL_group_optional_t */ + { H5VL_group_optional_t optional = (H5VL_group_optional_t)HDva_arg(ap, int); switch (optional) { #ifndef H5_NO_DEPRECATED_SYMBOLS case H5VL_NATIVE_GROUP_ITERATE_OLD: - HDfprintf(out, "H5VL_NATIVE_GROUP_ITERATE_OLD"); + H5RS_acat(rs, "H5VL_NATIVE_GROUP_ITERATE_OLD"); break; + case H5VL_NATIVE_GROUP_GET_OBJINFO: - HDfprintf(out, "H5VL_NATIVE_GROUP_GET_OBJINFO"); + H5RS_acat(rs, "H5VL_NATIVE_GROUP_GET_OBJINFO"); break; #endif /* H5_NO_DEPRECATED_SYMBOLS */ + default: - HDfprintf(out, "%ld", (long)optional); + H5RS_asprintf_cat(rs, "%ld", (long)optional); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'x': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'x': /* H5VL_link_optional_t */ + { H5VL_link_optional_t optional = (H5VL_link_optional_t)HDva_arg(ap, int); - switch (optional) { - default: - HDfprintf(out, "%ld", (long)optional); - break; - } /* end switch */ - } /* end else */ + H5RS_asprintf_cat(rs, "%ld", (long)optional); + } /* end block */ break; - case 'y': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'y': /* H5VL_object_optional_t */ + { H5VL_object_optional_t optional = (H5VL_object_optional_t)HDva_arg(ap, int); switch (optional) { case H5VL_NATIVE_OBJECT_GET_COMMENT: - HDfprintf(out, "H5VL_NATIVE_OBJECT_GET_COMMENT"); + H5RS_acat(rs, "H5VL_NATIVE_OBJECT_GET_COMMENT"); break; + case H5VL_NATIVE_OBJECT_SET_COMMENT: - HDfprintf(out, "H5VL_NATIVE_OBJECT_SET_COMMENT"); + H5RS_acat(rs, "H5VL_NATIVE_OBJECT_SET_COMMENT"); break; + case H5VL_NATIVE_OBJECT_DISABLE_MDC_FLUSHES: - HDfprintf(out, "H5VL_NATIVE_OBJECT_DISABLE_MDC_FLUSHES"); + H5RS_acat(rs, "H5VL_NATIVE_OBJECT_DISABLE_MDC_FLUSHES"); break; + case H5VL_NATIVE_OBJECT_ENABLE_MDC_FLUSHES: - HDfprintf(out, "H5VL_NATIVE_OBJECT_ENABLE_MDC_FLUSHES"); + H5RS_acat(rs, "H5VL_NATIVE_OBJECT_ENABLE_MDC_FLUSHES"); break; + case H5VL_NATIVE_OBJECT_ARE_MDC_FLUSHES_DISABLED: - HDfprintf(out, "H5VL_NATIVE_OBJECT_ARE_MDC_FLUSHES_DISABLED"); + H5RS_acat(rs, "H5VL_NATIVE_OBJECT_ARE_MDC_FLUSHES_DISABLED"); break; + case H5VL_NATIVE_OBJECT_GET_NATIVE_INFO: - HDfprintf(out, "H5VL_NATIVE_OBJECT_GET_NATIVE_INFO"); + H5RS_acat(rs, "H5VL_NATIVE_OBJECT_GET_NATIVE_INFO"); break; + default: - HDfprintf(out, "%ld", (long)optional); + H5RS_asprintf_cat(rs, "%ld", (long)optional); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'z': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'z': /* H5VL_request_optional_t */ + { H5VL_request_optional_t optional = (H5VL_request_optional_t)HDva_arg(ap, int); - switch (optional) { - default: - HDfprintf(out, "%ld", (long)optional); - break; - } /* end switch */ - } /* end else */ + H5RS_asprintf_cat(rs, "%ld", (long)optional); + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(Z%c)", type[1]); - goto error; - } /* end switch */ - break; - - case 'x': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - void **p = (void **)vp; + default: + H5RS_asprintf_cat(rs, "BADTYPE(Z%c)", type[1]); + goto error; + } /* end switch */ + break; - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) { - if (p[i]) - HDfprintf(out, "%s0x%p", (i ? ", " : ""), p[i]); - else - HDfprintf(out, "%sNULL", (i ? ", " : "")); - } /* end for */ - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'x': { /* void / va_list */ vp = HDva_arg(ap, void *); if (vp) - HDfprintf(out, "0x%p", vp); + H5RS_asprintf_cat(rs, "%p", vp); else - HDfprintf(out, "NULL"); - } /* end else */ + H5RS_acat(rs, "NULL"); + } /* end block */ break; - case 'z': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - size_t *p = (size_t *)vp; - - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) - HDfprintf(out, "%s%zu", (i ? ", " : ""), p[i]); - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'z': { size_t size = HDva_arg(ap, size_t); - HDfprintf(out, "%zu", size); + H5RS_asprintf_cat(rs, "%zu", size); asize[argno] = (hssize_t)size; - } /* end else */ + } /* end block */ break; - case 'Z': - switch (type[1]) { - case 'a': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'Z': + switch (type[1]) { + case 'a': /* H5Z_SO_scale_type_t */ + { H5Z_SO_scale_type_t scale_type = (H5Z_SO_scale_type_t)HDva_arg(ap, int); switch (scale_type) { case H5Z_SO_FLOAT_DSCALE: - HDfprintf(out, "H5Z_SO_FLOAT_DSCALE"); + H5RS_acat(rs, "H5Z_SO_FLOAT_DSCALE"); break; case H5Z_SO_FLOAT_ESCALE: - HDfprintf(out, "H5Z_SO_FLOAT_ESCALE"); + H5RS_acat(rs, "H5Z_SO_FLOAT_ESCALE"); break; case H5Z_SO_INT: - HDfprintf(out, "H5Z_SO_INT"); + H5RS_acat(rs, "H5Z_SO_INT"); break; default: - HDfprintf(out, "%ld", (long)scale_type); + H5RS_asprintf_cat(rs, "%ld", (long)scale_type); break; } /* end switch */ - } /* end else */ + } /* end block */ break; - case 'c': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'c': /* H5Z_class2_t */ + { H5Z_class2_t *filter = HDva_arg(ap, H5Z_class2_t *); - HDfprintf(out, "0x%p", (void *)filter); - } /* end else */ + H5RS_asprintf_cat(rs, "%p", (void *)filter); + } /* end block */ break; - case 'e': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'e': /* H5Z_EDC_t */ + { H5Z_EDC_t edc = (H5Z_EDC_t)HDva_arg(ap, int); if (H5Z_DISABLE_EDC == edc) - HDfprintf(out, "H5Z_DISABLE_EDC"); + H5RS_acat(rs, "H5Z_DISABLE_EDC"); else if (H5Z_ENABLE_EDC == edc) - HDfprintf(out, "H5Z_ENABLE_EDC"); + H5RS_acat(rs, "H5Z_ENABLE_EDC"); else - HDfprintf(out, "%ld", (long)edc); - } /* end else */ + H5RS_asprintf_cat(rs, "%ld", (long)edc); + } /* end block */ break; - case 'f': - if (ptr) { - if (vp) - HDfprintf(out, "0x%p", vp); - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + case 'f': /* H5Z_filter_t */ + { H5Z_filter_t id = HDva_arg(ap, H5Z_filter_t); - if (H5Z_FILTER_DEFLATE == id) - HDfprintf(out, "H5Z_FILTER_DEFLATE"); + if (H5Z_FILTER_NONE == id) + H5RS_acat(rs, "H5Z_FILTER_NONE"); + else if (H5Z_FILTER_DEFLATE == id) + H5RS_acat(rs, "H5Z_FILTER_DEFLATE"); + else if (H5Z_FILTER_SHUFFLE == id) + H5RS_acat(rs, "H5Z_FILTER_SHUFFLE"); + else if (H5Z_FILTER_FLETCHER32 == id) + H5RS_acat(rs, "H5Z_FILTER_FLETCHER32"); + else if (H5Z_FILTER_SZIP == id) + H5RS_acat(rs, "H5Z_FILTER_SZIP"); + else if (H5Z_FILTER_NBIT == id) + H5RS_acat(rs, "H5Z_FILTER_NBIT"); + else if (H5Z_FILTER_SCALEOFFSET == id) + H5RS_acat(rs, "H5Z_FILTER_SCALEOFFSET"); else - HDfprintf(out, "%ld", (long)id); - } /* end else */ - break; - - case 's': - if (ptr) { - if (vp) { - HDfprintf(out, "0x%p", vp); - if (asize_idx >= 0 && asize[asize_idx] >= 0) { - ssize_t *p = (ssize_t *)vp; - - HDfprintf(out, " {"); - for (i = 0; i < asize[asize_idx]; i++) - HDfprintf(out, "%s%zd", (i ? ", " : ""), p[i]); - HDfprintf(out, "}"); - } /* end if */ - } /* end if */ - else - HDfprintf(out, "NULL"); - } /* end if */ - else { + H5RS_asprintf_cat(rs, "%ld", (long)id); + } /* end block */ + break; + + case 'F': /* H5Z_filter_func_t */ + { + H5Z_filter_func_t ffunc = (H5Z_filter_func_t)HDva_arg(ap, H5Z_filter_func_t); + + H5RS_asprintf_cat(rs, "%p", (void *)(uintptr_t)ffunc); + } /* end block */ + break; + + case 's': { ssize_t ssize = HDva_arg(ap, ssize_t); - HDfprintf(out, "%zd", ssize); + H5RS_asprintf_cat(rs, "%zd", ssize); asize[argno] = (hssize_t)ssize; - } /* end else */ + } /* end block */ break; - default: - HDfprintf(out, "BADTYPE(Z%c)", type[1]); - goto error; - } /* end switch */ - break; + default: + H5RS_asprintf_cat(rs, "BADTYPE(Z%c)", type[1]); + goto error; + } /* end switch */ + break; + + case '#': + H5RS_acat(rs, "Unsupported type slipped through!"); + break; - default: - if (HDisupper(type[0])) - HDfprintf(out, "BADTYPE(%c%c)", type[0], type[1]); - else - HDfprintf(out, "BADTYPE(%c)", type[0]); - goto error; - } /* end switch */ - } /* end for */ + case '!': + H5RS_acat(rs, "Unknown type slipped through!"); + break; + + default: + if (HDisupper(type[0])) + H5RS_asprintf_cat(rs, "BADTYPE(%c%c)", type[0], type[1]); + else + H5RS_asprintf_cat(rs, "BADTYPE(%c)", type[0]); + goto error; + } /* end switch */ + } /* end else */ + } /* end for */ + + return SUCCEED; +error: + return FAIL; +} /* end H5_trace_args() */ + +/*------------------------------------------------------------------------- + * Function: H5_trace + * + * Purpose: This function is called whenever an API function is called + * and tracing is turned on. If RETURNING is non-zero then + * the caller is about to return and RETURNING points to the + * time for the corresponding function call event. Otherwise + * we print the function name and the arguments. + * + * The TYPE argument is a string which gives the type of each of + * the following argument pairs. Each type is zero or more + * asterisks (one for each level of indirection, although some + * types have one level of indirection already implied) followed + * by either one letter (lower case) or two letters (first one + * uppercase). + * + * The variable argument list consists of pairs of values. Each + * pair is a string which is the formal argument name in the + * calling function, followed by the argument value. The type + * of the argument value is given by the TYPE string. + * + * Note: The TYPE string is meant to be terse and is generated by a + * separate perl script. + * + * WARNING: DO NOT CALL ANY HDF5 FUNCTION THAT CALLS FUNC_ENTER(). DOING + * SO MAY CAUSE H5_trace() TO BE INVOKED RECURSIVELY OR MAY + * CAUSE LIBRARY INITIALIZATIONS THAT ARE NOT DESIRED. + * + * Return: Execution time for an API call + * + * Programmer: Robb Matzke + * Tuesday, June 16, 1998 + * + *------------------------------------------------------------------------- + */ +double +H5_trace(const double *returning, const char *func, const char *type, ...) +{ + va_list ap; + H5RS_str_t * rs = NULL; + hssize_t i; + FILE * out = H5_debug_g.trace; + static hbool_t is_first_invocation = TRUE; + H5_timer_t function_timer; + H5_timevals_t function_times; + static H5_timer_t running_timer; + H5_timevals_t running_times; + static int current_depth = 0; + static int last_call_depth = 0; + + /* FUNC_ENTER() should not be called */ + + if (!out) + return (double)0.0F; /*tracing is off*/ + + if (H5_debug_g.ttop) { + if (returning) { + if (current_depth > 1) { + --current_depth; + return (double)0.0F; + } /* end if */ + } /* end if */ + else { + if (current_depth > 0) { + /*do not update last_call_depth*/ + current_depth++; + return (double)0.0F; + } /* end if */ + } /* end else */ + } /* end if */ + + /* Get time for event if the trace times flag is set */ + if (is_first_invocation && H5_debug_g.ttimes) { + /* start the library-wide timer */ + is_first_invocation = FALSE; + H5_timer_init(&running_timer); + H5_timer_start(&running_timer); + } /* end if */ + if (H5_debug_g.ttimes) { + /* start the timer for this function */ + H5_timer_init(&function_timer); + H5_timer_start(&function_timer); + } /* end if */ + + /* Create the ref-counted string */ + rs = H5RS_create(NULL); + + /* Print the first part of the line. This is the indication of the + * nesting depth followed by the function name and either start of + * argument list or start of return value. If this call is for a + * function return and no other calls have been made to H5_trace() + * since the one for the function call, then we're continuing + * the same line. */ + if (returning) { + HDassert(current_depth > 0); + --current_depth; + if (current_depth < last_call_depth) { + /* We are at the beginning of a line */ + if (H5_debug_g.ttimes) { + char tmp[320]; + + H5_timer_get_times(function_timer, &function_times); + H5_timer_get_times(running_timer, &running_times); + HDsprintf(tmp, "%.6f", (function_times.elapsed - running_times.elapsed)); + H5RS_asprintf_cat(rs, " %*s ", (int)HDstrlen(tmp), ""); + } /* end if */ + for (i = 0; i < current_depth; i++) + H5RS_aputc(rs, '+'); + H5RS_asprintf_cat(rs, "%*s%s = ", 2 * current_depth, "", func); + } /* end if */ + else + /* Continue current line with return value */ + H5RS_acat(rs, " = "); + } /* end if */ + else { + if (current_depth > last_call_depth) + H5RS_acat(rs, " = <delayed>\n"); + if (H5_debug_g.ttimes) { + H5_timer_get_times(function_timer, &function_times); + H5_timer_get_times(running_timer, &running_times); + H5RS_asprintf_cat(rs, "@%.6f ", (function_times.elapsed - running_times.elapsed)); + } /* end if */ + for (i = 0; i < current_depth; i++) + H5RS_aputc(rs, '+'); + H5RS_asprintf_cat(rs, "%*s%s(", 2 * current_depth, "", func); + } /* end else */ + + /* Format arguments into the refcounted string */ + HDva_start(ap, type); + H5_trace_args(rs, type, ap); + HDva_end(ap); /* Display event time for return */ if (returning && H5_debug_g.ttimes) { H5_timer_get_times(function_timer, &function_times); H5_timer_get_times(running_timer, &running_times); - HDfprintf(out, " @%.6f [dt=%.6f]", (function_times.elapsed - running_times.elapsed), - (function_times.elapsed - *returning)); + H5RS_asprintf_cat(rs, " @%.6f [dt=%.6f]", (function_times.elapsed - running_times.elapsed), + (function_times.elapsed - *returning)); } /* end if */ -error: - HDva_end(ap); + /* Display generated string */ if (returning) - HDfprintf(out, ";\n"); + H5RS_acat(rs, ";\n"); else { last_call_depth = current_depth++; - HDfprintf(out, ")"); + H5RS_acat(rs, ")"); } /* end else */ + HDfputs(H5RS_get_str(rs), out); HDfflush(out); + H5RS_decr(rs); if (H5_debug_g.ttimes) return function_times.elapsed; else - return 0.0F; + return (double)0.0F; } /* end H5_trace() */ diff --git a/src/Makefile.am b/src/Makefile.am index cbecccd..e18b0ae 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -19,6 +19,8 @@ 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 @@ -33,13 +35,13 @@ lib_LTLIBRARIES=libhdf5.la libhdf5_la_LDFLAGS= -version-info $(LT_VERS_INTERFACE):$(LT_VERS_REVISION):$(LT_VERS_AGE) $(AM_LDFLAGS) # H5Tinit.c and H5lib_settings.c are generated files and should be cleaned. -MOSTLYCLEANFILES=H5Tinit.c H5lib_settings.c +MOSTLYCLEANFILES=H5Tinit.c H5lib_settings.c $(DX_CLEANFILES) # H5pubconf.h is generated by configure, and should be cleaned. DISTCLEANFILES=H5pubconf.h # library sources libhdf5_la_SOURCES= H5.c H5checksum.c H5dbg.c H5lib_settings.c H5system.c \ - H5timer.c H5trace.c \ + H5timer.c H5trace.c \ H5A.c H5Abtree2.c H5Adense.c H5Adeprec.c H5Aint.c H5Atest.c \ H5AC.c H5ACdbg.c H5ACproxy_entry.c \ H5B.c H5Bcache.c H5Bdbg.c \ @@ -61,7 +63,7 @@ libhdf5_la_SOURCES= H5.c H5checksum.c H5dbg.c H5lib_settings.c H5system.c \ H5Fsuper.c H5Fsuper_cache.c H5Ftest.c \ H5FA.c H5FAcache.c H5FAdbg.c H5FAdblock.c H5FAdblkpage.c H5FAhdr.c \ H5FAint.c H5FAstat.c H5FAtest.c \ - H5FD.c H5FDcore.c H5FDfamily.c H5FDhdfs.c H5FDint.c H5FDlog.c \ + H5FD.c H5FDcore.c H5FDfamily.c H5FDint.c H5FDlog.c \ H5FDmulti.c H5FDsec2.c H5FDspace.c \ H5FDsplitter.c H5FDstdio.c H5FDtest.c \ H5FL.c H5FO.c H5FS.c H5FScache.c H5FSdbg.c H5FSint.c H5FSsection.c \ @@ -75,7 +77,7 @@ libhdf5_la_SOURCES= H5.c H5checksum.c H5dbg.c H5lib_settings.c H5system.c \ H5HG.c H5HGcache.c H5HGdbg.c H5HGquery.c \ H5HL.c H5HLcache.c H5HLdbg.c H5HLint.c H5HLprfx.c H5HLdblk.c \ H5HP.c \ - H5I.c H5Itest.c \ + H5I.c H5Idbg.c H5Iint.c H5Itest.c \ H5L.c H5Ldeprec.c H5Lexternal.c \ H5M.c \ H5MF.c H5MFaggr.c H5MFdbg.c H5MFsection.c \ @@ -126,6 +128,11 @@ if DIRECT_VFD_CONDITIONAL libhdf5_la_SOURCES += H5FDdirect.c endif +# Only compile the read-only HDFS VFD if necessary +if HDFS_VFD_CONDITIONAL + libhdf5_la_SOURCES += H5FDhdfs.c +endif + # Only compile the mirror VFD if necessary if MIRROR_VFD_CONDITIONAL libhdf5_la_SOURCES += H5FDmirror.c @@ -196,12 +203,16 @@ $(top_srcdir)/src/H5version.h: $(top_srcdir)/src/H5vers.txt $(top_srcdir)/src/H5overflow.h: $(top_srcdir)/src/H5overflow.txt perl $(top_srcdir)/bin/make_overflow $? +# doxygen support +if BUILD_DOXYGEN_CONDITIONAL +doxygen: doxygen-doc +endif + # Add TRACE macros to library source files. This is done via the trace script # in the hdf5/bin directory. If the file contains HDF5 API macros, a "clean" # version of the source file is saved with a tilde (~) after its name and # tracing information is inserted. trace should have no effect on files # without HDF5 macros. -.PHONY: trace trace: $(libhdf5_la_SOURCES) @for dep in $? dummy; do \ diff --git a/src/libhdf5.settings.in b/src/libhdf5.settings.in index 98390b8..4fddbc8 100644 --- a/src/libhdf5.settings.in +++ b/src/libhdf5.settings.in @@ -39,7 +39,7 @@ Languages: H5_CPPFLAGS: @H5_CPPFLAGS@ AM_CPPFLAGS: @AM_CPPFLAGS@ C Flags: @CFLAGS@ - H5 C Flags: @H5_CFLAGS@ @H5_ECFLAGS@ + H5 C Flags: @H5_CFLAGS@ AM C Flags: @AM_CFLAGS@ Shared C Library: @enable_shared@ Static C Library: @enable_static@ |