Skip to content

Commit

Permalink
updated docs. for namelen returned
Browse files Browse the repository at this point in the history
  • Loading branch information
brtnfld committed Apr 29, 2024
1 parent 0fb0a9b commit 2eb91a7
Show file tree
Hide file tree
Showing 3 changed files with 12 additions and 60 deletions.
4 changes: 4 additions & 0 deletions doxygen/aliases
Original file line number Diff line number Diff line change
Expand Up @@ -387,6 +387,10 @@ ALIASES += str_pad_type="<table><tr><td>#H5T_STR_NULLTERM</td><td>0</td><td>Null
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="<table><tr><th>Flag</th><th>Purpose</th></tr><tr><td>#H5O_INFO_BASIC</td><td>Fill in the fileno, addr, type, and rc fields</td></tr><tr> <td>#H5O_INFO_TIME</td><td>Fill in the atime, mtime, ctime, and btime fields</td></tr><tr> <td>#H5O_INFO_NUM_ATTRS</td> <td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_HDR</td><td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_META_SIZE</td><td>Fill in the meta_size field</td></tr><tr><td>#H5O_INFO_ALL</td><td>#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE</td></tr></table>"

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
################################################################################
Expand Down
18 changes: 2 additions & 16 deletions src/H5Ppublic.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand Down Expand Up @@ -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
*
Expand Down
50 changes: 6 additions & 44 deletions src/H5Rpublic.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
*
Expand Down Expand Up @@ -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
*/
Expand Down

0 comments on commit 2eb91a7

Please sign in to comment.