1 files changed, 71 insertions, 0 deletions
diff --git a/doxygen/dox/cookbook/Files.dox b/doxygen/dox/cookbook/Files.dox
new file mode 100644
index 0000000..169d638
--- /dev/null
+++ b/doxygen/dox/cookbook/Files.dox
@@ -0,0 +1,71 @@
+/** \page Files
+
+\section Files
+
+\subsection CB_FreeSpace Tracking Free Space in HDF5 Files
+
+\par Problem
+You sometimes delete objects in HDF5 files and don't have new content to use the
+free space, but would like to reuse it in the future.
+
+\par Solution
+At file creation time, set the file space management strategy and persistence of
+free space tracking information via H5Pset_file_space_strategy().
+
+\note This feature is only supported in HDF5 1.10.1+.
+
+\snippet{lineno} Files.c free_space
+
+\par Discussion
+Free space tracking is supported only in HDF5 versions 1.10.x and higher.
+This has implications for the accessibility of your HDF5 files and
+should be considered carefully. If compatibility with previous versions of
+HDF5 must be maintained, space reclamation via \Code{h5repack} might be an option.\n
+The file space strategy #H5F_FSPACE_STRATEGY_FSM_AGGR is not the only option
+that supports free-space tracking. #H5F_FSPACE_STRATEGY_PAGE is another option,
+which adds paged allocation and is used most effectively with page buffering.\n
+For an in-depth account of HDF5 file space management, paged-allocation, and
+page buffering, see the following documents:
+\li \ref_rfc20121024
+\li \ref_rfc20120523
+\li \ref_rfc20150709
+
+\par See Also
+See \ref CB_MaintainCompat for HDF5 compatibility implications.
+
+
+\subsection CB_RemoveUnusedSpace Removing Unused Space from HDF5 Files
+
+\par Problem
+Based on estimates or \Code{h5stat} output you know that a large portion
+of an HDF5 file consists of free or unaccounted space, and you would like
+to remove it.
+
+
+\subsection CB_UserBlock Creating an HDF5 File User Block
+
+\par Problem
+You would like to include certain ancillary, non-HDF5 content in an
+HDF5 file such that it can be accessed without the HDF5 library.
+
+\par Solution
+Use a file creation property list in which the user block size is set via
+H5Pset_userblock(). In the example below, we create an 8 MiB user block.
+\snippet{lineno} Files.c user_block
+
+\par Discussion
+The user block begins at offset 0 and must be at least 512 bytes and a power
+of 2. The HDF5 library ignores any content between the beginning of the
+file and the end of the user block.\n
+You can add or strip a user block to/from an existing HDF5 file with the
+\Code{h5jam}/\Code{h5unjam} tool, respectively.
+\warning
+If you try to embed content into the user block for use by other applications,
+pay close attention to how they handle space beyond the last used byte in the
+user block or the user block in general. In the worst case, applications might
+try to truncate the rest of the file and destroy the HDF5 portion of the file.
+
+\par See Also
+References to related recipes
+
+ */
+\ No newline at end of file