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: [PATCH] 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 ec4097cca89..551a345d85a 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 f35bdd0e7f5..cee0660c5ce 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;
 //! <!-- [H5O_info2_t_snip] -->
 
@@ -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    */