Documents Windows badness in H5Pget_external() (#1821)

* Documents Windows badness in H5Pget_external()

* Added a cast for off_t

2 files changed, 13 insertions, 1 deletions

diff --git a/src/H5Pdcpl.c b/src/H5Pdcpl.c
index 3c7bc09..4926cbd 100644
--- a/src/H5Pdcpl.c
+++ b/src/H5Pdcpl.c
@@ -2995,8 +2995,17 @@ H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out
     /* Return values */
     if (name_size > 0 && name)
         HDstrncpy(name, efl.slot[idx].name, name_size);
+    /* XXX: Badness!
+     *
+     * The offset parameter is of type off_t and the offset field of H5O_efl_entry_t
+     * is HDoff_t which is a different type on Windows (off_t is a 32-bit long,
+     * HDoff_t is __int64, a 64-bit type).
+     *
+     * In a future API reboot, we'll either want to make this parameter a haddr_t
+     * or define a 64-bit HDF5-specific offset type that is platform-independent.
+     */
     if (offset)
-        *offset = efl.slot[idx].offset;
+        *offset = (off_t)efl.slot[idx].offset;
     if (size)
         *size = efl.slot[idx].size;
 
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index d0bc2b8..8c021f2 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -5781,6 +5781,9 @@ H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize);
  *          are null pointers then the corresponding information is not
  *          returned.
  *
+ * \note On Windows, off_t is typically a 32-bit signed long value, which
+ *       limits the valid offset that can be returned to 2 GiB.
+ *
  * \version 1.6.4 \p idx parameter type changed to unsigned.
  * \since 1.0.0
  *