From 987a734e759c82c65a661ae6090b2252d63a7aec Mon Sep 17 00:00:00 2001 From: mattjala <124107509+mattjala@users.noreply.github.com> Date: Mon, 29 Jan 2024 13:33:21 -0600 Subject: Document that fileno is the same for all handles (#3965) * Document that fileno is same for all handles * Mention filesystem requirement --- src/H5Fpublic.h | 7 +++++++ src/H5Opublic.h | 22 ++++++++++++---------- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index ec4097c..551a345 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -740,6 +740,13 @@ H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned *intent); * file identifier \p file_id and the pointer \p fnumber to the file * number. * + * This file number is the same for all open instances of the same + * file, as long as 1. The active VFD implements the file comparison operator, + * and 2. The current filesystem is able to determine if the same file is opened more + * than once. If these conditions are not met, it is the application's + * responsibility to avoid opening multiple handles into the same file, + * which results in undefined behavior. + * * \since 1.12.0 * */ diff --git a/src/H5Opublic.h b/src/H5Opublic.h index f35bdd0..cee0660 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -143,15 +143,16 @@ typedef struct H5O_hdr_info_t { * (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3) */ typedef struct H5O_info2_t { - unsigned long fileno; /**< File number that object is located in */ - H5O_token_t token; /**< Token representing the object */ - H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ - unsigned rc; /**< Reference count of object */ - time_t atime; /**< Access time */ - time_t mtime; /**< Modification time */ - time_t ctime; /**< Change time */ - time_t btime; /**< Birth time */ - hsize_t num_attrs; /**< Number of attributes attached to object */ + unsigned long + fileno; /**< File number that object is located in. Constant across multiple opens of the same file */ + H5O_token_t token; /**< Token representing the object */ + H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ + unsigned rc; /**< Reference count of object */ + time_t atime; /**< Access time */ + time_t mtime; /**< Modification time */ + time_t ctime; /**< Change time */ + time_t btime; /**< Birth time */ + hsize_t num_attrs; /**< Number of attributes attached to object */ } H5O_info2_t; //! @@ -1717,7 +1718,8 @@ typedef struct H5O_stat_t { * H5Oget_info_by_idx() versions 1 & 2.) */ typedef struct H5O_info1_t { - unsigned long fileno; /**< File number that object is located in */ + unsigned long + fileno; /**< File number that object is located in. Constant across multiple opens of the same file */ haddr_t addr; /**< Object address in file */ H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ unsigned rc; /**< Reference count of object */ -- cgit v0.12