summaryrefslogtreecommitdiffstats
path: root/doxygen/dox/ReferenceManual.dox
diff options
context:
space:
mode:
authorDana Robinson <43805+derobins@users.noreply.github.com>2022-12-21 00:49:33 (GMT)
committerGitHub <noreply@github.com>2022-12-21 00:49:33 (GMT)
commit83c7f928f97b56a7a83f7f81b207cbe082136b1f (patch)
treef4896b9715f5b7f51226e6663eb153ebbb921634 /doxygen/dox/ReferenceManual.dox
parenta2ce031f32114fdb8d785f5f9685dc5633e73467 (diff)
downloadhdf5-83c7f928f97b56a7a83f7f81b207cbe082136b1f.zip
hdf5-83c7f928f97b56a7a83f7f81b207cbe082136b1f.tar.gz
hdf5-83c7f928f97b56a7a83f7f81b207cbe082136b1f.tar.bz2
Brings the following changesets over from develop: (#2328)
b9244a85d9f1cc5e9bbec61ca73c0cbd9c4cf249 Align arg types of H5D_chunk_iter_op_t with H5Dget_chunk_info (#2074) 70cf2c390bc2eef8e57f8fa023341011e2d02d9d Removed idioms and misc. text clean-up (#2320) 8102fa8c972bdc0d8fd8f3dae604e070893150d6 Only document Fortran functions (#2319) 784061b15e176b9919c19a220ce278a9f4cddf0e moved onion VFD to FAPL group (#2321) 6b6bcdead66f0456ac0528683faac6a8e48b6565 Hdffv 11052 (#2315) 10c693a04ff0c4a5219879d7f8900157dcbece66 Update hdf5_header.html 0cb58080875070db09b5ecae92482519d58872bc Hdffv 11052 (#2303) a1c81eda203addced514ef655f7a9079f3f0bb04 added doc. warning for H5Literate_async return value (#2295) 502b32b0f22a4bcf6333c85c256db34162c2764a Updated H5ES documenation (#2293) a9036005c3916e6fda0296026323f00d043300f8 Fix for HDFFV-11052: h5debug fails on a corrupted file (h5_nrefs_POC)… (#2291)
Diffstat (limited to 'doxygen/dox/ReferenceManual.dox')
-rw-r--r--doxygen/dox/ReferenceManual.dox13
1 files changed, 4 insertions, 9 deletions
diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox
index e79de67..b9bcd49 100644
--- a/doxygen/dox/ReferenceManual.dox
+++ b/doxygen/dox/ReferenceManual.dox
@@ -145,23 +145,19 @@ Functions with \ref ASYNC<br />
</tr>
</table>
-</td></tr>
-<tr><th>Mind the gap</th></tr>
-<tr><td>
Follow these simple rules and stay out of trouble:
-\li \Bold{Handle discipline:} The HDF5 C-API is rife with handles or
+\li \Bold{Handle discipline:} The HDF5 API is rife with handles or
identifiers, which you typically obtain by creating new HDF5 items, copying
- items, or retrieving facets of items. \Emph{You acquire a handle, you own it!}
- (Colin Powell) In other words, you are responsible for releasing the underlying
+ items, or retrieving facets of items. Consequently, \Bold{and most importantly}, you are
+ responsible for releasing the underlying
resources via the matching \Code{H5*close()} call, or deal with the consequences
of resource leakage.
\li \Bold{Closed means closed:} Do not pass identifiers that were previously
\Code{H5*close()}-d to other API functions! It will generate an error.
\li \Bold{Dynamic memory allocation:} The API contains a few functions in which the
HDF5 library dynamically allocates memory on the caller's behalf. The caller owns
- this memory and eventually must free it by calling H5free_memory(). (\Bold{Not}
- the `free` function \Emph{du jour}!)
+ this memory and eventually must free it by calling H5free_memory() and not language-explicit memory functions.
\li \Bold{Be careful with that saw:} Do not modify the underlying collection when an
iteration is in progress!
\li \Bold{Use of locations:} Certain API functions, typically called \Code{H5***_by_name}
@@ -169,7 +165,6 @@ Follow these simple rules and stay out of trouble:
If the identifier fully specifies the object in question, pass \Code{'.'} (a dot)
for the name!
-Break a leg!
</td>
</tr>
</table>