mirror/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2025-04-12 17:31:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Translate release-specific changes docs to doxygen (#5314)

Browse Source
This commit is contained in:
Allen Byrne 2025-02-18 11:21:27 -06:00 committed by GitHub
parent 45e042c0bc
commit 409f738e9d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
33 changed files with 4304 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doxygen/aliases
View File

@ -283,6 +283,7 @@ ALIASES += ref_vol_doc="VOL documentation"
# RFCs
################################################################################
ALIASES += ref_rfc20240129="<a href=\"https://\RFCURL/RFC__Adding_support_for_16_bit_floating_point_and_Complex_number_datatypes_to_HDF5.pdf\">Adding support for 16-bit floating point and Complex number datatypes to HDF</a>"
ALIASES += ref_rfc20220819="<a href=\"https://\RFCURL/Terminal_VOL_Connector_Feature_Flags.pdf\">Terminal VOL Connector Feature Flags</a>"
ALIASES += ref_rfc20210528="<a href=\"https://\RFCURL/RFC_multi_thread.pdf\">Multi-Thread HDF5</a>"
ALIASES += ref_rfc20210219="<a href=\"https://\RFCURL/selection_io_RFC_210610.pdf\">Selection I/O</a>"

2
doxygen/dox/HDF5CompressionTroubleshooting.dox
View File

@ -597,7 +597,7 @@ HDF5 file size as much as possible.
For example, we looked at a NASA weather data product file packaged with it its geolocation
information (the file name is
<code>GCRIOREDRO_npp_d20030125_t0702533_e0711257_b00993_c20140501163427060570_XXXX_XXX.h5</code>)
and used h5repack to apply three different compressions to the original file:
and used \ref sec_cltools_h5repack to apply three different compressions to the original file:
\li gzip with compression level 7
\li szip compression using NN mode and 32-bit block size
\li Shuffle in combination with gzip compression level 7

5
doxygen/dox/HDF5ImprovingIOPerformanceCompressedDatasets.dox
View File

@ -131,7 +131,8 @@
* \ref sec_cltools_h5dump and \ref sec_cltools_h5ls
* and the HDF Java-based browser HDFView to find various properties of the dataset that would help us to
* understand performance problems and propose solutions. If the reader decides to follow the discussion
* using a “hands on” approach, the examples below illustrate how to use h5dump and h5ls to get the
* using a “hands on” approach, the examples below illustrate how to use \ref sec_cltools_h5dump and
* \ref sec_cltools_h5ls to get the
* characteristics of the <code>/All_Data/CrIS-SDR_All/ES_ImaginaryLW</code> dataset.
* \li <sup>2</sup>:The ratio itself is not a subject of this paper, but the fact that the dataset was
* compressed is. It is one of the factors that affected the performance. While the total compression
@ -234,7 +235,7 @@
* In our last experiment, we repacked both files with \ref sec_cltools_h5repack to use a chunk size of 1x30x9x717, 4
* times smaller than the original chunks, and read the file by using the original access pattern of
* 1x1x1x717 hyperslab (by “row”). The result is shown below in Table 4. Once again, we got much better
* performance than shown in Table 1, even when considering the time to repack the file with h5repack.
* performance than shown in Table 1, even when considering the time to repack the file with \ref sec_cltools_h5repack.
* <table>
* <caption>Table 4: Reading by 1x1x1x717 hyperslab (by “row”) from non-compressed and compressed datasets;
* a smaller chunk size of 1x30x9x717 was used to store data in both files. Performance for the

22
doxygen/dox/IntroHDF5.dox
View File

@ -199,13 +199,13 @@ as providing templates for storing objects. Following is a list of the High Leve
\subsubsection subsec_intro_desc_soft_tools Tools
Useful tools for working with HDF5 files include:
\li h5dump: A utility to dump or display the contents of an HDF5 File
\li h5cc, h5c++, h5fc: Unix scripts for compiling applications
\li HDFView: A java browser to view HDF (HDF4 and HDF5) files
\li \ref sec_cltools_h5dump : A utility to dump or display the contents of an HDF5 File
\li h5cc, h5c++, h5fc : Unix scripts for compiling applications
\li HDFView : A java browser to view HDF (HDF4 and HDF5) files
<h4>h5dump</h4>
The h5dump utility displays the contents of an HDF5 file in Data Description Language (\ref DDLBNF200).
Below is an example of h5dump output for an HDF5 file that contains no objects:
The \ref sec_cltools_h5dump utility displays the contents of an HDF5 file in Data Description Language (\ref DDLBNF200).
Below is an example of \ref sec_cltools_h5dump output for an HDF5 file that contains no objects:
\code
$ h5dump file.h5
HDF5 "file.h5" {
@ -214,9 +214,9 @@ $ h5dump file.h5
}
\endcode
With large files and datasets the output from h5dump can be overwhelming.
With large files and datasets the output from \ref sec_cltools_h5dump can be overwhelming.
There are options that can be used to examine specific parts of an HDF5 file.
Some useful h5dump options are included below:
Some useful \ref sec_cltools_h5dump options are included below:
\code
-H, --header Display header information only (no data)
-d <name> Display a dataset with a specified path and name
@ -268,13 +268,13 @@ are usually similar, see @ref HDF5LIB
For example:
<ul>
<li>
File Interface:<ul><li>#H5Fopen (C)</li><li>h5fopen_f (FORTRAN)</li><li>H5.H5Fopen (Java)</li></ul>
File Interface:<ul><li>#H5Fopen (C)</li><li>#h5f.h5fopen_f (FORTRAN)</li><li>H5.H5Fopen (Java)</li></ul>
</li>
<li>
Dataset Interface:<ul><li>#H5Dopen (C)</li><li>h5dopen_f (FORTRAN)</li><li>H5.H5Dopen (Java)</li></ul>
Dataset Interface:<ul><li>#H5Dopen (C)</li><li>#h5d.h5dopen_f (FORTRAN)</li><li>H5.H5Dopen (Java)</li></ul>
</li>
<li>
Dataspace interface:<ul><li>#H5Sclose (C)</li><li>h5sclose_f (FORTRAN)</li><li>H5.H5Sclose (Java)</li></ul>
Dataspace interface:<ul><li>#H5Sclose (C)</li><li>#h5s.h5sclose_f (FORTRAN)</li><li>H5.H5Sclose (Java)</li></ul>
</li>
</ul>
The HDF5 Python APIs use methods associated with specific objects.
@ -311,7 +311,7 @@ import numpy
<li>
<strong>FORTRAN</strong>:<br />
<code>USE HDF5</code><br />
and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
and call #h5lib.h5open_f and #h5lib.h5close_f to initialize and close the HDF5 FORTRAN interface
</li>
<li>
<strong>Java</strong>:<br />

20
doxygen/dox/IntroParExamples.dox
View File

@ -106,7 +106,7 @@ If using this example with 4 processes, then,
\li Process 2 writes "12"s.
\li Process 3 writes "13"s.
The following is the output from h5dump for the HDF5 file created by this example using 4 processes:
The following is the output from \ref sec_cltools_h5dump for the HDF5 file created by this example using 4 processes:
\code
HDF5 "SDS_row.h5" {
GROUP "/" {
@ -210,8 +210,8 @@ Below is the F90 example program which illustrates how to write contiguous hyper
</tr>
</table>
If you run this program with 4 processes and look at the output with h5dump you will notice that the output is
much like the output shown above for the C example. This is because h5dump is written in C. The data would be
If you run this program with 4 processes and look at the output with \ref sec_cltools_h5dump you will notice that the output is
much like the output shown above for the C example. This is because \ref sec_cltools_h5dump is written in C. The data would be
displayed in columns if it was printed using Fortran 90 code.
<hr>
@ -280,7 +280,7 @@ Below is an example program for writing hyperslabs by column in Parallel HDF5:
</tr>
</table>
The following is the output from h5dump for the HDF5 file created by this example:
The following is the output from \ref sec_cltools_h5dump for the HDF5 file created by this example:
\code
HDF5 "SDS_col.h5" {
GROUP "/" {
@ -351,8 +351,8 @@ Below is the example program for writing hyperslabs by column in Parallel HDF5:
</tr>
</table>
The output for h5dump on the file created by this program will look like the output as shown above for the C example. This is
because h5dump is written in C. The data would be displayed in rows if it were printed using Fortran 90 code.
The output for \ref sec_cltools_h5dump on the file created by this program will look like the output as shown above for the C example. This is
because \ref sec_cltools_h5dump is written in C. The data would be displayed in rows if it were printed using Fortran 90 code.
<hr>
Navigate back: \ref index "Main" / \ref GettingStarted / \ref IntroParHDF5
@ -441,7 +441,7 @@ Below are example programs for writing hyperslabs by pattern in Parallel HDF5:
</tr>
</table>
The following is the output from h5dump for the HDF5 file created in this example:
The following is the output from \ref sec_cltools_h5dump for the HDF5 file created in this example:
\code
HDF5 "SDS_pat.h5" {
GROUP "/" {
@ -462,7 +462,7 @@ GROUP "/" {
}
}
\endcode
The h5dump utility is written in C so the output is in C order.
The \ref sec_cltools_h5dump utility is written in C so the output is in C order.
<hr>
@ -540,7 +540,7 @@ Below are example programs for writing hyperslabs by pattern in Parallel HDF5:
</tr>
</table>
The following is the output from h5dump for the HDF5 file created in this example:
The following is the output from \ref sec_cltools_h5dump for the HDF5 file created in this example:
\code
HDF5 "SDS_chnk.h5" {
GROUP "/" {
@ -561,7 +561,7 @@ GROUP "/" {
}
}
\endcode
The h5dump utility is written in C so the output is in C order.
The \ref sec_cltools_h5dump utility is written in C so the output is in C order.
<hr>
Navigate back: \ref index "Main" / \ref GettingStarted / \ref IntroParHDF5

18
doxygen/dox/LearnBasics1.dox
View File

@ -166,10 +166,10 @@ Keep the following in mind when looking at the example programs included in this
<table>
<tr>
<td>File Interface: </td>
<td>h5fopen_f</td>
<td>#h5f.h5fopen_f</td>
</tr><tr>
<td>Dataset Interface:</td>
<td>h5dopen_f</td>
<td>#h5d.h5dopen_f</td>
</tr>
</table>
@ -208,7 +208,7 @@ import numpy
<li>
<strong>FORTRAN</strong>:<br />
<code>USE HDF5</code><br />
and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
and call #h5lib.h5open_f and #h5lib.h5close_f to initialize and close the HDF5 FORTRAN interface
</li>
<li>
<strong>Java</strong>:<br />
@ -364,8 +364,9 @@ inadvertently left open. A File Access property controls how the file is closed.
\subsection subsecLBFileExampleCont File Contents
The HDF Group has developed tools for examining the contents of HDF5 files. The tool used throughout the HDF5 tutorial
is the HDF5 dumper, <code style="background-color:whitesmoke;">h5dump</code>, which displays the file contents in human-readable form. The output of <code style="background-color:whitesmoke;">h5dump</code> is an ASCII
display formatted according to the HDF5 DDL grammar. This grammar is defined, using Backus-Naur Form, in the
is the HDF5 dumper, <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>, which displays the file
contents in human-readable form. The output of <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>
is an ASCII display formatted according to the HDF5 DDL grammar. This grammar is defined, using Backus-Naur Form, in the
\ref DDLBNF200.
To view the HDF5 file contents, simply type:
@ -382,8 +383,11 @@ h5dump <filename>
</tr>
</table>
The text description of <code style="background-color:whitesmoke;">file.h5</code>, as generated by <code style="background-color:whitesmoke;">h5dump</code>. The HDF5 file called <code style="background-color:whitesmoke;">file.h5</code>
contains a group called <code style="background-color:whitesmoke;">/</code>, or the root group. (The file called <code style="background-color:whitesmoke;">filef.h5</code>, created by the FORTRAN version of the example,
The text description of <code style="background-color:whitesmoke;">file.h5</code>, as generated by
<code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>. The HDF5 file called
<code style="background-color:whitesmoke;">file.h5</code>
contains a group called <code style="background-color:whitesmoke;">/</code>, or the root group.
(The file called <code style="background-color:whitesmoke;">filef.h5</code>, created by the FORTRAN version of the example,
has the same output except that the filename shown is <code style="background-color:whitesmoke;">filef.h5</code>.)
\code
HDF5 "file.h5" {

14
doxygen/dox/LearnBasics2.dox
View File

@ -155,17 +155,21 @@ For details on compiling an HDF5 application:
#H5Gcreate creates a group at the location specified by a location identifier and a name. The location identifier
can be a file identifier or a group identifier and the name can be relative or absolute.
The first #H5Gcreate/h5gcreate_f creates the group <code style="background-color:whitesmoke;">MyGroup</code> in the root group of the specified file.
The first #H5Gcreate/#h5g.h5gcreate_f creates the group <code style="background-color:whitesmoke;">MyGroup</code>
in the root group of the specified file.
The second #H5Gcreate/h5gcreate_f creates the group <code style="background-color:whitesmoke;">Group_A</code> in the group <code style="background-color:whitesmoke;">MyGroup</code> in the root group of the specified
The second #H5Gcreate/#h5g.h5gcreate_f creates the group <code style="background-color:whitesmoke;">Group_A</code>
in the group <code style="background-color:whitesmoke;">MyGroup</code> in the root group of the specified
file. Note that the parent group (<code style="background-color:whitesmoke;">MyGroup</code>) already exists.
The third #H5Gcreate/h5gcreate_f creates the group <code style="background-color:whitesmoke;">Group_B</code> in the specified group.
The third #H5Gcreate/#h5g.h5gcreate_f creates the group <code style="background-color:whitesmoke;">Group_B</code> in the specified group.
\subsection secLBGrpCreateNamesExCont File Contents
Shown below is the contents and the definition of the group of <code style="background-color:whitesmoke;">groups.h5</code> (created by the C program).
(The FORTRAN program creates the HDF5 file <code style="background-color:whitesmoke;">groupsf.h5</code> and the resulting DDL shows the filename
Shown below are the contents and the definition of the group of <code style="background-color:whitesmoke;">groups.h5</code>
(created by the C program).
(The FORTRAN program creates the HDF5 file <code style="background-color:whitesmoke;">groupsf.h5</code> and
the resulting DDL shows the filename
<code style="background-color:whitesmoke;">groupsf.h5</code> in the first line.)
<table>
<caption>The Contents of groups.h5.</caption>

4
doxygen/dox/LearnBasics3.dox
View File

@ -287,10 +287,10 @@ Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics
<hr>
\section secLBContents Discovering what is in an HDF5 file
HDFView and h5dump are standalone tools which cannot be called within an application, and using
HDFView and \ref sec_cltools_h5dump are standalone tools which cannot be called within an application, and using
#H5Dopen and #H5Dread require that you know the name of the HDF5 dataset. How would an application
that has no prior knowledge of an HDF5 file be able to determine or discover the contents of it,
much like HDFView and h5dump?
much like HDFView and \ref sec_cltools_h5dump?
The answer is that there are ways to discover the contents of an HDF5 file, by using the
\ref H5G, \ref H5L and \ref H5O APIs:

2
doxygen/dox/Overview.dox
View File

@ -20,6 +20,8 @@ while the \link Cookbook \endlink is focused on tasks. The different guide-type
documents cover a mix of tasks, concepts, and reference, to help a specific
<em>audience</em> succeed.
\ref release_specific_info
\par Offline reading
You can <a href="https://\RELURL/v1_14/v1_14_5/downloads/hdf5-1.14.5.doxygen.zip">download</a> it as an archive for offline reading.

20
doxygen/dox/SWMRTechNote.dox
View File

@ -40,10 +40,10 @@ A beneficial side effect of using SWMR access is better fault tolerance. It is m
</ul>
\subsubsection subsubsec_swmr_doc_tools Tools
\li h5watch — Outputs new records appended to a dataset as the dataset grows
\li h5format_convert — Converts the layout format version and chunked indexing types of datasets created with
\li \ref sec_cltools_h5watch — Outputs new records appended to a dataset as the dataset grows
\li \ref sec_cltools_h5format_convert — Converts the layout format version and chunked indexing types of datasets created with
HDF5-1.10 so that applications built with HDF5-1.8 can access them
\li h5clear — Clears superblock status_flags field, removes metadata cache image, prints EOA and EOF, or sets EOA of a file
\li \ref sec_cltools_h5clear — Clears superblock status_flags field, removes metadata cache image, prints EOA and EOF, or sets EOA of a file
\subsubsection subsubsec_swmr_doc_design Design Documents
@ -120,9 +120,9 @@ The following operations are not allowed (and the corresponding HDF5 files will
\li File space recycling is not allowed. As a result the size of a file modified by a SWMR writer may be larger than a file modified by a non-SWMR writer.</p>
\subsection subsec_swmr_tools Tools for Working with SWMR
Two new tools, h5watch and h5clear, are available for use with SWMR. The other HDF5 utilities have also been modified to recognize SWMR
\li The h5watch tool allows a user to monitor the growth of a dataset.
\li The h5clear tool clears the status flags in the superblock of an HDF5 file.
Two new tools, \ref sec_cltools_h5watch and \ref sec_cltools_h5clear, are available for use with SWMR. The other HDF5 utilities have also been modified to recognize SWMR
\li The \ref sec_cltools_h5watch tool allows a user to monitor the growth of a dataset.
\li The \ref sec_cltools_h5clear tool clears the status flags in the superblock of an HDF5 file.
\li The rest of the HDF5 tools will exit gracefully but not work with SWMR otherwise.
\subsection subsec_swmr_example Programming Example
@ -135,12 +135,12 @@ Build the software. No special configuration options are needed to use SWMR.
In the other window go into the test directory of the HDF5-1.10 source code that was just built.
\li In the window in the test directory compile and run use_append_chunk.c. The example writes a three
dimensional dataset by planes (with chunks of size 1 x 256 x 256).
\li In the other window (in the bin directory) run h5watch on the file created by
\li In the other window (in the bin directory) run \ref sec_cltools_h5watch on the file created by
use_append_chunk.c (use_append_chunk.h5). It should be run while use_append_chunk is executing and you
will see valid data displayed with h5watch.
\li Interrupt use_append_chunk while it is running, and stop h5watch.
\li Use h5clear to clear the status flags in the superblock of the HDF5 file (use_append_chunk.h5).
\li View the file with h5dump. You will see that it is a valid file even though the application did not
\li Interrupt use_append_chunk while it is running, and stop \ref sec_cltools_h5watch.
\li Use \ref sec_cltools_h5clear to clear the status flags in the superblock of the HDF5 file (use_append_chunk.h5).
\li View the file with \ref sec_cltools_h5dump. You will see that it is a valid file even though the application did not
close properly. It will contain data up to the point that it was interrupted.
*/

6
doxygen/dox/VDSTechNote.dox
View File

@ -96,9 +96,9 @@ The %b indicates that the block count of the selection in the dimension should b
<h4>C Example</h4>
For details on compiling an HDF5 application: [ Compiling HDF5 Applications ]
Using h5dump with a VDS
The h5dump utility can be used to view a VDS. The h5dump output for a VDS looks exactly like that for any other dataset.
If h5dump cannot find a source dataset then the fill value will be displayed.
Using \ref sec_cltools_h5dump with a VDS
The \ref sec_cltools_h5dump utility can be used to view a VDS. The \ref sec_cltools_h5dump output for a VDS looks exactly like that for any other dataset.
If \ref sec_cltools_h5dump cannot find a source dataset then the fill value will be displayed.
You can determine that a dataset is a VDS by looking at its properties with
\code

91
doxygen/dox/ViewTools.dox
View File

@ -72,85 +72,85 @@ does not cover all of the HDF5 tools.
<tr>
<td><strong>@ref ViewToolsView</strong></td>
<td>@ref secViewToolsViewContent</td>
<td>h5dump and h5ls
<td>\ref sec_cltools_h5dump and \ref sec_cltools_h5ls
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsViewDset</td>
<td>h5dump and h5ls
<td>\ref sec_cltools_h5dump and \ref sec_cltools_h5ls
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsViewGrps</td>
<td>h5dump and h5ls
<td>\ref sec_cltools_h5dump and \ref sec_cltools_h5ls
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsViewAttr</td>
<td>h5dump
<td>\ref sec_cltools_h5dump
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsViewSub</td>
<td>h5dump
<td>\ref sec_cltools_h5dump
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsViewDtypes</td>
<td>h5dump
<td>\ref sec_cltools_h5dump
</td>
</tr>
<tr>
<td>@ref ViewToolsEdit</td>
<td>@ref secViewToolsEditRemove</td>
<td>h5repack
<td>\ref sec_cltools_h5repack
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsEditChange</td>
<td>h5repack
<td>\ref sec_cltools_h5repack
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsEditApply</td>
<td>h5repack
<td>\ref sec_cltools_h5repack
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsEditCopy</td>
<td>h5copy
<td>\ref sec_cltools_h5copy
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsEditAdd</td>
<td>h5jam and h5unjam
<td>\ref sec_cltools_h5jam and \ref sec_cltools_h5unjam
</td>
</tr>
<tr>
<td>@ref ViewToolsConvert</td>
<td>@ref secViewToolsConvertASCII</td>
<td>h5dump
<td>\ref sec_cltools_h5dump
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsConvertBinary</a></td>
<td>h5dump
<td>\ref sec_cltools_h5dump
</td>
</tr>
<tr>
<td></td>
<td>@ref secViewToolsConvertExport</td>
<td>h5dump and h5import
<td>\ref sec_cltools_h5dump and \ref sec_cltools_h5import
</td>
</tr>
</table>
@ -173,22 +173,22 @@ Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
</ul>
\section secViewToolsViewContent File Content and Structure
The h5dump and h5ls tools can both be used to view the contents of an HDF5 file. The tools are discussed below:
The \ref sec_cltools_h5dump and \ref sec_cltools_h5ls tools can both be used to view the contents of an HDF5 file. The tools are discussed below:
<ul>
<li>\ref subsecViewToolsViewContent_h5dump</li>
<li>\ref subsecViewToolsViewContent_h5ls</li>
</ul>
\subsection subsecViewToolsViewContent_h5dump h5dump
The h5dump tool dumps or displays the contents of an HDF5 file (textually). By default if you specify no options,
h5dump will display the entire contents of a file. There are many h5dump options for examining specific details
of a file. To see all of the available h5dump options, specify the <code style="background-color:whitesmoke;">-h</code>
The \ref sec_cltools_h5dump tool dumps or displays the contents of an HDF5 file (textually). By default if you specify no options,
\ref sec_cltools_h5dump will display the entire contents of a file. There are many \ref sec_cltools_h5dump options for examining specific details
of a file. To see all of the available \ref sec_cltools_h5dump options, specify the <code style="background-color:whitesmoke;">-h</code>
or <code style="background-color:whitesmoke;">--help</code> option:
\code
h5dump -h
\endcode
The following h5dump options can be helpful in viewing the content and structure of a file:
The following \ref sec_cltools_h5dump options can be helpful in viewing the content and structure of a file:
<table>
<tr>
<th>Option</th>
@ -306,8 +306,8 @@ GROUP "/" {
\see H5TOOL_DP_UG for more information.
\subsection subsecViewToolsViewContent_h5ls h5ls
The h5ls tool by default just displays the objects in the root group. It will not display
items in groups beneath the root group unless specified. Useful h5ls options for viewing
The \ref sec_cltools_h5ls tool by default just displays the objects in the root group. It will not display
items in groups beneath the root group unless specified. Useful \ref sec_cltools_h5ls options for viewing
file content and structure are:
<table>
<tr>
@ -335,7 +335,8 @@ and attribute values, but no dataset values)
</table>
\subsubsection subsubsecViewToolsViewContent_h5lsEx3 Example 3
The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar to h5dump, except that h5ls also shows dataspace information for each dataset:
The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar
to \ref sec_cltools_h5dump, except that \ref sec_cltools_h5ls also shows dataspace information for each dataset:
\code
h5ls -r OMI-Aura.he5
\endcode
@ -360,14 +361,14 @@ The output is shown below:
\see H5TOOL_LS_UG for more information.
\section secViewToolsViewDset Datasets and Dataset Properties
Both h5dump and h5ls can be used to view specific datasets.
Both \ref sec_cltools_h5dump and h5ls can be used to view specific datasets.
<ul>
<li>\ref subsecViewToolsViewDset_h5dump</li>
<li>\ref subsecViewToolsViewDset_h5ls</li>
</ul>
\subsection subsecViewToolsViewDset_h5dump h5dump
Useful h5dump options for examining specific datasets include:
Useful \ref sec_cltools_h5dump options for examining specific datasets include:
<table>
<tr>
<th>Option</th>
@ -417,10 +418,10 @@ Useful h5dump options for examining specific datasets include:
</table>
\subsubsection subsubsecViewToolsViewDset_h5dumpEx4 Example 4
A specific dataset can be viewed with <code style="background-color:whitesmoke;">h5dump</code> using the <code style="background-color:whitesmoke;">-d D</code> option and specifying the entire
A specific dataset can be viewed with <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> using the <code style="background-color:whitesmoke;">-d D</code> option and specifying the entire
path and name of the dataset for <code style="background-color:whitesmoke;">D</code>. The path is important in identifying the correct dataset,
as there can be multiple datasets with the same name. The path can be determined by looking at
the objects in the file with <code style="background-color:whitesmoke;">h5dump -n</code>.
the objects in the file with <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump -n</code>.
The following example uses the <code style="background-color:whitesmoke;">groups.h5</code> file that is created by the
\ref LBExamples
@ -489,7 +490,7 @@ You can obtain the <code style="background-color:whitesmoke;">h5ex_d_gzip.c</cod
from the \ref ExAPI page.
\subsection subsecViewToolsViewDset_h5ls h5ls
Specific datasets can be specified with <code style="background-color:whitesmoke;">h5ls</code> by simply adding the dataset path and dataset after the
Specific datasets can be specified with <code style="background-color:whitesmoke;">\ref sec_cltools_h5ls</code> by simply adding the dataset path and dataset after the
file name. As an example, this command displays dataset <code style="background-color:whitesmoke;">dset2</code> in the <code style="background-color:whitesmoke;">groups.h5</code>
file used in @ref subsubsecViewToolsViewDset_h5dumpEx4 :
\code
@ -542,14 +543,14 @@ The output of using <code style="background-color:whitesmoke;">-d</code> is show
\endcode
\section secViewToolsViewGrps Groups
Both h5dump and h5ls can be used to view specific groups in a file.
Both \ref sec_cltools_h5dump and \ref sec_cltools_h5ls can be used to view specific groups in a file.
<ul>
<li>\ref subsecViewToolsViewGrps_h5dump</li>
<li>\ref subsecViewToolsViewGrps_h5ls</li>
</ul>
\subsection subsecViewToolsViewGrps_h5dump h5dump
The <code style="background-color:whitesmoke;">h5dump</code> options that are useful for examining groups are:
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> options that are useful for examining groups are:
<table>
<tr>
<th>Option</th>
@ -615,8 +616,8 @@ The <code style="background-color:whitesmoke;">-A 0</code> option suppresses att
\endcode
\subsection subsecViewToolsViewGrps_h5ls h5ls
You can view the contents of a group with <code style="background-color:whitesmoke;">h5ls</code>/ by specifying the group after the file name.
To use <code style="background-color:whitesmoke;">h5ls</code> to view the contents of the <code style="background-color:whitesmoke;">/HDFEOS</code> group in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
You can view the contents of a group with <code style="background-color:whitesmoke;">\ref sec_cltools_h5ls</code>/ by specifying the group after the file name.
To use <code style="background-color:whitesmoke;">\ref sec_cltools_h5ls</code> to view the contents of the <code style="background-color:whitesmoke;">/HDFEOS</code> group in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
\code
h5ls -r OMI-Aura.he5/HDFEOS
\endcode
@ -639,9 +640,9 @@ If you specify the <code style="background-color:whitesmoke;">-v</code> option,
\section secViewToolsViewAttr Attributes
\subsection subsecViewToolsViewAttr_h5dump h5dump
Attributes are displayed by default if using <code style="background-color:whitesmoke;">h5dump</code>. Some files contain many attributes, which
Attributes are displayed by default if using <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>. Some files contain many attributes, which
can make it difficult to examine the objects in the file. Shown below are options that can help
when using <code style="background-color:whitesmoke;">h5dump</code> to work with files that have attributes.
when using <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> to work with files that have attributes.
\subsubsection subsubsecViewToolsViewAttr_h5dumpEx6 Example 6
The <code style="background-color:whitesmoke;">-a</code> A option will display an attribute. However, the path to the attribute must be included
@ -746,7 +747,7 @@ specified file, dataset or group. You cannot display individual attributes.
\subsection subsecViewToolsViewSub_h5dump h5dump
If you have a very large dataset, you may wish to subset or see just a portion of the dataset.
This can be done with the following <code style="background-color:whitesmoke;">h5dump</code> options.
This can be done with the following <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> options.
<table>
<tr>
<th>Option</th>
@ -792,7 +793,7 @@ define the shape and size of the selection. They are arrays with the same number
of the dataset's dataspace, and they all work together to define the selection. A change to one of
these arrays can affect the others.
When specifying these h5dump options, a comma is used as the delimiter for each dimension in the
When specifying these \ref sec_cltools_h5dump options, a comma is used as the delimiter for each dimension in the
option value. For example, with a 2-dimensional dataset, the option value is specified as "H,W",
where H is the height and W is the width. If the offset is 0 for both dimensions, then
<code style="background-color:whitesmoke;">START</code> would be specified as follows:
@ -913,7 +914,7 @@ The output of the above command is shown below:
\section secViewToolsViewDtypes Datatypes
\subsection subsecViewToolsViewDtypes_h5dump h5dump
The following datatypes are discussed, using the output of <code style="background-color:whitesmoke;">h5dump</code> with HDF5 files from the
The following datatypes are discussed, using the output of <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> with HDF5 files from the
\ref ExAPI page:
<ul>
<li>@ref subsubsecViewToolsViewDtypes_array</li>
@ -1027,13 +1028,13 @@ GROUP "/" {
\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference
A Region Reference is a reference to a selection within a dataset. A selection can be either
individual elements or a hyperslab. In <code style="background-color:whitesmoke;">h5dump</code> you will see the name of the dataset along with
individual elements or a hyperslab. In <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> you will see the name of the dataset along with
the elements or slab that is selected. A dataset with a Region Reference datatype consists of
one or more Region References.
An example of a Region Reference dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.h5</code>) can be found on the
\ref ExAPI page,
under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a
under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a
Region Reference dataset as indicated by its datatype, highlighted in bold below:
\code
$ h5dump h5ex_t_regref.h5
@ -1113,7 +1114,7 @@ These start, stride, count, and block values will select the elements shown in b
116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0
\endcode
If you use <code style="background-color:whitesmoke;">h5dump</code> to select a subset of dataset
If you use <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> to select a subset of dataset
<code style="background-color:whitesmoke;">/DS2</code> with these start, stride, count, and block values, you will see that the same elements are selected:
\code
$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5
@ -1143,7 +1144,7 @@ NOTE that you must release the references created in the code with the #H5Rdestr
For more information on selections, see the tutorial topic on
@ref LBDsetSubRW. Also see the
\ref secViewToolsViewSub tutorial topic on using <code style="background-color:whitesmoke;">h5dump</code> to view a subset.
\ref secViewToolsViewSub tutorial topic on using <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> to view a subset.
\subsubsection subsubsecViewToolsViewDtypes_depr_objref Deprecated Object Reference
An Object Reference is a reference to an entire object (dataset, group, or named datatype).
@ -1177,13 +1178,13 @@ GROUP "/" {
\subsubsection subsubsecViewToolsViewDtypes_depr_regref Deprecated Region Reference
A Region Reference is a reference to a selection within a dataset. A selection can be either
individual elements or a hyperslab. In <code style="background-color:whitesmoke;">h5dump</code> you will see the name of the dataset along with
individual elements or a hyperslab. In <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> you will see the name of the dataset along with
the elements or slab that is selected. A dataset with a Region Reference datatype consists of
one or more Region References.
An example of a Region Reference dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.h5</code>) can be found on the
\ref ExAPI page,
under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a
under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a
Region Reference dataset as indicated by its datatype, highlighted in bold below:
\code
$ h5dump h5ex_t_regref.h5
@ -1254,7 +1255,7 @@ These start, stride, count, and block values will select the elements shown in b
116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0
\endcode
If you use <code style="background-color:whitesmoke;">h5dump</code> to select a subset of dataset
If you use <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> to select a subset of dataset
<code style="background-color:whitesmoke;">/DS2</code> with these start, stride, count, and block values, you will see that the same elements are selected:
\code
$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5
@ -1278,12 +1279,12 @@ DATASET "/DS2" {
For more information on selections, see the tutorial topic on
@ref LBDsetSubRW. Also see the
\ref secViewToolsViewSub tutorial topic on using <code style="background-color:whitesmoke;">h5dump</code> to view a subset.
\ref secViewToolsViewSub tutorial topic on using <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> to view a subset.
\subsubsection subsubsecViewToolsViewDtypes_string String
There are two types of string data, fixed length strings and variable length strings.
Below is the <code style="background-color:whitesmoke;">h5dump</code> output for two files that have the same strings written to them. In one file,
Below is the <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> output for two files that have the same strings written to them. In one file,
the strings are fixed in length, and in the other, the strings have different sizes (and are variable in size).
<em>Dataset of Fixed Length Strings</em>

78
doxygen/dox/ViewTools2.dox
View File

@ -15,20 +15,20 @@ Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
HDF5 files may accumulate unused space when they are read and rewritten to or if objects are deleted within
them. With many edits and deletions this unused space can add up to a sizable amount.
The <code style="background-color:whitesmoke;">h5repack</code> tool can be used to remove unused space in an HDF5
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code> tool can be used to remove unused space in an HDF5
file. If no options other than the input and output HDF5 files are specified on the
<code style="background-color:whitesmoke;">h5repack</code> command line, it will write the file to the new
<code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code> command line, it will write the file to the new
file, getting rid of the unused space:
\code
h5repack <input file> <output file>
\endcode
\section secViewToolsEditChange Change a Dataset's Storage Layout
The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to change a dataset's storage
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code> utility can be used to change a dataset's storage
layout. By default, the storage layout of a dataset is defined at creation time and it cannot be changed.
However, with h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file.
However, with \ref sec_cltools_h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file.
The <code style="background-color:whitesmoke;">-l</code> option in <code style="background-color:whitesmoke;">h5repack</code>
The <code style="background-color:whitesmoke;">-l</code> option in <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code>
is used to change the layout for an object. The string following the <code style="background-color:whitesmoke;">-l</code>
option defines the layout type and parameters for specified objects (or all objects):
\code
@ -40,11 +40,11 @@ layout type and parameters. If objects are specified then everything in the inpu
output file as is, except for those specified objects. They will be written to the output file with the given
layout type and parameters.
Following is a description of the dataset layouts and the <code style="background-color:whitesmoke;">h5repack</code>
Following is a description of the dataset layouts and the <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code>
options to use to change a dataset:
<table>
<tr>
<th>Storage Layout</th><th>h5repack Option</th><th>Description</th>
<th>Storage Layout</th><th>@ref sec_cltools_h5repack Option</th><th>Description</th>
</tr>
<tr>
<td>Contiguous
@ -76,10 +76,10 @@ If you type <code style="background-color:whitesmoke;">h5repack -h</code> on the
a detailed usage statement with examples of modifying the layout.
In the following example, the dataset <code style="background-color:whitesmoke;">/dset</code> in the file
dset.h5 is contiguous, as shown by the <code style="background-color:whitesmoke;">h5dump -pH</code> command.
The <code style="background-color:whitesmoke;">h5repack</code> utility writes dset.h5 to a new file, dsetrpk.h5,
dset.h5 is contiguous, as shown by the <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump -pH</code> command.
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code> utility writes dset.h5 to a new file, dsetrpk.h5,
where the dataset <code style="background-color:whitesmoke;">dset</code> is chunked. This can be seen by examining
the resulting dsetrpk.h5 file with <code style="background-color:whitesmoke;">h5dump</code>, as shown:
the resulting dsetrpk.h5 file with <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>, as shown:
\code
$ h5dump -pH dset.h5
HDF5 "dset.h5" {
@ -137,9 +137,9 @@ There can be many reasons that the storage layout needs to be changed for a data
there may be a performance issue with a dataset due to a small chunk size.
\section secViewToolsEditApply Apply Compression Filter to a Dataset
The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to compress or
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code> utility can be used to compress or
remove compression from a dataset in a file. By default, compression cannot be added to or removed
from a dataset once it has been created. However, with <code style="background-color:whitesmoke;">h5repack</code>
from a dataset once it has been created. However, with <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code>
you can write a file to a new file and specify a compression filter to apply to a dataset or datasets in the new file.
To apply a filter to an object in an HDF5 file, specify the <code style="background-color:whitesmoke;">-f</code> option,
@ -205,13 +205,13 @@ numerous filters that you can apply to a dataset:
</table>
Be aware that a dataset must be chunked to apply compression to it. If the dataset is not already chunked,
then <code style="background-color:whitesmoke;">h5repack</code> will apply chunking to it. Both chunking
and compression cannot be applied to a dataset at the same time with <code style="background-color:whitesmoke;">h5repack</code>.
then <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code> will apply chunking to it. Both chunking
and compression cannot be applied to a dataset at the same time with <code style="background-color:whitesmoke;">\ref sec_cltools_h5repack</code>.
In the following example,
\li <em>h5dump</em> lists the properties for the objects in <em>dset.h5</em>. Note that the dataset <em>dset</em> is contiguous.
\li <em>h5repack</em> writes dset.h5 into a new file <em>dsetrpk.h5</em>, applying GZIP Level 5 compression to the dataset <em>/dset</em> in dsetrpk.h5.
\li <em>h5dump</em> lists the properties for the new <em>dsetrpk.h5</em> file. Note that <em>/dset</em> is both compressed and chunked.
\li <em>\ref sec_cltools_h5dump</em> lists the properties for the objects in <em>dset.h5</em>. Note that the dataset <em>dset</em> is contiguous.
\li <em>\ref sec_cltools_h5repack</em> writes dset.h5 into a new file <em>dsetrpk.h5</em>, applying GZIP Level 5 compression to the dataset <em>/dset</em> in dsetrpk.h5.
\li <em>\ref sec_cltools_h5dump</em> lists the properties for the new <em>dsetrpk.h5</em> file. Note that <em>/dset</em> is both compressed and chunked.
<em>Example</em>
\code
@ -268,11 +268,11 @@ GROUP "/" {
\endcode
\section secViewToolsEditCopy Copy Objects to Another File
The <code style="background-color:whitesmoke;">h5copy</code> utility can be used to copy an object or
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5copy</code> utility can be used to copy an object or
objects from one HDF5 file to another or to a different location in the same file. It uses the
#H5Ocopy and #H5Lcopy APIs in HDF5.
Following are some of the options that can be used with <code style="background-color:whitesmoke;">h5copy</code>.
Following are some of the options that can be used with <code style="background-color:whitesmoke;">\ref sec_cltools_h5copy</code>.
<table>
<tr>
<th>h5copy Options</th><th>Description</th>
@ -321,7 +321,7 @@ Following are some of the options that can be used with <code style="background-
</tr>
</table>
For a complete list of options and information on using <code style="background-color:whitesmoke;">h5copy</code>, type:
For a complete list of options and information on using <code style="background-color:whitesmoke;">\ref sec_cltools_h5copy</code>, type:
\code
h5copy --help
\endcode
@ -365,7 +365,7 @@ GROUP "/" {
}
\endcode
There are also <code style="background-color:whitesmoke;">h5copy</code> flags that can be specified
There are also <code style="background-color:whitesmoke;">\ref sec_cltools_h5copy</code> flags that can be specified
with the <code style="background-color:whitesmoke;">-f</code> option. In the example below, the
<code style="background-color:whitesmoke;">-f shallow</code> option specifies to copy only the
immediate members of the group <code style="background-color:whitesmoke;">/MyGroup</code> from
@ -404,23 +404,23 @@ list that can be added when creating a file. See the #H5Pset_userblock API in th
information regarding this property.
Once created in a file, the user block cannot be removed. However, you can use the
<code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code>
<code style="background-color:whitesmoke;">\ref sec_cltools_h5jam</code> and <code style="background-color:whitesmoke;">\ref sec_cltools_h5unjam</code>
utilities to add or remove a user block from a file into a new file.
These two utilities work similarly, except that <code style="background-color:whitesmoke;">h5jam</code>
adds a user block to a file and <code style="background-color:whitesmoke;">h5unjam</code> removes the user
These two utilities work similarly, except that <code style="background-color:whitesmoke;">\ref sec_cltools_h5jam</code>
adds a user block to a file and <code style="background-color:whitesmoke;">\ref sec_cltools_h5unjam</code> removes the user
block. You can also overwrite or delete a user block in a file.
Specify the <code style="background-color:whitesmoke;">-h</code> option to see a complete list of options
that can be used with <code style="background-color:whitesmoke;">h5jam</code> and
<code style="background-color:whitesmoke;">h5unjam</code>. For example:
that can be used with <code style="background-color:whitesmoke;">\ref sec_cltools_h5jam</code> and
<code style="background-color:whitesmoke;">\ref sec_cltools_h5unjam</code>. For example:
\code
h5jam -h
h5unjam -h
\endcode
Below are the basic options for adding or removing a user block with <code style="background-color:whitesmoke;">h5jam</code>
and <code style="background-color:whitesmoke;">h5unjam</code>:
Below are the basic options for adding or removing a user block with <code style="background-color:whitesmoke;">\ref sec_cltools_h5jam</code>
and <code style="background-color:whitesmoke;">\ref sec_cltools_h5unjam</code>:
<table>
<tr>
@ -450,7 +450,7 @@ Let's say you wanted to add the program that creates an HDF5 file to its user bl
can take the <code style="background-color:whitesmoke;">h5_crtgrpar.c</code> program from the
\ref LBExamples
and add it to the file it creates, <code style="background-color:whitesmoke;">groups.h5</code>. This can
be done with <code style="background-color:whitesmoke;">h5jam</code>, as follows:
be done with <code style="background-color:whitesmoke;">\ref sec_cltools_h5jam</code>, as follows:
\code
h5jam -i groups.h5 -u h5_crtgrpar.c -o groupsub.h5
\endcode
@ -484,7 +484,7 @@ Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
</ul>
\section secViewToolsConvertASCII Output HDF5 Dataset into an ASCII File (to Import into Excel and Other Applications)
The <code style="background-color:whitesmoke;">h5dump</code> utility can be used to convert an HDF5 dataset
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> utility can be used to convert an HDF5 dataset
into an ASCII file, which can then be imported into Excel and other applications. The following options are used:
<table>
<tr>
@ -521,7 +521,7 @@ As an example, <code style="background-color:whitesmoke;">h5_crtdat.c</code> fro
HDF5 Tutorial topic, creates the file <code style="background-color:whitesmoke;">dset.h5</code> with
a dataset <code style="background-color:whitesmoke;">/dset</code> that is a 4 x 6 integer array. The
following is displayed when viewing <code style="background-color:whitesmoke;">dset.h5</code> with
<code style="background-color:whitesmoke;">h5dump</code>:
<code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>:
\code
$ h5dump dset.h5
HDF5 "dset.h5" {
@ -547,10 +547,10 @@ h5dump -d /dset -o dset.asci -y -w 50 dset.h5
\endcode
In particular, note that:
\li The default behavior of <code style="background-color:whitesmoke;">h5dump</code> is to print indices,
\li The default behavior of <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> is to print indices,
and the <code style="background-color:whitesmoke;">-y</code> option suppresses this.
\li The <code style="background-color:whitesmoke;">-w 50</code> option tells
<code style="background-color:whitesmoke;">h5dump</code> to allow 50 columns for outputting the data. The
<code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> to allow 50 columns for outputting the data. The
value specified must be large enough to accommodate the dimension size of the dataset multiplied by the
number of positions and spaces needed to print each value. If the value is not large enough, the output
will wrap to the next line, and the data will not display as expected in Excel or other applications. To
@ -579,7 +579,7 @@ The <code style="background-color:whitesmoke;">dset.asci</code> file will contai
\endcode
\section secViewToolsConvertBinary Output HDF5 Dataset into Binary File
The <code style="background-color:whitesmoke;">h5dump</code> utility can be used to convert an
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> utility can be used to convert an
HDF5 dataset to a binary file with the following options:
<table>
<tr>
@ -610,7 +610,7 @@ As an example, <code style="background-color:whitesmoke;">h5_crtdat.c</code> fro
\ref LBDsetCreate HDF5 Tutorial topic, creates the file dset.h5 with a dataset
<code style="background-color:whitesmoke;">/dset</code> that is a 4 x 6 integer array. The
following is displayed when viewing <code style="background-color:whitesmoke;">dset.h5</code>
with <code style="background-color:whitesmoke;">h5dump</code>:
with <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>:
\code
$ h5dump -d /dset/ dset.h5
HDF5 "dset.h5" {
@ -629,7 +629,7 @@ DATASET "/dset/" {
As specified by the <code style="background-color:whitesmoke;">-d</code> and
<code style="background-color:whitesmoke;">-o</code> options, the following
<code style="background-color:whitesmoke;">h5dump</code> command will output the values of the dataset
<code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> command will output the values of the dataset
<code style="background-color:whitesmoke;">/dset </code>to a file called
<code style="background-color:whitesmoke;">dset.bin</code>. The <code style="background-color:whitesmoke;">-b</code>
option specifies that the output will be binary in Little Endian format (LE).
@ -665,10 +665,10 @@ $ od -t d dset.bin
\endcode
\section secViewToolsConvertExport Export from h5dump and Import into HDF5
The <code style="background-color:whitesmoke;">h5import</code> utility can use the output of
<code style="background-color:whitesmoke;">h5dump</code> as input to create a dataset or file.
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5import</code> utility can use the output of
<code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> as input to create a dataset or file.
The <code style="background-color:whitesmoke;">h5dump</code> utility must first create two files:
The <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> utility must first create two files:
\li A DDL file, which will be used as an <code style="background-color:whitesmoke;">h5import</code> configuration file
\li A raw data file containing the data to be imported

20
doxygen/dox/ViewToolsJPSS.dox
View File

@ -44,7 +44,7 @@ with references to selected regions in datasets under <code style="background-co
</table>
\subsection subsecViewToolsJPSSDeter_h5dump h5dump
With <code style="background-color:whitesmoke;">h5dump</code> you can see a list of the objects
With <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code> you can see a list of the objects
in the file using the <code style="background-color:whitesmoke;">-n</code> option:
\code
h5dump -n <file>
@ -90,9 +90,9 @@ In the output above you can see that there are four granules (ending in
<code style="background-color:whitesmoke;">/Data_Products/VIIRS-M9-SDR/</code> group.
\subsection subsecViewToolsJPSSDeter_h5ls h5ls
With <code style="background-color:whitesmoke;">h5ls</code> you can see a list of the objects in the
With <code style="background-color:whitesmoke;">\ref sec_cltools_h5ls</code> you can see a list of the objects in the
file using the <code style="background-color:whitesmoke;">-lr</code>
options. The <code style="background-color:whitesmoke;">h5ls</code> utility also shows shape and size
options. The <code style="background-color:whitesmoke;">\ref sec_cltools_h5ls</code> utility also shows shape and size
(dataspace) information about datasets.
\code
h5ls -lr <file>
@ -166,13 +166,13 @@ that can help with this:
<th>Utility</th><th>Description</th>
</tr>
<tr>
<td>h5unjam
<td>@ref sec_cltools_h5unjam
</td>
<td>Extracts a user block from an HDF5 file
</td>
</tr>
<tr>
<td>h5dump
<td>@ref sec_cltools_h5dump
</td>
<td>The -B (--superblock) option displays the size of the user block in an HDF5 file
</td>
@ -181,7 +181,7 @@ that can help with this:
\subsection subsecViewToolsJPSSView_h5unjam h5unjam
The \ref secViewToolsEditAdd tutorial topic discusses the use of the
<code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code>
<code style="background-color:whitesmoke;">\ref sec_cltools_h5jam</code> and <code style="background-color:whitesmoke;">\ref sec_cltools_h5unjam</code>
utilities for adding or removing a user block from a file. An input HDF5 file
(<code style="background-color:whitesmoke;">-i</code>), output HDF5 file
(<code style="background-color:whitesmoke;">-o</code>), and user block text file
@ -202,7 +202,7 @@ The <code style="background-color:whitesmoke;">UB.xml</code> file contains the u
which can be viewed with a browser.
\subsection subsecViewToolsJPSSView_h5dump h5dump
The h5dump utility has the <code style="background-color:whitesmoke;">-B (--superblock)</code> option for displaying the superblock in an HDF5 file.
The \ref sec_cltools_h5dump utility has the <code style="background-color:whitesmoke;">-B (--superblock)</code> option for displaying the superblock in an HDF5 file.
The superblock contains information about the file such as the file signature, file consistency flags,
the number of bytes to store addresses and size of an object, as well as the size of the user block:
\code
@ -249,7 +249,7 @@ There are Unix tools for Windows that may work, such as <a href="http://gnuwin32
</ul>
\subsection subsecViewToolsJPSSExam_h5dump h5dump
There are several options that you may first want to use when examining a granule with h5dump:
There are several options that you may first want to use when examining a granule with \ref sec_cltools_h5dump
<table>
<tr>
<th>Option</th><th>Description</th>
@ -506,7 +506,7 @@ DATASET "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" {
\endcode
\subsubsection subsubsecViewToolsJPSSExam_h5dumpQuality Viewing a Quality Flag
The quality flags in an NPP file can be viewed with h5dump using the <code style="background-color:whitesmoke;">-M</code>
The quality flags in an NPP file can be viewed with \ref sec_cltools_h5dump using the <code style="background-color:whitesmoke;">-M</code>
option. Quality flags are packed into each integer value in a quality flag dataset. Quality flag datasets in NPP
files begin with the letters <code style="background-color:whitesmoke;">QF</code>.
@ -596,7 +596,7 @@ h5dump -d DATASET -M 0,2,2,2 FILE
\endcode
\subsubsection subsubsecViewToolsJPSSExam_h5dumpProps Properties
To view properties of a specific dataset with <code style="background-color:whitesmoke;">h5dump</code>
To view properties of a specific dataset with <code style="background-color:whitesmoke;">\ref sec_cltools_h5dump</code>
use the <code style="background-color:whitesmoke;">-p</code> option along with the
<code style="background-color:whitesmoke;">-d</code> option. Depending on the number of attributes
and the amount of data, the <code style="background-color:whitesmoke;">-A 0</code> and

385
doxygen/dox/hdf5_1_10.dox Normal file
View File

@ -0,0 +1,385 @@
/** \page rel_spec_110 Release Specific Information for HDF5 1.10
\section sec_rel_spec_110_migrate Migrating from HDF5 1.8 to HDF5 1.10
The HDF Group will drop support for HDF5 1.8.\* releases in the summer of 2020. We strongly recommend
that our users start migrating their applications as soon as possible and we ask that any problems that
are encountered be reported to The HDF Group. Problems can be reported by sending email to help@hdfgroup.org,
submitting a request to the The HDF Group&rsquo;s Help Desk at <a href="mailto:help@hdfgroup.org">HDF Help Desk</a>,
or posting to the <a href="https://forum.hdfgroup.org/">HDF Forum</a>.
Please follow these steps for moving your HDF5 application to HDF5 1.10:
<ol>
<li>Make sure the latest (1.1.0.5+) version of HDF5 1.10 is installed on your system. You can
download the HDF5 1.10 release source code or pre-built binaries from The HDF Group,
<a href="https://support.hdfgroup.org/archive/support/ftp/HDF5/releases/index.html">Archive Releases</a>
and follow the included installation instructions.</li>
<li>If on Unix, you can recompile and relink your application with HDF5 1.10, by using the h5cc
script with any compiler flags needed for your application. The h5cc script can be found under
the bin sub-directory of the HDF5 1.10 installation point. In cases where your software package
has a more complex build system and dependencies, just make sure you point to the new
HDF5 1.10.* library when rebuilding your software.</li>
<li>If your application or software package has any regression test suite, run it and make
sure that all tests pass.</li>
<li>Please contact us if you find any problems.</li>
</ol>
If you have concerns about the files created by the rebuilt application (or software package), you may wish to consider several verification steps to assure that the files can be read by applications built with HDF5 1.8 releases.
<ol>
<li>Use the tools you regularly work with to open, browse, and modify the files created by the
rebuilt application (for example, HDFView, MATLAB, IDL, etc.).</li>
<li>If you have an HDF5 1.8.* installation on your system, use \ref sec_cltools_h5dump from that installation to
read files created by the rebuilt application. If you encounter any errors, please rerun
\ref sec_cltools_h5dump with the <code>--enable-error-stack</code> flag and report the issue.</li>
<li>If you have files created by your application that were built with HDF5 1.8, use \ref sec_cltools_h5diff
from the HDF5 1.8 installation to compare with the files created by the rebuilt application.</li>
</ol>
If you want to learn more, please see the frequently asked questions (FAQ) below.
\subsection subsec_rel_spec_110_migrate_faq FAQ
\subsubsection subsubsec_rel_spec_110_migrate_faq_1 What is the difference between the HDF5 1.8 and HDF5 1.10 releases ?
Many new features (e.g., SWMR, VDS, paged allocation, etc.) that required extensions to the HDF5 file format were added to HDF5 1.10.0.
For more information please see the Release Specific Information pages.
\subsubsection subsubsec_rel_spec_110_migrate_faq_2 Why one should (or should not) move an application to HDF5 1.10 ?
HDF5 1.8 will not be supported after the May 2020 release, i.e., there will be no more public releases
of HDF5 1.8 with security patches, bug fixes, performance improvements and support for OSs and compilers.
In addition, applications originally written for use with HDF5 Release 1.8.x can be linked against the HDF5
Release 1.10.x library, thus taking advantage of performance improvements in 1.10. Users are encouraged to
move to the latest releases of HDF5 1.10 or to HDF5 1.12.0 (coming out in the summer of 2019) if they want
to stay with the current HDF5 upgrades.
If you are not planning to upgrade your system environment, and a version of HDF5 1.8.* works for you,
then there is no reason to upgrade to the latest HDF5. However, if you regularly update your software
to use the latest HDF5 1.8 maintenance release, then you need to plan a transition to HDF5 1.10 after
the HDF5 1.8 May 2020 release.
\subsubsection subsubsec_rel_spec_110_migrate_faq_3 Why do I need to rebuild my application with HDF5 1.10?
The HDF5 1.10.* binaries are not ABI compatible with the HDF5 1.8.* binaries due to changes in the
public header files and APIs. One has to rebuild an application with the HDF5 1.10.* library. The
HDF Group tries hard to maintain ABI compatibility for minor maintenance releases, for example when
moving from 1.8.21 to 1.8.22, or 1.10.5 to 1.10.6, but this is not the case when migrating from
one major release to another, for example, from 1.8.21 to 1.10.5. If you want to learn more about
HDF5 versioning please see HDF5 Library Release Version Numbers.
\subsubsection subsubsec_rel_spec_110_migrate_faq_4 Can I migrate my application if I still use the HDF5 1.6 APIs?
Yes, use the -DH5_USE_16_API compiler flag. For more information see the \ref api-compat-macros.
\subsubsection subsubsec_rel_spec_110_migrate_faq_5 Will my old software read files created by an application rebuilt with HDF5 1.10?
If the application built on HDF5 Release 1.10 avoids use of the new features and does not request
use of the latest format, applications built on HDF5 Release 1.8.x will be able to read files the first application created.
\subsubsection subsubsec_rel_spec_110_migrate_faq_6 Can I use the HDF5 tools I use now to read files created with the new HDF5 1.10 features?
Unfortunately, no. However, we provide a few tools that will help you to “downgrade” the file, so
it can be opened and used with tools and applications built with the 1.8 versions of HDF5.
If your application uses SWMR, then the \ref sec_cltools_h5format_convert tool can be used to “downgrade” the file to
the HDF5 1.8 compatible file format without rewriting raw data.
The \ref sec_cltools_h5repack tool with –l flag can be used to repack VDS source datasets into the HDF5 file using
contiguous, chunked or compact storage. The tool can also be used to rewrite the file using the
HDF5 1.8 format by specifying the <code>--high=H5F_LIBVER_V18</code> flag.
\section sec_rel_spec_110_feat New Features in HDF5 Release 1.10
HDF5 1.10 introduces several new features in the HDF5 library. These new features were added in
the first three releases of HDF5-1.10. For a brief description of each new feature see:
\li \ref subsec_rel_spec_110_feat_new_8
\li \ref subsec_rel_spec_110_feat_new_7
\li \ref subsec_rel_spec_110_feat_new_6
\li \ref subsec_rel_spec_110_feat_new_5
\li \ref subsec_rel_spec_110_feat_new_4
\li \ref subsec_rel_spec_110_feat_new_3
\li \ref subsec_rel_spec_110_feat_new_2
\li \ref subsec_rel_spec_110_feat_new_1
\li \ref subsec_rel_spec_110_feat_new_0
This release includes changes in the HDF5 storage format. For detailed information on the changes,
see: Changes to the File Format Specification
/note
PLEASE NOTE that HDF5-1.8 cannot read files created with the new features described below that are marked with \*.
These changes come into play when one or more of the new features is used or when an application calls for use
of the latest storage format (#H5Pset_libver_bounds). See the \ref_rfc20160105 for more details.
Due to the requirements of some of the new features, the format of a 1.10.x HDF5 file is likely to be different
from that of a 1.8.x HDF5 file. This means that tools and applications built to read 1.10.x files will be able
to read a 1.8.x file, but tools built to read 1.8.x files may not be able to read a 1.10.x file.
If an application built on HDF5 Release 1.10 avoids use of the new features and does not request use of the latest
format, applications built on HDF5 Release 1.8.x will be able to read files the first application created. In
addition, applications originally written for use with HDF5 Release 1.8.x can be linked against a suitably
configured HDF5 Release 1.10.x library, thus taking advantage of performance improvements in 1.10.
\subsection subsec_rel_spec_110_feat_new_8 New Features Introduced in HDF5 1.10.8
The following important new features and changes were introduced in HDF5-1.10.8. For complete details
see the Release Notes and the \ref sec_rel_spec_110_change page.
\subsection subsec_rel_spec_110_feat_new_7 New Features Introduced in HDF5 1.10.7
The following important new features and changes were introduced in HDF5-1.10.7. For complete details
see the Release Notes and the \ref sec_rel_spec_110_change page.
<strong>Addition of AEC (open source SZip) Compression Library</strong>
HDF5 now supports building with the AEC library as a replacement library for SZip.
<strong>Addition of the Splitter and Mirror VFDs</strong>
Two VFDs were added in this release:
\li The Splitter VFD maintains separate R/W and W/O channels for "concurrent" file writes to two files
using a single HDF5 file handle.
\li The Mirror VFD uses TCP/IP sockets to perform write-only (W/O) file I/O on a remote machine.
<strong>Improvements to Performance</strong>
Performance has continued to improve in this release. Please see the images under
Compatibility and Performance Issues on the \ref sec_rel_spec_110_change page.
<strong>Addition of Hyperslab Selection Functions</strong>
Several hyperslab selection routines introduced in HDF5-1.12 were ported to 1.10. See the
\ref sec_rel_spec_110_change page for details.
\subsection subsec_rel_spec_110_feat_new_6 New Features Introduced in HDF5 1.10.6
The following important new features and changes were introduced in HDF5-1.10.6. For complete details
see the Release Notes and the \ref sec_rel_spec_110_change page:
\subsubsection subsubsec_rel_spec_110_feat_new_6_cmake Improvements to the CMake Support
Several improvements were added to the CMake support, including:
\li Support was added for VS 2019 on Windows (with CMake 3.15).
\li Support was added for MinGW using a toolchain file on Linux (C only).
\subsubsection subsubsec_rel_spec_110_feat_new_6_virt Virtual File Drivers - S3 and HDFS
Two Virtual File Drivers (VFDs) have been introduced in 1.10.6:
\li The S3 VFD enables access to an HDF5 file via the Amazon Simple Storage Service (Amazon S3).
\li The HDFS VFD enables access to an HDF5 file with the Hadoop Distributed File System (HDFS).
See the Virtual File Drivers - S3 and HDFS page for more information.
\subsubsection subsubsec_rel_spec_110_feat_new_6_perf Improvement to Performance
Performance was improved when creating a large number of small datasets.
\subsection subsec_rel_spec_110_feat_new_5 New Features Introduced in HDF5 1.10.5
The following important new features were added in HDF5-1.10.5. Please see the release announcement
and \ref sec_rel_spec_110_change page for more details regarding these features:
\subsubsection subsubsec_rel_spec_110_feat_new_5_ohdr Minimized Dataset Object Headers
The ability to minimize dataset object headers was added to reduce the file bloat caused by extra
space in the dataset object header. The file bloat can occur when creating many, very small
datasets. See the Release Notes and \ref_rfc20181231 for more details regarding this issue.
The following APIs were introduced to support this feature:
\li #H5Fget_dset_no_attrs_hint - Retrieves the setting for determining whether the specified
file does or does not create minimized dataset object headers
\li #H5Fset_dset_no_attrs_hint - Sets the flag to create minimized dataset object headers
\li #H5Pget_dset_no_attrs_hint - Retrieves the setting for determining whether the specified
DCPL does or does not create minimized dataset object headers
\li #H5Pset_dset_no_attrs_hint - Sets the flag to create minimized dataset object headers
\subsubsection subsubsec_rel_spec_110_feat_new_5_parchg Parallel Library Change (RFC)
A change was added to the default behavior in parallel when reading the same dataset in its
entirety (i.e. H5S_ALL dataset selection) which is being read by all the processes collectively.
The dataset must be contiguous, less than 2GB, and of an atomic datatype. The new behavior in the
HDF5 library uses an MPI_Bcast to pass the data read from the disk by the root process to the
remaining processes in the MPI communicator associated with the HDF5 file.
A CFD application was used to benchmark CGNS with:
\li compact storage
\li read-proc0-and-bcast
These results were reported by Greg Sjaardema from Sandia National Laboratories.
(image missing)
Series 1 is the read-proc0-and-bcast solution
Series 2 is a single MPI_Bcast
Series 3 uses multiple MPI_Bcast totaling 2 MiB total data 64 bytes at a time (IIRC)
Series 4 is unmodified CGNS develop
Compact is using compact storage
Compact 192 is also using compact storage
Compact 384 is also using compact storage
The last 3 "compact" curves are just three different batch jobs on 192, 384, and 552 nodes
(with 36 core/node). The Series 2 and 3 curves are not related to the CGNS benchmark, but give
a qualitative indication on the scaling behavior of MPI_Bcast. Both read-proc0-and-bcast and
compact storage follow MPI_Bcast's trend, which makes sense since both methods rely on
MPI_Bcast. See \ref_rfc20181220 for better resolution.
\subsubsection subsubsec_rel_spec_110_feat_new_5_mpi OpenMPI Support
Support for OpenMPI was added. For known problems and issues please see OpenMPI Build Issues.
To better support OpenMPI, all MPI-1 API calls were replaced by MPI-2 equivalents.
\subsubsection subsubsec_rel_spec_110_feat_new_5_chunk Chunk Query Functions
New functions were added to find locations, sizes and filters applied to chunks of a dataset.
This functionality is useful for applications that need to read chunks directly from the file,
bypassing the HDF5 library.
\li #H5Dget_chunk_info - Retrieves information about a chunk specified by the chunk index
\li #H5Dget_chunk_info_by_coord - Retrieves information about a chunk specified by its coordinates
\li #H5Dget_num_chunks - Retrieves number of chunks that have nonempty intersection with a specified selection
See \ref_rfc20180620 for more details.
\subsection subsec_rel_spec_110_feat_new_4 New Features Introduced in HDF5 1.10.4
This release was incorrectly developed and should not be used.
\subsection subsec_rel_spec_110_feat_new_3 New Features Introduced in HDF5 1.10.3
This release was incorrectly developed and should not be used.
\subsection subsec_rel_spec_110_feat_new_2 New Features Introduced in HDF5 1.10.2
Several important features and changes were added to HDF5 1.10.2. See the release announcement
and blog for complete details. Following are the major new features:
\subsection subsec_rel_spec_110_feat_new_2_compat Forward Compatibility for HDF5 1.8-based Applications Accessing Files Created by HDF5 1.10.2 ( RFC )
In HDF5 1.8.0, the #H5Pset_libver_bounds function was introduced for specifying the
earliest ("low") and latest ("high") versions of the library to use when writing objects.
With HDF5 1.10.2, new values for "low" and "high" were introduced: #H5F_LIBVER_V18 and #H5F_LIBVER_LATEST is
now mapped to #H5F_LIBVER_V110. See the #H5Pset_libver_bounds function for details.
\subsubsection subsubsec_rel_spec_110_feat_new_2_perf Performance Optimizations for HDF5 Parallel Applications
Optimizations were introduced to parallel HDF5 for improving the performance of open,
close and flush operations at scale.
\subsubsection subsubsec_rel_spec_110_feat_new_2_comp Using Compression with HDF5 Parallel Applications
HDF5 parallel applications can now write data using compression (and other filters
such as the Fletcher32 checksum filter).
\subsection subsec_rel_spec_110_feat_new_1 New Features Introduced in HDF5 1.10.1
\subsubsection subsubsec_rel_spec_110_feat_new_1_cache Metadata Cache Image -> Fine-tuning the Metadata Cache *
HDF5 metadata is typically small, and scattered throughout the HDF5 file. This can affect
performance, particularly on large HPC systems. The Metadata Cache Image feature can improve
performance by writing the metadata cache in a single block on file close, and then populating
the cache with the contents of this block on file open, thus avoiding the many small I/O
operations that would otherwise be required on file open and close.
See \ref_rfc20150615 for more details.
\subsubsection subsubsec_rel_spec_110_feat_new_1_evict Metadata Cache Evict on Close -> Fine-tuning the Metadata Cache
The HDF5 library's metadata cache is fairly conservative about holding on to HDF5 object
metadata (object headers, chunk index structures, etc.), which can cause the cache size
to grow, resulting in memory pressure on an application or system. The "evict on close"
property will cause all metadata for an object to be evicted from the cache as long as
metadata is not referenced from any other open object.
\subsubsection subsubsec_rel_spec_110_feat_new_1_pagg Paged Aggregation -> File Space Management *
The current HDF5 file space allocation accumulates small pieces of metadata and raw
data in aggregator blocks which are not page aligned and vary widely in sizes. The
paged aggregation feature was implemented to provide efficient paged access of these
small pieces of metadata and raw data.
See \ref_rfc20120523 and \ref_rfc20121024 for more details.
\subsubsection subsubsec_rel_spec_110_feat_new_1_pbuf Page Buffering
Small and random I/O accesses on parallel file systems result in poor performance
for applications. Page buffering in conjunction with paged aggregation can improve
performance by giving an application control of minimizing HDF5 I/O requests to a
specific granularity and alignment.
See \ref_rfc20150709 for more details.
\subsection subsec_rel_spec_110_feat_new_0 New Features Introduced in HDF5 1.10.0
\subsubsection subsubsec_rel_spec_110_feat_new_0_smr SWMR *
Data acquisition and computer modeling systems often need to analyze and visualize data
while it is being written. It is not unusual, for example, for an application to produce
results in the middle of a run that suggest some basic parameters be changed, sensors be
adjusted, or the run be scrapped entirely.
To enable users to check on such systems, we have been developing a concurrent read/write
file access pattern we call SWMR (pronounced swimmer). SWMR is short for
single-writer/multiple-reader. SWMR functionality allows a writer process to add data
to a file while multiple reader processes read from the file.
\subsubsection subsubsec_rel_spec_110_feat_new_0_tune Fine-tuning the Metadata Cache
The orderly operation of the metadata cache is crucial to SWMR functioning. A number
of APIs have been developed to handle the requests from writer and reader processes
and to give applications the control of the metadata cache they might need. However,
the metadata cache APIs can be used when SWMR is not being used; so, these functions
are described separately.
\subsubsection subsubsec_rel_spec_110_feat_new_0_coll Collective Metadata I/O
Calls for HDF5 metadata can result in many small reads and writes. On metadata reads,
collective metadata I/O can improve performance by allowing the library to perform
optimizations when reading the metadata, by having one rank read the data and broadcasting
it to all other ranks.
Collective metadata I/O improves metadata write performance through the construction
of an MPI derived datatype that is then written collectively in a single call.
\subsubsection subsubsec_rel_spec_110_feat_new_0_fspace File Space Management *
Usage patterns when working with an HDF5 file sometimes result in wasted space within the file
This can also impair access times when working with the resulting files. The new file space
management feature provides strategies for managing space in a file to improve performance
in both of these arenas.
\subsubsection subsubsec_rel_spec_110_feat_new_0_vds Virtual Datasets (VDS) *
With a growing amount of data in HDF5, the need has emerged to access data stored across
multiple HDF5 files using standard HDF5 objects, such as groups and datasets, without rewriting
or rearranging the data. The new virtual dataset (VDS) feature enables an application to draw
on multiple datasets and files to create virtual datasets without moving or rewriting any data.
\subsubsection subsubsec_rel_spec_110_feat_new_0_edge Partial Edge Chunk Options *
New options for the storage and filtering of partial edge chunks in a dataset provide a tool
for tuning I/O speed and file size in cases where the dataset size may not be a multiple of the chunk size.
\subsubsection subsubsec_rel_spec_110_feat_new_0_add Additional New APIs
In addition to the features described above, several additional new functions, a new struct,
and new macros have been introduced or newly versioned in this release.
\subsubsection subsubsec_rel_spec_110_feat_new_0_form Changes to the File Format Specification
The file format of the HDF5 library has been changed to support the new features in HDF5-1.10.
See the \ref FMT11 for complete details on the changes. This specification describes how the bytes in
an HDF5 file are organized on the storage media where the file is kept. In other words, when a file is
written to disk, the file will be written according to the information described in this file. The
following sections have been added or changed:
\li Another version of the superblock was added.
\li Additional B-tree types were added to the version 2 B-trees.
\li The global heap block for virtual datasets was added.
\li The Data Layout Message was changed: the name was changed, and version 4 of the data layout message
was added for the virtual type.
\li Additional types of indexes were added for dataset chunks.
HDF5-1.8 cannot read files created with the new features described on this page that are marked with *.
\subsection subsec_rel_spec_110_feat_add Additional New APIs
This page describes various new functions, a new struct, and new macros that are either unrelated to
new features described elsewhere or have aspects that are unrelated to the feature where they are
otherwise described. The page includes the following sections:
\li Versioned Functions and Struct with Associated Macros<br />
Two functions in the HDF5 C interface, and a struct associated with one of those functions,
have been versioned in this release. At the same time, interface compatibility macros were
created for programmatic management of these functions. See \ref api-compat-macros in HDF5
for a detailed discussion of versioned functions and structs and the related macros.<br />
<ul>
<li>#H5Fget_info - Macro for programmatic control of versioned functions</li>
<li>#H5Fget_info1 Original function</li>
<li>#H5Fget_info2 New version introduced at Release 1.10.0</li>
<li>#H5Rdereference Macro for programmatic control of versioned functions</li>
<li>#H5Rdereference1 Original function</li>
<li>#H5Rdereference2 New version introduced at Release 1.10.0</li>
</ul>
\li Property List Encoding and Decoding Functions<br />
Property List Encoding and Decoding Functions Functions have been added in the HDF5 C interface
to encode and decode property lists.<br />
<ul>
<li>#H5Pencode</li>
<li>#H5Pdecode</li>
</ul>
\li External File Prefix Functions<br />
External File Prefix Functions Datasets that store raw data in external files can be created
in HDF5. Functions have been added in the HDF5 C interface to enable such external files to be
located via a relative path from the directory where the HDF5 file containing such a dataset is located:<br />
<ul>
<li>#H5Pset_efile_prefix</li>
<li>#H5Pget_efile_prefix</li>
</ul>
RFCs for the new features in HDF5-1.10:
\li \ref_rfc20180620
\li \ref_rfc20181231
\li Parallel Library Change (RFC)(https://docs.hdfgroup.org/hdf5/develop/_r_f_c.html)
\li \ref_rfc20181220
\li \ref_rfc20160105
\ref rel_spec_110_change
*/

147
doxygen/dox/hdf5_1_12.dox Normal file
View File

@ -0,0 +1,147 @@
/** \page rel_spec_112 Release Specific Information for HDF5 1.12
\section sec_rel_spec_112_migrate Migrating from HDF5 1.10 to HDF5 1.12
Also see the video presentation:
<a href="https://www.hdfgroup.org/2020/03/moving-applications-from-1-10-to-hdf5-1-12-video-materials">Moving Applications from 1.10 to 1.12</a>
There were many existing functions that were modified in 1.12. Applications created with 1.10 or earlier
that use these functions will encounter errors when compiled with 1.12. This page describes how to
compile 1.10 and earlier applications with 1.12 without modifying an application, and provides details
on the functions that changed for users who wish to update their applications.
\li \ref subsec_rel_spec_112_migrate_compile
\li \ref subsec_rel_spec_112_migrate_func
For further information, see:
\li \ref sec_rel_spec_112_feat
\li \ref sec_rel_spec_112_change
\li \ref api-compat-macros
\subsection subsec_rel_spec_112_migrate_compile Compiling 1.10 and earlier applications with 1.12
Applications that were created with earlier HDF5 releases may not compile with 1.12 by default.
The \ref api-compat-macros allow users to work around this issue. Users can specify a
compatibility macro mapping for the version of HDF5 that an application was built with. For
example, a 1.10 application can be built with 1.12 using either an application or library mapping as follows:
\li To compile an application built with a version of HDF5 that includes deprecated symbols (the default),
make sure to pass <code>-DH5_USE_110_API</code> to the compiler. For example:<br />
<ul><li>Autotools: <code>h5cc -DH5_USE_110_API (C)</code></li>
<li>CMake: <code>cmake -DCMAKE_C_FLAGS="-DH5_USE_110_API"</code> (and likewise for other <code>CMAKE_<LANG>_FLAGS</code>)</li></ul>
\li To build an HDF5 library with the 1.10 APIs specify:<br />
<ul><li>Autotools: <code>--with-default-api-version=v110</code><br />
execute: <code>./configure --with-default-api-version=v110</code></li>
<li>CMake: <code>-DDEFAULT_API_VERSION:STRING=v110</code><br />
If using the source code packaged with CMake configuration files (CMake-hdf5-1.12.0*), edit HDF5options.cmake, and add this line:<br />
<code>set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DDEFAULT_API_VERSION:STRING=v110")</code></li></ul>
View the libhdf5.settings file to verify that the library was built with the 1.10 APIs:
\li <code>Default API mapping: v110</code> (under Features:)
\note However, users will not be able to take advantage of some of the new features in 1.12 if using these compatibility mappings.
\subsection subsec_rel_spec_112_migrate_func Functions that changed
Functions were modified in HDF5 version 1.12 to support a token type used in the
Virtual Object Layer (VOL) and to enable 64-bit selection encodings. These changes
are described below.
\remark
\li The updated versions of the functions have a number (for eg '2' or '3') at the end of the original function name.
\li The original versions of these functions were retained and renamed to have an earlier number (for eg '1')
at the end of the original function name.
\li A macro was created with the name of the original function.
\li Please read \ref api-compat-macros for more details on how the function names changed in version 1.12.
\subsection subsec_rel_spec_112_migrate_token Token Type
In HDF5 1.12, a token type, #H5O_token_t, replaced the address type, haddr_t, for representing locations
in an HDF5 file. This change better supports the Virtual Object Layer (VOL), as the concept of an "address"
does not make sense for many connectors. A token type is a more generic type that can function as both a
connector and address location.
This change affected the following functions:
| Original Function in 1.10/Macro in 1.12 (H5xxx) | Deprecated Function in 1.12 (H5xxx1) | New Function (using token type)<br>(H5xxx2 or H5xxx3 |
| ----------------------------------------------- | ------------------------------------ | ------------------------------- |
| | | |
| #H5Lget_info | #H5Lget_info1 | #H5Lget_info2 |
| #H5Lget_info_by_idx | #H5Lget_info_by_idx1 | #H5Lget_info_by_idx2 |
| #H5Literate | #H5Literate1 | #H5Literate2 |
| #H5Literate_by_name | #H5Literate_by_name1 | #H5Literate_by_name2 |
| #H5Lvisit | #H5Lvisit1 | #H5Lvisit2 |
| #H5Lvisit_by_name | #H5Lvisit_by_name1 | #H5Lvisit_by_name2 |
| #H5Oget_info | #H5Oget_info1 | #H5Oget_info3 |
| #H5Oget_info_by_idx | #H5Oget_info_by_idx1 | #H5Oget_info_by_idx3 |
| #H5Oget_info_by_name | #H5Oget_info_by_name1 | #H5Oget_info_by_name3 |
| #H5Ovisit | #H5Ovisit1 | #H5Ovisit3 |
| #H5Ovisit_by_name | #H5Ovisit_by_name1 | #H5Ovisit_by_name3 |
| | | |
\subsection subsec_rel_spec_112_migrate_encode Encoding Properties
These functions were introduced in HDF5 version 1.12 as part of the H5Sencode format change to enable
64-bit selection encodings and a dataspace selection that is tied to a file. See the \ref_sencode_fmt_change RFC for details.
| Original Function in 1.10/Macro in 1.12 (H5xxx) | Deprecated Function in 1.12 (H5xxx1) | New Function (using token type) |
| ----------------------------------------------- | ------------------------------------ | ------------------------------- |
| | | |
| #H5Pencode | #H5Pencode1 | #H5Pencode2 |
| #H5Sencode | #H5Sencode1 | #H5Sencode2 |
| | | |
\section sec_rel_spec_112_feat New Features in HDF5 Release 1.12
This release includes changes in the HDF5 storage format.
\note
PLEASE NOTE that HDF5-1.10 and earlier releases cannot read files created with the new features described below that are marked with a \*.
HDF5 1.12 introduces several new features in the HDF5 library:
\li \ref_sencode_fmt_change
\li \ref_rfc20180712
\li \ref_rfc20210219
\li \ref_rfc20140916
\li \ref subsec_rel_spec_112_feat_hyper
\subsection subsec_rel_spec_112_feat_vol Virtual Object Layer (VOL)
See the \ref_rfc20140916 for more information.
The Virtual Object Layer (VOL) is an abstraction layer within the HDF5 library that enables
different methods for accessing data and objects that conform to the HDF5 data model. The VOL
intercepts all HDF5 API calls that potentially modify data on disk and forwards those calls
to a plugin "object driver". The data on disk can be a different format than the HDF5 format.
The plugins can actually store the objects in variety of ways. A plugin could, for example, have
objects be distributed remotely over different platforms, provide a raw mapping of the model to
the file system, or even store the data in other file formats (like native netCDF or HDF4 format).
The user still gets the same data model where access is done to a single HDF5 \"container\";
however the plugin object driver translates from what the user sees to how the data is actually
stored. Having this abstraction layer maintains the object model of HDF5 and allows better usage of
new object storage file systems that are targeted for Exascale systems.
\subsection subsec_rel_spec_112_feat_hyper Hyperslab Performance Improvements
In 1.12.0 the hyperslab selection code was optimized to achieve better performance. In general,
performance improved by an order of a magnitude. In the case of reading a regular selection from
a 20 GB dataset into a one dimensional array, performance improved by a factor of 6000. If you
are interested in the benchmark we ran, please see issue HDFFV-10930 by logging into
jira.hdfgroup.org with your hdfgroup.org login.
\subsection subsec_rel_spec_112_feat_rfc Update to References (RFC) *
See the Update to References page for details on the changes in HDF5-1.12.
HDF5 references were extended to support attributes, as well as object and dataset selections
that reside in another HDF5 file. In order to support these features several functions were introduced:
\li Create (H5Rcreate*) functions were added for each reference type: object, dataset region and attribute.
\li A function was added to release a reference (H5Rdestroy). This is required because a region reference no longer modifies the original file.
\li Functions were added to query references (H5Rget*).
\li Other functions were added to simplify or clarify the API.
\subsection subsec_rel_spec_112_feat_sel Update to Selections
Several new H5S APIs were introduced to allow a user to more flexibly operate on two hyperslab selections.
See Update to Selections for more details.
<h4>RFCs</h4>
\li \ref_sencode_fmt_change
\li \ref_rfc20180712
\li \ref_rfc20210219
\li \ref_rfc20140916
\li \ref subsec_rel_spec_112_feat_hyper
\ref rel_spec_112_change
*/

95
doxygen/dox/hdf5_1_14.dox Normal file
View File

@ -0,0 +1,95 @@
/** \page rel_spec_114 Release Specific Information for HDF5 1.14
\section sec_rel_spec_114_migrate Migrating from HDF5 1.12 to HDF5 1.14
# Migrating to HDF5 1.14 from Previous Versions of HDF5
\subsection subsec_rel_spec_114_migrate_api API Changes
There are new API calls that require API Compatibility Macros in HDF5 1.14.0. There are, however,
two API calls which have had their signature change.
\subsection subsec_rel_spec_114_migrate_api_h5ireg H5Iregister_type / H5I_free_t
The signature of #H5Iregister_type did not change, but the #H5I_free_t callback it accepts did
have its signature change to add an asynchronous request parameter. There is no API compatibility
macro to paper over this change. The request parameter can be ignored in the callback if you are
not concerned with asynchronous operations and future IDs. A description of how the request
parameter should be used will be found in the (soon to be released) HDF5 Asynchronous Programming Guide.
\li <strong>Old:</strong> - <code>typedef herr_t (*H5I_free_t)(void *obj);</code>
\li <strong>New:</strong> - <code>typedef herr_t (*H5I_free_t)(void *obj, void **request);</code>
\subsubsection subsubsec_rel_spec_114_migrate_api_h5vlquery H5VLquery_optional
The way optional operations are handled in the virtual object layer (VOL) changed significantly in
HDF5 1.14.0. To better support this, the #H5VLquery_optional API call now takes an output flags
parameter instead of a Boolean. Since the entire 1.12 VOL API has been deprecated, no API
compatibility macro exists for this API call.
\li <strong>Old:</strong> - <code>herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported);</code>
\li <strong>New:</strong> - <code>herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags);</code>
\subsection subsec_rel_spec_114_migrate_vfl Virtual File Layer (VFL) Changes
The virtual file layer has changed in HDF5 1.14.0. Existing virtual file drivers (VFDs) will have
to be updated to work with this version of the library.
\subsection subsec_rel_spec_114_migrate_vol Virtual Object Layer (VOL) Changes
The virtual object layer has changed significantly in HDF5 1.14.0 and the 1.12 VOL API is now
considered deprecated and unsupported. Existing virtual object layer connectors should be updated
to work with this version of the library.
\section sec_rel_spec_114_feat New Features in HDF5 Release 1.14
The new features in the HDF5 1.14 series include:
\li \ref_rfc20240129<br />
Support for the 16-bit floating-point \_Float16 C type has been added to
HDF5. On platforms where this type is available, this can enable more
efficient storage of floating-point data when an application doesn't
need the precision of larger floating-point datatypes. It can also allow
for improved performance when converting between 16-bit floating-point
data and data of another HDF5 datatype.
\li \ref sec_async<br />
HDF5 provides asynchronous APIs for the HDF5 VOL connectors that
support asynchronous HDF5 operations using the HDF5 Event Set (H5ES)
API. This allows I/O to proceed in the background while the application
is performing other tasks.
\li \ref_rfc20200213<br />
The basic idea behind sub-filing is to find the middle ground between
single shared file and one file per process - thereby avoiding some
of the complexity of one file per process, and minimizing the locking
issues of a single shared file on a parallel file system.
\li \ref_rfc20200210<br />
There is a desire to introduce and track modifications to an HDF5 file
while preserving or having access to the file as it existed prior to a
particular set of modifications. To this end, this RFC proposes an Onion
Virtual File Driver (VFD) as an effectively in-file revision management
facility. Users will be able to open a particular revision of the file,
read from and make modifications to the file, and write to file as a new
revision. The name "Onion" derives from a mnemonic: the original file
exists with data layered atop one another from an original file to the
most recent revision
\li \ref_rfc20120828<br />
The HDF5 library allows a data access operation to access one dataset at
a time, whether access is collective or independent. However, accessing
multiple datasets will require the user to issue an I/O call for each
dataset. This release provides a set of new routines that allow users
to access multiple datasets with a single I/O call.
\li New tools h5dwalk and h5delete<br />
The new tool h5dwalk provides parallelism for improved performance while
also including critical logging capabilities to capture outputs from
applying the serial tools over large collections of HDF5 files.
Note that the HDF5 Release 1.14.0 is the final released version of all the features
that were released in 1.13.0-1.13.3.
<h4>RFCs</h4>
\li \ref_rfc20240129
\li \ref sec_async
\li \ref_rfc20200213
\li \ref_rfc20200210
\li \ref_rfc20120828
\ref sec_rel_spec_114_change
*/

2316
doxygen/dox/hdf5_1_8.dox Normal file
View File

File diff suppressed because it is too large Load Diff

23
doxygen/dox/release_specific_info.dox Normal file
View File

@ -0,0 +1,23 @@
/** \page release_specific_info Release Specific Information
\ref rel_spec_114
\li \ref sec_rel_spec_114_feat
\li \ref sec_rel_spec_114_change
\li \ref sec_rel_spec_114_migrate
\ref rel_spec_112
\li \ref sec_rel_spec_112_feat
\li \ref sec_rel_spec_112_change
\li \ref sec_rel_spec_112_migrate
\ref rel_spec_110
\li \ref sec_rel_spec_110_feat
\li \ref sec_rel_spec_110_change
\li \ref sec_rel_spec_110_migrate
\ref rel_spec_18
\li \ref sec_rel_spec_18_change
\ref api-compat-macros
*/

659
doxygen/dox/sw_changes_1.10.dox Normal file
View File

@ -0,0 +1,659 @@
/** \page rel_spec_110_change Release Software Changes for HDF5 1.10
\section sec_rel_spec_110_change Software Changes from Release to Release in HDF5 1.10
For a description of the major new features that were introduced,
please see \ref sec_rel_spec_110_feat.
This page provides information on the changes that a maintenance developer needs to be
aware of between successive releases of HDF5, such as:
\li New or changed features or tools
\li Syntax and behavioral changes in the existing application programming interface (API)
\li Certain types of changes in configuration or build processes
Note that bug fixes and performance enhancements in the C library are automatically picked
up by the C++, Fortran, and Java libraries.
The following information is included below.
\li \ref subsec_rel_spec_110_change_compatibility
\li \ref subsec_rel_spec_110_change_9versus8
\li \ref subsec_rel_spec_110_change_8versus7
\li \ref subsec_rel_spec_110_change_7versus6
\li \ref subsec_rel_spec_110_change_6versus5
\li \ref subsec_rel_spec_110_change_5versus4
\li \ref subsec_rel_spec_110_change_4versus3
\li \ref subsec_rel_spec_110_change_3versus2
\li \ref subsec_rel_spec_110_change_2versus1
\li \ref subsec_rel_spec_110_change_1versus0
\li \ref subsec_rel_spec_110_change_0versus8_16
See [API Compatibility Reports for 1.10]() for information regarding compatibility with previous releases.
\subsection subsec_rel_spec_110_change_compatibility Compatibility and Performance Issues
Not all HDF5-1.10 releases are compatible. Users should NOT be using 1.10 releases prior
to HDF5-1.10.3. See the compatibility matrix below for details on compatibility between 1.10 releases:
<table>
<tr><th>Release</th><th>1.10.5+</th><th>1.10.4</th><th>1.10.3</th><th>1.10.2</th><th>1.10.1</th><th>1.10.0-patch1</th><th>1.10.0</th></tr>
<tr><td>1.10.5+</td><td>.</td><td>Yes</td><td>Yes</td><td>No</td><td>No</td><td>No</td><td>No</td></tr>
<tr><td>1.10.4</td><td>Yes</td><td>.</td><td>Yes</td><td>No</td><td>No</td><td>No</td><td>No</td></tr>
<tr><td>1.10.3</td><td>Yes</td><td>Yes</td><td>.</td><td>No</td><td>No</td><td>No</td><td>No</td></tr>
<tr><td>1.10.2</td><td>No</td><td>No</td><td>No</td><td>.</td><td>No</td><td>No</td><td>No</td></tr>
</table>
The following images show how performance has changed from release to release.
<table>
<tr><td>\image html cgns.png</td></tr>
</table>
<table>
<tr><td>\image html writeLgNumDsets.png</td></tr>
</table>
The release notes also list changes made to the library, but these notes tend to be more at a more
detail-oriented level. The release notes may include new features, bugs fixed, supported configuration
features, platforms on which the library has been tested, and known problems. The release note files
are listed below and can be found at the top level of the HDF5 source code tree in the release_docs directory.
<table>
<tr><th>Filename</th><th>Description</th></tr>
<tr><th>Release Notes</th><td> Technical notes regarding the current release of the HDF5 library (RELEASE.txt in the source code)</td></tr>
<tr><th>HISTORY-1_10.txt</th><td>Release information for all HDF5-1.10 releases</td></tr>
<tr><th>HISTORY-1_8_0-1_10_0.txt</th><td>Development history between the HDF5-1.8.0 and HDF5-1.10.0 releases</td></tr>
<tr><th>HISTORY-1_8.txt</th><td>Release information for HDF5-1.8.0 through HDF5-1.8.21 releases</td></tr>
<tr><th>HISTORY-1_0-1_8_0_rc3.txt</th><td>Technical notes starting with HDF5-1.0.0 and ending with HDF5-1.8.0-rc3 (the state of the code prior to the HDF5-1.8.0 release)</td></tr>
</table>
\subsection subsec_rel_spec_110_change_9versus8 Release 1.10.9 versus 1.10.8
\subsection subsec_rel_spec_110_change_9versus8_func New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the Java API</h4>
One Java wrapper was added:
\li H5.H5export_dataset
\subsection subsec_rel_spec_110_change_9versus8_compat Compatibility Notes and Reports
See the [API compatibility report between 1.10.8 and 1.10.9]() for information regarding compatibility with the previous release.
\subsection subsec_rel_spec_110_change_8versus7 Release 1.10.8 versus 1.10.7
\subsection subsec_rel_spec_110_change_8versus7_func New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the C++ API</h4>
One C++ wrapper was added:
\li <code>DataSet::operator=</code>
\subsection subsec_rel_spec_110_change_8versus7_compat Compatibility Notes and Reports
See the [API compatibility report between 1.10.7 and 1.10.8]() for information regarding compatibility with the previous release.
\subsection subsec_rel_spec_110_change_7versus6 Release 1.10.7 versus 1.10.6
\subsubsection subsubsec_rel_spec_110_change_7versus6_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the C Interface (main library)</h4>
The following are new C functions in this release:
\li #H5Pget_fapl_splitter - Retrieves information for a splitter file access property list
\li #H5Pget_fapl_splitter - Retrieves information for a splitter file access property list
\li #H5Pset_fapl_splitter - Sets the file access property list to use the splitter driver
\li #H5Pget_file_locking - Gets the file locking property values
\li #H5Pset_file_locking - Sets the file locking property values
\li #H5get_free_list_sizes - Gets the current size of the free lists used to manage memory
\li #H5Scombine_hyperslab - Performs an operation on a hyperslab and an existing selection and returns the resulting selection
\li #H5Scombine_select - Combines two hyperslab selections with an operation, returning a dataspace with the resulting selection
\li #H5Smodify_select - Refines a hyperslab selection with an operation using a second hyperslab to modify it
\li #H5Sselect_adjust - Adjusts a selection by subtracting an offset
\li #H5Sselect_copy - Copies a selection from one dataspace to another
\li #H5Sselect_intersect_block - Checks if current selection intersects with a block
\li #H5Sselect_project_intersection - Projects the intersection of two source selections to a destination selection
\li #H5Sselect_shape_same - Checks if two selections are the same shape
<h4>In the C++ API</h4>
The following C++ wrappers were added:
\li <code>FileAccPropList::getFileLocking</code> - See #H5Pget_file_locking for details
\li <code>FileAccPropList::setFileLocking</code> - See #H5Pset_file_locking for details
\subsection subsec_rel_spec_110_change_7versus6_compat Compatibility Notes and Reports
See the [API compatibility report between 1.10.7 and 1.10.8]() for information regarding compatibility with the previous release.
\subsection subsec_rel_spec_110_change_6versus5 Release 1.10.6 versus 1.10.5
\subsubsection subsubsec_rel_spec_110_change_6versus5_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the C Interface (main library)</h4>
The following are new C functions in this release:
\li #H5Pget_fapl_hdfs - Gets the information of the given Read-Only HDFS virtual file driver
\li #H5Pget_fapl_ros3 - Gets the information of the given Read-Only S3 virtual file driver
\li #H5Pset_fapl_hdfs - Sets up Read-Only HDFS virtual file driver
\li #H5Pset_fapl_ros3 - Sets up Read-Only S3 virtual file driver
<h4>In the C++ API</h4>
The following C++ wrappers were added:
\li <code>LinkCreatPropList::getCreateIntermediateGroup() const</code> - See #H5Pget_create_intermediate_group
\li <code>LinkCreatPropList::setCreateIntermediateGroup(bool crt_intmd_group) const</code> - See #H5Pset_create_intermediate_group
\subsection subsec_rel_spec_110_change_6versus5_compat Compatibility Notes and Reports
See the [API compatibility report between 1.10.7 and 1.10.8]() for information regarding compatibility with the previous release.
\subsection subsec_rel_spec_110_change_5versus4 Release 1.10.5 versus 1.10.4
\subsubsection subsubsec_rel_spec_110_change_5versus4_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the C Interface (main library)</h4>
The following are new C functions in this release:
\li #H5Dget_chunk_info - Retrieves information about a chunk specified by the chunk index
\li #H5Dget_chunk_info_by_coord - Retrieves information about a chunk specified by its coordinates
\li #H5Dget_num_chunks - Retrieves number of chunks that have nonempty intersection with a specified selection
\li #H5Fget_dset_no_attrs_hint - Retrieves the setting for determining whether the specified file does or does not create minimized dataset object headers
\li #H5Fset_dset_no_attrs_hint - Sets the flag to create minimized dataset object headers
\li #H5Pget_dset_no_attrs_hint - Retrieves the setting for determining whether the specified DCPL does or does not create minimized dataset object headers
\li #H5Pset_dset_no_attrs_hint - Sets the flag to create minimized dataset object headers
The following changed in this release:
\li #H5Oget_info
\li #H5Oget_info_by_name
\li #H5Oget_info_by_idx
\li #H5Ovisit
\li #H5Ovisit_by_name
In 1.10.3 the original functions were versioned to H5Oget_info*1 and H5Ovisit*1 and the macros
H5Oget_info* and H5Ovisit* were created. This broke the API compatibility for a maintenance release.
In HDF5-1.10.5, the macros introduced in HDF5-1.10.3 were removed. The H5Oget_info*1 and H5Ovisit*1 APIs
were copied to H5Oget_Info* and H5Ovisit*. As an example, #H5Oget_info and #H5Oget_info1
are identical in this release.
<h4>In the C++ API</h4>
The following C++ wrapper was added:
\li <code>H5Object::visit()</code> - Wrapper for the C API #H5Ovisit2. Recursively visit elements
reachable from an HDF5 object and perform a common set of operations across all of those elements.
<h4>In the Fortran API</h4>
The following Fortran wrappers were added or changed:
\li #h5f.h5fget_dset_no_attrs_hint_f - Wrappers for the dataset object header minimization calls. See #H5Fget_dset_no_attrs_hint.
\li #h5f.h5fset_dset_no_attrs_hint_f - Wrappers for the dataset object header minimization calls. See #H5Fset_dset_no_attrs_hint.
\li #h5p.h5pget_dset_no_attrs_hint_f - Wrappers for the dataset object header minimization calls. See #H5Pget_dset_no_attrs_hint.
\li #h5p.h5pset_dset_no_attrs_hint_f - Wrappers for the dataset object header minimization calls. See #H5Pset_dset_no_attrs_hint.
\li #h5o.h5ovisit_f - Added new Fortran 'fields' optional parameter. See #H5Ovisit2.
\li #h5o.h5oget_info_by_name_f - Added new Fortran 'fields' optional parameter. See #H5Oget_info_by_name2.
\li #h5o.h5oget_info_f - Added new Fortran 'fields' optional parameter. See #H5Oget_info2.
\li #h5o.h5oget_info_by_idx_f - Added new Fortran 'fields' optional parameter. See #H5Oget_info_by_idx2.
\li #h5o.h5ovisit_by_name_f - Added new Fortran 'fields' optional parameter. See #H5Ovisit_by_name2.
The following Fortran utility function was added:
\li #h5lib.h5gmtime - converts (C) <code>time_t</code> structure to Fortran DATE AND TIME storage format
A new Fortran derived type was added:
\li c_h5o_info_t - This is interoperable with C's h5o_info_t. This is needed for callback functions which
pass C's h5o_info_t data type definition.
<h4>In the Java wrapper</h4>
The following Java wrappers were added or changed:
\li #H5Fset_libver_bounds
\li #H5Fget_dset_no_attrs_hint
\li #H5Fset_dset_no_attrs_hint
\li #H5Pget_dset_no_attrs_hint
\li #H5Pset_dset_no_attrs_hint
\subsection subsec_rel_spec_110_change_5versus4_compat Compatibility Notes and Reports
See the [API compatibility report between 1.10.5 and 1.10.2/1.10.3/1.10.4]() for details.
\subsection subsec_rel_spec_110_change_4versus3 Release 1.10.4 versus 1.10.3
See the [API compatibility report between 1.10.4 and 1.10.3]() for details.
\subsection subsec_rel_spec_110_change_3versus2 Release 1.10.3 versus 1.10.2
New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the C Interface (main library)</h4>
The following are new C functions in this release:
\li #H5Dread_chunk - Moved from HDF5 High Level Optimizations library to core library
\li #H5Dwrite_chunk - Moved from HDF5 High Level Optimizations library to core library
\li #H5Oget_info - The function #H5Oget_info was moved to #H5Oget_info1, and the macro #H5Oget_info
was created that can be mapped to either #H5Oget_info1 or #H5Oget_info2. For HDF5-1.10 and
earlier releases, #H5Oget_info is mapped to #H5Oget_info1 by default.
\li #H5Oget_info1
\li #H5Oget_info2
\li #H5Oget_info_by_idx - The function #H5Oget_info_by_idx was moved to #H5Oget_info_by_idx1, and
the macro #H5Oget_info_by_idx was created that can be mapped to either #H5Oget_info_by_idx1 or
#H5Oget_info_by_idx2. For HDF5-1.10 and earlier releases, #H5Oget_info_by_idx is mapped to #H5Oget_info_by_idx1 by default.
\li #H5Oget_info_by_idx1
\li #H5Oget_info_by_idx2
\li #H5Oget_info_by_name - The function #H5Oget_info_by_name was moved to #H5Oget_info_by_name1,
and the macro #H5Oget_info_by_name was created that can be mapped to either #H5Oget_info_by_name1
or #H5Oget_info_by_name2. For HDF5-1.10 and earlier releases, #H5Oget_info_by_name is mapped to
#H5Oget_info_by_name1 by default.
\li #H5Oget_info_by_name1
\li #H5Oget_info_by_name2
\li #H5Ovisit - The function #H5Ovisit was moved to #H5Ovisit1, and the macro H5Ovisit was created that
can be mapped to either #H5Ovisit1 or #H5Ovisit2. For HDF5-1.10 and earlier releases, #H5Ovisit is
mapped to #H5Ovisit1 by default.
\li #H5Ovisit1
\li #H5Ovisit2
\li #H5Ovisit_by_name - The function #H5Ovisit_by_name was moved to #H5Ovisit_by_name1, and the macro
#H5Ovisit_by_name was created that can be mapped to either #H5Ovisit_by_name1 or #H5Ovisit_by_name2.
For HDF5-1.10 and earlier releases, #H5Ovisit_by_name is mapped to #H5Ovisit_by_name1 by default.
\li #H5Ovisit_by_name1
\li #H5Ovisit_by_name2
<h4>In the C High Level Interface</h4>
The following C functions were deprecated in this release:
\li #H5DOread_chunk - Deprecated, moved to #H5Dread_chunk
\li #H5DOwrite_chunk - Deprecated, moved to #H5Dwrite_chunk
<h4>In the C++ API</h4>
Several C++ wrappers were added or modified to provide additional support. See the
API Compatibility Report for details.
\subsection subsec_rel_spec_110_change_4versus3_compat Compatibility Notes and Report
See the [API compatibility report between 1.10.4 and 1.10.3]() for details.
\subsection subsec_rel_spec_110_change_2versus1 Release 1.10.2 versus 1.10.1
This section lists interface-level changes and other user-visible changes in behavior in the
transition from HDF5 Release 1.10.1 to Release 1.10.2.
New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the C Interface (main library)</h4>
The following are new C functions in this release:
\li #H5Dget_chunk_storage_size - Returns storage amount allocated within a file for a raw data chunk in a dataset
\li #H5Fget_eoa - Retrieves the file's EOA
\li #H5Fincrement_filesize - Sets the file's EOA to the maximum of (EOA, EOF) + increment
\li #H5Fset_libver_bounds - Enables the switch of version bounds setting for a file
\li #H5FDdriver_query - Queries a VFL driver for its feature flags when a file is not available (not documented in Reference Manual)
\li #H5Pget_virtual_prefix - Retrieves prefix applied to VDS source file paths
\li #H5Pset_virtual_prefix - Sets prefix to be applied to VDS source file paths
The following C functions changed in this release:
\li #H5Pset_libver_bounds - HDF5-1.10 was added to the range of versions
\li #H5Pset_virtual - A change was made to the method of searching for VDS source files
\li H5PL* - The parameters for many of the H5PL APIs were renamed
<h4>In the C High Level Interface</h4>
The following new C function was added to this release:
\li #H5DOread_chunk - Reads a raw data chunk directly from a dataset in a file
<h4>In the C++ API</h4>
The following C++ wrappers were added:
\li #H5Lcreate_soft - Creates a soft link from link_name to target_name
\li #H5Lcreate_hard - Creates a hard link from new_name to curr_name
\li #H5Lcopy - Copy an object from a group of file
\li #H5Lmove - Rename an object in a group or file
\li #H5Ldelete - Removes the specified link from this location
\li #H5Tencode - Creates a binary object description of this datatype
\li #H5Tdecode - Returns the decoded type from the binary object description
\li #H5Lget_info - Returns the information of the named link
These were also added:
\li <code>Class LinkCreatPropList</code> for link create property list
Overloaded functions:
\li <code>H5Location::createGroup</code> to take a link creation property list
See the API Compatibility report for complete details.
<h4>In the Java API</h4>
The following Java wrappers were added:
\li #H5Pset_evict_on_close - Controls the library's behavior of evicting metadata associated with a closed object
\li #H5Pget_evict_on_close - Retrieves the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when closed
\li #H5Pset_chunk_opts - Sets the edge chunk option in a dataset creation property list
\li #H5Pget_chunk_opts - Retrieves the edge chunk option setting from a dataset creation property list
\li #H5Pset_efile_prefix - Sets the external dataset storage file prefix in the dataset access property list
\li #H5Pget_efile_prefix - Retrieves the prefix for external raw data storage files as set in the dataset access property list
\li #H5Pset_virtual_prefix - Sets prefix to be applied to VDS source file paths
\li #H5Pget_virtual_prefix - Retrieves prefix applied to VDS source file paths
See the Release.txt file for details.
<h4>Tools</h4>
New options were added to the \ref sec_cltools_h5clear utility:
\li <code>--filesize</code> - Print the file's EOA and EOF
\li <code>--increment=C</code> - Set the file's EOA to the maximum of <code>(EOA, EOF) + C</code>
for the file <code>C is >= 0</code>; C is optional and will default to 1M when not set
A new option was added to \ref sec_cltools_h5diff
\li <code>--enable-error-stack</code> - Enable the error stack
\subsection subsec_rel_spec_110_change_2versus1_compat Compatibility Notes and Report
See the [API compatibility report between 1.10.4 and 1.10.3]() for details.
\subsection subsec_rel_spec_110_change_1versus0 Release 1.10.1 versus 1.10.0
This section lists interface-level changes and other user-visible changes in behavior in the
transition from HDF5 Release 1.10.0 (and HDF5-1.10.0-patch1) to Release 1.10.1.
\subsubsection subsubsec_rel_spec_110_change_1versus0_new New Features
Several new features are introduced in HDF5 Release 1.10.1.
\li Metadata Cache Image
\li Metadata Cache Evict on Close
\li Paged Aggregation
\li Page Buffering
<h4>New Features, including associated C Functions</h4>
The following features are described and documented in New Features in HDF5 Release 1.10.
Each new feature in 1.10.1 is listed below along with the associated C functions:
\li <strong>Metadata Cache Image:</strong><br />
<ul>
<li>#H5Pget_mdc_image_config - Retrieves the metadata cache image configuration values for a file access property list.</li>
<li>#H5Pset_mdc_image_config - Sets the metadata cache image option for a file access property list.</li>
<li>#H5Fget_mdc_image_info - Gets information about a metadata cache image if it exists.</li>
</ul>
\li <strong>Metadata Cache Evict on Close:</strong><br />
<ul>
<li>#H5Pget_evict_on_close - Retrieves the property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed.</li>
<li>#H5Pset_evict_on_close - Controls the library's behavior of evicting metadata associated with a closed object.</li>
</ul>
\li <strong>Paged Aggregation:</strong><br />
<ul>
<li>#H5Pget_file_space_page_size - Retrieves the file space page size for a file creation property list.
<li>#H5Pset_file_space_page_size - Sets the file space page size (used with paged aggregation) for a file creation property list.
<li>#H5Pget_file_space_strategy - Retrieves the file space handling strategy for a file creation property list.
<li>#H5Pset_file_space_strategy - Sets the file space allocation strategy for a file creation property list.
</ul>
\li <strong>Page Buffering:</strong><br />
<ul>
<li>#H5Pget_page_buffer_size - Retrieves the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.</li>
<li>#H5Pset_page_buffer_size - Sets the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.</li>
<li>#H5Fget_page_buffering_stats - Retrieves statistics about page access when it is enabled.</li>
<li>#H5Freset_page_buffering_stats - Resets the page buffer statistics.</li>
</ul>
New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
<h4>In the C Interface (main library)</h4>
The following new C functions were added:
\li #H5PLappend
\li #H5PLget
\li #H5PLinsert
\li #H5PLprepend
\li #H5PLremove
\li #H5PLreplace
\li #H5PLsize
<h4>In the C++ API</h4>
New member functions were added to provide const versions. For example, these methods,
\li <code>ArrayType::getArrayDims ( hsize_t* dims ) const</code>
\li <code>ArrayType::getArrayNDims ( ) const</code>
replace these:
\li <code>ArrayType::getArrayDims(hsize_t* dims)</code>
\li <code>ArrayType::getArrayNDims()</code>
Several functions were moved to other classes. For example, this method,
\li <code>H5Location::openDataSet (char const* name) const</code>
replaces:
\li <code>CommonFG::openDataSet (char const* name) const</code>
PLEASE review the Compatibility report below for complete information on the C++ changes in this release.
\subsection subsec_rel_spec_110_change_1versus0_compat Compatibility Report
See the [API compatibility report between 1.10.1 and 1.10.0-patch1]() for details.
\subsection subsec_rel_spec_110_change_0versus8_16 Release 1.10.0 versus Release 1.8.16
This section lists interface-level changes and other user-visible changes in behavior in
the transition from HDF5 Release 1.8.16 to Release 1.10.0.
Changed Type
\li hid_t - Changed from a 32-bit to a 64-bit value. hid_t is the type is used for all HDF5
identifiers. This change, which is necessary to accommodate the capacities of modern
computing systems, therefore affects all HDF5 applications. If an application has been
using HDF5's hid_t the type, recompilation will normally be sufficient to take advantage
of HDF5 Release 1.10.0. If an application uses an integer type instead of HDF5's hid_t
type, those identifiers must be changed to a 64-bit type when the application is ported
to the 1.10.x series.
<h4>New Features and Feature Sets</h4>
Several new features are introduced in HDF5 Release 1.10.0.
\li Single-Writer / Multiple-Reader or SWMR
\li Collective Metadata I/O
\li Fine-tuning the metadata cache
\li File Space Management
\li Virtual Datasets or VDS
\li Partial Edge Chunk Options
\li Relative Pathnames for External Links
\li Property List Encoding and Decoding
More substantial lists follow, including new and modified C functions and Fortran subroutines.
<h4>New Features, including associated C Functions and Fortran Wrappers</h4>
The following features are described and documented in New Features in HDF5 Release 1.10.0. On this
page, we list each feature and its associated C functions and Fortran wrappers.
<h4>Single-writer / Multiple-reader, commonly called SWMR:</h4>
\li #H5Fstart_swmr_write - Enables SWMR writing mode for a file.
\li #H5DOappend - Appends data to a dataset along a specified dimension. (This is a high-level API.)
\li #H5Pget_append_flush - Retrieves the values of the append property that is set up in the dataset access property list.
\li #H5Pset_append_flush - Sets two actions to perform when the size of a dataset's dimension being appended reaches a specified boundary.
\li #H5Pget_object_flush_cb - Retrieves the object flush property values from the file access property list.
\li #H5Pset_object_flush_cb - Sets a callback function to invoke when an object flush occurs in the file.
\li #H5Odisable_mdc_flushes - Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage.
\li #H5Oenable_mdc_flushes - Returns the cache entries associated with an HDF5 object to the default metadata flush and eviction algorithm.
\li #H5Oare_mdc_flushes_disabled - Determines if an HDF5 object (dataset, group, committed datatype) has had flushes of metadata entries disabled.
\li H5Fdisable_mdc_flushes - Globally prevents dirty metadata entries from being flushed from the metadata cache to storage.
\li H5Fenable_mdc_flushes - Returns a file's metadata cache to the standard eviction and flushing algorithm.
\li H5Fare_mdc_flushes_disabled - Determines if flushes have been globally disabled for a file's metadata cache.
\li H5Fget_mdc_flush_disabled_obj_ids - Returns a list of all object identifiers for which flushes have been disabled in a file's metadata cache.
<h4>Command-line Tools:</h4>
\li \ref sec_cltools_h5watch - Allows users to output new records appended to a dataset under SWMR
access as it grows. The functionality is similar to the Unix user command tail with the follow
option, which outputs appended data as the file grows.
\li \ref sec_cltools_h5format_convert - This tool allows users to convert the indexing type of a
chunked dataset made with a 1.10.x version of the HDF5 Library when the latest file format is
used to the 1.8.x version 1 B-tree indexing type. For example, datasets created using SWMR access,
can be converted to be accessed by the HDF5 1.18 library and tools. The tool does not rewrite
raw data, but it does rewrite HDF5 metadata.
<h4>Collective Metadata I/O:</h4>
\li #H5Pset_coll_metadata_write and #h5p.h5pset_coll_metadata_write_f - Establishes I/O mode property setting,
collective or independent, for metadata writes.
\li #H5Pget_coll_metadata_write and #h5p.h5pget_coll_metadata_write_f - Retrieves I/O mode property setting
for metadata writes.
\li #H5Pset_all_coll_metadata_ops and #h5p.h5pset_all_coll_metadata_ops_f - Establishes I/O mode, collective
or independent, for metadata read operations.
\li #H5Pget_all_coll_metadata_ops and #h5p.h5pget_all_coll_metadata_ops_f - Retrieves I/O mode for metadata
read operations.
<h4>Fine-tuning the Metadata Cache:</h4>
\li #H5Fget_metadata_read_retry_info - Retrieves the collection of read retries for metadata items with checksum.
\li #H5Pget_metadata_read_attempts - Retrieves the number of read attempts from a file access property list.
\li #H5Pset_metadata_read_attempts - Sets the number of read attempts in a file access property list.
\li #H5Dflush - Causes all buffers associated with a dataset to be immediately written to disk without removing the data from the cache.
\li #H5Drefresh - Causes all buffers associated with a dataset to be cleared and immediately re-loaded with updated contents from disk storage.
\li #H5Gflush - Causes all buffers associated with a group to be immediately flushed to disk without removing the data from the cache.
\li #H5Grefresh - Causes all buffers associated with a group to be cleared and immediately re-loaded with updated contents from disk storage.
\li #H5Oflush - Causes all buffers associated with an object to be immediately flushed to disk without removing the data from the cache.
\li #H5Orefresh - Causes all buffers associated with an object to be cleared and immediately re-loaded with updated contents from disk storage.
\li #H5Tflush - Causes all buffers associated with a committed datatype to be immediately flushed to disk without removing the data from the cache.
\li #H5Trefresh - Causes all buffers associated with a committed datatype to be cleared and immediately re-loaded with updated contents from disk storage.
\li #H5Fget_intent - Determines the read/write or read-only status of a file.
<h4>Logging APIs:</h4>
\li #H5Pset_mdc_log_options - Sets metadata cache logging options.
\li #H5Pget_mdc_log_options - Gets metadata cache logging options.
\li #H5Fstart_mdc_logging - Starts logging metadata cache events if logging was previously enabled.
\li #H5Fstop_mdc_logging - Stops logging metadata cache events if logging was previously enabled and is currently ongoing.
\li H5Pget_mdc_logging_status - Gets the current metadata cache logging status.
<h4>File Space Management:</h4>
\li #H5Fget_free_sections - Retrieves free-space section information for a file.
\li #H5Fget_freespace - Returns the amount of free space in a file.
\li #H5Fget_info2 - Returns global information for a file.
\li #H5Pset_file_space - Sets the file space management strategy and/or the free-space section threshold for an HDF5 file.
\li #H5Pget_file_space - Retrieves the file space management strategy and/or the free-space section threshold for an HDF5 file.
The following tool has been modified to preserve or modify file freepace information appropriately
when processing files employing the VDS feature:
\li \ref sec_cltools_h5repack - Repacks HDF5 files with various options, including the ability
to change the applied filters. This version of \ref sec_cltools_h5repack understands the file free space feature
and handles the file and metadata appropriately.
<h4>Virtual Dataset or VDS:</h4>
\li #H5Pset_virtual and #h5p.h5pset_virtual_f - Sets the mapping between virtual and source datasets.
\li #H5Pget_virtual_count and #h5p.h5pget_virtual_count_f - Retrieves the number of mappings for the
virtual dataset.
\li #H5Pget_virtual_vspace and #h5p.h5pget_virtual_vspace_f - Retrieves a dataspace identifier for the
selection within the virtual dataset used in the mapping.
\li #H5Pget_virtual_srcspace and #h5p.h5pget_virtual_srcspace_f - Retrieves a dataspace identifier
for the selection within the source dataset used in the mapping.
\li #H5Pget_virtual_dsetname and #h5p.h5pget_virtual_dsetname_f - Retrieves the name of a source
dataset used in the mapping.
\li #H5Pget_virtual_filename and #h5p.h5pget_virtual_filename_f - Retrieves the filename of a source
dataset used in the mapping.
\li #H5Pset_virtual_printf_gap and #h5p.h5pset_virtual_printf_gap_f - Sets maximum number of missing
source files and/or datasets with printf-style names when getting the extent of an unlimited virtual dataset.
\li #H5Pget_virtual_printf_gap and #h5p.h5pget_virtual_printf_gap_f - Returns maximum number of missing
source files and/or datasets with printf-style names when getting the extent for an unlimited virtual dataset.
\li #H5Pset_virtual_view and #h5p.h5pset_virtual_view_f - Sets the view of the virtual dataset to include
or exclude missing mapped elements.
\li #H5Pget_virtual_view and #h5p.h5pget_virtual_view_f - Retrieves the view of a virtual dataset.
<h4>Supporting Functions:</h4>
\li #H5Sis_regular_hyperslab and #h5s.h5sis_regular_hyperslab_f - Determines whether a hyperslab selection is regular.
\li #H5Sget_regular_hyperslab and #h5s.h5sget_regular_hyperslab_f - Retrieves a regular hyperslab selection.
<h4>Modified Functions:</h4>
The following pre-exising functions have been modified to understand virtual datasets.
\li #H5Pset_layout and #h5p.h5pset_layout_f - Specifies the layout to be used for a dataset.
Virtual dataset, #H5D_VIRTUAL, has been added to the list of layouts available through this function.
\li #H5Pget_layout and #h5p.h5pget_layout_f - Retrieves the layout in use for a dataset.
Virtual dataset, #H5D_VIRTUAL, has been added to the list of layouts.
<h4>Partial Edge Chunks:</h4>
\li #H5Pset_chunk_opts - Sets a partial edge chunk option in a dataset access property list.
\li #H5Pget_chunk_opts - Retrieves partial edge chunk option setting from a dataset access property list.
<h4>Relative Pathnames for External Links:</h4>
\li #H5Pset_elink_prefix - Sets the prefix to be applied to external link paths.
\li #H5Pget_elink_prefix - Retrieves the prefix applied to external link paths.
These functions enable the user to specify the locations of external files.
(These functions are not yet documented as of the time of release for 1.10.0.)
\li #H5Pget_elink_prefix
<h4>Property List Encoding and Decoding:</h4>
\li #H5Pencode
\li #H5Pdecode
<h4>Additional New Functions:</h4>
The following new functions appear in HDF5 Release 1.10.0 but are not yet documented:
\li H5Dformat_convert
\li H5Dget_chunk_index_type
\li #H5FDlock
\li #H5FDunlock
\li H5Fformat_convert
\li #H5LDget_dset_dims
\li #H5LDget_dset_elmts
\li #H5LDget_dset_type_size
New and Changed Elements of the Packet Table (H5PT) High-level API
<h4>In the C Interface</h4>
<strong>Replacement functions:</strong><br />
\li #H5PTcreate - Takes a property list identifier to provide flexibility on creation properties. H5PTcreate_fl has been removed.
\li #H5PTfree_vlen_buff - Replaces H5PTfree_vlen_readbuff.
<strong>New functions:</strong><br />
Two accessor functions have been added.
\li #H5PTget_dataset - Returns the identifier of the dataset associated a packet table.
\li #H5PTget_type - Returns the identifier of the datatype used by a packet table.
\li #H5PTis_varlen - Determines whether a type is variable-length.
<h4>In the C++ Interface</h4>
<strong>Overloaded constructor</strong><br />
An overloaded constructor has been added.
\li FL_PacketTable - Takes a property list identifier to provide flexibility on creation properties.</dd>
\li H5PTfree_vlen_buff - Replaces H5PTfree_vlen_readbuff.
<strong>Accessor wrappers</strong><br />
Two accessor wrappers are added to class PacketTable.
\li PacketTable::GetDataset() - Returns the identifier of the dataset associated a packet table.
\li PacketTable::GetDatatype() - Returns the identifier of the datatype used by a packet table.
<strong>Other wrappers</strong>
\li PacketTable::FreeBuff() - Replaces VL_PacketTable::FreeReadBuff().
\li PacketTable::IsVariableLength() - Replaces VL_PacketTable::IsVariableLength().
<strong>Overloaded functions:</strong><br />
Where a member functions has a char* as an argument, an overloaded functions has been added to provide the const char* argument.
The existing version will be deprecated in a future release.
<h4>Java Interface Changes</h4>
\li Integration into Main HDF5 Library - The Java HDF5 JNI library has been integrated into the HDF5 repository.
<strong>Configure option:</strong>
\li <code>--enable-java</code>
<strong>CMake option:</strong>
\li <code>-DHDF5_BUILD_JAVA:BOOL=ON</code>
Prior to the 1.10.x series, the HDF5 Java tools were built from an independent repository
and were not as fully integrated with HDF5. were built from an independent repository
and were not as fully integrated with HDF5.
<strong>Package Hierarchy Change</strong>
\li The package hierarchy has changed to hdf.hdflib.hdf5.
\li Prior to the 1.10.x series, the hierarchy was ncsa.hdf.hdflib.hdf5.
<h4>New Java APIs</h4>
A number of new APIs have been added in the Java interface, including APIs for the VDS and SWMR features.
<h4>Functions with Changed Behavior</h4>
\li #H5Lexists - The behavior of this function has changed in this release. When testing the
pathname / (a slash representing the root of an HDF5 file) #H5Lexists now returns
successfully with the value 1 (one). See the entry in the \ref RM for #H5Lexists for more information.
\subsection subsec_rel_spec_110_change_0versus8_16_apicompat API Compatibility
See \ref api-compat-macros for details on the following.
<h4>New API Compatibility Flag</h4>
A new v18 flag was added enabling the building of HDF5 such that the default API is compatible
with the HDF5 Release 1.8.x API:
\li <code>--with-default-api-version=v18</code>
<h4>New versioned functions and associated compatibility macros</h4>
Two functions and a struct have been converted to a versioned form in this release.
Compatibility macros have been created for each.
\li #H5Fget_info - The original function is renamed to #H5Fget_info1 and deprecated.
A new version of the function, #H5Fget_info2, is introduced.
The compatibility macro #H5Fget_info is introduced.
\li #H5F_info_t - This is the struct used by the #H5Fget_info functions and macro.
The original struct is renamed to #H5F_info1_t and deprecated.
A new version of the struct, #H5F_info2_t, is introduced.
The compatibility macro #H5F_info_t is introduced.
\li #H5Rdereference - The original function is renamed to #H5Rdereference1 and deprecated.
A new version of the function, #H5Rdereference2, is introduced.
The compatibility macro #H5Rdereference is introduced.
\subsection subsec_rel_spec_110_change_0versus8_16_auto Autotools Configuration and Large File Support
Autotools configuration has been extensively reworked and autotool's handling of large
file support has been overhauled in this release.
See the following sections in RELEASE.txt:
\li Autotools Configuration Has Been Extensively Reworked
\li LFS Changes
RELEASE.txt can be found in the release_docs/ subdirectory at the root level of the HDF5 code distribution.
\subsection subsec_rel_spec_110_change_0versus8_16_compat Compatibility Report and Comments
[Compatibility report for Release 1.10.0 versus Release 1.8.16]()
Comments regarding the report
In the C interface, the hid_t change from 32-bit to 64-bit was made in order to address
a performance problem that arose when the library "ran out" of valid object identifiers
to issue and thus needed to employ an expensive algorithm to find previously issued
identifiers that could be re-issued. This problem is avoided by switching the size of
the hid_t type to 64-bit integers instead of 32-bit integers in order to make the pool
of available integers significantly larger. (#H5E_major_t and #H5E_minor_t are aliased to
hid_t which is why they changed size as well). (An alternate solution to this problem was
applied in release HDF5 1.8.5 but this is the cleaner/preferred solution and had to wait
until 1.10.0 to be included).
hbool_t will now be defined as a Bool type when configure determines that it's available.
Public structs that have members of type hid_t or hbool_t are affected by the above changes accordingly.
The #H5Fget_info function was renamed due to the introduction of a newer version of the
function which returns additional information. The #H5Rdereference function was renamed
due to the introduction of a newer version of the function which allows a data access
property list to be passed in. Both changes are accompanied with compatibility macros,
so while existing code will need to be recompiled in order to use the newer library version,
these functions do not need to be changed in application code using them provided that the
\ref api-compat-macros are configured appropriately.
*/

214
doxygen/dox/sw_changes_1.12.dox Normal file
View File

@ -0,0 +1,214 @@
/** \page rel_spec_112_change Release Software Changes for HDF5 1.12
\section sec_rel_spec_112_change Software Changes from Release to Release in HDF5 1.12
For a description of the major new features that were introduced, please see \ref sec_rel_spec_112_feat.
This page provides information on the changes that a maintenance developer needs to be aware of between successive releases of HDF5, such as:
\li New or changed features or tools
\li Syntax and behavioral changes in the existing application programming interface (the API)
\li Certain types of changes in configuration or build processes
Note that bug fixes and performance enhancements in the C library are automatically picked up by the C++, Fortran, and Java libraries.
The following information is included below.
\li \ref subsec_rel_spec_112_change_2versus1
\li \ref subsec_rel_spec_112_change_1versus0
\li \ref subsec_rel_spec_112_change_0versus10_6
The release notes also list changes made to the library, but these notes tend to be more at a more
detail-oriented level. The release notes may include new features, bugs fixed, supported configuration
features, platforms on which the library has been tested, and known problems. The release note files
are listed below and can be found at the top level of the HDF5 source code tree in the release_docs directory.
<table>
<tr><th>Filename</th><th>Description</th></tr>
<tr><th>Release Notes</th><td> Technical notes regarding the current release of the HDF5 library (RELEASE.txt in the source code)</td></tr>
<tr><th>HISTORY-1_12.txt</th><td>Release information for all HDF5-1.12 releases</td></tr>
<tr><th>HISTORY-1_10_0-1_12_0.txt</th><td>Development history between the HDF5-1.10.0 and HDF5-1.12.0 releases</td></tr>
<tr><th>HISTORY-1_10.txt</th><td>Release information for all HDF5-1.10 releases</td></tr>
<tr><th>HISTORY-1_8_0-1_10_0.txt</th><td>Development history between the HDF5-1.8.0 and HDF5-1.10.0 releases</td></tr>
<tr><th>HISTORY-1_8.txt</th><td>Release information for HDF5-1.8.0 through HDF5-1.8.21 releases</td></tr>
<tr><th>HISTORY-1_0-1_8_0_rc3.txt</th><td>Technical notes starting with HDF5-1.0.0 and ending with HDF5-1.8.0-rc3 (the state of the code prior to the HDF5-1.8.0 release)</td></tr>
</table>
\subsection subsec_rel_spec_112_change_2versus1 Release 1.12.2 versus Release 1.12.1
This section lists interface-level changes and other user-visible changes in behavior in the
transition from HDF5 Release 1.12.1 to Release 1.12.2.
\subsubsection subsubsec_rel_spec_112_change_2versus1_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
The following are new C functions in this release:
\li #H5DSwith_new_ref - Determines if new references are used with dimension scales
\li #H5LTget_attribute_ullong - Reads an unsigned long long attribute
\li #H5LTset_attribute_ullong - Create an unsigned long long attribute
\li #H5VLobject_is_native - Determines whether an object ID represents a native VOL connector object
See API Compatibility Reports for 1.12.2 for complete details.
\subsection subsec_rel_spec_112_change_1versus0 Release 1.12.1 versus Release 1.12.0
This section lists interface-level changes and other user-visible changes in behavior in the
transition from HDF5 Release 1.12.0 to Release 1.12.1.
\subsubsection subsubsec_rel_spec_112_change_1versus0_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
The following are new C functions in this release:
\li #H5Pget_fapl_splitter - Retrieves information for a splitter file access property list
\li #H5Pset_fapl_splitter - Sets the file access property list to use the splitter driver
\li #H5Pget_file_locking - Gets the file locking property values
\li #H5Pset_file_locking - Sets the file locking property values
\li #H5get_free_list_sizes - Gets the current size of the free lists used to manage memory
\li #H5Ssel_iter_reset - Resets a dataspace selection iterator back to an initial state
\li #H5VLquery_optional - Determines whether a VOL connector supports a particular optional callback operation
<h4>In the C++ Wrapper</h4>
The following C++ wrappers were added:
\li <code>DataSet::operator=</code> - <code>Operator=</code> for DataSet class
\li <code>FileAccPropList::getFileLocking</code> - See #H5Pget_file_locking for details
\li <code>FileAccPropList::setFileLocking</code> - See #H5Pset_file_locking for details
See the API Compatibility report for complete details.
\subsubsection subsubsec_rel_spec_112_change_1versus0_compat Compatibility Notes and Report
See API Compatibility Reports for 1.12 for information regarding compatibility with previous releases.
\subsection subsec_rel_spec_112_change_0versus10_6 Release 1.12.0 versus Release 1.10.6
This section lists interface-level changes and other user-visible changes in behavior in the
transition from HDF5 Release 1.10.6 to Release 1.12.0.
\subsubsection subsubsec_rel_spec_112_change_0versus10_6_new New Features
For a description of the major new features that were introduced, please see \ref sec_rel_spec_112_feat.
<h4>New and Changed Functions, Classes, Subroutines, Wrappers, and Macros</h4>
<strong>In the C Interface (main library)</strong><br />
Following are the new or changed APIs introduced in HDF5-1.12.0. Those introduced with a new feature
list the specific new feature that they were added for.
\li #H5Fdelete - Deletes an HDF5 file
\li #H5Fget_fileno - Retrieves a file's file number that uniquely identifies the open file
\li #H5Fis_accessible - Determines if a file can be opened with a given fapl
\li #H5Iiterate - Calls a callback for each member of the identifier type specified
\li #H5Lget_info<br />H5Lget_info1<br />#H5Lget_info2 - The function H5Lget_info was moved to #H5Lget_info1, and
#H5Lget_info2 was introduced. The macro H5Lget_info was created that can be mapped to either #H5Lget_info1 or
#H5Lget_info2. For HDF5-1.12, H5Lget_info is mapped to #H5Lget_info2 by default. In earlier releases, H5Lget_info
is mapped to #H5Lget_info1.
\li #H5Lget_info_by_idx<br /> #H5Lget_info_by_idx1<br /> #H5Lget_info_by_idx2 - The function H5Lget_info_by_idx was moved to
#H5Lget_info_by_idx1, and #H5Lget_info_by_idx2 was introduced. The macro H5Lget_info_by_idx was created that can be
mapped to either #H5Lget_info_by_idx1 or #H5Lget_info_by_idx2. For HDF5-1.12, H5Lget_info_by_idx is mapped to
#H5Lget_info_by_idx2 by default. In earlier releases, H5Lget_info_by_idx is mapped to #H5Lget_info_by_idx1.
\li #H5Literate<br />#H5Literate1<br />#H5Literate2 - The function H5Literate was moved to #H5Literate1, and #H5Literate2
was introduced. The macro H5Literate was created that can be mapped to either #H5Literate1 or #H5Literate2. For
HDF5-1.12, H5Literate is mapped to #H5Literate2 by default. In earlier releases, H5Literate is mapped to #H5Literate1.
\li #H5Literate_by_name<br />#H5Literate_by_name1<br />#H5Literate_by_name2 - The function H5Literate_by_name was moved
to #H5Literate_by_name1, and #H5Literate_by_name2 was introduced. The macro H5Literate_by_name was created that
can be mapped to either #H5Literate_by_name1 or #H5Literate_by_name2. For HDF5-1.12, H5Literate_by_name is mapped
to #H5Literate_by_name2 by default. In earlier releases, H5Literate_by_name is mapped to #H5Literate_by_name1.
\li #H5Lvisit<br />#H5Lvisit1<br />#H5Lvisit2 - The function H5Lvisit was moved to #H5Lvisit1, and #H5Lvisit2 was
introduced. The macro H5Lvisit was created that can be mapped to either #H5Lvisit1 or #H5Lvisit2. For HDF5-1.12,
H5Lvisit is mapped to #H5Lvisit2 by default. In earlier releases, H5Lvisit is mapped to #H5Lvisit1.
\li #H5Lvisit_by_name<br />#H5Lvisit_by_name1<br />#H5Lvisit_by_name2 - The function H5Lvisit_by_name was moved
to #H5Lvisit_by_name1, and #H5Lvisit_by_name2 was introduced. The macro H5Lvisit_by_name was created that
can be mapped to either #H5Lvisit_by_name1 or #H5Lvisit_by_name2. For HDF5-1.12, H5Lvisit_by_name is mapped
to #H5Lvisit_by_name2 by default. In earlier releases, H5Lvisit_by_name is mapped to #H5Lvisit_by_name1.
\li #H5Oget_info<br />#H5Oget_info3 - The function H5Oget_info was replaced by the macro H5Oget_info and the
function H5Oget_info3 was added.
\li #H5Oget_info_by_idx<br />#H5Oget_info_by_idx3 - The function H5Oget_info_by_idx was replaced by the macro
H5Oget_info_by_idx. The functionH5Oget_info_by_idx3 was added.
\li #H5Oget_info_by_name<br />#H5Oget_info_by_name3 - The function H5Oget_info_by_name was replaced by the
macro H5Oget_info_by_name. The function H5Oget_info_by_name3 was added.
\li #H5Oget_native_info - Retrieves the native file format information about an object
\li #H5Oget_native_info_by_idx - Retrieves native file format information about an object according to the order of an index
\li #H5Oget_native_info_by_name - Retrieves native file format information about an object given its name
\li #H5Oopen_by_token - Opens an object in an HDF5 file using its VOL independent token
\li #H5Otoken_cmp - Compares two VOL connector object tokens
\li #H5Otoken_from_str - Deserializes a string into a connector object token
\li #H5Otoken_to_str - Serializes a connector's object token into a string
\li #H5Ovisit<br />#H5Ovisit3 - The function H5Ovisit was replaced by the macro H5Ovisit and the function #H5Ovisit3 was added
\li #H5Ovisit_by_name -
\li #H5Ovisit_by_name3 - The function H5Ovisit_by_name was replaced by the macro H5Ovisit_by_name,
and the function #H5Ovisit_by_name3 was added.
\li #H5Pencode<br />#H5Pencode1<br />#H5Pencode2 - Encodes properties on a property list into a buffer<br>The previous function was
renamed to H5Pencode1 and deprecated, and the macro H5Pencode was introduced.
\li #H5Pget_vol_id - Returns the identifier of the current VOL connector
\li #H5Pget_vol_info - Returns a copy of the VOL information for a connector
\li #H5Pset_vol - Set the file VOL connector for a file access property list
\li #H5Rcopy - Copies an existing reference
\li #H5Rcreate_attr - Creates an attribute reference
\li #H5Rcreate_object - Creates an object reference
\li #H5Rcreate_region - Creates a region reference
\li #H5Rdestroy - Closes a reference
\li #H5Requal - Determines whether two references are equal
\li #H5Rget_attr_name - Retrieves the attribute name for a referenced object
\li #H5Rget_file_name - Retrieves the file name for a referenced object
\li #H5Rget_obj_name - Retrieves the object name for a referenced object
\li #H5Rget_obj_type3 - Retrieves the type of object that an object reference points to
\li #H5Rget_type - Retrieves the type of reference
\li #H5Ropen_attr - Opens the referenced HDF5 attribute
\li #H5Ropen_object - Opens the referenced HDF5 object
\li #H5Ropen_region - Sets up a dataspace and selection as specified by a region reference
\li #H5Scombine_hyperslab - Performs an operation on a hyperslab and an existing selection and returns the resulting selection
\li #H5Scombine_select - Combines two hyperslab selections with an operation, returning a dataspace with the resulting selection
\li #H5Sencode<br />#H5Sencode1<br />#H5Sencode2 - Encodes a dataspace object description into a binary buffer<br />The function H5Sencode
was renamed to #H5Sencode1 and deprecated in this release. The macro H5Sencode and the function #H5Sencode2
were introduced in this release.
\li #H5Smodify_select - Refines a hyperslab selection with an operation using a second hyperslab to modify it
\li #H5Ssel_iter_close - Closes a dataspace selection iterator
\li #H5Ssel_iter_create - Creates a dataspace selection iterator for a dataspace's selection
\li #H5Ssel_iter_get_seq_list - Retrieves a list of offset / length sequences for the elements in an iterator
\li #H5Sselect_adjust - Adjusts a selection by subtracting an offset
\li #H5Sselect_copy - Copies a selection from one dataspace to another
\li #H5Sselect_intersect_block - Checks if current selection intersects with a block
\li #H5Sselect_project_intersection - Projects the intersection of two source selections to a destination selection
\li #H5Sselect_shape_same - Checks if two selections are the same shape
\li #H5Treclaim - Frees the buffers allocated for storing variable-length data in memory
\li #H5VLclose - Closes a VOL connector identifier
\li #H5VLget_connector_id - Retrieves the VOL connector identifier for a given object identifier
\li #H5VLget_connector_id_by_name - Retrieves the identifier for a registered VOL connector name
\li #H5VLget_connector_id_by_value - Retrieves the identifier for a registered VOL connector value
\li #H5VLget_connector_name - Retrieves the connector name for the VOL associated with the object or file identifier
\li #H5VLis_connector_registered_by_name - Tests whether a VOL class has been registered or not for a connector name
\li #H5VLis_connector_registered_by_value - Tests whether a VOL class has been registered or not for a connector value
\li #H5VLregister_connector - Registers a new VOL connector
\li #H5VLregister_connector_by_name - Registers a new VOL connector by name
\li #H5VLregister_connector_by_value - Registers a new VOL connector by connector value
\li #H5VLunregister_connector - Removes a VOL connector identifier from the library
<strong>In the Fortran Interface (main library)</strong><br />
Following are the new or changed APIs introduced in HDF5-1.12.0. Those introduced with a new feature
list the specific new feature that they were added for.
\li #h5f.h5fget_fileno_f - Retrieves a file's file number that uniquely identifies the open file
\li #h5f.h5fis_accessible_f - Determines if a file can be opened with a given fapl
\li #h5l.h5lget_info_f - The function h5lget_info_f is mapped to #H5Lget_info2.
\li #h5l.h5lget_info_by_idx_f - The function h5lget_info_by_idx_f is mapped to #H5Lget_info_by_idx2.
\li #h5l.h5literate_f - The function h5literate_f is mapped to #H5Literate2.
\li #h5l.h5literate_by_name_f - The function h5literate_by_name_f is mapped to #H5Literate_by_name2.
\li #h5o.h5oopen_by_token_f - Opens an object in an HDF5 file using its VOL independent token
\li #h5o.h5otoken_cmp_f - Compares two VOL connector object tokens
\li #h5p.h5pget_vol_id_f - Returns the identifier of the current VOL connector
\li #h5p.h5pset_vol_f - Set the file VOL connector for a file access property list
\li #h5vl.h5vlclose_f - Closes a VOL connector identifier
\li #h5vl.h5vlget_connector_id_f - Retrieves the VOL connector identifier for a given object identifier
\li #h5vl.h5vlget_connector_id_by_name_f - Retrieves the identifier for a registered VOL connector name
\li #h5vl.h5vlget_connector_id_by_value_f - Retrieves the identifier for a registered VOL connector value
\li #h5vl.h5vlget_connector_name_f - Retrieves the connector name for the VOL associated with the object or file identifier
\li #h5vl.h5vlis_connector_registered_by_name_f - Tests whether a VOL class has been registered or not for a connector name
\li #h5vl.h5vlis_connector_registered_by_value_f - Tests whether a VOL class has been registered or not for a connector value
\li #h5vl.h5vlregister_connector_by_name_f - Registers a new VOL connector by name
\li #h5vl.h5vlregister_connector_by_value_f - Registers a new VOL connector by connector value
\li #h5vl.h5vlunregister_connector_f - Removes a VOL connector identifier from the library
<h4>In the C++ Wrapper</h4>
\li <code>H5File::getFileNum</code> - See #H5Fget_fileno
\li <code>H5File::isAccessible</code> - See #H5Fis_accessible
\li <code>LinkCreatPropList::getCreateIntermediateGroup</code> - See #H5Pget_create_intermediate_group
\li <code>LinkCreatPropList::setCreateIntermediateGroup</code> - See #H5Pset_create_intermediate_group
\li <code>H5Location::getLinkInfo</code> - See #H5Lget_info
\li <code>H5Location::getNativeObjinfo</code> - See #H5Oget_native_info
\li <code>H5Location::getObjinfo</code> - See #H5Oget_info
\li <code>H5Object::visit</code> - See #H5Ovisit
\subsubsection subsubsec_rel_spec_112_change_0versus10_6_compat API Compatibility
See API Compatibility Macros in HDF5 for details on using HDF5 version 1.12 with previous releases.
[Compatibility report for Release 1.12.0 versus Release 1.10.6](Compatibility report for Release 1.12.0 versus Release 1.10.6)
*/

256
doxygen/dox/sw_changes_1.14.dox Normal file
View File

@ -0,0 +1,256 @@
/** \page rel_spec_114_change Release Software Changes for HDF5 1.14
\section sec_rel_spec_114_change Software Changes from Release to Release in HDF5 1.14
\subsection subsec_rel_spec_114_change_compat API Compatibility
See \ref api-compat-macros for details on using HDF5 version 1.14 with previous releases.
\li <a href="https://\RELURL/v1_14/v1_14_6/downloads/hdf5-1.14.6.html.abi.reports.tar.gz">Compatibility reports for Release 1.14.6 versus Release 1.14.5</a>
\li <a href="https://\RELURL/v1_14/v1_14_5/downloads/hdf5-1.14.5.html.abi.reports.tar.gz">Compatibility reports for Release 1.14.5 versus Release 1.14.4</a>
\li <a href="https://\RELURL/v1_14/v1_14_4/downloads/hdf5-1.14.4-3.html.abi.reports.tar.gz">Compatibility reports for Release 1.14.4 versus Release 1.14.3</a>
\li <a href="https://\RELURL/v1_14/v1_14_3/downloads/hdf5-1.14.3.html.abi.reports.tar.gz">Compatibility reports for Release 1.14.3 versus Release 1.14.2</a>]
\li <a href="https://\RELURL/v1_14/v1_14_2/downloads/hdf5-1.14.2.html.abi.reports.tar.gz">Compatibility reports for Release 1.14.2 versus Release 1.14.1</a>]
\li <a href="https://\RELURL/v1_14/v1_14_1/downloads/hdf5-1.14.1.html.abi.reports.tar.gz">Compatibility reports for Release 1.14.1 versus Release 1.14.0</a>]
\li <a href="https://\RELURL/v1_14/v1_14_0/downloads/hdf5-1.14.0.html.abi.reports.tar.gz">Compatibility reports for Release 1.14.0 versus Release 1.12.2</a>]
This page provides information on the changes that a maintenance developer needs to
be aware of between successive releases of HDF5, such as:
\li New or changed features or tools
\li Syntax and behavioral changes in the existing application programming interface (the API)
\li Certain types of changes in configuration or build processes
\li Note that bug fixes and performance enhancements in the C library are automatically picked up by the C++, Fortran, and Java libraries.
The following information is included below.
\li \ref subsec_rel_spec_114_change_6versus5
\li \ref subsec_rel_spec_114_change_5versus4
\li \ref subsec_rel_spec_114_change_4versus3
\li \ref subsec_rel_spec_114_change_3versus2
\li \ref subsec_rel_spec_114_change_2versus1
\li \ref subsec_rel_spec_114_change_1versus0
\li \ref subsec_rel_spec_114_change_0versus12_2
The release notes also list changes made to the library, but these notes tend to be more at a
more detail-oriented level. The release notes may include new features, bugs fixed, supported
configuration features, platforms on which the library has been tested, and known problems.
The release note files are listed in each release section and can be found at the top level of
the HDF5 source code tree in the release_docs directory.
\subsection subsec_rel_spec_114_change_6versus5 Release 1.14.6 versus Release 1.14.5
\subsubsection subsubsec_rel_spec_114_change_6versus5_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
\li <a href="https://\RELURL/v1_14/v1_14_6/downloads/compat_report/hdf5-1.14.6-hdf5_compat_report.html">C API Compatibility report for Release 1.14.6 versus Release 1.14.5</a>
\li <a href="https://\RELURL/v1_14/v1_14_6/downloads/compat_report/hdf5-1.14.6-hdf5_cpp_compat_report.html">C++ API Compatibility report for Release 1.14.6 versus Release 1.14.5</a>
\li <a href="https://\RELURL/v1_14/v1_14_6/downloads/compat_report/hdf5-1.14.6-hdf5_hl_compat_report.html">High-Level API Compatibility report for Release 1.14.6 versus Release 1.14.5</a>
\li <a href="https://\RELURL/v1_14/v1_14_6/downloads/compat_report/hdf5-1.14.6-java_compat_report.html">Java API Compatibility report for Release 1.14.6 versus Release 1.14.5</a>
\subsection subsec_rel_spec_114_change_5versus4 Release 1.14.5 versus Release 1.14.4
\subsubsection subsubsec_rel_spec_114_change_5versus4_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
\li <a href="https://\RELURL/v1_14/v1_14_5/downloads/compat_report/hdf5-1.14.5-hdf5_compat_report.html">C API Compatibility report for Release 1.14.5 versus Release 1.14.4</a>
\li <a href="https://\RELURL/v1_14/v1_14_5/downloads/compat_report/hdf5-1.14.5-hdf5_cpp_compat_report.html">C++ API Compatibility report for Release 1.14.5 versus Release 1.14.4</a>
\li <a href="https://\RELURL/v1_14/v1_14_5/downloads/compat_report/hdf5-1.14.5-hdf5_hl_compat_report.html">High-Level API Compatibility report for Release 1.14.5 versus Release 1.14.4</a>
\li <a href="https://\RELURL/v1_14/v1_14_5/downloads/compat_report/hdf5-1.14.5-java_compat_report.html">Java API Compatibility report for Release 1.14.5 versus Release 1.14.4</a>
Following are the new APIs/macros introduced in HDF5-1.14.5.
<h4>In the C Interface (main library)</h4>
\li #H5Eis_paused - Check if pushing errors on an error stack is paused
\li #H5Epause_stack - Pause pushing errors on an error stack
\li #H5Eresume_stack - Resume pushing errors on an error stack
\subsection subsec_rel_spec_114_change_4versus3 Release 1.14.4 versus Release 1.14.3
\subsubsection subsubsec_rel_spec_114_change_4versus3_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
\li <a href="https://\RELURL/v1_14/v1_14_4/downloads/compat_report/hdf5-1.14.4-3-hdf5_compat_report.html">C API Compatibility report for Release 1.14.4 versus Release 1.14.3</a>
\li <a href="https://\RELURL/v1_14/v1_14_4/downloads/compat_report/hdf5-1.14.4-3-hdf5_cpp_compat_report.html">C++ API Compatibility report for Release 1.14.4 versus Release 1.14.3</a>
\li <a href="https://\RELURL/v1_14/v1_14_4/downloads/compat_report/hdf5-1.14.4-3-hdf5_hl_compat_report.html">High-Level API Compatibility report for Release 1.14.4 versus Release 1.14.3</a>
\li <a href="https://\RELURL/v1_14/v1_14_4/downloads/compat_report/hdf5-1.14.4-3-java_compat_report.html">Java API Compatibility report for Release 1.14.4 versus Release 1.14.3</a>
Following are the new APIs/macros introduced in HDF5-1.14.4.
<h4>In the C Interface (main library)</h4>
\li #H5Pget_relax_file_integrity_checks - Retrieves relaxed file integrity check flags
\li #H5Pset_relax_file_integrity_checks - Relaxes certain file integrity checks
<h4>Macro</h4>
\li #H5T_IEEE_F16BE - 16-bit big-endian IEEE floating-point numbers
\li #H5T_IEEE_F16LE - 16-bit little-endian IEEE floating-point numbers
\li #H5T_NATIVE_FLOAT16 - C-style <code>_Float16</code>
\subsection subsec_rel_spec_114_change_3versus2 Release 1.14.3 versus Release 1.14.2
This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.14.2 to Release 1.14.3.
\subsubsection subsubsec_rel_spec_114_change_3versus2_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
\li <a href="https://\RELURL/v1_14/v1_14_3/downloads/compat_report/hdf5-1.14.2-vs-hdf5-1.14.3-interface_compatibility_report.html">High-Level API Compatibility report for Release 1.14.3 versus Release 1.14.2</a>
\li <a href="https://\RELURL/v1_14/v1_14_3/downloads/compat_report/hdf5-1.14.2-vs-hdf5-1.14.3-java-interface_compatibility_report.html">Java API Compatibility report for Release 1.14.3 versus Release 1.14.2</a>
Following are the new APIs introduced in HDF5-1.14.3.
<h4>In the C Interface (main library)</h4>
\li #H5Pget_actual_selection_io_mode - Retrieves the type(s) of I/O performed on raw data
<h4>In the Fortran Interface</h4>
\li #h5lib.h5get_free_list_sizes_f - Gets the current size of the free lists used to manage memory
\li #h5d.h5dwrite_chunk_f - Writes a raw data chunk from a buffer directly to a dataset in a file
\li #h5d.h5dread_chunk_f - Reads a raw data chunk directly from a dataset in a file into a buffer
\li #h5f.h5fget_info_f - Retrieves global file information
\li #h5l.h5lvisit_f - Recursively visits all links starting from a specified group
\li #h5l.h5lvisit_by_name_f - Recursively visits all links starting from a specified group
\li #h5p.h5pget_no_selection_io_cause_f - Retrieves the cause for not performing selection or vector I/O on the last parallel I/O call
\li #h5p.h5pget_mpio_no_collective_cause_f - Retrieves local and global causes that broke collective I/O on the last parallel I/O call
\li #h5s.h5sselect_shape_same_f - Checks if two selections are the same shape
\li #h5s.h5sselect_intersect_block_f - Checks if current selection intersects with a block
\li #h5p.h5pget_file_space_page_size_f - Gets the file space page size for a file creation property list
\li #h5p.h5pset_file_space_page_size_f - Sets the file space page size for a file creation property list
\li #h5p.h5pget_file_space_strategy_f - Gets the file space handling strategy and persisting free-space values for a file creation property list
\li #h5p.h5pset_file_space_strategy_f - Sets the file space handling strategy and persisting free-space values for a file creation property list
In addition, there are other new Fortran functions including the Fortran async APIs
and the Fortran VOL capability definitions.
\subsection subsec_rel_spec_114_change_2versus1 Release 1.14.2 versus Release 1.14.1
This section lists interface-level changes and other user-visible changes in behavior in the transition from HDF5 Release 1.14.1 to Release 1.14.2.
\subsubsection subsubsec_rel_spec_114_change_2versus1_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
\li <a href="https://\RELURL/v1_14/v1_14_2/downloads/compat_report/hdf5-1.14.1-2-vs-hdf5-1.14.2-interface_compatibility_report.html">High-Level API Compatibility report for Release 1.14.2 versus Release 1.14.1</a>
\li <a href="https://\RELURL/v1_14/v1_14_2/downloads/compat_report/hdf5-1.14.1-vs-hdf5-1.14.2-java-interface_compatibility_report.html">Java API Compatibility report for Release 1.14.2 versus Release 1.14.1</a>
Following are the new APIs introduced in HDF5-1.14.2.
<h4>In the C Interface (main library)</h4>
\li #H5FDread_from_selection - Performs a series of scalar reads.
\li #H5FDread_vector_from_selection - Performs a vector read if vector reads are supported, or a series of scalar reads, otherwise.
\li #H5FDwrite_from_selection - Performs a series of scalar writes.
\li #H5FDwrite_vector_from_selection - Performs a vector write if vector writes are supported, or a series of scalar writes, otherwise.
\li #H5Pget_fapl_ros3\_token - Returns session/security token of the ros3 file access property list
\li #H5Pset_fapl_ros3\_token - Modifies the file access property list to use the H5FD_ROS3 driver
\subsection subsec_rel_spec_114_change_1versus0 Release 1.14.1 versus Release 1.14.0
This section lists interface-level changes and other user-visible changes in behavior in the
transition from HDF5 Release 1.14.0 to Release 1.14.1.
\subsubsection subsubsec_rel_spec_114_change_1versus0_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
\li <a href="https://\RELURL/v1_14/v1_14_1/downloads/compat_report/hdf5-1.14.0-vs-hdf5-1.14.1-interface_compatibility_report.html">High-Level API Compatibility report for Release 1.14.1 versus Release 1.14.0</a>
\li <a href="https://\RELURL/v1_14/v1_14_1/downloads/compat_report/hdf5-1.14.0-vs-hdf5-1.14.1-java-interface_compatibility_report.html">Java API Compatibility report for Release 1.14.1 versus Release 1.14.0</a>
Following are the new APIs introduced in HDF5-1.14.1.
<h4>In the C Interface (main library)</h4>
\li #H5Pget_modify_write_buf - Retrieves the "modify write buffer" property
\li #H5Pget_no_selection_io_cause - Retrieves the cause for not performing selection or vector I/O on the last parallel I/O call
\li #H5Pget_selection_io - Retrieves the selection I/O mode
\li #H5Pset_modify_write_buf - Allows the library to modify the contents of the write buffer
\li #H5Pset_selection_io - Sets the selection I/O mode
<h4>In the Fortran Interface</h4>
\li #h5p.h5pget_modify_write_buf_f - Retrieves the "modify write buffer" property
\li #h5p.h5pget_selection_io_f - Retrieves the selection I/O mode
\li #h5p.h5pset_modify_write_buf_f - Allows the library to modify the contents of the write buffer
\li #h5p.h5pset_selection_io_f - Sets the selection I/O mode
\subsection subsec_rel_spec_114_change_0versus12_2 Release 1.14.0 versus Release 1.12.2
HDF5 version 1.14.0 introduces the following new features:
\li Asynchronous I/O operations
\li New tools h5dwalk and h5delete
\li Subfiling VFD
\li Onion VFD
\li Multi Dataset I/O
Users might find these names familiar already and that is because they were introduced in the
experimental series 1.13.
In addition, this version provides many new C APIs and other user-visible changes in behavior
in the transition from HDF5 Release 1.12.2 to Release 1.14.0. HDF5 1.14.0 adds no new API calls
that require use of the API Compatibility Macros for the main library. Some calls have been
removed or have had their signature change, however.
\subsubsection subsubsec_rel_spec_114_change_0versus12_2_new New and Changed Functions, Classes, Subroutines, Wrappers, and Macros
\li <a href="https://\RELURL/v1_14/v1_14_0/downloads/compat_report/hdf5-1.12.2-vs-hdf5-1.14.0-interface_compatibility_report.html">High-Level API Compatibility report for Release 1.14.0 versus Release 1.12.2</a>
\li <a href="https://\RELURL/v1_14/v1_14_0/downloads/compat_report/hdf5-1.12.2-vs-hdf5-1.14.0-java-interface_compatibility_report.html">Java API Compatibility report for Release 1.14.0 versus Release 1.12.2</a>
<h4>In the C Interface (main library)</h4>
Following are the new APIs introduced in HDF5-1.14.0.
\li #H5Aclose_async - Asynchronous version of #H5Aclose
\li #H5Acreate_async - Asynchronous version of #H5Acreate
\li #H5Acreate_by_name_async - Asynchronous version of #H5Acreate_by_name
\li #H5Aexists_async - Asynchronous version of #H5Aexists
\li #H5Aexists_by_name_async - Asynchronous version of #H5Aexists_by_name
\li #H5Aopen_async - Asynchronous version of #H5Aopen
\li #H5Aopen_by_idx_async - Asynchronous version of #H5Aopen_by_idx
\li #H5Aopen_by_name_async - Asynchronous version of #H5Aopen_by_name
\li #H5Aread_async - Asynchronous version of #H5Aread
\li #H5Arename_async - Asynchronous version of #H5Arename
\li #H5Arename_by_name_async - Asynchronous version of #H5Arename_by_name
\li #H5Awrite_async - Asynchronous version of #H5Awrite
\li #H5Dchunk_iter - Iterate over all chunks of a chunked dataset
\li #H5Dclose_async - Asynchronous version of #H5Dclose
\li #H5Dcreate_async - Asynchronous version of #H5Dcreate
\li #H5Dget_space_async - Asynchronous version of #H5Dget_space
\li #H5Dopen_async - Asynchronous version of #H5Dopen
\li #H5Dread_async - Asynchronous version of #H5Dread
\li #H5Dread_multi - Reads raw data from a set of datasets into the provided buffers
\li #H5Dread_multi_async - Asynchronous version of #H5Dread_multi
\li #H5Dset_extent_async - Asynchronous version of #H5Dset_extent
\li #H5Dwrite_async - Asynchronous version of #H5Dwrite
\li #H5Dwrite_multi - Writes raw data from a set buffers to a set of datasets
\li #H5Dwrite_multi_async - Asynchronous version of #H5Dwrite_multi
\li #H5Eappend_stack - Appends one error stack to another, optionally closing the source stack
\li #H5EScancel - Attempt to cancel operations in an event set
\li #H5ESclose - Terminates access to an event set
\li #H5EScreate - Creates an event set
\li #H5ESfree_err_info - Convenience routine to free an array of #H5ES_err_info_t structs
\li #H5ESget_count - Retrieves number of events in an event set
\li #H5ESget_err_count - Retrieves the number of failed operations
\li #H5ESget_err_info - Retrieves information about failed operations
\li #H5ESget_err_status] - Checks for failed operations
\li #H5ESget_op_counter - Retrieves the accumulative operation counter for an event set
\li #H5ESregister_complete_func - Registers a callback to invoke when an operation completes within an event set
\li #H5ESregister_insert_func - Registers a callback to invoke when a new operation is inserted into
\li #H5ESwait - Waits for operations in event set to complete
\li #H5FDonion_get_revision_count - Gets the number of revisions
\li #H5Pget_fapl_onion - Gets the onion info from the file access property list
\li #H5Pset_fapl_onion - Sets the onion info for the file access property list
\li #H5Fclose_async - Asynchronous version of #H5Fclose
\li #H5Fcreate_async - Asynchronous version of #H5Fcreate
\li #H5Fflush_async - Asynchronous version of #H5Fflush
\li #H5Fopen_async - Asynchronous version of #H5Fopen
\li #H5Freopen_async - Asynchronous version of #H5Freopen
\li #H5Gclose_async - Asynchronous version of #H5Gclose
\li #H5Gcreate_async - Asynchronous version of #H5Gcreate
\li #H5Gget_info_async - Asynchronous version of #H5Gget_info
\li #H5Gget_info_by_idx_async - Asynchronous version of #H5Gget_info_by_idx
\li #H5Gget_info_by_name_async - Asynchronous version of #H5Gget_info_by_name
\li #H5Gopen_async - Asynchronous version of #H5Gopen
\li #H5Iregister_future - Registers a "future" object under a type and returns an ID for it
\li #H5Lcreate_hard_async - Asynchronous version of #H5Lcreate_hard
\li #H5Lcreate_soft_async - Asynchronous version of #H5Lcreate_soft
\li #H5Ldelete_async - Asynchronous version of #H5Ldelete
\li #H5Ldelete_by_idx_async - Asynchronous version of #H5Ldelete_by_idx
\li #H5Lexists_async - Asynchronous version of #H5Lexists
\li #H5Literate_async - Asynchronous version of #H5Literate
\li #H5Oclose_async - Asynchronous version of #H5Oclose
\li #H5Ocopy_async - Asynchronous version of #H5Ocopy
\li #H5Oflush_async - Asynchronous version of #H5Oflush
\li #H5Oget_info_by_name_async - Asynchronous version of #H5Oget_info_by_name
\li #H5Oopen_async - Asynchronous version of #H5Oopen
\li #H5Oopen_by_idx_async - Asynchronous version of #H5Oopen_by_idx
\li #H5Orefresh_async - Asynchronous version of #H5Orefresh
\li #H5Pget_driver_config_str - Retrieves a string representation of the configuration for the driver set on the given FAPL
\li #H5Pget_vol_cap_flags - Query the capability flags for the VOL connector that will be used with this file access property list (FAPL)
\li #H5Pset_dataset_io_hyperslab_selection - Sets a hyperslab file selection for a dataset I/O operation
\li #H5Pset_driver_by_name - Sets a file driver according to a given driver name
\li #H5Pset_driver_by_value - Sets a file driver according to a given driver value (ID)
\li #H5atclose - Registers a callback for the library to invoke when it's closing
\li #H5is_library_terminating - Checks whether the HDF5 library is closing
\li #H5Ropen_attr_async - Asynchronous version of #H5Ropen_attr
\li #H5Ropen_object_async - Asynchronous version of #H5Ropen_object
\li #H5Ropen_region_async - Asynchronous version of #H5Ropen_region
\li #H5Tclose_async - Asynchronous version of #H5Tclose
\li #H5Tcommit_async - Asynchronous version of #H5Tcommit2
\li #H5Topen_async - Asynchronous version of #H5Topen2
*/

BIN
doxygen/img/cgns.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
doxygen/img/writeLgNumDsets.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

6
hl/src/H5LDpublic.h
View File

@ -33,7 +33,7 @@ extern "C" {
* It will return failure if \p cur_dims is NULL.
*
* \note See Also:
* \note Dataset Watch functions (used with h5watch):
* \note Dataset Watch functions (used with \ref sec_cltools_h5watch):
* - H5LDget_dset_dims()
* - H5LDget_dset_elmts()
* - H5LDget_dset_type_size()
@ -70,7 +70,7 @@ H5_HLDLL herr_t H5LDget_dset_dims(hid_t did, hsize_t *cur_dims);
* conflict with these two separators.
*
* \note See Also:
* \note Dataset Watch functions (used with h5watch):
* \note Dataset Watch functions (used with \ref sec_cltools_h5watch):
* - H5LDget_dset_dims()
* - H5LDget_dset_elmts()
* - H5LDget_dset_type_size()
@ -122,7 +122,7 @@ H5_HLDLL size_t H5LDget_dset_type_size(hid_t did, const char *fields);
* two separators.
*
* \note See Also:
* \note Dataset Watch functions (used with h5watch):
* \note Dataset Watch functions (used with \ref sec_cltools_h5watch):
* - H5LDget_dset_dims()
* - H5LDget_dset_elmts()
* - H5LDget_dset_type_size()

14
src/H5Dmodule.h
View File

@ -881,7 +881,8 @@
* HDF5 Library that has the new filter as a part of the library.
*
* If a user of such data does not have a modified HDF5 Library installed on his system, command-line tools
* such as h5dump or h5ls will not be able to display the compressed data. Furthermore, it would be
* such as \ref sec_cltools_h5dump or \ref sec_cltools_h5ls will not be able to display the compressed data.
* Furthermore, it would be
* practically impossible to determine the compression method used, making the data stored in HDF5
* useless.
*
@ -1088,9 +1089,9 @@
*
* \subsection subsec_dataset_allocation Allocation of Space in the File
* When a dataset is created, space is allocated in the file for its header and initial data. The amount
of space allocated when the dataset is created depends on the storage properties. When the
dataset is modified (data is written, attributes added, or other changes), additional storage may be
allocated if necessary.
* of space allocated when the dataset is created depends on the storage properties. When the
* dataset is modified (data is written, attributes added, or other changes), additional storage may be
* allocated if necessary.
*
* <table>
* <caption>Initial dataset size</caption>
@ -1474,12 +1475,13 @@ allocated if necessary.
* reclaim the storage space occupied by a deleted object.
*
* Removing a dataset and reclaiming the space it used can be done with the #H5Ldelete function
* and the h5repack utility program. With the H5Ldelete function, links to a dataset can be removed
* and the \ref sec_cltools_h5repack utility program. With the H5Ldelete function, links to a dataset can be
* removed
* from the file structure. After all the links have been removed, the dataset becomes inaccessible to
* any application and is effectively removed from the file. The way to recover the space occupied
* by an unlinked dataset is to write all of the objects of the file into a new file. Any unlinked object
* is inaccessible to the application and will not be included in the new file. Writing objects to a
* new file can be done with a custom program or with the h5repack utility program.
* new file can be done with a custom program or with the \ref sec_cltools_h5repack utility program.
*
* For more information, @see @ref sec_group
*

20
src/H5Fmodule.h
View File

@ -214,12 +214,12 @@
* More comprehensive discussions regarding all of these steps are provided below.
*
* \subsection subsec_file_h5dump Using h5dump to View a File
* h5dump is a command-line utility that is included in the HDF5 distribution. This program
* \ref sec_cltools_h5dump is a command-line utility that is included in the HDF5 distribution. This program
* provides a straight-forward means of inspecting the contents of an HDF5 file. You can use
* h5dump to verify that a program is generating the intended HDF5 file. h5dump displays ASCII
* output formatted according to the HDF5 DDL grammar.
* \ref sec_cltools_h5dump to verify that a program is generating the intended HDF5 file. \ref
* sec_cltools_h5dump displays ASCII output formatted according to the HDF5 DDL grammar.
*
* The following h5dump command will display the contents of SampleFile.h5:
* The following \ref sec_cltools_h5dump command will display the contents of SampleFile.h5:
* \code
* h5dump SampleFile.h5
* \endcode
@ -235,7 +235,7 @@
*
* Note that the root group, indicated above by <b>/</b>, was automatically created when the file was created.
*
* h5dump is described on the
* \ref sec_cltools_h5dump is described on the
* \ref subsecViewToolsViewContent_h5dump
* page under
* \ref ViewToolsCommand.
@ -943,13 +943,14 @@
*
* <h4>Unix Tools and an HDF5 Utility</h4>
* It occasionally becomes necessary to repartition a file family. A command-line utility for this
* purpose, h5repart, is distributed with the HDF5 library.
* purpose, \ref sec_cltools_h5repart, is distributed with the HDF5 library.
*
* \code
* h5repart [-v] [-b block_size[suffix]] [-m member_size[suffix]] source destination
* \endcode
*
* h5repart repartitions an HDF5 file by copying the source file or file family to the destination file
* \ref sec_cltools_h5repart repartitions an HDF5 file by copying the source file or file family to
* the destination file
* or file family, preserving holes in the underlying UNIX files. Families are used for the source
* and/or destination if the name includes a printf-style integer format such as %d. The -v switch
* prints input and output file names on the standard error stream for progress monitoring, -b sets
@ -957,7 +958,7 @@
* family name (the default is 1GB). block_size and member_size may be suffixed with the letters
* g, m, or k for GB, MB, or KB respectively.
*
* The h5repart utility is described on the Tools page of the \ref RM.
* The \ref sec_cltools_h5repart utility is described on the Tools page of the \ref RM.
*
* An existing HDF5 file can be split into a family of files by running the file through split(1) on a
* UNIX system and numbering the output files. However, the HDF5 Library is lazy about
@ -965,7 +966,8 @@
* concatenation of the family members.
*
* Splitting the file and rejoining the segments by concatenation (split(1) and cat(1) on UNIX
* systems) does not generate files with holes; holes are preserved only through the use of h5repart.
* systems) does not generate files with holes; holes are preserved only through the use of \ref
* sec_cltools_h5repart.
*
* \subsubsection subsubsec_file_alternate_drivers_multi The Multi Driver
* In some circumstances, it is useful to separate metadata from raw data and some types of

9
src/H5Gmodule.h
View File

@ -317,15 +317,12 @@
* stored in either the original indexed format or the compact-or-indexed format.
*
* \subsection subsec_group_h5dump Using h5dump
* You can use h5dump, the command-line utility distributed with HDF5, to examine a file for
* You can use \ref sec_cltools_h5dump, the command-line utility distributed with HDF5, to examine a file for
* purposes either of determining where to create an object within an HDF5 file or to verify that
* you have created an object in the intended place.
*
* In the case of the new group created later in this chapter, the following h5dump command will
* display the contents of FileA.h5:
* \code
* h5dump FileA.h5
* \endcode
* In the case of the new group created later in this chapter, the following \ref sec_cltools_h5dump command
* will display the contents of FileA.h5: \code h5dump FileA.h5 \endcode
*
* For more information, @see @ref subsubsec_group_program_create.
*

7
src/H5Smodule.h
View File

@ -229,8 +229,8 @@
*
* When a C application reads data back, the dimensions will come out as 100 and 20, correctly describing
* the size of the array to read data into, since the data was written as 100 records of 20 elements each.
* Therefore C tools such as h5dump and h5ls always display transposed dimensions and values for the data
* written by a Fortran application.
* Therefore C tools such as \ref sec_cltools_h5dump and \ref sec_cltools_h5ls always display transposed
* dimensions and values for the data written by a Fortran application.
*
* Consider the following simple example of equivalent C 3 x 5 and Fortran 5 x 3 arrays. As illustrated in
* the figure below, a C application will store a 3 x 5 2‐dimensional array as three 5‐element rows. In order
@ -1387,7 +1387,8 @@
* \subsection subsec_dataspace_sample Sample Programs
*
* This section contains the full programs from which several of the code examples in this chapter were
* derived. The h5dump output from the program's output file immediately follows each program.
* derived. The \ref sec_cltools_h5dump output from the program's output file immediately follows each
program.
*
* <em>h5_write.c</em>
* \code

6
src/H5Tmodule.h
View File

@ -3445,7 +3445,7 @@ filled according to the value of this property. The padding can be:
* \li “T4”, a string
*
* Below the example code is a figure that shows this datatype as a logical tree. The output of the
* h5dump utility is shown in the example below the figure.
* \ref sec_cltools_h5dump utility is shown in the example below the figure.
*
* Each datatype is created as a separate datatype object. Figure "The storage layout for the
* four member datatypes" below shows the storage layout
@ -3522,7 +3522,7 @@ filled according to the value of this property. The padding can be:
* </tr>
* </table>
*
* <em> Output from h5dump for the compound datatype</em>
* <em> Output from \ref sec_cltools_h5dump for the compound datatype</em>
* \code
* DATATYPE H5T_COMPOUND {
* H5T_COMPOUND {
@ -3617,7 +3617,7 @@ filled according to the value of this property. The padding can be:
* its type is analyzed depending on the datatype class. Through this method, the complete storage
* layout can be discovered.
*
* <em> Output from h5dump for the compound datatype</em>
* <em> Output from \ref sec_cltools_h5dump for the compound datatype</em>
* \code
* s1_tid = H5Dget_type(dataset);
*

32
src/H5VLmodule.h
View File

@ -553,19 +553,19 @@
* so the h5o_info_t, etc. structs no longer contain native file format information
* and the callbacks will need to match the non-deprecated, token-enabled versions.
* <ul>
* <li>h5lget_info_f</li>
* <li>h5lget_info_by_idx f</li>
* <li>h5literate_f</li>
* <li>h5literate_by_name_f</li>
* <li>h5oget_info_f</li>
* <li>h5oget_info_by_idx_f</li>
* <li>h5oget_info_by_name_f</li>
* <li>h5oopen_by_token_f</li>
* <li>h5ovisit_f</li>
* <li>h5ovisit_by_name_f</li>
* <li>@ref h5l.h5lget_info_f</li>
* <li>@ref h5l.h5lget_info_by_idx_f</li>
* <li>@ref h5l.h5literate_f</li>
* <li>@ref h5l.h5literate_by_name_f</li>
* <li>@ref h5o.h5oget_info_f</li>
* <li>@ref h5o.h5oget_info_by_idx_f</li>
* <li>@ref h5o.h5oget_info_by_name_f</li>
* <li>@ref h5o.h5oopen_by_token_f</li>
* <li>@ref h5o.h5ovisit_f</li>
* <li>@ref h5o.h5ovisit_by_name_f</li>
* </ul>
*
* Additionally, h5fis_hdf5_f was updated to use \ref H5Fis_accessible internally,
* Additionally, \ref h5f.h5fis_hdf5_f was updated to use \ref H5Fis_accessible internally,
* though with the same caveat as the C++ implementation: the default fapl is
* always passed in so arbitrary VOL connectors will only work if the default VOL
* connector is changed via the environment variable.
@ -587,11 +587,11 @@
*
* \subsection subsec_vol_cl Using VOL Connectors With The HDF5 Command-Line Tools
* The following command-line tools are VOL-aware and can be used with arbitrary VOL connectors:
* \li (p)h5diff
* \li h5dump
* \li h5ls
* \li h5mkgrp
* \li h5repack
* \li (p)\ref sec_cltools_h5diff
* \li \ref sec_cltools_h5dump
* \li \ref sec_cltools_h5ls
* \li \ref sec_cltools_h5mkgrp
* \li \ref sec_cltools_h5repack
*
* The VOL connector can be set either using the #HDF5_VOL_CONNECTOR environment variable
* (see above) or via the command line. Each of the above tools

2
src/H5Zdevelop.h
View File

@ -249,7 +249,7 @@ extern "C" {
* H5Z_class2_t, depending on the needs of the application. To affect
* only this macro, H5Z_class_t_vers may be defined as either 1 or 2.
* Otherwise, it will behave in the same manner as other API
* compatibility macros. See API Compatibility Macros in HDF5 for more
* compatibility macros. See \ref api-compat-macros for more
* information. H5Z_class1_t matches the #H5Z_class_t structure that is
* used in the 1.6.x versions of the HDF5 library.
*

3
tools/src/h5jam/h5jam.h
View File

@ -14,7 +14,7 @@
/** \page H5TOOL_JAM_UG The HDF5 h5jam/h5unjam Tool
*
* \section sec_cltools_h5jam h5jam and h5unjam
* \section sec_cltools_h5jam h5jam
*
* \subsection subsec_cltools_h5jam_intro Introduction
* \li h5jam Adds user block to the front of an HDF5 file and creates a new concatenated file.
@ -41,6 +41,7 @@
* \li <strong>-h</strong> Prints a usage message and exits.
* \li <strong>-V</strong> Prints the HDF5 library version and exits.
*
* \section sec_cltools_h5unjam h5unjam
* \subsection subsec_cltools_h5unjam_options h5unjam Options
* \li <strong>-i in_file.h5</strong> Specifies the HDF5 as input. If the input HDF5 file
* contains no user block, exit with an error message.