From 2eb91a77f4973d10a32451d32cc0046b167f15c3 Mon Sep 17 00:00:00 2001 From: Scot Breitenfeld Date: Mon, 29 Apr 2024 16:30:22 -0500 Subject: [PATCH] updated docs. for namelen returned --- doxygen/aliases | 4 ++++ src/H5Ppublic.h | 18 ++---------------- src/H5Rpublic.h | 50 ++++++------------------------------------------- 3 files changed, 12 insertions(+), 60 deletions(-) diff --git a/doxygen/aliases b/doxygen/aliases index e972dd33da0..e3ec6438021 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -387,6 +387,10 @@ ALIASES += str_pad_type="
#H5T_STR_NULLTERM0Null ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()" ALIASES += obj_info_fields="
FlagPurpose
#H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
#H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
#H5O_INFO_NUM_ATTRS Fill in the num_attrs field
#H5O_INFO_HDRFill in the num_attrs field
#H5O_INFO_META_SIZEFill in the meta_size field
#H5O_INFO_ALL#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE
" +ALIASES += details_namelen{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name. That value, plus 1 for a NULL terminator, must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name. +ALIASES += details_namelen_plusone{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name plus 1 for a NULL terminator. That value must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name. + + ################################################################################ # FORTRAN ################################################################################ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 390f2009bf3..57d84350391 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -6222,14 +6222,7 @@ H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count /*out*/); * \p name; additional characters, if any, are not returned to * the user application. * - * If the length of the dataset name, which determines the - * required value of \p size, is unknown, a preliminary call - * to H5Pget_virtual_dsetname() with the last two parameters - * set to NULL and zero respectively can be made. The return - * value of this call will be the size in bytes of the dataset - * name. That value, plus 1 for a NULL terminator, must then be - * assigned to \p size for a second H5Pget_virtual_dsetname() - * call, which will retrieve the actual dataset name. + * \details_namelen{dataset,H5Pget_virtual_dsetname} * * \see_virtual * @@ -6266,14 +6259,7 @@ H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name / * \p name; additional characters, if any, are not returned to * the user application. * - * If the length of the filename, which determines the required - * value of \p size, is unknown, a preliminary call to - * H5Pget_virtual_filename() with the last two parameters set - * to NULL and zero respectively can be made. The return value - * of this call will be the size in bytes of the filename. That - * value, plus 1 for a NULL terminator, must then be assigned to - * \p size for a second H5Pget_virtual_filename() call, which - * will retrieve the actual filename. + * \details_namelen{file,H5Pget_virtual_filename} * * \see_virtual * diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index b47cd36a4d2..53472f933ab 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -527,15 +527,7 @@ H5_DLL herr_t H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *ob * \details H5Rget_file_name() retrieves the file name for the object, * region or attribute reference pointed to by \p ref_ptr. * - * Up to \p 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 size, is unknown, a preliminary - * H5Rget_file_name() call can be made. The return value of this - * call will be the size of the file name (the size does not include - * the \p NULL terminator). That value can then be - * passed in for size in the second call to H5Rget_file_name(), - * which will retrieve the actual name. + * \details_namelen{file,H5Rget_file_name} * * \since 1.12.0 * @@ -566,16 +558,7 @@ H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t siz * be used to access external files that the reference points to * (through a file access property list). * - * 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 call to H5Rget_obj_name() call - * can be made. The return value of this call will be the size of the - * object name. That value can then be passed in for \p size in the - * second call to H5Rget_obj_name(), which will retrieve the actual - * name. If there is no name associated with the object identifier - * or if the name is NULL, H5Rget_obj_name() returns the size of - * the name buffer (the size does not include the \c \0 terminator). + * \details_namelen{object,H5Rget_obj_name} * * If \p ref_ptr is an object reference, \p name will be returned with * a name for the referenced object. If \p ref_ptr is a dataset region @@ -606,15 +589,7 @@ H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, si * \details H5Rget_attr_name() retrieves the attribute name for the * attribute reference pointed to by \p ref_ptr. * - * 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 - * H5Rget_attr_name() call can be made. The return value of this - * call will be the size of the attribute name (the size \Bold{does} include - * the \p NULL terminator). That value can then - * be passed in for size in the second call to H5Rget_attr_name(), - * which will retrieve the actual name. + * \details_namelen_plusone{attribute,H5Rget_attr_name} * * \since 1.12.0 * @@ -973,23 +948,10 @@ H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); * reference, \p name will contain a name for the object containing the * referenced region. * - * Up to \p size characters of the name are returned in \p name; - * additional characters, if any, are not returned to the user - * application. + * \details_namelen{,H5Rget_name} * - * If the length of the name, which determines the required value of \p - * size, is unknown, a preliminary H5Rget_name() call can be made. The - * return value of this call will be the size of the object name. That - * value can then be assigned to \p size for a second H5Rget_name() - * call, which will retrieve the actual name. - * - * If there is no name associated with the object identifier or if the - * \p name is \c NULL, H5Rget_name() returns the size of the \p name - * buffer (the size does not include the \p NULL terminator). - * - * 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. + * \note An object in an HDF5 file may have multiple paths if multiple + * links point to it. This function may return any one of these paths. * * \since 1.8.0 */