diff options
34 files changed, 1506 insertions, 143 deletions
diff --git a/c++/src/H5Location.cpp b/c++/src/H5Location.cpp index 98da713..89e4fe1 100644 --- a/c++/src/H5Location.cpp +++ b/c++/src/H5Location.cpp @@ -1323,7 +1323,7 @@ H5Location::copyLink(const H5std_string &src_name, const H5std_string &dst_name, ///\note /// Exercise care in moving groups as it is possible to render /// data in a file inaccessible with H5Location::moveLink. Please refer -/// to the Group Interface in the HDF5 User's Guide for details. +/// to the Group Interface in the HDF5 User Guide for details. // March, 2018 //-------------------------------------------------------------------------- void @@ -1366,7 +1366,7 @@ H5Location::moveLink(const H5std_string &src_name, const Group &dst, const H5std ///\note /// Exercise care in moving groups as it is possible to render /// data in a file inaccessible with H5Location::moveLink. Please refer -/// to the Group Interface in the HDF5 User's Guide for details. +/// to the Group Interface in the HDF5 User Guide for details. // March, 2018 //-------------------------------------------------------------------------- void @@ -1406,7 +1406,7 @@ H5Location::moveLink(const H5std_string &src_name, const H5std_string &dst_name, ///\note /// Exercise care in moving groups as it is possible to render /// data in a file inaccessible with H5Location::move. Please refer -/// to the Group Interface in the HDF5 User's Guide for details. +/// to the Group Interface in the HDF5 User Guide for details. // Modification // 2007: QAK modified to use H5L APIs - BMR // 2018: Will be replaced by H5Location::moveLink() -BMR diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox index 53f64a7..155352a 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -1,4 +1,4 @@ -/** \page RM Reference Manual +/** \page RM HDF5 Reference Manual The functions provided by the HDF5 C-API are grouped into the following \Emph{modules}: diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox index 22fe5c6..0e2b4fd 100644 --- a/doxygen/dox/UsersGuide.dox +++ b/doxygen/dox/UsersGuide.dox @@ -1,4 +1,4 @@ -/** \page UG HDF5 User’s Guide +/** \page UG HDF5 User Guide <center> HDF5 Release 1.10 @@ -7,57 +7,214 @@ HDF5 Release 1.10 </center> -\section sec_data_model The HDF5 Data Model and File Structure - - <!-- @ref subsec_data_model_intro --> Introduction - - <!-- @ref subsec_data_model_abstract --> The Abstract Data Model - - <!-- @ref subsec_data_model_storage --> The HDF5 Storage Model - - <!-- @ref subsec_data_model_structure --> The Structure of an HDF5 File - -\section sec_program The HDF5 Library and Programming Model - - <!-- @ref subsec_program_intro --> Introduction - - <!-- @ref subsec_program_model --> The HDF5 Programming Model - - <!-- @ref subsec_program_transfer_pipeline --> The Data Transfer Pipeline - -\section sec_file The HDF5 File - - <!-- @ref subsec_file_intro --> Introduction - - <!-- @ref subsec_file_access_modes --> File Access Modes - - <!-- @ref subsec_file_creation_access --> File Creation and File Access Properties - - <!-- @ref subsec_file_drivers --> Low-level File Drivers - - <!-- @ref subsec_file_program_model --> "Programming Model for Files - - <!-- @ref subsec_file_h5dump --> Using h5dump to View a File - - <!-- @ref subsec_file_summary --> File Function Summaries - - <!-- @ref subsec_file_create --> Creating or Opening an HDF5 File - - <!-- @ref subsec_file_closes --> Closing an HDF5 File - - <!-- @ref subsec_file_property_lists --> File Property Lists - - <!-- @ref subsec_file_alternate_drivers --> Alternate File Storage Layouts and Low-level File Drivers - - <!-- @ref subsec_file_examples --> Code Examples for Opening and Closing Files - - <!-- @ref subsec_file_multiple --> Working with Multiple HDF5 Files - -\section sec_group HDF5 Groups - - <!-- @ref subsec_group_intro --> Introduction - - <!-- @ref subsec_group_descr --> Description of the Group Object - - <!-- @ref subsec_group_h5dump --> Using h5dump - - <!-- @ref subsec_group_function --> Group Function Summaries - - <!-- @ref subsec_group_program --> Programming Model for Groups - - <!-- @ref subsec_group_examples --> Examples of File Structures - -\section sec_dataset HDF5 Datasets - - <!-- @ref subsec_dataset_intro --> Introduction - - <!-- @ref subsec_dataset_function --> Dataset Function Summaries - - <!-- @ref subsec_dataset_program --> Programming Model for Datasets - - <!-- @ref subsec_dataset_transfer --> Data Transfer - - <!-- @ref subsec_dataset_allocation --> Allocation of Space in the File - - <!-- @ref subsec_dataset_filters --> Using HDF5 Filters - -\section sec_datatype HDF5 Datatypes - -\section sec_dataspace HDF5 Dataspaces and Partial I/O +\ref sec_data_model +\li \ref subsec_data_model_intro +\li \ref subsec_data_model_abstract + <ul> + <li> \ref subsubsec_data_model_abstract_file + <li> \ref subsubsec_data_model_abstract_group + <li> \ref subsubsec_data_model_abstract_dataset + <li> \ref subsubsec_data_model_abstract_space + <li> \ref subsubsec_data_model_abstract_type + <li> \ref subsubsec_data_model_abstract_attr + <li> \ref subsubsec_data_model_abstract_plist + <li> \ref subsubsec_data_model_abstract_link + </ul> +\li \ref subsec_data_model_storage + <ul> + <li> \ref subsubsec_data_model_storage_spec + <li> \ref subsubsec_data_model_storage_imple + </ul> +\li \ref subsec_data_model_structure + <ul> + <li> \ref subsubsec_data_model_structure_file + <li> \ref subsubsec_data_model_structure_path + <li> \ref subsubsec_data_model_structure_example + </ul> + +\ref sec_program +\li \ref subsec_program_intro +\li \ref subsec_program_model + <ul> + <li> \ref subsubsec_program_model_create + <li> \ref subsubsec_program_model_dset + <li> \ref subsubsec_program_model_close + <li> \ref subsubsec_program_model_data + <li> \ref subsubsec_program_model_partial + <li> \ref subsubsec_program_model_info + <li> \ref subsubsec_program_model_compound + <li> \ref subsubsec_program_model_extend + <li> \ref subsubsec_program_model_group + <li> \ref subsubsec_program_model_attr + </ul> +\li \ref subsec_program_transfer_pipeline + +\ref sec_file +\li \ref subsec_file_intro +\li \ref subsec_file_access_modes +\li \ref subsec_file_creation_access +\li \ref subsec_file_drivers +\li \ref subsec_file_program_model + <ul> + <li> \ref subsubsec_file_program_model_create + <li> \ref subsubsec_file_program_model_open + <li> \ref subsubsec_file_program_model_close + </ul> +\li \ref subsec_file_h5dump +\li \ref subsec_file_summary +\li \ref subsec_file_create +\li \ref subsec_file_closes +\li \ref subsec_file_property_lists + <ul> + <li> \ref subsubsec_file_property_lists_create + <li> \ref subsubsec_file_property_lists_props + <li> \ref subsubsec_file_property_lists_access + </ul> +\li \ref subsec_file_alternate_drivers + <ul> + <li> \ref subsubsec_file_alternate_drivers_id + <li> \ref subsubsec_file_alternate_drivers_sec2 + <li> \ref subsubsec_file_alternate_drivers_direct + <li> \ref subsubsec_file_alternate_drivers_log + <li> \ref subsubsec_file_alternate_drivers_win + <li> \ref subsubsec_file_alternate_drivers_stdio + <li> \ref subsubsec_file_alternate_drivers_mem + <li> \ref subsubsec_file_alternate_drivers_family + <li> \ref subsubsec_file_alternate_drivers_multi + <li> \ref subsubsec_file_alternate_drivers_split + <li> \ref subsubsec_file_alternate_drivers_par + </ul> +\li \ref subsec_file_examples + <ul> + <li> \ref subsubsec_file_examples_trunc + <li> \ref subsubsec_file_examples_props + <li> \ref subsubsec_file_examples_access + </ul> +\li \ref subsec_file_multiple + +\ref sec_group +\li \ref subsec_group_intro +\li \ref subsec_group_descr + <ul> + <li> \ref subsubsec_group_descr_object + <li> \ref subsubsec_group_descr_model + <li> \ref subsubsec_group_descr_path + <li> \ref subsubsec_group_descr_impl + </ul> +\li \ref subsec_group_h5dump +\li \ref subsec_group_function +\li \ref subsec_group_program + <ul> + <li> \ref subsubsec_group_program_create + <li> \ref subsubsec_group_program_open + <li> \ref subsubsec_group_program_dataset + <li> \ref subsubsec_group_program_close + <li> \ref subsubsec_group_program_links + <li> \ref subsubsec_group_program_info + <li> \ref subsubsec_group_program_objs + <li> \ref subsubsec_group_program_all + </ul> +\li \ref subsec_group_examples + +\ref sec_dataset +\li \ref subsec_dataset_intro +\li \ref subsec_dataset_function +\li \ref subsec_dataset_program + <ul> + <li> \ref subsubsec_dataset_program_general + <li> \ref subsubsec_dataset_program_create + <li> \ref subsubsec_dataset_program_transfer + <li> \ref subsubsec_dataset_program_read + </ul> +\li \ref subsec_dataset_transfer Data Transfer + <ul> + <li> \ref subsubsec_dataset_transfer_pipe + <li> \ref subsubsec_dataset_transfer_filter + <li> \ref subsubsec_dataset_transfer_drive + <li> \ref subsubsec_dataset_transfer_props + <li> \ref subsubsec_dataset_transfer_store + <li> \ref subsubsec_dataset_transfer_partial + </ul> +\li \ref subsec_dataset_allocation + <ul> + <li> \ref subsubsec_dataset_allocation_store + <li> \ref subsubsec_dataset_allocation_delete + <li> \ref subsubsec_dataset_allocation_release + <li> \ref subsubsec_dataset_allocation_ext + </ul> +\li \ref subsec_dataset_filters + <ul> + <li> \ref subsubsec_dataset_filters_nbit + <li> \ref subsubsec_dataset_filters_scale + <li> \ref subsubsec_dataset_filters_szip + </ul> + +\ref sec_datatype +\li \ref subsec_datatype_intro +\li \ref subsec_datatype_model + <ul> + <li> \ref subsubsec_datatype_model_class + <li> \ref subsubsec_datatype_model_predefine + </ul> +\li \ref subsec_datatype_usage + <ul> + <li> \ref subsubsec_datatype_usage_object + <li> \ref subsubsec_datatype_usage_create + <li> \ref subsubsec_datatype_usage_transfer + <li> \ref subsubsec_datatype_usage_discover + <li> \ref subsubsec_datatype_usage_user + </ul> +\li \ref subsec_datatype_function +\li \ref subsec_datatype_program + <ul> + <li> \ref subsubsec_datatype_program_discover + <li> \ref subsubsec_datatype_program_define + </ul> +\li \ref subsec_datatype_other + <ul> + <li> \ref subsubsec_datatype_other_strings + <li> \ref subsubsec_datatype_other_refs + <li> \ref subsubsec_datatype_other_enum + <li> \ref subsubsec_datatype_other_opaque + <li> \ref subsubsec_datatype_other_bitfield + </ul> +\li \ref subsec_datatype_fill +\li \ref subsec_datatype_complex + <ul> + <li> \ref subsubsec_datatype_complex_create + <li> \ref subsubsec_datatype_complex_analyze + </ul> +\li \ref subsec_datatype_life +\li \ref subsec_datatype_transfer +\li \ref subsec_datatype_text + +\ref sec_dataspace +\li \ref subsec_dataspace_intro +\li \ref subsec_dataspace_function +\li \ref subsec_dataspace_program + <ul> + <li> \ref subsubsec_dataspace_program_object + <li> \ref subsubsec_dataspace_program_model + </ul> +\li \ref subsec_dataspace_transfer + <ul> + <li> \ref subsubsec_dataspace_transfer_select + <li> \ref subsubsec_dataspace_transfer_model + </ul> +\li \ref subsec_dataspace_select +\li \ref subsec_dataspace_refer + <ul> + <li> \ref subsubsec_dataspace_refer_use + <li> \ref subsubsec_dataspace_refer_create + <li> \ref subsubsec_dataspace_refer_read + </ul> +\li \ref subsec_dataspace_sample \ref sec_attribute \li \ref subsec_attribute_intro \li \ref subsec_attribute_program <ul> - <li> <!-- @ref subsubsec_attribute_program_exist --> To Open and Read or Write an Existing Attribute + <li> <!-- \subsubsection subsubsec_attribute_program_exist --> To Open and Read or Write an Existing Attribute </li> </ul> \li \ref subsec_error_H5A \li \ref subsec_attribute_work @@ -91,9 +248,140 @@ HDF5 Release 1.10 <li> \ref subsubsec_error_adv_app </ul> -\section sec_plist Properties and Property Lists in HDF5 +\ref sec_plist +\li \ref subsec_plist_intro +\li \ref subsec_plist_class + <ul> + <li> \ref subsubsec_plist_class + <li> \ref subsubsec_plist_lists + <li> \ref subsubsec_plist_props + </ul> +\li \ref subsec_plist_program + <ul> + <li> \ref subsubsec_plist_default + <li> \ref subsubsec_plist_basic + <li> \ref subsubsec_plist_additional + </ul> +\li \ref subsec_plist_generic +\li \ref subsec_plist_H5P +\li \ref subsec_plist_resources +\li \ref subsec_plist_notes + +\ref sec_addition + +\page AR_UG Additional Resources \section sec_addition Additional Resources +These documents provide additional information for the use and tuning of specific HDF5 features. + <table style=" border-spacing:0; padding-left:6.00pt; padding-top:6.00pt; padding-right:6.00pt; padding-bottom:6.00pt; float:aligncenter; width:100%; max-width:432.00pt;" cellspacing="0"> + <caption x-list-start="1" style="font-size: 12.0pt;">Table of Additional resources</caption> + <tr style="height: 23.00pt;"> + <th style="width: 234.000pt; border-top-style: solid; border-top-width: 1px; border-top-color: #228a22; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align : top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Document</p> +</th> + <th style="width: 198.000pt; border-top-style: solid; border-top-width: 1px; border-top-color: #228a22; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align : top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Comments</p> +</th> +</tr> + <tr style="height: 23.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/examples/">HDF5 Examples</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Code examples by API. </p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/Chunking/index.html">Chunking in HDF5</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Structuring the use of chunking and tuning it for performance.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span class="FM_LT_LinkText"><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/DirectChunkWrite/UsingDirectChunkWrite.pdf">Using the Direct Chunk Write Function</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes another way that chunks can be written to datasets.</p> +</td> +</tr> + <tr style="height: 88.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/CommittedDatatypeCopying/CopyingCommittedDatatypesWithH5Ocopy.pdf">Copying Committed Datatypes with H5Ocopy</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how to copy to another file a dataset that uses a committed datatype or an object with an attribute that uses a committed datatype so that the committed datatype in the destination file can be used by multiple objects.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/MetadataCache/index.html">Metadata Caching in HDF5</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Managing the HDF5 metadata cache and tuning it for performance.</p> +</td> +</tr> + <tr style="height: 49.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/DynamicallyLoadedFilters/HDF5DynamicallyLoadedFilters.pdf">HDF5 Dynamically Loaded Filters</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how an HDF5 application can apply a filter that is not registered with the HDF5 Library.</p> +</td> +</tr> + <tr style="height: 62.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/FileImageOperations/HDF5FileImageOperations.pdf">HDF5 File Image Operations</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how to work with HDF5 files in memory. Disk I/O is not required when file images are opened, created, read from, or written to.</p> +</td> +</tr> + <tr style="height: 62.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/ModifiedRegionWrites/ModifiedRegionWrites.pdf">Modified Region Writes</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how to set write operations for in-memory files so that only modified regions are written to storage. Available when the Core (Memory) VFD is used.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/UsingIdentifiers/index.html">Using Identifiers</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how identifiers behave and how they should be treated.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/UsingUnicode/index.html">Using UTF-8 Encoding in HDF5 Applications</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes the use of UTF-8 Unicode character encodings in HDF5 applications.</p> +</td> +</tr> + <tr style="height: 49.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/FreeingMemory/FreeingMemoryAllocatedByTheHdf5Library.pdf">Freeing Memory Allocated by the HDF5 Library</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how inconsistent memory management can cause heap corruption or resource leaks and possible solutions.</p> +</td> +</tr> + <tr style="height: 23.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Glossary.html">HDF5 Glossary</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>A glossary of terms.</p> +</td> +</tr> + </table> + +Previous Chapter \ref sec_plist <!-- <table> @@ -136,7 +424,7 @@ HDF5 Release 1.10 </table> --> -\par Don't like what you see? - You can help to improve this User’s Guide +\par Don't like what you see? - You can help to improve this User Guide Complete the survey linked near the top of this page!\n We treat documentation like code: Fork the <a href="https://github.com/HDFGroup/hdf5">HDF5 repo</a>, make changes, and create a diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html index d2b6610..041cdb6 100644 --- a/doxygen/examples/H5.format.1.0.html +++ b/doxygen/examples/H5.format.1.0.html @@ -139,7 +139,7 @@ <p>This document describes the lower-level data objects; the higher-level objects and their properties are described - in the <a href="H5.user.html"><cite>HDF5 User's Guide</cite></a>. + in the <a href="H5.user.html"><cite>HDF5 User Guide</cite></a>. <!-- diff --git a/doxygen/examples/H5.format.1.1.html b/doxygen/examples/H5.format.1.1.html index b91ac90..4b6d42d 100644 --- a/doxygen/examples/H5.format.1.1.html +++ b/doxygen/examples/H5.format.1.1.html @@ -172,7 +172,7 @@ TABLE.list TD { border:none; } <p>This document describes the lower-level data objects; the higher-level objects and their properties are described - in the <a href="H5.user.html"><cite>HDF5 User's Guide</cite></a>. + in the <a href="H5.user.html"><cite>HDF5 User Guide</cite></a>. <P>Three levels of information comprise the file format. Level 0 contains basic information for identifying and diff --git a/doxygen/examples/H5.format.2.0.html b/doxygen/examples/H5.format.2.0.html index 4a5fe37..242fdea 100644 --- a/doxygen/examples/H5.format.2.0.html +++ b/doxygen/examples/H5.format.2.0.html @@ -357,7 +357,7 @@ div { page-break-inside:avoid; <p>This document describes the lower-level data objects; the higher-level objects and their properties are described - in the <a href="UG/HDF5_Users_Guide-Responsive HTML5/index.html"><cite>HDF5 User’s Guide</cite></a>.</p> + in the <a href="UG/HDF5_User_Guide-Responsive HTML5/index.html"><cite>HDF5 User Guide</cite></a>.</p> <p>Three levels of information comprise the file format. Level 0 contains basic information for identifying and @@ -12861,9 +12861,9 @@ Pipeline Message</a></h4> datatypes).</p> <p>In 1.8.x versions of the library, attributes can be larger than 64KB. See the - <a href="UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FAttributes%2FHDF5_Attributes.htm%3Frhtocid%3Dtoc8.2_1%23TOC_8_5_Special_Issuesbc-13"> + <a href="UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_User_Guide%2FAttributes%2FHDF5_Attributes.htm%3Frhtocid%3Dtoc8.2_1%23TOC_8_5_Special_Issuesbc-13"> “Special Issues”</a> section of the Attributes chapter - in the <cite>HDF5 User’s Guide</cite> for more information.</p> + in the <cite>HDF5 User Guide</cite> for more information.</p> <p>Note: Attributes on an object must have unique names: the HDF5 Library currently enforces this by causing the creation of an attribute with a duplicate name to fail. diff --git a/doxygen/examples/H5.format.html b/doxygen/examples/H5.format.html index cbcb387..378f7a3 100644 --- a/doxygen/examples/H5.format.html +++ b/doxygen/examples/H5.format.html @@ -418,7 +418,7 @@ <p>This document describes the lower-level data objects; the higher-level objects and their properties are described - in the <a href="UG/HDF5_Users_Guide-Responsive HTML5/index.html"><cite>HDF5 User’s Guide</cite></a>.</p> + in the <a href="UG/HDF5_User_Guide-Responsive HTML5/index.html"><cite>HDF5 User Guide</cite></a>.</p> <p>Three levels of information comprise the file format. Level 0 contains basic information for identifying and @@ -14647,9 +14647,9 @@ Data Layout message. datatypes).</p> <p>In 1.8.x versions of the library, attributes can be larger than 64KB. See the - <a href="UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FAttributes%2FHDF5_Attributes.htm%3Frhtocid%3Dtoc8.2_1%23TOC_8_5_Special_Issuesbc-13"> + <a href="UG/HDF5_User_Guide-Responsive%20HTML5/index.html#t=HDF5_User_Guide%2FAttributes%2FHDF5_Attributes.htm%3Frhtocid%3Dtoc8.2_1%23TOC_8_5_Special_Issuesbc-13"> “Special Issues”</a> section of the Attributes chapter - in the <cite>HDF5 User’s Guide</cite> for more information.</p> + in the <cite>HDF5 User Guide</cite> for more information.</p> <p>Note: Attributes on an object must have unique names: the HDF5 Library currently enforces this by causing the creation of an attribute with a duplicate name to fail. diff --git a/doxygen/img/PropListClassInheritance.gif b/doxygen/img/PropListClassInheritance.gif Binary files differnew file mode 100644 index 0000000..c6f0309 --- /dev/null +++ b/doxygen/img/PropListClassInheritance.gif diff --git a/doxygen/img/PropListEcosystem.gif b/doxygen/img/PropListEcosystem.gif Binary files differnew file mode 100644 index 0000000..cf77ba4 --- /dev/null +++ b/doxygen/img/PropListEcosystem.gif diff --git a/java/examples/groups/H5Ex_G_Traverse.java b/java/examples/groups/H5Ex_G_Traverse.java index 4b27629..dcb664a 100644 --- a/java/examples/groups/H5Ex_G_Traverse.java +++ b/java/examples/groups/H5Ex_G_Traverse.java @@ -17,7 +17,7 @@ the recursion will not enter an infinite loop, but does not prevent objects from being visited more than once. The program prints the directory structure of the file specified in FILE. The default file used by this example -implements the structure described in the User's Guide, +implements the structure described in the User Guide, chapter 4, figure 26. ************************************************************/ package examples.groups; diff --git a/java/examples/groups/H5Ex_G_Visit.java b/java/examples/groups/H5Ex_G_Visit.java index 1f1f70a..593b9cc 100644 --- a/java/examples/groups/H5Ex_G_Visit.java +++ b/java/examples/groups/H5Ex_G_Visit.java @@ -15,7 +15,7 @@ using H5Ovisit and H5Lvisit. The program prints all of the objects in the file specified in FILE, then prints all of the links in that file. The default file used by this - example implements the structure described in the User's + example implements the structure described in the User Guide, chapter 4, figure 26. ************************************************************/ package examples.groups; diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h index c853794..ad25de0 100644 --- a/src/H5ACpublic.h +++ b/src/H5ACpublic.h @@ -567,7 +567,7 @@ typedef struct H5AC_cache_config_t { * The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to * start in the serial case. In the parallel case, a larger value is needed * -- see the overview of the metadata cache in the - * “Metadata Caching in HDF5” section of the -- <em>HDF5 User’s Guide</em> + * “Metadata Caching in HDF5” section of the -- <em>\ref UG</em> * for details. */ size_t max_size; diff --git a/src/H5Amodule.h b/src/H5Amodule.h index b973304..62851ff 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -361,7 +361,9 @@ * \li No special storage capability is provided for attributes: there is no compression or chunking, and * attributes are not extendable * - * \defgroup H5A H5A + * Previous Chapter \ref sec_dataspace - Next Chapter \ref sec_error + * + * \defgroup H5A H5A Attributes * * An HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data * object. A primary data object may be a dataset, group, or committed datatype. diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index 596fd48..d23d34a 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -29,7 +29,35 @@ #define H5_MY_PKG_ERR H5E_DATASET #define H5_MY_PKG_INIT YES -/**\defgroup H5D H5D +/** \page H5D_UG HDF5 Datasets + * + * \section sec_dataset HDF5 Datasets + * \subsection subsec_dataset_intro Introduction + * \subsection subsec_dataset_function Dataset Function Summaries + * \subsection subsec_dataset_program Programming Model for Datasets + * \subsubsection subsubsec_dataset_program_general General Model + * \subsubsection subsubsec_dataset_program_create Create Dataset + * \subsubsection subsubsec_dataset_program_transfer Data Transfer Operations on a Dataset + * \subsubsection subsubsec_dataset_program_read Retrieve the Properties of a Dataset + * \subsection subsec_dataset_transfer Data Transfer + * \subsubsection subsubsec_dataset_transfer_pipe The Data Pipeline + * \subsubsection subsubsec_dataset_transfer_filter Data Pipeline Filters + * \subsubsection subsubsec_dataset_transfer_drive File Drivers + * \subsubsection subsubsec_dataset_transfer_props Data Transfer Properties to Manage the Pipeline + * \subsubsection subsubsec_dataset_transfer_store Storage Strategies + * \subsubsection subsubsec_dataset_transfer_partial Partial I/O Sub‐setting and Hyperslabs + * \subsection subsec_dataset_allocation Allocation of Space in the File + * \subsubsection subsubsec_dataset_allocation_store Storage Allocation in the File: Early, Incremental, Late + * \subsubsection subsubsec_dataset_allocation_delete Deleting a Dataset from a File and Reclaiming Space + * \subsubsection subsubsec_dataset_allocation_release Releasing Memory Resources + * \subsubsection subsubsec_dataset_allocation_ext External Storage Properties + * \subsection subsec_dataset_filters Using HDF5 Filters + * \subsubsection subsubsec_dataset_filters_nbit N‐bit Filter + * \subsubsection subsubsec_dataset_filters_scale Scale‐offset Filter + * \subsubsection subsubsec_dataset_filters_szip Szip Filter + */ + +/**\defgroup H5D H5D Datasets * * Use the functions in this module to manage HDF5 datasets, including the * transfer of data between memory and disk and the description of dataset diff --git a/src/H5Emodule.h b/src/H5Emodule.h index e9f2aab..f3edebd 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -578,7 +578,9 @@ * </tr> * </table> * - * \defgroup H5E H5E + * Previous Chapter \ref sec_attribute - Next Chapter \ref sec_plist + * + * \defgroup H5E H5E Error Handling * * \internal The \c FUNC_ENTER macro clears the error stack whenever an * interface function is entered. When an error is detected, an entry diff --git a/src/H5FDfamily.h b/src/H5FDfamily.h index 20ef532..d07d659 100644 --- a/src/H5FDfamily.h +++ b/src/H5FDfamily.h @@ -39,7 +39,7 @@ H5_DLL hid_t H5FD_family_init(void); * each family member * \returns \herr_t * - * \details H5Pset_fapl_family() sets the file access property list identifier, + * \details H5Pset_fapl_family sets the file access property list identifier, * \p fapl_id, to use the family driver. * * \p memb_size is the size in bytes of each file member. This size @@ -71,7 +71,7 @@ H5_DLL herr_t H5Pset_fapl_family(hid_t fapl_id, hsize_t memb_size, hid_t memb_fa * each family member * \returns \herr_t * - * \details H5Pget_fapl_family() returns file access property list for use with + * \details H5Pget_fapl_family returns file access property list for use with * the family driver. This information is returned through the output * parameters. * diff --git a/src/H5FDmulti.h b/src/H5FDmulti.h index 62cc9c8..defaa84 100644 --- a/src/H5FDmulti.h +++ b/src/H5FDmulti.h @@ -172,7 +172,7 @@ H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const * \param[out] relax Allows read-only access to incomplete file sets when \c TRUE * \returns \herr_t * - * \details H5Pget_fapl_multi() returns information about the multi-file access + * \details H5Pget_fapl_multi returns information about the multi-file access * property list. * * \since 1.4.0 @@ -193,7 +193,7 @@ H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid * \param[in] raw_plist_id * \returns \herr_t * - * \details H5Pset_fapl_split() is a compatibility function that enables the + * \details H5Pset_fapl_split is a compatibility function that enables the * multi-file driver to emulate the split driver from HDF5 Releases 1.0 * and 1.2. The split file driver stored metadata and raw data in * separate files but provided no mechanism for separating types of diff --git a/src/H5FDsec2.h b/src/H5FDsec2.h index 541ac71..773f968 100644 --- a/src/H5FDsec2.h +++ b/src/H5FDsec2.h @@ -26,7 +26,21 @@ extern "C" { #endif -H5_DLL hid_t H5FD_sec2_init(void); +H5_DLL hid_t H5FD_sec2_init(void); +/** + * \ingroup FAPL + * + * \brief Sets the sec2 driver + * + * \fapl_id + * \returns \herr_t + * + * \details H5Pset_fapl_sec2 modifies the file access property list to use + * the sec2 driver, H5FDsec2. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_sec2(hid_t fapl_id); #ifdef __cplusplus diff --git a/src/H5FDstdio.h b/src/H5FDstdio.h index 9db92ed..42cd6a0 100644 --- a/src/H5FDstdio.h +++ b/src/H5FDstdio.h @@ -37,8 +37,8 @@ H5_DLL hid_t H5FD_stdio_init(void); * \fapl_id * \returns \herr_t * - * \details H5Pset_fapl_stdio() modifies the file access property list to use - * the standard I/O driver, H5FDstdio(). + * \details H5Pset_fapl_stdio modifies the file access property list to use + * the standard I/O driver, H5FDstdio. * * \since 1.4.0 * diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index 81c1ede..9d06265 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -29,7 +29,46 @@ #define H5_MY_PKG_ERR H5E_FILE #define H5_MY_PKG_INIT YES -/**\defgroup H5F H5F +/** \page H5F_UG The HDF5 File + * + * \section sec_file The HDF5 File + * \subsection subsec_file_intro Introduction + * \subsection subsec_file_access_modes File Access Modes + * \subsection subsec_file_creation_access File Creation and File Access Properties + * \subsection subsec_file_drivers Low-level File Drivers + * \subsection subsec_file_program_model Programming Model for Files + * \subsubsection subsubsec_file_program_model_create Creating a New File + * \subsubsection subsubsec_file_program_model_open Opening an Existing File + * \subsubsection subsubsec_file_program_model_close Closing a File + * \subsection subsec_file_h5dump Using h5dump to View a File + * \subsection subsec_file_summary File Function Summaries + * \subsection subsec_file_create Creating or Opening an HDF5 File + * \subsection subsec_file_closes Closing an HDF5 File + * \subsection subsec_file_property_lists File Property Lists + * \subsubsection subsubsec_file_property_lists_create Creating a Property List + * \subsubsection subsubsec_file_property_lists_props File Creation Properties + * \subsubsection subsubsec_file_property_lists_access File Access Properties + * \subsection subsec_file_alternate_drivers Alternate File Storage Layouts and Low-level File Drivers + * \subsubsection subsubsec_file_alternate_drivers_id Identifying the Previously‐used File Driver + * \subsubsection subsubsec_file_alternate_drivers_sec2 The POSIX (aka SEC2) Driver + * \subsubsection subsubsec_file_alternate_drivers_direct The Direct Driver + * \subsubsection subsubsec_file_alternate_drivers_log The Log Driver + * \subsubsection subsubsec_file_alternate_drivers_win The Windows Driver + * \subsubsection subsubsec_file_alternate_drivers_stdio The STDIO Driver + * \subsubsection subsubsec_file_alternate_drivers_mem The Memory (aka Core) Driver + * \subsubsection subsubsec_file_alternate_drivers_family The Family Driver + * \subsubsection subsubsec_file_alternate_drivers_multi The Multi Driver + * \subsubsection subsubsec_file_alternate_drivers_split The Split Driver + * \subsubsection subsubsec_file_alternate_drivers_par The Parallel Driver + * \subsection subsec_file_examples Code Examples for Opening and Closing Files + * \subsubsection subsubsec_file_examples_trunc Example Using the H5F_ACC_TRUNC Flag + * \subsubsection subsubsec_file_examples_props Example with the File Creation Property List + * \subsubsection subsubsec_file_examples_access Example with the File Access Property List + * \subsection subsec_file_multiple Working with Multiple HDF5 Files + * + */ + +/**\defgroup H5F H5F File * * Use the functions in this module to manage HDF5 files. * diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index a0e121d..d1aaa28 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -29,7 +29,31 @@ #define H5_MY_PKG_ERR H5E_SYM #define H5_MY_PKG_INIT YES -/** \defgroup H5G H5G +/** \page H5G_UG HDF5 Groups + * + * \section sec_group HDF5 Groups + * \subsection subsec_group_intro Introduction + * \subsection subsec_group_descr Description of the Group Object + * \subsubsection subsubsec_group_descr_object The Group Object + * \subsubsection subsubsec_group_descr_model The Hierarchy of Data Objects + * \subsubsection subsubsec_group_descr_path HDF5 Path Names + * \subsubsection subsubsec_group_descr_impl Group Implementations in HDF5 + * \subsection subsec_group_h5dump Using h5dump + * \subsection subsec_group_function Group Function Summaries + * \subsection subsec_group_program Programming Model for Groups + * \subsubsection subsubsec_group_program_create Creating a Group + * \subsubsection subsubsec_group_program_open Opening a Group and Accessing an Object in that Group + * \subsubsection subsubsec_group_program_dataset Creating a Dataset in a Specific Group + * \subsubsection subsubsec_group_program_close Closing a Group + * \subsubsection subsubsec_group_program_links Creating Links + * \subsubsection subsubsec_group_program_info Discovering Information about Objects + * \subsubsection subsubsec_group_program_objs Discovering Objects in a Group + * \subsubsection subsubsec_group_program_all Discovering All of the Objects in the File + * \subsection subsec_group_examples Examples of File Structures + * + */ + +/** \defgroup H5G H5G Groups * * Use the functions in this module to manage HDF5 groups. * diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index 1d8f8fb..b91c09c 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -660,7 +660,7 @@ H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, * * \attention Exercise care in moving groups as it is possible to render data in * a file inaccessible with H5Gmove(). See The Group Interface in the - * HDF5 User's Guide. + * \ref UG. * * \version 1.8.0 Function deprecated in this release. * @@ -691,7 +691,7 @@ H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_na * * \attention Exercise care in moving groups as it is possible to render data in * a file inaccessible with H5Gmove2(). See The Group Interface in the - * HDF5 User's Guide. + * \ref UG. * * \version 1.8.0 Function deprecated in this release. * @@ -728,11 +728,11 @@ H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, * Note that space identified as freespace is available for re-use only * as long as the file remains open; once a file has been closed, the * HDF5 library loses track of freespace. See “Freespace Management” in - * the HDF5 User's Guide for further details. + * the \ref UG for further details. * * \attention Exercise care in moving groups as it is possible to render data in * a file inaccessible with H5Gunlink(). See The Group Interface in the - * HDF5 User's Guide. + * \ref UG. * * \version 1.8.0 Function deprecated in this release. * diff --git a/src/H5Imodule.h b/src/H5Imodule.h index d77591d..1c5a230 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -29,7 +29,7 @@ #define H5_MY_PKG_ERR H5E_ATOM #define H5_MY_PKG_INIT NO -/**\defgroup H5I H5I +/**\defgroup H5I H5I Identifiers * * Use the functions in this module to manage identifiers defined by the HDF5 * library. See \ref H5IUD for user-defined identifiers and identifier diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index cffd25c..54aeae2 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -29,7 +29,7 @@ #define H5_MY_PKG_ERR H5E_LINK #define H5_MY_PKG_INIT YES -/**\defgroup H5L H5L +/**\defgroup H5L H5L Links * * Use the functions in this module to manage HDF5 links and link types. * diff --git a/src/H5Omodule.h b/src/H5Omodule.h index 8afba29..fe127d6 100644 --- a/src/H5Omodule.h +++ b/src/H5Omodule.h @@ -29,7 +29,7 @@ #define H5_MY_PKG_ERR H5E_OHDR #define H5_MY_PKG_INIT YES -/**\defgroup H5O H5O +/**\defgroup H5O H5O Objects * * Use the functions in this module to manage HDF5 objects. * diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 5eddb7e..3d77801 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -270,7 +270,7 @@ H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id); * The object’s address within the file, \p addr, is the byte offset of the first byte * of the object header from the beginning of the HDF5 file space, i.e., from the * beginning of the super block (see the “HDF5 Storage Model” section of the The - * HDF5 Data Model and File Structure chapter of the <em>HDF5 User's Guide</em>.) + * HDF5 Data Model and File Structure chapter of the <em>\ref UG</em>.) * * \p addr can be obtained via either of two function calls. H5Gget_objinfo() returns * the object’s address in the \c objno field of the H5G_stat_t \c struct; @@ -652,7 +652,7 @@ H5_DLL herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_ * * An object’s reference count is the number of hard links in the * file that point to that object. See the “Programming Model” - * section of the HDF5 Groups chapter in the -- <em>HDF5 User’s Guide</em> + * section of the HDF5 Groups chapter in the -- <em>\ref UG</em> * for a more complete discussion of reference counts. * * If a user application needs to determine an object’s reference @@ -687,7 +687,7 @@ H5_DLL herr_t H5Oincr_refcount(hid_t object_id); * * An object’s reference count is the number of hard links in the * file that point to that object. See the “Programming Model” - * section of the HDF5 Groups chapter in the <em>HDF5 User’s Guide</em> + * section of the HDF5 Groups chapter in the <em>\ref UG</em> * for a more complete discussion of reference counts. * * If a user application needs to determine an object’s reference diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index 8076205..9c076fe 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -27,7 +27,7 @@ #define H5_MY_PKG_ERR H5E_PLUGIN #define H5_MY_PKG_INIT YES -/**\defgroup H5PL H5PL +/**\defgroup H5PL H5PL Plugins * * Use the functions in this module to manage the loading behavior of HDF5 * plugins. diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index 8081ee3..5bd45a2 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -29,7 +29,849 @@ #define H5_MY_PKG_ERR H5E_PLIST #define H5_MY_PKG_INIT YES -/**\defgroup H5P H5P +/** \page H5P_UG Properties and Property Lists in HDF5 + * + * \section sec_plist Properties and Property Lists in HDF5 + * + * HDF5 property lists are the main vehicle to configure the + * behavior of HDF5 API functions. + * + * Typically, property lists are created by instantiating one of the built-in + * or user-defined property list classes. After adding suitable properties, + * property lists are used when opening or creating HDF5 items, or when reading + * or writing data. Property lists can be modified by adding or changing + * properties. Property lists are deleted by closing the associated handles. + * + * \subsection subsec_plist_intro Introduction + * + * HDF5 properties and property lists make it possible to shape or modify an HDF5 file, group, + * dataset, attribute, committed datatype, or even an I/O stream, in a number of ways. For example, + * you can do any of the following: + * \li Customize the storage layout of a file to suit a project or task. + * \li Create a chunked dataset. + * \li Apply compression or filters to raw data. + * \li Use either ASCII or UTF-8 character encodings. + * \li Create missing groups on the fly. + * \li Switch between serial and parallel I/O. + * \li Create consistency within a single file or across an international project. + * + * Some properties enable an HDF5 application to take advantage of the capabilities of a specific + * computing environment while others make a file more compact; some speed the reading or + * writing of data while others enable more record-keeping at a per-object level. HDF5 offers + * nearly one hundred specific properties that can be used in literally thousands of combinations to + * maximize the usability of HDF5-stored data. + * + * At the most basic level, a property list is a collection of properties, represented by name/value + * pairs that can be passed to various HDF5 functions, usually modifying default settings. A + * property list inherits a set of properties and values from a property list class. But that statement + * hardly provides a complete picture; in the rest of this section and in the next section, + * \ref subsec_plist_class , we will discuss these things in much more detail. + * After reading that material, the reader should have a reasonably complete understanding of how + * properties and property lists can be used in HDF5 applications. + * + * \image html PropListEcosystem.gif "The HDF5 property environment" + * + * The remaining sections in this chapter discuss the following topics: + * \li What are properties, property lists, and property list classes? + * \li Property list programming model + * \li Generic property functions + * \li Summary listings of property list functions + * \li Additional resources + * + * The discussions and function listings in this chapter focus on general property operations, object + * and link properties, and related functions. + * + * File, group, dataset, datatype, and attribute properties are discussed in the chapters devoted to + * those features, where that information will be most convenient to users. For example, \ref sec_dataset + * discusses dataset creation property lists and functions, dataset access property lists and + * functions, and dataset transfer property lists and functions. This chapter does not duplicate those + * discussions. + * + * Generic property operations are an advanced feature and are beyond the scope of this guide. + * + * This chapter assumes an understanding of the following chapters of this \ref UG + * \li \ref sec_data_model + * \li \ref sec_program + * + * \subsection subsec_plist_class Property List Classes, Property Lists, and Properties + * + * HDF5 property lists and the property list interface \ref H5P provide a mechanism for storing + * characteristics of objects in an HDF5 file and economically passing them around in an HDF5 + * application. In this capacity, property lists significantly reduce the burden of additional function + * parameters throughout the HDF5 API. Another advantage of property lists is that features can + * often be added to HDF5 by adding only property list functions to the API; this is particularly true + * when all other requirements of the feature can be accomplished internally to the library. + * + * For instance, a file creation operation needs to know several things about a file, such as the size + * of the userblock or the sizes of various file data structures. Bundling this information as a + * property list simplifies the interface by reducing the number of parameters to the function + * \ref H5Fcreate. + * + * As illustrated in the figure above ("The HDF5 property environment"), the HDF5 property + * environment is a three-level hierarchy: + * \li Property list classes + * \li Property lists + * \li Properties + * + * The following subsections discuss property list classes, property lists, and properties in more detail. + * + * \subsubsection subsubsec_plist_class Property List Classes + * + * A property list class defines the roles that property lists of that class can play. Each class includes + * all properties that are valid for that class with each property set to its default value. HDF5 offers + * a property lists class for each of the following situations. + * + * <table> + * <caption align=top>Property list classes in HDF5</caption> + * <tr><th>Property List Class</th><th></th><th>For further discussion</th></tr> + * <tr valign="top"> + * <td> + * File creation (FCPL) + * </td> + * <td> + * \ref H5P_FILE_CREATE + * </td> + * <td> + * See various sections of \ref sec_file + * </td> + * <tr valign="top"> + * <td> + * File access (FAPL) + * </td> + * <td> + * \ref H5P_FILE_ACCESS + * </td> + * <td> + * Used only as \ref H5P_DEFAULT. + * </td> + * </tr> + * <tr valign="top"> + * <td> + * File mount (FMPL) + * </td> + * <td> + * \ref H5P_FILE_MOUNT + * </td> + * <td> + * For more information, see \ref FileMountProps "File Mount Properties" + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Object creation (OCPL) + * </td> + * <td> + * \ref H5P_OBJECT_CREATE + * </td> + * <td> + * See \ref OCPL + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Object copy (OCPYPL) + * </td> + * <td> + * \ref H5P_OBJECT_COPY + * </td> + * <td> + * + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Group creation (GCPL) + * </td> + * <td> + * \ref H5P_GROUP_CREATE + * </td> + * <td> + * See \ref subsec_group_program + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Group access (GAPL) + * </td> + * <td> + * \ref H5P_GROUP_ACCESS + * </td> + * <td> + * + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Link creation (LCPL) + * </td> + * <td> + * \ref H5P_LINK_CREATE + * </td> + * <td> + * See examples in \ref subsec_plist_program and \ref LCPL + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Link access (LAPL) + * </td> + * <td> + * \ref H5P_LINK_ACCESS + * </td> + * <td> + * + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Dataset creation (DCPL) + * </td> + * <td> + * \ref H5P_DATASET_CREATE + * </td> + * <td> + * See \ref subsec_dataset_program + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Dataset access (DAPL) + * </td> + * <td> + * \ref H5P_DATASET_ACCESS + * </td> + * <td> + * + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Dataset transfer (DXPL) + * </td> + * <td> + * \ref H5P_DATASET_XFER + * </td> + * <td> + * + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Datatype creation (TCPL) + * </td> + * <td> + * \ref H5P_DATATYPE_CREATE + * </td> + * <td> + * See various sections of \ref sec_datatype + * </td> + * </tr> + * <tr valign="top"> + * <td> + * String creation (STRCPL) + * </td> + * <td> + * \ref H5P_STRING_CREATE + * </td> + * <td> + * See \ref subsec_dataset_program and \ref subsec_datatype_program + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Attribute creation (ACPL) + * </td> + * <td> + * \ref H5P_ATTRIBUTE_CREATE + * </td> + * <td> + * See \ref subsec_attribute_work. + * </td> + * </tr> + * </table> + * + * Note: In the table above, the abbreviations to the right of each property list class name in this + * table are widely used in both HDF5 programmer documentation and HDF5 source code. For + * example, \ref FCPL (FCPL) is the file creation property list, \ref OCPL (OCPL) is the object creation + * property list, \ref OCPYPL (OCPYPL) is object copy property list, and \ref STRCPL (STRCPL) is the string + * creation property list. These abbreviations may appear in either uppercase or lowercase. + * + * The “HDF5 property list class inheritance hierarchy” figure, immediately following, illustrates + * the inheritance hierarchy of HDF5’s property list classes. Properties are defined at the root of the + * HDF5 property environment (\ref PLCR in the figure below). Property list + * classes then inherit properties from that root, either directly or indirectly through a parent class. + * In every case, a property list class inherits only the properties relevant to its role. For example, + * the \ref OCPL (OCPL) inherits all properties that are relevant to the + * creation of any object while the \ref GCPL (GCPL) inherits only those + * properties that are relevant to group creation. + * + * \image html PropListClassInheritance.gif "HDF5 property list class inheritance hierarchy" + * Note: In the figure above, property list classes displayed in black are directly accessible through + * the programming interface; the root of the property environment and the \ref STRCPL and \ref OCPL + * property list classes, in gray above, are not user-accessible. The red empty set symbol indicates + * that the \ref FMPL (FMPL) is an empty class; that is, it has no set table + * properties. For more information, see \ref FileMountProps "File Mount Properties". Abbreviations + * used in this figure are defined in the preceding table, “Property list classes in HDF5”. + * + * + * \subsubsection subsubsec_plist_lists Property Lists + * + * A property list is a collection of related properties that are used together in specific + * circumstances. A new property list created from a property list class inherits the properties of the + * property list class and each property’s default value. A fresh dataset creation property list, for + * example, includes all of the HDF5 properties relevant to the creation of a new dataset. + * + * Property lists are implemented as containers holding a collection of name/value pairs. Each pair + * specifies a property name and a value for the property. A property list usually contains + * information for one to many properties. + * + * HDF5’s default property values are designed to be reasonable for general use cases. Therefore, + * an application can often use a property list without modification. On the other hand, adjusting + * property list settings is a routine action and there are many reasons for an application to do so. + * + * A new property list may either be derived from a property list class or copied from an existing + * property list. When a property list is created from a property list class, it contains all the + * properties that are relevant to the class, with each property set to its default value. A new + * property list created by copying an existing property list will contain the same properties and + * property values as the original property list. In either case, the property values can be changed as + * needed through the HDF5 API. + * + * Property lists can be freely reused to create consistency. For example, a single set of file, group, + * and dataset creation property lists might be created at the beginning of a project and used to + * create hundreds, thousands, even millions, of consistent files, file structures, and datasets over + * the project’s life. When such consistency is important to a project, this is an economical means + * of providing it. + * + * \subsubsection subsubsec_plist_props Properties + * + * A property is the basic element of the property list hierarchy. HDF5 offers nearly one hundred + * properties controlling things ranging from file access rights, to the storage layout of a dataset, + * through optimizing the use of a parallel computing environment. + * + * Further examples include the following: + * <table> + * <tr><th>Purpose</th><th>Examples</th><th>Property List</th></tr> + * <tr valign="top"> + * <td> + * Specify the driver to be used to open a file + * </td> + * <td> + * A POSIX driver or an MPI IO driver + * </td> + * <td> + * \ref FAPL + * </td> + * <tr valign="top"> + * <td> + * Specify filters to be applied to a dataset + * </td> + * <td> + * Gzip compression or checksum evaluation + * </td> + * <td> + * \ref DCPL + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Specify whether to record key times associated with an object + * </td> + * <td> + * Creation time and/or last-modified time + * </td> + * <td> + * \ref OCPL + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Specify the access mode for a file opened via an external link + * </td> + * <td> + * Read-only or read-write + * </td> + * <td> + * \ref LAPL + * </td> + * </tr> + * </table> + * + * Each property is initialized with a default value. For each property, there are one or more + * dedicated H5Pset_*calls that can be used to change that value. + * + * <h4>Creation, access, and transfer properties:</h4> + * + * Properties fall into one of several major categories: creation properties, access properties, and + * transfer properties. + * + * Creation properties control permanent object characteristics. These characteristics must be + * established when an object is created, cannot change through the life of the object (they are + * immutable), and the property setting usually has a permanent presence in the file. + * + * <table> + * <caption align=top>Examples of creation properties include:</caption> + * <tr> + * <td> + * <p> + * Whether a dataset is stored in a compact, contiguous, or chunked layout <br /> + * <br /> + * The default for this dataset creation property (\ref H5Pset_layout) is that a dataset is + * stored in a contiguous block. This works well for datasets with a known size limit that + * will fit easily in system memory. <br /> + * <br /> + * A chunked layout is important if a dataset is to be compressed, to enable extending + * the dataset’s size, or to enable caching during I/O. <br /> + * <br /> + * A compact layout is suitable only for very small datasets because the raw data is + * stored in the object header. + * </p> + * </td> + * </tr> + * <tr> + * <td> + * <p> + * Creation of intermediate groups when adding an object to an HDF5 file<br /> + * <br /> + * This link creation property, \ref H5Pset_create_intermediate_group, enables an + * application to add an object in a file without having to know that the group or group + * hierarchy containing that object already exists. With this property set, HDF5 + * automatically creates missing groups. If this property is not set, an application must + * verify that each group in the path exists, and create those that do not, before creating + * the new object; if any group is missing, the create operation will fail. + * </p> + * </td> + * </tr> + * <tr> + * <td> + * <p> + * Whether an HDF5 file is a single file or a set of tightly related files that form a virtual + * HDF5 file<br /> + * <br /> + * Certain file creation properties enable the application to select one of several file + * layouts. Examples of the available layouts include a standard POSIX-compliant + * layout (\ref H5Pset_fapl_sec2), a family of files (\ref H5Pset_fapl_family), and a split file + * layout that separates raw data and metadata into separate files (\ref H5Pset_fapl_split). + * These and other file layout options are discussed in \ref subsec_file_alternate_drivers. + * </p> + * </td> + * </tr> + * <tr> + * <td> + * <p> + * To enable error detection when creating a dataset<br /> + * <br /> + * In settings where data integrity is vulnerable, it may be desirable to set + * checksumming when datasets are created (\ref H5Pset_fletcher32). A subsequent + * application will then have a means to verify data integrity when reading the dataset. + * </p> + * </td> + * </tr> + * </table> + * + * Access properties control transient object characteristics. These characteristics may change with + * the circumstances under which an object is accessed. + * + * <table> + * <caption align=top>Examples of access properties include:</caption> + * <tr> + * <td> + * <p> + * The driver used to open a file<br /> + * <br /> + * For example, a file might be created with the MPI I/O driver (\ref H5Pset_fapl_mpio) + * during high-speed data acquisition in a parallel computing environment. The same + * file might later be analyzed in a serial computing environment with I/O access + * handled through the serial POSIX driver (\ref H5Pset_fapl_sec2). + * </p> + * </td> + * </tr> + * <tr> + * <td> + * <p> + * Optimization settings in specialized environments<br /> + * <br /> + * Optimizations differ across computing environments and according to the needs of + * the task being performed, so are transient by nature. + * </p> + * </td> + * </tr> + * </table> + * + * Transfer properties apply only to datasets and control transient aspects of data I/O. These + * characteristics may change with the circumstances under which data is accessed. + * + * <table> + * <caption align=top>Examples of dataset transfer properties include:</caption> + * <tr> + * <td> + * <p> + * To enable error detection when reading a dataset<br /> + * <br /> + * If checksumming has been set on a dataset (with \ref H5Pset_fletcher32, in the dataset + * creation property list), an application reading that dataset can choose whether to check + * for data integrity (\ref H5Pset_edc_check). + * </p> + * </td> + * </tr> + * <tr> + * <td> + * <p> + * Various properties to optimize chunked data I/O on parallel computing systems<br /> + * <br /> + * HDF5 provides several properties for tuning I/O of chunked datasets in a parallel + * computing environment (\ref H5Pset_dxpl_mpio_chunk_opt, \ref H5Pset_dxpl_mpio_chunk_opt_num, + * \ref H5Pset_dxpl_mpio_chunk_opt_ratio, and \ref H5Pget_mpio_actual_chunk_opt_mode).<br /> + * <br /> + * Optimal settings differ due to the characteristics of a computing environment and due + * to an application’s data access patterns; even when working with the same file, these + * settings might change for every application and every platform. + * </p> + * </td> + * </tr> + * </table> + * + * \subsection subsec_plist_program Programming Model for Properties and Property Lists + * + * The programming model for HDF5 property lists is actually quite simple: + * \li Create a property list. + * \li Modify the property list, if required. + * \li Use the property list. + * \li Close the property list. + * + * There are nuances, of course, but that is the basic process. + * + * In some cases, you will not have to define property lists at all. If the default property settings are + * sufficient for your application, you can tell HDF5 to use the default property list. + * + * The following sections first discuss the use of default property lists, then each step of the + * programming model, and finally a few less frequently used property list operations. + * + * \subsubsection subsubsec_plist_default Using Default Property Lists + * + * Default property lists can simplify many routine HDF5 tasks because you do not always have to + * create every property list you use. + * + * An application that would be well-served by HDF5’s default property settings can use the default + * property lists simply by substituting the value \ref H5P_DEFAULT for a property list identifier. + * HDF5 will then apply the default property list for the appropriate property list class. + * + * For example, the function \ref H5Dcreate2 calls for a link creation property list, a dataset creation + * property list, and a dataset access property list. If the default properties are suitable for a dataset, + * this call can be made as + * \code + * dset_id = H5Dcreate2( loc_id, name, dtype_id, space_id, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT ); + * \endcode + * HDF5 will then apply the default link creation, dataset creation, and dataset access property lists + * correctly. + * + * Of course, you would not want to do this without considering where it is appropriate, as there + * may be unforeseen consequences. Consider, for example, the use of chunked datasets. Optimal + * chunking is quite dependent on the makeup of the dataset and the most common access patterns, + * both of which must be taken into account in setting up the size and shape of chunks. + * + * \subsubsection subsubsec_plist_basic Basic Steps of the Programming Model + * + * The steps of the property list programming model are described in the sub-sections below. + * + * <h4>Create a Property List</h4> + * + * A new property list can be created either as an instance of a property list class or by copying an + * existing property list. Consider the following examples. A new dataset creation property list is + * first created "from scratch" with \ref H5Pcreate. A second dataset creation property list is then + * created by copying the first one with \ref H5Pcopy. + * + * \code + * dcplA_id = H5Pcreate (H5P_DATASET_CREATE); + * \endcode + * + * The new dataset creation property list is created as an instance of the property list class + * \ref H5P_DATASET_CREATE. + * + * The new dataset creation property list’s identifier is returned in dcplA_id and the property list is + * initialized with default dataset creation property values. + * + * A list of valid classes appears in the table "Property list classes in HDF5". + * + * \code + * dcplB_id = H5Pcopy (dcplA_id); + * \endcode + * + * A new dataset creation property list, dcplB_id, is created as a copy of dcplA_id and is initialized + * with dataset creation property values currently in dcplA_id. + * + * At this point, dcplA_id and dcplB_id are identical; they will both contain any modified property + * values that were changed in dcplA_id before dcplB_id was created. They may, however, diverge + * as additional property values are reset in each. + * + * While we are creating property lists, let’s create a link creation property list; we will need this + * property list when the new dataset is linked into the file below: + * \code + * lcplAB_id = H5Pcreate (H5P_LINK_CREATE); + * \endcode + * + * <h4>Change Property Values</h4> + * + * This section describes how to set property values. + * + * Later in this section, the dataset creation property lists dcplA_id and dcplB_id created in the + * section above will be used respectively to create chunked and contiguous datasets. To set this up, + * we must set the layout property in each property list. The following example sets dcplA_id for + * chunked datasets and dcplB_id for contiguous datasets: + * \code + * error = H5Pset_layout (dcplA_id, H5D_CHUNKED); + * error = H5Pset_layout (dcplB_id, H5D_CONTIGUOUS); + * \endcode + * + * Since dcplA_id specifies a chunked layout, we must also set the number of dimensions and the + * size of the chunks. The example below specifies that datasets created with dcplA_id will be + * 3-dimensional and that the chunk size will be 100 in each dimension: + * \code + * error = H5Pset_chunk (dcplA_id, 3, [100,100,100]); + * \endcode + * + * These datasets will be created with UTF-8 encoded names. To accomplish that, the following + * example sets the character encoding property in the link creation property list to create link + * names with UTF-8 encoding: + * \code + * error = H5Pset_char_encoding (lcplAB_id, H5T_CSET_UTF8); + * \endcode + * + * dcplA_id can now be used to create chunked datasets and dcplB_id to create contiguous datasets. + * And with the use of lcplAB_id, they will be created with UTF-8 encoded names. + * + * <h4>Use the Property List</h4> + * + * Once the required property lists have been created, they can be used to control various HDF5 + * processes. For illustration, consider dataset creation. + * + * Assume that the datatype dtypeAB and the dataspaces dspaceA and dspaceB have been defined + * and that the location identifier locAB_id specifies the group AB in the current HDF5 file. We + * have already created the required link creation and dataset creation property lists. + * For the sake of illustration, we assume that the default dataset access property list meets our application + * requirements. The following calls would create the datasets dsetA and dsetB in the group AB. + * The raw data in dsetA will be contiguous while dsetB raw data will be chunked; both datasets + * will have UTF-8 encoded link names: + * + * \code + * dsetA_id = H5Dcreate2( locAB_id, dsetA, dtypeAB, dspaceA_id, + * lcplAB_id, dcplA_id, H5P_DEFAULT ); + * dsetB_id = H5Dcreate2( locAB_id, dsetB, dtypeAB, dspaceB_id, + * lcplAB_id, dcplB_id, H5P_DEFAULT ); + * \endcode + * + * <h4>Close the Property List</h4> + * + * Generally, creating or opening anything in an HDF5 file results in an HDF5 identifier. These + * identifiers are of HDF5 type hid_t and include things like file identifiers, often expressed as + * file_id; dataset identifiers, dset_id; and property list identifiers, plist_id. To reduce the risk of + * memory leaks, all of these identifiers must be closed once they are no longer needed. + * + * Property list identifiers are no exception to this rule, and \ref H5Pclose is used for this purpose. The + * calls immediately following would close the property lists created and used in the examples above. + * + * \code + * error = H5Pclose (dcplA_id); + * error = H5Pclose (dcplB_id); + * error = H5Pclose (lcplAB_id); + * \endcode + * + * \subsubsection subsubsec_plist_additional Additional Property List Operations + * + * A few property list operations fall outside of the programming model described above. This + * section describes those operations. + * + * <h4>Query the Class of an Existing Property List</h4> + * + * Occasionally an application will have a property list but not know the corresponding property list + * class. A call such as in the following example will retrieve the unknown class of a known property list: + * \code + * PList_Class = H5Pget_class (dcplA_id); + * \endcode + * + * Upon this function’s return, PList_Class will contain the value \ref H5P_DATASET_CREATE indicating that + * dcplA_id is a dataset creation property list. + + * <h4>Determine Current Creation Property List Settings in an Existing Object</h4> + * + * After a file has been created, another application may work on the file without knowing how the + * creation properties for the file were set up. Retrieving these property values is often unnecessary; + * HDF5 can read the data and knows how to deal with any properties it encounters. + * + * But sometimes an application must do something that requires knowing the creation property + * settings. HDF5 makes the acquisition of this information fairly straight-forward; for each + * property setting call, H5Pset_*, there is a corresponding H5Pget_*call to retrieve the property’s + * current setting. + * + * Consider the following examples which illustrate the determination of dataset layout and chunking settings: + * + * The application must first identify the creation property list with the appropriate get creation property + * list call. There is one such call for each kind of object. + * + * \ref H5Dget_create_plist will return a property list identifier for the creation property list that was + * used to create the dataset. Call it DCPL1_id. + * + * \ref H5Pset_layout sets a dataset’s layout to be compact, contiguous, or chunked. + * + * \ref H5Pget_layout called with DCPL1_id will return the dataset’s layout, + * either \ref H5D_COMPACT, \ref H5D_CONTIGUOUS, or \ref H5D_CHUNKED. + * + * \ref H5Pset_chunk sets the rank of a dataset, that is the number of dimensions it will have, and the + * maximum size of each dimension. + * + * \ref H5Pget_chunk, also called with DCPL1_id, will return the rank of the dataset and the maximum + * size of each dimension. + * + * If a creation property value has not been explicitly set, these H5Pget_calls will return the + * property’s default value. + * + * <h4>Determine Access Property Settings</h4> + * + * Access property settings are quite different from creation properties. Since access property + * settings are not retained in an HDF5 file or object, there is normally no knowledge of the settings + * that were used in the past. On the other hand, since access properties do not affect characteristics + * of the file or object, this is not normally an issue. For more information, see "Access and + * Creation Property Exceptions." + * + * One circumstance under which an application might need to determine access property settings + * might be when a file or object is already open but the application does not know the property list + * settings. In that case, the application can use the appropriate get access property list + * call to retrieve a property list identifier. For example, if the dataset dsetA + * from the earlier examples is still open, the following call would return an identifier for the dataset + * access property list in use: + * \code + * dsetA_dacpl_id = H5Dget_access_plist( dsetA_id ); + * \endcode + * + * The application could then use the returned property list identifier to analyze the property settings + * + * \subsection subsec_plist_generic Generic Properties Interface and User-defined Properties + * + * HDF5’s generic property interface provides tools for managing the entire property hierarchy and + * for the creation and management of user-defined property lists and properties. This interface also + * makes it possible for an application or a driver to create, modify, and manage custom properties, + * property lists, and property list classes. A comprehensive list of functions for this interface + * appears under "Generic Property Operations (Advanced)" in the "H5P: Property List Interface" + * section of the HDF5 Reference Manual. + * + * Further discussion of HDF5’s generic property interface and user-defined properties and + * property lists is beyond the scope of this document. + * + * \subsection subsec_plist_H5P Property List Function Summaries + * + * General property functions, generic property functions and macros, property functions that are + * used with multiple types of objects, and object and link property functions are listed below. + * + * Property list functions that apply to a specific type of object are listed in the chapter that + * discusses that object. For example, the \ref sec_dataset chapter has two property list function listings: + * one for dataset creation property list functions and one for dataset access property list functions. + * As has been stated, this chapter is not intended to describe every property list function. + * + * \ref H5P reference manual + * + * \subsection subsec_plist_resources Additional Property List Resources + * Property lists are ubiquitous in an HDF5 environment and are therefore discussed in many places + * in HDF5 documentation. The following sections and listings in the \ref UG are of + * particular interest: + * \li In the \ref sec_data_model chapter, see \ref subsubsec_data_model_abstract_plist. + * \li In the \ref sec_file chapter, see the following sections and listings: + * <ul> <li>\ref subsec_file_creation_access</li> + * <li>\ref subsec_file_property_lists</li> + * <li>\ref subsubsec_file_examples_props</li> + * <li>\ref subsubsec_file_examples_access</li> + * <li>"File creation property list functions (H5P)"</li> + * <li>"File access property list functions (H5P)"</li> + * <li>"File driver functions (H5P)"</li></ul> + * \li In the \ref sec_attribute chapter, see "Attribute creation property list functions (H5P)". + * \li In the \ref sec_group chapter, see "Group creation property list functions (H5P)". + * \li Property lists are discussed throughout \ref sec_dataset. + * + * All property list functions are described in the \ref H5P section of the + * \ref RM. The function index at the top of the page provides a categorized listing + * grouped by property list class. Those classes are listed below: + * \li File creation properties + * \li File access properties + * \li Group creation properties + * \li Dataset creation properties + * \li Dataset access properties + * \li Dataset transfer properties + * \li Link creation properties + * \li Link access properties + * \li Object creation properties + * \li Object copy properties + * + * Additional categories not related to the class structure are as follows: + * \li General property list operations + * \li Generic property list functions + * + * The general property functions can be used with any property list; the generic property functions + * constitute an advanced feature. + * + * The in-memory file image feature of HDF5 uses property lists in a manner that differs + * substantially from their use elsewhere in HDF5. Those who plan to use in-memory file images + * must study "File Image Operations" (PDF) in the Advanced Topics in HDF5collection. + * + * \subsection subsec_plist_notes Notes + * + * \anchor FileMountProps <h4>File Mount Properties</h4> + * + * While the file mount property list class \ref H5P_FILE_MOUNT is a valid HDF5 property list class, + * no file mount properties are defined by the HDF5 Library. References to a file mount property + * list should always be expressed as \ref H5P_DEFAULT, meaning the default file mount property list. + * + * <h4>Access and Creation Property Exceptions</h4> + * + * There are a small number of exceptions to the rule that creation properties are always retained in + * a file or object and access properties are never retained. + * + * The following properties are file access properties but they are not transient; they have + * permanent and different effects on a file. They could be validly classified as file creation + * properties as they must be set at creation time to properly create the file. But they are access + * properties because they must also be set when a file is reopened to properly access the file. + * <table> + * <tr><th>Property</th><th>Related function</th></tr> + * <tr valign="top"> + * <td> + * Family file driver + * </td> + * <td> + * \ref H5Pset_fapl_family + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Split file driver + * </td> + * <td> + * \ref H5Pset_fapl_split + * </td> + * </tr> + * <tr valign="top"> + * <td> + * Core file driver + * </td> + * <td> + * \ref H5Pset_fapl_core + * </td> + * </tr> + * </table> + * + * The following is a link creation property, but it is not relevant after an object has been created + * and is not retained in the file or object. + * <table> + * <tr><th>Property</th><th>Related function</th></tr> + * <tr valign="top"> + * <td> + * Create missing intermediate groups + * </td> + * <td> + * \ref H5Pset_create_intermediate_group + * </td> + * </tr> + * </table> + * + * Previous Chapter \ref sec_error - Next Chapter \ref sec_addition + * + * \defgroup H5P H5P Properties and Property Lists * * Use the functions in this module to manage HDF5 property lists and property * list classes. HDF5 property lists are the main vehicle to configure the @@ -61,7 +903,7 @@ * </tr> * </table> * - * \defgroup ALCAPL Attribute and Link Creation Properties + * \defgroup STRCPL String Creation Properties * \ingroup H5P * Currently, there are only two creation properties that you can use to control * the creation of HDF5 attributes and links. The first creation property, the @@ -69,8 +911,26 @@ * The second creation property applies to links only, and advises the library * to automatically create missing intermediate groups when creating new objects. * - * \defgroup DAPL Dataset Access Properties + * \defgroup LCPL Link Creation Properties + * \ingroup STRCPL + * The first creation property, the choice of a character encoding, applies to + * both attributes and links. + * The second creation property applies to links only, and advises the library + * to automatically create missing intermediate groups when creating new objects. + * + * See \ref STRCPL + * + * \defgroup ACPL Attribute Creation Properties + * \ingroup STRCPL + * The creation property, the choice of a character encoding, applies to attributes. + * + * See \ref STRCPL + * + * \defgroup LAPL Link Access Properties * \ingroup H5P + * + * \defgroup DAPL Dataset Access Properties + * \ingroup LAPL * Use dataset access properties to modify the default behavior of the HDF5 * library when accessing datasets. The properties include adjusting the size * of the chunk cache, providing prefixes for external content and virtual @@ -79,7 +939,7 @@ * a dataset is created or opened. * * \defgroup DCPL Dataset Creation Properties - * \ingroup H5P + * \ingroup OCPL * Use dataset creation properties to control aspects of dataset creation such * as fill time, storage layout, compression methods, etc. * Unlike dataset access and transfer properties, creation properties \Emph{are} @@ -102,7 +962,7 @@ * can be adjusted at runtime before a file is created or opened. * * \defgroup FCPL File Creation Properties - * \ingroup H5P + * \ingroup GCPL * Use file creation properties to control aspects of file creation such * as setting a file space management strategy or creating a user block. * Unlike file access properties, creation properties \Emph{are} @@ -110,19 +970,19 @@ * created. * * \defgroup GAPL General Access Properties - * \ingroup H5P + * \ingroup LAPL * The functions in this section can be applied to different kinds of property * lists. * * \defgroup GCPL Group Creation Properties - * \ingroup H5P + * \ingroup OCPL * Use group creation properties to control aspects of group creation such * as storage layout, compression, and link creation order tracking. * Unlike file access properties, creation properties \Emph{are} * stored with the group, and cannot be changed once a group has been * created. * - * \defgroup GPLO General Property List Operations + * \defgroup PLCR Property List Class Root * \ingroup H5P * * Use the functions in this module to manage HDF5 property lists. @@ -147,7 +1007,7 @@ * </tr> * </table> * - * \defgroup GPLOA General Property List Operations (Advanced) + * \defgroup PLCRA Property List Class Root (Advanced) * \ingroup H5P * * You can create and customize user-defined property list classes using the @@ -175,16 +1035,26 @@ * </tr> * </table> * - * \defgroup LAPL Link Access Properties + * \defgroup OCPL Object Creation Properties * \ingroup H5P * + * \defgroup OCPYPL Object Copy Properties + * \ingroup H5P * - * \defgroup OCPL Object Creation Properties + * \defgroup FMPL File Mount Properties * \ingroup H5P * + * Empty property class. * - * \defgroup OCPPL Object Copy Properties - * \ingroup H5P + * \defgroup TCPL Datatype Creation Properties + * \ingroup OCPL + * + * TCPL isn't supported yet. + * + * \defgroup TAPL Datatype Access Properties + * \ingroup LAPL + * + * TAPL isn't supported yet. * * */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 474339f..017b636 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -353,7 +353,7 @@ H5_DLLVAR hid_t H5P_CLS_OBJECT_COPY_ID_g; H5_DLLVAR hid_t H5P_CLS_LINK_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_LINK_ACCESS_ID_g; -/* Default roperty list IDs */ +/* Default property list IDs */ /* (Internal to library, do not use! Use macros above) */ H5_DLLVAR hid_t H5P_LST_FILE_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_FILE_ACCESS_ID_g; @@ -378,7 +378,7 @@ H5_DLLVAR hid_t H5P_LST_LINK_ACCESS_ID_g; /* Generic property list routines */ /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Terminates access to a property list * @@ -396,7 +396,7 @@ H5_DLLVAR hid_t H5P_LST_LINK_ACCESS_ID_g; */ H5_DLL herr_t H5Pclose(hid_t plist_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Closes an existing property list class * @@ -413,7 +413,7 @@ H5_DLL herr_t H5Pclose(hid_t plist_id); */ H5_DLL herr_t H5Pclose_class(hid_t plist_id); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Copies an existing property list to create a new property list * @@ -430,7 +430,7 @@ H5_DLL herr_t H5Pclose_class(hid_t plist_id); */ H5_DLL hid_t H5Pcopy(hid_t plist_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Copies a property from one list or class to another * @@ -466,7 +466,7 @@ H5_DLL hid_t H5Pcopy(hid_t plist_id); */ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Creates a new property list as an instance of a property list class * @@ -584,7 +584,7 @@ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); */ H5_DLL hid_t H5Pcreate(hid_t cls_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Creates a new property list class * @@ -627,7 +627,7 @@ H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func H5P_cls_copy_func_t copy, void *copy_data, H5P_cls_close_func_t close, void *close_data); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Decodes property list received in a binary object buffer and * returns a new property list identifier @@ -656,7 +656,7 @@ H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func */ H5_DLL hid_t H5Pdecode(const void *buf); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Encodes the property values in a property list into a binary * buffer @@ -695,7 +695,7 @@ H5_DLL hid_t H5Pdecode(const void *buf); */ H5_DLL herr_t H5Pencode(hid_t plist_id, void *buf, size_t *nalloc); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Compares two property lists or classes for equality * @@ -715,7 +715,7 @@ H5_DLL herr_t H5Pencode(hid_t plist_id, void *buf, size_t *nalloc); */ H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries whether a property name exists in a property list or * class @@ -733,7 +733,7 @@ H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2); */ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries the value of a property * @@ -765,7 +765,7 @@ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name); */ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value); /** - *\ingroup GPLO + *\ingroup PLCR * * \brief Returns the property list class identifier for a property list * @@ -828,7 +828,7 @@ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value); */ H5_DLL hid_t H5Pget_class(hid_t plist_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Retrieves the name of a class * @@ -972,7 +972,7 @@ H5_DLL hid_t H5Pget_class(hid_t plist_id); */ H5_DLL char *H5Pget_class_name(hid_t pclass_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Retrieves the parent class of a property class * @@ -988,7 +988,7 @@ H5_DLL char *H5Pget_class_name(hid_t pclass_id); */ H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries the number of properties in a property list or class * @@ -1011,7 +1011,7 @@ H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id); */ H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries the size of a property value in bytes * @@ -1032,7 +1032,7 @@ H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops); */ H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Registers a temporary property with a property list * @@ -1282,7 +1282,7 @@ H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *va H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Determines whether a property list is a member of a class * @@ -1302,7 +1302,7 @@ H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *va */ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Iterates over properties in a property class or list * @@ -1348,7 +1348,7 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); */ H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Registers a permanent property with a property list class * @@ -1629,7 +1629,7 @@ H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *de H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Removes a property from a property list * @@ -1655,7 +1655,7 @@ H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *de */ H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Sets a property list value * @@ -1687,7 +1687,7 @@ H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); */ H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, const void *value); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Removes a property from a property list class * @@ -1706,8 +1706,6 @@ H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, const void *value); */ H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); -/* Object creation property list (OCPL) routines */ - /** * \ingroup DCPL * @@ -1727,6 +1725,9 @@ H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); * */ H5_DLL htri_t H5Pall_filters_avail(hid_t plist_id); + +/* Object creation property list (OCPL) routines */ + /** * \ingroup OCPL * @@ -7899,7 +7900,7 @@ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no /* Link creation property list (LCPL) routines */ /** - * \ingroup ALCAPL + * \ingroup STRCPL * * \brief Determines whether property is set to enable creating missing * intermediate groups @@ -7930,7 +7931,7 @@ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no */ H5_DLL herr_t H5Pget_create_intermediate_group(hid_t plist_id, unsigned *crt_intmd /*out*/); /** - * \ingroup ALCAPL + * \ingroup STRCPL * * \brief Specifies in property list whether to create missing * intermediate groups @@ -8266,7 +8267,7 @@ H5_DLL herr_t H5Pset_local_heap_size_hint(hid_t plist_id, size_t size_hint); /* String creation property list (STRCPL) routines */ /** - * \ingroup ALCAPL + * \ingroup STRCPL * * \brief Retrieves the character encoding used to create a link or * attribute name @@ -8295,7 +8296,7 @@ H5_DLL herr_t H5Pset_local_heap_size_hint(hid_t plist_id, size_t size_hint); */ H5_DLL herr_t H5Pget_char_encoding(hid_t plist_id, H5T_cset_t *encoding /*out*/); /** - * \ingroup ALCAPL + * \ingroup STRCPL * * \brief Sets the character encoding used to encode link and attribute * names @@ -8336,7 +8337,6 @@ H5_DLL herr_t H5Pget_char_encoding(hid_t plist_id, H5T_cset_t *encoding /*out*/) */ H5_DLL herr_t H5Pset_char_encoding(hid_t plist_id, H5T_cset_t encoding); -/* Link access property list (LAPL) routines */ /** * \ingroup LAPL * @@ -8695,7 +8695,7 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); /* Object copy property list (OCPYPL) routines */ /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Adds a path to the list of paths that will be searched in the * destination file for a matching committed datatype @@ -8810,7 +8810,7 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); */ H5_DLL herr_t H5Padd_merge_committed_dtype_path(hid_t plist_id, const char *path); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Clears the list of paths stored in the object copy property list * @@ -8861,7 +8861,7 @@ H5_DLL herr_t H5Padd_merge_committed_dtype_path(hid_t plist_id, const char *path */ H5_DLL herr_t H5Pfree_merge_committed_dtype_paths(hid_t plist_id); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Retrieves the properties to be used when an object is copied * @@ -8886,7 +8886,7 @@ H5_DLL herr_t H5Pfree_merge_committed_dtype_paths(hid_t plist_id); */ H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *copy_options /*out*/); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Retrieves the callback function from the specified object copy * property list @@ -8924,7 +8924,7 @@ H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *copy_options /*out*/) */ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, void **op_data); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Sets properties to be used when an object is copied * @@ -9017,7 +9017,7 @@ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, */ H5_DLL herr_t H5Pset_copy_object(hid_t plist_id, unsigned copy_options); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Sets the callback function that H5Ocopy() will invoke before * searching the entire destination file for a matching committed @@ -9115,7 +9115,7 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v /* Typedefs */ /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Registers a permanent property with a property list class * @@ -9245,7 +9245,7 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Registers a temporary property with a property list * diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index 32343be..d444ba9 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -26,7 +26,7 @@ #define H5_MY_PKG_INIT YES /** - * \defgroup H5R H5R + * \defgroup H5R H5R References * * Use the functions in this module to manage HDF5 references. Referents can * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset diff --git a/src/H5Smodule.h b/src/H5Smodule.h index 010f4a6..fc60ed7 100644 --- a/src/H5Smodule.h +++ b/src/H5Smodule.h @@ -29,7 +29,28 @@ #define H5_MY_PKG_ERR H5E_DATASPACE #define H5_MY_PKG_INIT YES -/**\defgroup H5S H5S +/** \page H5S_UG Dataspaces and Partial I/O + * + * + * \section sec_dataspace HDF5 Dataspaces and Partial I/O + * \subsection subsec_dataspace_intro Introduction + * \subsection subsec_dataspace_function Dataspace Function Summaries + * \subsection subsec_dataspace_program Definition of Dataspace Objects and the Dataspace Programming Model + * \subsubsection subsubsec_dataspace_program_object Dataspace Objects + * \subsubsection subsubsec_dataspace_program_model Dataspace Programming Model + * \subsection subsec_dataspace_transfer Dataspaces and Data Transfer + * \subsubsection subsubsec_dataspace_transfer_select Data Selection + * \subsubsection subsubsec_dataspace_transfer_model Programming Model + * \subsection subsec_dataspace_select Dataspace Selection Operations and Data Transfer + * \subsection subsec_dataspace_refer References to Dataset Regions + * \subsubsection subsubsec_dataspace_refer_use Example Uses for Region References + * \subsubsection subsubsec_dataspace_refer_create Creating References to Regions + * \subsubsection subsubsec_dataspace_refer_read Reading References to Regions + * \subsection subsec_dataspace_sample Sample Programs + * + */ + +/**\defgroup H5S H5S Dataspaces * * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections. * diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index 30ac702..a636dc5 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -29,7 +29,40 @@ #define H5_MY_PKG_ERR H5E_DATATYPE #define H5_MY_PKG_INIT YES -/**\defgroup H5T H5T +/** \page H5T_UG HDF5 Datatypes + * + * \section sec_datatype HDF5 Datatypes + * \subsection subsec_datatype_intro Introduction and Definitions + * \subsection subsec_datatype_model Datatype Model + * \subsubsection subsubsec_datatype_model_class Datatype Classes and Properties + * \subsubsection subsubsec_datatype_model_predefine Predefined Datatypes + * \subsection subsec_datatype_usage How Datatypes are Used + * \subsubsection subsubsec_datatype_usage_object The Datatype Object and the HDF5 Datatype API + * \subsubsection subsubsec_datatype_usage_create Dataset Creation + * \subsubsection subsubsec_datatype_usage_transfer Data Transfer (Read and Write) + * \subsubsection subsubsec_datatype_usage_discover Discovery of Data Format + * \subsubsection subsubsec_datatype_usage_user Creating and Using User‐defined Datatypes + * \subsection subsec_datatype_function Datatype Function Summaries + * \subsection subsec_datatype_program Programming Model for Datatypes + * \subsubsection subsubsec_datatype_program_discover Discovery of Datatype Properties + * \subsubsection subsubsec_datatype_program_define Definition of Datatypes + * \subsection subsec_datatype_other Other Non-numeric Datatypes + * \subsubsection subsubsec_datatype_other_strings Strings + * \subsubsection subsubsec_datatype_other_refs Reference + * \subsubsection subsubsec_datatype_other_enum ENUM + * \subsubsection subsubsec_datatype_other_opaque Opaque + * \subsubsection subsubsec_datatype_other_bitfield Bitfield + * \subsection subsec_datatype_fill Fill Values + * \subsection subsec_datatype_complex Complex Combinations of Datatypes + * \subsubsection subsubsec_datatype_complex_create Creating a Complicated Compound Datatype + * \subsubsection subsubsec_datatype_complex_analyze Analyzing and Navigating a Compound Datatype + * \subsection subsec_datatype_life Life Cycle of the Datatype Object + * \subsection subsec_datatype_transfer Data Transfer: Datatype Conversion and Selection + * \subsection subsec_datatype_text Text Descriptions of Datatypes: Conversion to and from + * + */ + +/**\defgroup H5T H5T Datatypes * * Use the functions in this module to manage HDF5 datatypes. * diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index 9312b72..37d9f70 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -29,7 +29,7 @@ #define H5_MY_PKG_ERR H5E_PLINE #define H5_MY_PKG_INIT YES -/**\defgroup H5Z H5Z +/**\defgroup H5Z H5Z Filters * * Use the functions in this module to manage HDF5 filters. * diff --git a/src/H5module.h b/src/H5module.h index f37dfc7..d335d87 100644 --- a/src/H5module.h +++ b/src/H5module.h @@ -26,6 +26,48 @@ #define H5_MY_PKG_ERR H5E_LIB #define H5_MY_PKG_INIT NO +/** \page H5DM_UG The HDF5 Data Model and File Structure + * + * \section sec_data_model The HDF5 Data Model and File Structure + * \subsection subsec_data_model_intro Introduction + * \subsection subsec_data_model_abstract The Abstract Data Model + * \subsubsection subsubsec_data_model_abstract_file File + * \subsubsection subsubsec_data_model_abstract_group Group + * \subsubsection subsubsec_data_model_abstract_dataset Dataset + * \subsubsection subsubsec_data_model_abstract_space Dataspace + * \subsubsection subsubsec_data_model_abstract_type Datatype + * \subsubsection subsubsec_data_model_abstract_attr Attribute + * \subsubsection subsubsec_data_model_abstract_plist Property List + * \subsubsection subsubsec_data_model_abstract_link Link + * \subsection subsec_data_model_storage The HDF5 Storage Model + * \subsubsection subsubsec_data_model_storage_spec The Abstract Storage Model: the HDF5 Format Specification + * \subsubsection subsubsec_data_model_storage_imple Concrete Storage Model + * \subsection subsec_data_model_structure The Structure of an HDF5 File + * \subsubsection subsubsec_data_model_structure_file Overall File Structure + * \subsubsection subsubsec_data_model_structure_path HDF5 Path Names and Navigation + * \subsubsection subsubsec_data_model_structure_example Examples of HDF5 File Structures + * + */ + +/** \page H5_UG The HDF5 Library and Programming Model + * + * \section sec_program The HDF5 Library and Programming Model + * \subsection subsec_program_intro Introduction + * \subsection subsec_program_model The HDF5 Programming Model + * \subsubsection subsubsec_program_model_create Creating an HDF5 File + * \subsubsection subsubsec_program_model_dset Creating and Initializing a Dataset + * \subsubsection subsubsec_program_model_close Closing an Object + * \subsubsection subsubsec_program_model_data Writing or Reading a Dataset to or from a File + * \subsubsection subsubsec_program_model_partial Reading and Writing a Portion of a Dataset + * \subsubsection subsubsec_program_model_info Getting Information about a Dataset + * \subsubsection subsubsec_program_model_compound Creating and Defining Compound Datatypes + * \subsubsection subsubsec_program_model_extend Creating and Writing Extendable Datasets + * \subsubsection subsubsec_program_model_group Creating and Working with Groups + * \subsubsection subsubsec_program_model_attr Working with Attributes + * \subsection subsec_program_transfer_pipeline The Data Transfer Pipeline + * + */ + /**\defgroup H5 H5 * * Use the functions in this module to manage the life cycle of HDF5 library |
